mirror of
https://github.com/Kpa-clawbot/meshcore-analyzer.git
synced 2026-06-30 13:21:40 +00:00
22fe929da2
Implements #1727. ## What this adds **Mobile client-RX coverage** — an opt-in, crowdsourced RF-coverage feature. A roaming MeshCore **companion** radio (driven by the open-source [corescope-rx](https://github.com/efiten/corescope-rx) PWA, GPLv3) reports which nodes it heard directly, tagged with the phone's GPS and the packet's SNR/RSSI. CoreScope ingests these into a new `client_receptions` table and renders per-node **hex coverage** on the Reach page, plus a standalone **Coverage dashboard** (`#/rx-coverage`) with a top-mobile-observers leaderboard. Also includes **`GET /api/nodes/resolve?prefix=<hex>`** — a read-only node-name lookup by pubkey prefix (`{name, pubkey, ambiguous}`), used by the companion app for friendly names. ## Opt-in — default OFF (zero impact on existing deployments) The whole feature is gated behind one config flag, **disabled by default**: ```jsonc "clientRxCoverage": { "enabled": false } ``` When disabled (the default): the ingestor writes **no** `client_receptions`; the three coverage endpoints return a clean **404**; the UI hides the Coverage nav link, the `#/rx-coverage` route, and the Reach-page toggle. `/api/nodes/resolve` is always available (not coverage-specific). ## How it works ``` companion ──BLE 0x88 (snr+rssi+raw)──▶ corescope-rx PWA ──▶ MQTT meshcore/client/{pubkey}/packets │ ingestor (gated) ──▶ client_receptions (GPS + SNR + heard-key) │ server: pure-Go hex grid ──▶ GeoJSON ──▶ Reach hex overlay + Coverage dashboard ``` - **Direct-only capture:** records only what the companion heard itself and directly — a 0-hop advert's pubkey, or `path[last]` (last forwarder) for FLOOD routes; ≥2-byte path-hash required. Upstream hops discarded. - **No new deps:** hexbins are a pure-Go pointy-top grid over Web Mercator (`cmd/server/hexgrid.go`) computed at query time (`CGO_ENABLED=0` / `modernc.org/sqlite` friendly); frontend uses the existing Leaflet. - **Trust:** companion pubkey = identity; an EMQX ACL binds each client to publish only to its own `meshcore/client/{pubkey}/packets` topic. Payload contract in `docs/client-rx-coverage.md`. ## How to enable / try it 1. In `config.json`, set `"clientRxCoverage": { "enabled": true }` and restart server + ingestor. 2. Point an EMQX (or any broker) listener so a client can publish to `meshcore/client/<pubkey>/packets`; the ingestor already subscribes under `meshcore/#`. 3. Run the [corescope-rx](https://github.com/efiten/corescope-rx) PWA on an Android phone paired (BLE) to a MeshCore companion — it captures heard nodes + GPS and publishes. 4. View results: per-node Reach page → toggle **coverage**, or the **Coverage** dashboard at `#/rx-coverage`. ## What's where - **Ingestor:** `cmd/ingestor/client_reception.go` (ingest), `db.go` (`client_receptions` + `client_observers` schema), `main.go` (gated dispatch), `config.go` (flag). - **Server:** `cmd/server/rx_coverage.go` + `rx_dashboard.go` (endpoints, self-guard 404 when off), `hexgrid.go` (pure-Go grid), `node_resolve.go` (resolve), `routes.go` / `types.go` / `config.go` (wiring + flag + `/api/config/client` field). - **Frontend:** `public/rx-coverage.js` (dashboard), `node-reach-coverage.js` + `.css` (overlay), `node-reach.js` (Reach toggle, flag-gated), `roles.js` (reads the flag, hides nav when off). - **Docs:** `docs/client-rx-coverage.md`. ## Testing - Go: `cd cmd/server && go test ./...` and `cd cmd/ingestor && go test ./...` — green, including new gate tests (`coverage_gate_test.go` in both: off → no rows / 404, on → works) and the rx-coverage / resolve / hexgrid suites. - JS: `node test-coverage-gate.js`, `node test-node-reach-coverage.js` (wired into CI). The Playwright `test-node-reach-coverage-e2e.js` is wired into the e2e job and **skips when `clientRxCoverage` is disabled**, so it's safe under the default-off config. ## Notes for reviewers - The four new routes are registered in `cmd/server/openapi_known_gaps.json` (the existing OpenAPI-completeness ratchet), matching how other not-yet-spec'd routes are tracked. Happy to write full OpenAPI spec entries instead if you prefer. - Commits are split per layer (ingestor / server endpoints / resolve / frontend / CI) for review. --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> Co-authored-by: Erwin Fiten <e.fiten@opteco.be>
87 lines
3.6 KiB
Go
87 lines
3.6 KiB
Go
package main
|
|
|
|
import (
|
|
"encoding/json"
|
|
"net/http/httptest"
|
|
"testing"
|
|
|
|
"github.com/gorilla/mux"
|
|
)
|
|
|
|
func serveResolve(srv *Server, path string) *httptest.ResponseRecorder {
|
|
router := mux.NewRouter()
|
|
router.HandleFunc("/api/nodes/resolve", srv.handleResolvePrefix).Methods("GET")
|
|
rr := httptest.NewRecorder()
|
|
router.ServeHTTP(rr, httptest.NewRequest("GET", path, nil))
|
|
return rr
|
|
}
|
|
|
|
func TestResolvePrefix(t *testing.T) {
|
|
db := setupTestDBv2(t)
|
|
mustExecDB(t, db, `INSERT INTO nodes (public_key, name, role, last_seen, first_seen, advert_count)
|
|
VALUES ('efef7943505052b47f1809488ea4b4d3942d4ed72d2b1953b90a9f5e62a65fb5','NodeUnique','repeater','t','t',1)`)
|
|
// Two nodes sharing the 4-hex prefix aabb → ambiguous at the new minimum.
|
|
mustExecDB(t, db, `INSERT INTO nodes (public_key, name, role, last_seen, first_seen, advert_count)
|
|
VALUES ('aabb110000000000000000000000000000000000000000000000000000000000','NodeA','repeater','t','t',1)`)
|
|
mustExecDB(t, db, `INSERT INTO nodes (public_key, name, role, last_seen, first_seen, advert_count)
|
|
VALUES ('aabb220000000000000000000000000000000000000000000000000000000000','NodeB','repeater','t','t',1)`)
|
|
srv := &Server{db: db}
|
|
|
|
// unique 3-byte prefix → name
|
|
var r1 ResolvePrefixResp
|
|
json.Unmarshal(serveResolve(srv, "/api/nodes/resolve?prefix=efef79").Body.Bytes(), &r1)
|
|
if r1.Name != "NodeUnique" || r1.Ambiguous {
|
|
t.Fatalf("unique: %+v", r1)
|
|
}
|
|
// colliding 4-hex prefix (aabb…) → ambiguous, no name
|
|
var r2 ResolvePrefixResp
|
|
json.Unmarshal(serveResolve(srv, "/api/nodes/resolve?prefix=aabb").Body.Bytes(), &r2)
|
|
if !r2.Ambiguous || r2.Name != "" {
|
|
t.Fatalf("ambiguous: %+v", r2)
|
|
}
|
|
// not found → empty name, not ambiguous
|
|
var r3 ResolvePrefixResp
|
|
json.Unmarshal(serveResolve(srv, "/api/nodes/resolve?prefix=dead").Body.Bytes(), &r3)
|
|
if r3.Name != "" || r3.Ambiguous {
|
|
t.Fatalf("notfound: %+v", r3)
|
|
}
|
|
// non-hex prefix → 400
|
|
if serveResolve(srv, "/api/nodes/resolve?prefix=xyz").Code != 400 {
|
|
t.Fatal("non-hex prefix should be 400")
|
|
}
|
|
// #15: prefixes shorter than 4 hex are rejected (kills 256-prefix enumeration)
|
|
for _, short := range []string{"a", "aa", "abc"} {
|
|
if code := serveResolve(srv, "/api/nodes/resolve?prefix="+short).Code; code != 400 {
|
|
t.Fatalf("prefix %q (<4 hex) should be 400, got %d", short, code)
|
|
}
|
|
}
|
|
}
|
|
|
|
// TestResolvePrefixHidesBlacklistedAndHidden verifies the #15 parity fix: a
|
|
// unique match that is blacklisted or whose name is hidden (#1181) resolves as
|
|
// not-found, never leaking an identity the rest of the API hides.
|
|
func TestResolvePrefixHidesBlacklistedAndHidden(t *testing.T) {
|
|
db := setupTestDBv2(t)
|
|
const blPK = "bbcc110000000000000000000000000000000000000000000000000000000000"
|
|
const hidPK = "ddee220000000000000000000000000000000000000000000000000000000000"
|
|
mustExecDB(t, db, `INSERT INTO nodes (public_key, name, role, last_seen, first_seen, advert_count)
|
|
VALUES ('`+blPK+`','BlacklistedNode','repeater','t','t',1)`)
|
|
mustExecDB(t, db, `INSERT INTO nodes (public_key, name, role, last_seen, first_seen, advert_count)
|
|
VALUES ('`+hidPK+`','🚫HiddenNode','repeater','t','t',1)`)
|
|
srv := &Server{db: db, cfg: &Config{
|
|
NodeBlacklist: []string{blPK},
|
|
HiddenNamePrefixes: []string{"🚫"},
|
|
}}
|
|
|
|
var rb ResolvePrefixResp
|
|
json.Unmarshal(serveResolve(srv, "/api/nodes/resolve?prefix=bbcc11").Body.Bytes(), &rb)
|
|
if rb.Name != "" || rb.Pubkey != "" || rb.Ambiguous {
|
|
t.Fatalf("blacklisted node must resolve as not-found: %+v", rb)
|
|
}
|
|
var rh ResolvePrefixResp
|
|
json.Unmarshal(serveResolve(srv, "/api/nodes/resolve?prefix=ddee22").Body.Bytes(), &rh)
|
|
if rh.Name != "" || rh.Pubkey != "" || rh.Ambiguous {
|
|
t.Fatalf("hidden-prefix node must resolve as not-found: %+v", rh)
|
|
}
|
|
}
|