@meshbench/client 0.0.1

package/README.md

@@ -0,0 +1,216 @@
+# MeshBench Node client
+
+Drive a MeshBench workbench from Node, over the same control socket the
+[Go](../client-go) and [Python](../client-python) clients speak. The three are
+peers on the wire and peers in shape: one protocol, one handshake, one set of
+transports, one generated set of closed enums, and the same helpers with the
+same names.
+
+No dependencies, no build step, no TypeScript compiler. It is ES modules on
+Node's own `net`.
+
+```js
+import { Workbench } from "@meshbench/client"; // or "./meshbench.mjs" from a checkout
+
+const wb = await Workbench.headless({ fixture: "fife-strict", seed: 9001 });
+try {
+  await wb.sim.start();                          // warm, firmware, then play
+  await wb.sim.run(5 * 60_000);                  // five minutes of the mesh's clock
+  console.log(String(await wb.provenance()));
+  console.log(await wb.events.total(), "events");
+} finally {
+  await wb.close();
+}
+```
+
+## Two layers, both public
+
+`wb.call(verb, params)` is the whole protocol, so a verb this package has not
+shaped is one line away rather than a blocker. The shape above it is what a
+script should reach for first, because **every helper on it exists to stop a
+mistake somebody has already made**:
+
+| | |
+|---|---|
+| `wb.sim` | the clock, and `start()` - see below |
+| `wb.nodes`, `wb.node(name)` | the network, and one node: place, move, firmware, board, antenna, card, console, device |
+| `wb.firmware` | the library: find, import, build, `useWhatIsHere()`, `waitStarted()` |
+| `wb.events` | the log: `recent()`, `total()`, `dump()`, `wait()` |
+| `wb.project`, `wb.boundary`, `wb.live` | the network as a whole, the study area, and the import chain |
+| `wb.schedule`, `wb.assertions` | what a run is told to send, and what has to be true of it |
+| `wb.subscribe(...)` | being told rather than asking |
+| `sessions()` | which workbenches are running on this machine |
+
+### `sim.start()`, and why it is not `sim.start`
+
+The verb `sim.start` is the play button's own handler and answers four ways: it
+**pauses** if already playing, declines while links are being measured, or
+starts firmware and does not play. Worse, it starts firmware only when *no* node
+is running, so a mesh where you pinned a build onto two nodes is "started" with
+the other fifty-six down.
+
+`wb.sim.start()` asks for the three things a script actually means, in order,
+and checks each: wait out the warm, start whatever firmware is down, wait for
+it, then `sim.play` by its own name.
+
+### Waits are methods, and there are two clocks
+
+Every wait is a method - `node.waitRunning()`, `sim.run()`,
+`firmware.waitStarted()`, `wb.waitIdle()` - never a sleep in a script. They poll
+today and will subscribe later, and no script changes when they do.
+
+Simulated time is the mesh's own: `sim.run(5 * 60_000)` is five minutes of *its*
+clock, and on 155 emulated nodes that is a great deal longer than five of yours.
+Wall clock is yours: every `timeoutMs`, and `sim.run(..., {waitMs})`. Both are
+milliseconds, so the name is what tells them apart, and nothing that means the
+mesh's clock is called a timeout.
+
+## Refusals
+
+**The workbench answers "no" by returning a value, not by raising** - so read
+the reply of anything that looks like a command. What this client raises is a
+`WorkbenchError` carrying the verb, the workbench's own words and its `code`,
+subclassed by that code so `instanceof` works where Go has `errors.Is` and
+Python has an exception hierarchy:
+
+```js
+import { NotFound, Timeout, VersionMismatch } from "@meshbench/client";
+
+try {
+  await wb.nodes.find("West Lomond");
+} catch (e) {
+  if (e instanceof NotFound) …   // its message names what it did find
+}
+```
+
+`MeshbenchError` is the base. `UnknownVerb`, `BadParams`, `NotFound`,
+`Conflict`, `Unavailable` and `Closing` are the workbench's own codes;
+`ProtocolMismatch` and `VersionMismatch` are the two ends refusing each other;
+`Timeout` is a wait that ran out, and says what it last saw rather than only
+that it gave up.
+
+## Enums, not strings
+
+`Kind`, `Board`, `Preset`, `Role`, `Class`, `Tab`, `Strategy` and `Transport`
+are generated by `tools/clientgen` from `internal/world/scenario`, the same one
+place the Go and Python clients are generated from, and CI fails when the three
+drift. Never spell one as a free string: a board name nothing matches produces a
+different node, silently.
+
+```js
+import { Board, Kind, Role } from "@meshbench/client";
+
+await wb.nodes.place({ name: "Deck", kind: Kind.COMPANION, lat: 56.19, lon: -3.17,
+                       board: Board.LILYGO_TDECK });
+```
+
+Each is a frozen object of plain strings, so a member goes on the wire as itself
+and a literal is still accepted anywhere one is asked for. The member names match
+the Python client's exactly, so a script moved between the two changes the dots
+and nothing else.
+
+## Installing, and starting a workbench
+
+```
+npm install @meshbench/client
+```
+
+You also need the `meshbench` binary: this package drives a workbench, it does
+not contain one. Put it on `PATH` or name it in `MESHBENCH_BINARY`.
+
+- `Workbench.headless(opts)` starts one with no window and owns it: no display,
+  no GPU, no toolkit. The one to use from a test or from CI.
+- `Workbench.launch(opts)` opens the desktop workbench and owns it.
+- `Workbench.attach(opts)` connects to one already running and never owns it -
+  `close()` hangs up, and whatever was on screen stays on screen.
+- `Workbench.attachOrHeadless(opts)` / `attachOrLaunch(opts)` use the session
+  that is running, or start one. Ask `wb.ownsProcess` which you got.
+
+`headless` and `launch` take `{fixture, seed, socket, binary, args,
+startTimeoutMs, callTimeoutMs, stderr}`. Given a `fixture` they wait for it to
+open, not merely for the socket: the windowed build loads a fixture on a worker
+so the window appears first, and a client that believed the socket would be told
+there are no nodes and no jobs, and `waitIdle` would return in 0.00s having
+waited for work nobody had queued.
+
+Each owns its own private address unless you name a socket, so two of them do
+not fight over the per-user default.
+
+## Connecting
+
+`Workbench.attach()` finds the workbench the same way the other clients do, so
+all three agree on one machine:
+
+- `MESHBENCH_CONTROL_SOCKET` if set - a path, `tcp`, or `tcp:host:port`.
+- otherwise a unix socket at `$XDG_RUNTIME_DIR/meshbench.sock` (Linux) or the
+  per-user cache directory (macOS).
+- Windows has no unix socket, so the workbench listens on loopback TCP and
+  writes its address and a token to a rendezvous file; this reads that file and
+  presents the token.
+
+A unix socket path over 104 bytes is refused before it ever reaches `connect`,
+the same limit and the same message the other two give - the raw OS error names
+neither the limit nor what to do about it.
+
+Where several workbenches are running, `sessions()` lists them and a row goes
+straight to `attach`, which is the only way to reach a second TCP session: its
+token sits beside its address in its own file, where the per-user rendezvous
+file two of them share has only one of the two.
+
+```js
+import { sessions, Workbench } from "@meshbench/client";
+
+const running = await sessions();
+const wb = await Workbench.attach({ session: running.at(-1) });
+```
+
+There is deliberately no "attach to whatever is running": where several are up
+and none was named, guessing is how a script ends up driving the session
+somebody else was watching.
+
+**A client and the workbench it drives must be the same release.** This package
+declares its own version on the wire, the workbench refuses a pair it cannot be
+half of, and the refusal arrives as a `VersionMismatch` naming both releases and
+what to install. An end that is not a release build - a workbench compiled from
+a checkout - is served instead, because there is no second version there to
+disagree with; when that happens `wb.versionCheck` says which end was skipped
+and why.
+
+```js
+const wb = await Workbench.attach({
+  socket: "/run/user/1000/meshbench.sock",
+  timeoutMs: 5000,       // how long to wait for the connection itself
+  callTimeoutMs: 20000,  // the default budget for every call() on it
+});
+
+// A single call known to take longer gets its own budget, or none:
+await wb.call("firmware.build", { source: "~/src/MeshCore" }, 20 * 60_000);
+await wb.call("sim.run", { for_ms: 10 * 60_000 }, null); // no timeout
+```
+
+`callTimeoutMs` defaults to 300000 (five minutes), matching the Python client's
+socket timeout, so a script ported between the two waits the same length of time
+before it hears about a verb the workbench never answered.
+
+## Running
+
+```bash
+node --test                                 # the client's own tests, no workbench needed
+node examples/small-mesh-with-traffic.mjs   # needs meshbench on PATH
+```
+
+The tests stand up a fake workbench on a unix socket and check the wire and
+every helper above it - no real workbench, no network. They also import every
+example, which is Node's answer to `go build ./...` compiling the Go ones: an
+example that has stopped parsing, or that reaches for a helper this client no
+longer has, is a red test run rather than something somebody finds by trying it.
+
+See [examples/](examples/) for the set, one file each, matching the Go and
+Python examples one for one.
+
+## What a scripted result is
+
+A number this prints is a simulated number, kinder than the air, exactly as it
+is from the application. The limits travel with it - `wb.provenance()` is the
+line to print above any number a script emits - see
+[what it does not do](https://meshbench.github.io/docs/what-it-does-not-do.html).

package/lib/boundary.mjs

@@ -0,0 +1,123 @@
+// The study area: which nodes are in the question being asked.
+//
+// Not the firmware's region concept. A boundary decides what is studied; a
+// region decides what is forwarded. Both words are in this application, and
+// confusing them is how somebody concludes the RF model is broken.
+//
+// Set it before importing. The import filters at fetch time, so a boundary set
+// afterwards prunes what has already been paid for rather than never fetching
+// it.
+
+import fs from "node:fs";
+
+import { MeshbenchError, NotFound } from "./errors.mjs";
+
+/** The study area, however you have it. Live. */
+export class Boundary {
+  constructor(wb) { this._wb = wb; }
+
+  /** Take a study area from a place name or from GeoJSON.
+   *
+   *  The one to call. A path to a .geojson file is loaded; anything else is
+   *  searched for by name and the best match accepted. Both end with the area in
+   *  the study, which is the only thing the caller wanted to say.
+   *
+   *  `name` renames a single loaded polygon, so a file called `export(3).geojson`
+   *  can still join the study as "Tay catchment". */
+  async use(area, { name = "" } = {}) {
+    if (isGeoJSONPath(area)) return this.load(area, { name });
+    const found = await this.search(String(area));
+    return [await this.accept(found[0])];
+  }
+
+  /** Places matching a name, best first. Needs the network.
+   *
+   *  Names rather than geometry: the geometry stays at the workbench, and the
+   *  name is what `accept` takes. */
+  async search(query) {
+    const got = (await this._wb.call("boundary.set", { query })) || {};
+    const found = got.names || [];
+    if (found.length === 0) {
+      throw new NotFound("boundary.set", `nothing is called "${query}"`, "not_found");
+    }
+    return found;
+  }
+
+  /** Take one of the search results into the study area.
+   *
+   *  Areas union rather than replace: a study is often two council areas rather
+   *  than one. */
+  async accept(name) {
+    const got = (await this._wb.call("boundary.accept", { name })) || {};
+    return got.accepted || name;
+  }
+
+  /** Take a study area from GeoJSON: a path, the document itself, or an object.
+   *
+   *  A Polygon, a MultiPolygon, a Feature or a FeatureCollection. Each polygon
+   *  becomes an area named from its "name" property, or from `name`, or from the
+   *  file.
+   *
+   *  The one way to study an area nothing has an administrative name for - a
+   *  catchment, a valley, the bit north of the river - and the only one that
+   *  works with no network at all. */
+  async load(source, { name = "" } = {}) {
+    const params = {};
+    if (source && typeof source === "object") {
+      params.geojson = JSON.stringify(source);
+    } else if (isGeoJSONPath(source)) {
+      params.path = String(source);
+    } else if (isJSONDocument(source)) {
+      params.geojson = String(source);
+    } else {
+      // Said here rather than at the workbench, which would report it as a parse
+      // failure on a document that is really a mistyped path.
+      throw new MeshbenchError(
+        `"${source}" is neither a .geojson path that exists nor a GeoJSON document`);
+    }
+    if (name) params.name = name;
+    return ((await this._wb.call("boundary.load", params)) || {}).loaded || [];
+  }
+
+  /** What the study area is made of - the names, not a count of them. */
+  async list() {
+    return ((await this._wb.call("boundary.list")) || {}).names || [];
+  }
+
+  /** Take one area back out.
+   *
+   *  Changes what is measured, never what is loaded: the nodes stay until
+   *  something prunes them. */
+  async remove(name) { await this._wb.call("boundary.remove", { name }); }
+
+  /** Delete the nodes outside the study area, and say how many went.
+   *
+   *  For a mesh that was imported before the boundary was set. The margin is
+   *  kept on purpose and zero means the session's own: a node just outside still
+   *  interferes with one just inside, and dropping it makes the inside look
+   *  quieter than it is. */
+  async prune({ marginKm = 0 } = {}) {
+    const params = marginKm > 0 ? { margin_km: marginKm } : {};
+    return ((await this._wb.call("boundary.prune", params)) || {}).removed || 0;
+  }
+}
+
+function isJSONDocument(s) {
+  return typeof s === "string" && s.trimStart().startsWith("{");
+}
+
+/** A path, rather than a place name or a GeoJSON document.
+ *
+ *  Judged by extension as well as by existence, so a mistyped path is reported
+ *  as a missing file rather than searched for as a place - which answers
+ *  "nothing is called ./bounds/fife.geojson" and sends the reader looking in
+ *  entirely the wrong direction. */
+function isGeoJSONPath(s) {
+  if (typeof s !== "string" || isJSONDocument(s)) return false;
+  if (s.endsWith(".geojson") || s.endsWith(".json")) return true;
+  try {
+    return fs.statSync(s).isFile();
+  } catch {
+    return false;
+  }
+}

package/lib/checks.mjs

@@ -0,0 +1,178 @@
+// What a run is told to send, and what has to be true of it afterwards.
+//
+// These were reachable only through call("schedule.add", {at_ms: 5000,
+// every_ms: 20000}), which is the shape this package exists to remove: a verb
+// name spelled by hand, parameters in milliseconds because that is what the
+// wire happens to use, and nothing to tell a reader which clock they are in. An
+// example written that way is an advertisement for not using the library.
+
+import fs from "node:fs";
+
+/** What the mesh is told to send, and when. Live. */
+export class Schedule {
+  constructor(wb) { this._wb = wb; }
+
+  /** Have a node send something, once or repeatedly.
+   *
+   *  `atMs` and `everyMs` are simulated time - the mesh's own clock, not
+   *  yours - which is why neither is called a timeout.
+   *
+   *  Repeating traffic has worked all along and nothing said so, which to
+   *  somebody writing a script is the same as it not existing. */
+  async add({ node, command, atMs = 0, everyMs = 0 }) {
+    const params = { node: String(node), command };
+    if (atMs > 0) params.at_ms = atMs;
+    if (everyMs > 0) params.every_ms = everyMs;
+    return ((await this._wb.call("schedule.add", params)) || {}).sends || 0;
+  }
+
+  /** Forget all of them. */
+  async clear() {
+    return ((await this._wb.call("schedule.clear")) || {}).cleared || 0;
+  }
+
+  /** How many are scheduled. */
+  async count() {
+    return (await this._wb.snapshot()).scheduled_sends || 0;
+  }
+}
+
+/** One assertion, and what the run made of it. */
+export class Check {
+  constructor(raw = {}) {
+    this.kind = raw.kind || "";
+    this.node = raw.node || "";
+    this.passed = Boolean(raw.pass);
+    this.got = raw.got || "";
+    this.want = raw.want || "";
+  }
+
+  toString() {
+    const mark = this.passed ? "pass" : "FAIL";
+    const where = this.node ? ` at ${this.node}` : "";
+    return `${mark}  ${this.kind}${where}: got ${this.got}, want ${this.want}`;
+  }
+}
+
+/** What a run passed and failed, with what it was measured under. */
+export class Report {
+  constructor(raw = {}, provenance = null) {
+    this.passed = raw.passed || 0;
+    this.total = raw.total || 0;
+    this.checks = (raw.results || []).map((r) => new Check(r));
+    /** What the numbers were measured under, carried with the verdict because a
+     *  delivery figure without it is the number this project exists not to
+     *  publish. */
+    this.provenance = provenance;
+  }
+
+  /** Whether every assertion held.
+   *
+   *  A report with no assertions is not ok. A fixture that carries none can
+   *  report but cannot pass, and a green tick that checked nothing is the worst
+   *  outcome available here. */
+  get ok() { return this.total > 0 && this.passed === this.total; }
+
+  get failures() { return this.checks.filter((c) => !c.passed); }
+
+  toString() {
+    const lines = [];
+    if (this.provenance) lines.push(String(this.provenance));
+    lines.push(this.total === 0
+      ? "no assertions, so this run checked nothing"
+      : `${this.passed} of ${this.total} assertions passed`);
+    for (const c of this.failures) lines.push(`  ${c}`);
+    return lines.join("\n");
+  }
+
+  /** Write a JUnit file, with the caveats inside it.
+   *
+   *  In the file rather than only on stdout, because the file is what a CI
+   *  system keeps and shows six months later - and a delivery figure with no
+   *  note of what the model assumed is exactly the number this project exists
+   *  not to publish. */
+  writeJUnit(path, suite = "meshbench") {
+    const lines = ['<?xml version="1.0" encoding="utf-8"?>',
+      `<testsuite name="${xml(suite)}" tests="${this.total}" ` +
+      `failures="${this.failures.length}">`];
+    if (this.provenance) {
+      lines.push("  <properties>",
+        `    <property name="meshbench.provenance" value="${xml(this.provenance)}"></property>`,
+        "  </properties>");
+    }
+    for (const c of this.checks) {
+      const name = c.kind + (c.node ? ` at ${c.node}` : "");
+      const open = `  <testcase classname="${xml(suite)}.assertions" name="${xml(name)}"`;
+      if (c.passed) {
+        lines.push(open + "></testcase>");
+        continue;
+      }
+      lines.push(open + ">",
+        `    <failure message="got ${xml(c.got)}, want ${xml(c.want)}"></failure>`,
+        "  </testcase>");
+    }
+    lines.push("</testsuite>", "");
+    fs.writeFileSync(path, lines.join("\n"));
+  }
+}
+
+/** Escape text for an XML attribute or body.
+ *
+ *  Written out rather than pulled in: a dependency for five replacements would
+ *  cost this package the one thing it promises, which is that `npm install`
+ *  fetches nothing but itself. */
+function xml(s) {
+  return String(s)
+    .replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+
+/** What has to be true for a run to have passed. Live. */
+export class Assertions {
+  constructor(wb) { this._wb = wb; }
+
+  /** At least this many nodes received something. */
+  async delivered(atLeast, { withinMs = 0 } = {}) {
+    return this.add({ kind: "delivered", atLeast, withinMs });
+  }
+
+  /** This node - or the whole mesh - transmitted within these bounds.
+   *
+   *  `atMost` is the interesting one: it is how a relay-suppression change is
+   *  held to not having made the mesh chattier. */
+  async sent({ node = "", atLeast = 0, atMost = 0, withinMs = 0 } = {}) {
+    return this.add({ kind: "sent", node, atLeast, atMost, withinMs });
+  }
+
+  /** The general form, for a kind this package has no name for yet.
+   *
+   *  `withinMs` is simulated time, like everything else the mesh is measured
+   *  over. A kind this build does not understand is a failure rather than a
+   *  pass, because a green run that checked nothing is the worst outcome
+   *  available here. */
+  async add({ kind, node = "", atLeast = 0, atMost = 0, maxPct = 0, withinMs = 0 }) {
+    const params = { kind };
+    if (node) params.node = String(node);
+    if (atLeast) params.at_least = atLeast;
+    if (atMost) params.at_most = atMost;
+    if (maxPct) params.max_pct = maxPct;
+    if (withinMs) params.within_ms = withinMs;
+    return ((await this._wb.call("assert.add", params)) || {}).assertions || 0;
+  }
+
+  /** Measure every assertion against the run so far.
+   *
+   *  The provenance travels with the verdict, because a delivery figure without
+   *  what the model assumed is the number this project exists not to publish. */
+  async check() {
+    const got = (await this._wb.call("assert.check")) || {};
+    return new Report(got, await this._wb.provenance());
+  }
+
+  /** How many are recorded. */
+  async count() { return (await this._wb.snapshot()).assertions || 0; }
+}
+
+/** The assertion kinds this build understands. */
+export const ASSERTION_KINDS = Object.freeze(
+  ["delivered", "deliveries", "unique_deliveries", "sent", "transmissions"]);

package/lib/device.mjs

@@ -0,0 +1,97 @@
+// A running board, as something a script can look at and prod.
+//
+// Read what the display is showing, capture it as an image, press the buttons,
+// type at the keyboard, touch the panel. All of it works headless - the display
+// is the framebuffer the controller holds, not a picture of anybody's desktop -
+// which is the point: a board test that needs a screen in front of it does not
+// run in CI.
+
+import { MeshbenchError } from "./errors.mjs";
+
+/** How long to wait for the screen to change before giving up, when a caller
+ *  names no timeout of its own. */
+export const SCREEN_WAIT_MS = 30_000;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** One running node's board, as a device to drive. A handle, not a copy. */
+export class Device {
+  constructor(wb, name) {
+    this._wb = wb;
+    this.name = name;
+  }
+
+  // ---- looking ---------------------------------------------------------
+
+  /** What the display is showing, as numbers rather than a picture.
+   *
+   *  Enough to answer "did anything change" after a press or a touch, which is
+   *  what every check of an input comes down to; for the picture itself, ask for
+   *  a screenshot. `digest` identifies the frame - two screens with the same one
+   *  are the same picture, which `lit` cannot promise. */
+  async screen() {
+    return (await this._wb.call("board.screen", { node: this.name })) || {};
+  }
+
+  /** Write the display to a PNG and say where it landed. The frame is exactly
+   *  what the controller holds, at the size it holds it. */
+  async screenshot() {
+    return (await this._wb.call("board.screenshot", { node: this.name })) || {};
+  }
+
+  // ---- prodding --------------------------------------------------------
+
+  /** Hold a button pin down, or release it.
+   *
+   *  Held rather than clicked because the firmware cares: MeshCore wakes a
+   *  sleeping display on a press and powers the board off on a long one, so a
+   *  caller times the release itself - or uses `tap`, which does not hold. */
+  async press(pin, down = true) {
+    await this._wb.call("board.press", { node: this.name, pin, down });
+  }
+
+  /** Press a button and let go - the ordinary click. */
+  async tap(pin) {
+    await this.press(pin, true);
+    await this.press(pin, false);
+  }
+
+  /** Enter text at the board's own keyboard, one character at a time - which is
+   *  what the keyboard sends, and what the firmware polls for. */
+  async type(text) {
+    await this._wb.call("board.key", { node: this.name, text });
+  }
+
+  /** Put a finger on the panel at a point, or lift it off. */
+  async touch(x, y, down = true) {
+    await this._wb.call("board.touch", { node: this.name, x, y, down });
+  }
+
+  /** Touch a point and lift off - a tap on the panel. */
+  async tapAt(x, y) {
+    await this.touch(x, y, true);
+    await this.touch(x, y, false);
+  }
+
+  // ---- waiting ---------------------------------------------------------
+
+  /** Wait until the display changes from what it shows now and return the new
+   *  frame, or fail with what it was still showing when the time ran out.
+   *
+   *  This is the honest way to check an input. Half duplex eats stimuli - a
+   *  board handed a packet while transmitting never hears it - so a tap followed
+   *  by an immediate screen read will intermittently read the frame from before
+   *  the tap landed. Change is by digest, so a redraw that keeps the same number
+   *  of lit pixels still counts. */
+  async waitScreen(timeoutMs = SCREEN_WAIT_MS) {
+    const before = await this.screen();
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      await sleep(50);
+      const now = await this.screen();
+      if (now.digest !== before.digest) return now;
+    }
+    throw new MeshbenchError(
+      `board ${this.name}: the screen did not change within ${timeoutMs} ms`);
+  }
+}