@meshbench/client 0.0.1

package/lib/socket.mjs

@@ -0,0 +1,311 @@
+// The wire: one JSON request per line, one reply.
+//
+// Everything above this is shape. This is the whole protocol, and it is small
+// on purpose - a client that needed a framework to speak to a local socket
+// would be a client nobody could debug.
+//
+// Two transports, because one does not travel:
+//
+// - A unix socket, where the operating system has one. The filesystem is the
+//   access control, and the kernel enforces it.
+// - Loopback TCP with a token, where it does not. The workbench binds 127.0.0.1
+//   on an ephemeral port and writes the address and a 128-bit token to a 0600
+//   file; this reads that file and presents the token before anything else.
+//
+// The choice is by operating system, not by language, so all three clients
+// speak the same thing on the same machine.
+
+import net from "node:net";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { PROTOCOL, RELEASE } from "./pairing.mjs";
+import { MeshbenchError, refusal } from "./errors.mjs";
+
+/** Chooses where the workbench answers: a path, or "tcp", or "tcp:host:port". */
+export const SOCKET_ENV = "MESHBENCH_CONTROL_SOCKET";
+
+/** What to run when a client is asked to start a workbench and nothing named a
+ *  binary. A checkout has one built but not installed, and every example and
+ *  every test then needs the same three lines to find it. */
+export const BINARY_ENV = "MESHBENCH_BINARY";
+
+/** Chooses the file a TCP listener writes its address and token to. Per user by
+ *  default, which is wrong for two runs at once - the second would overwrite
+ *  the first's - so a client that starts a workbench gives it one of its own. */
+export const RENDEZVOUS_ENV = "MESHBENCH_CONTROL_RENDEZVOUS";
+
+/** Chooses the directory the session files live in, for a test or a CI job that
+ *  wants a registry of its own rather than the user's. */
+export const SESSIONS_ENV = "MESHBENCH_CONTROL_SESSIONS";
+
+/** How long a call waits for a reply before it gives up, unless a caller says
+ *  otherwise. Matches 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. */
+export const DEFAULT_CALL_TIMEOUT_MS = 300000;
+
+/** The shortest sun_path any platform we run on allows: 108 on Linux, 104 on
+ *  macOS and the BSDs. Matches the Go and Python clients exactly. */
+export const MAX_UNIX_PATH = 104;
+
+/** The per-user cache directory this OS already defines - the same one the Go
+ *  and Python clients use, so all three read one rendezvous file. */
+export function cacheDir() {
+  let base;
+  if (process.platform === "win32") base = process.env.LOCALAPPDATA || os.homedir();
+  else if (process.platform === "darwin") base = path.join(os.homedir(), "Library", "Caches");
+  else base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
+  return path.join(base, "meshbench");
+}
+
+/** Where a workbench answers on this operating system unless told otherwise.
+ *  Matches the Go and Python clients exactly, because the choice is by OS, not
+ *  by language: all three must name the same address on one machine. */
+export function defaultAddress() {
+  const env = process.env[SOCKET_ENV];
+  if (env) return env;
+  if (process.platform === "win32") return "tcp"; // no AF_UNIX on Windows
+  const runtime = process.env.XDG_RUNTIME_DIR;
+  if (runtime) return path.join(runtime, "meshbench.sock");
+  return path.join(cacheDir(), "control.sock");
+}
+
+/** Where a TCP listener leaves its address and token. A named path wins over
+ *  the environment, so a client that started a workbench with a rendezvous of
+ *  its own reads that one rather than whatever else on this machine left one. */
+export function rendezvousPath(named) {
+  return named || process.env[RENDEZVOUS_ENV] || path.join(cacheDir(), "control.json");
+}
+
+/** The loopback address and token a workbench wrote for itself. */
+export function readRendezvous(named) {
+  const p = rendezvousPath(named);
+  let raw;
+  try {
+    raw = fs.readFileSync(p, "utf8");
+  } catch (e) {
+    throw new MeshbenchError(`no workbench has left an address at ${p}: ${e.message}`);
+  }
+  let got;
+  try {
+    got = JSON.parse(raw);
+  } catch (e) {
+    throw new MeshbenchError(`${p} is not readable as an address: ${e.message}`);
+  }
+  return { address: got.address || "", token: got.token || "" };
+}
+
+/** The socket an address names, and the token to present on it. Not connected:
+ *  the two decisions are separated so a caller can be refused for a path too
+ *  long for sun_path before anything is dialled, which the raw OS error names
+ *  neither the limit for nor what to do about. */
+function plan(address, token, rendezvous) {
+  if (address === "tcp" || address.startsWith("tcp:")) {
+    let hostPort;
+    if (address === "tcp") {
+      const got = readRendezvous(rendezvous);
+      hostPort = got.address;
+      token = token || got.token;
+    } else {
+      hostPort = address.slice("tcp:".length);
+      if (!hostPort.includes(":")) hostPort = "127.0.0.1:" + hostPort;
+      // A port somebody named still needs the token, and without one in hand
+      // the rendezvous file is the only place it exists.
+      if (!token) token = readRendezvous(rendezvous).token;
+    }
+    const i = hostPort.lastIndexOf(":");
+    return {
+      connect: { host: hostPort.slice(0, i) || "127.0.0.1", port: Number(hostPort.slice(i + 1)) },
+      token,
+    };
+  }
+  const p = address.startsWith("unix:") ? address.slice("unix:".length) : address;
+  if (p.length > MAX_UNIX_PATH) {
+    throw new MeshbenchError(
+      `${p} is ${p.length} bytes and a unix socket path may be at most ` +
+      `${MAX_UNIX_PATH} - choose a shorter one, or use tcp`);
+  }
+  return { connect: { path: p }, token: "" };
+}
+
+/** One connection to a workbench, and the queue that keeps two callers from
+ *  interleaving a half-frame on the wire.
+ *
+ *  The protocol has request ids but the workbench answers in order, so the
+ *  simplest correct thing is one call at a time. Replies are still matched by
+ *  id, because a client that trusted the order would be wrong the day the
+ *  server stopped keeping it. */
+export class Connection {
+  constructor(sock, address, callTimeoutMs) {
+    this._sock = sock;
+    /** The address this connection was asked for, as the caller wrote it or as
+     *  `defaultAddress()` chose it, so a script driving more than one workbench
+     *  can say which of them refused. It is not re-read from the socket: with
+     *  `tcp` it stays the word `tcp`, not the loopback port behind it. */
+    this.address = address;
+    /** Called with every frame that carries no id, which is how the socket says
+     *  "this is not a reply". Set by a subscription; a request/reply client
+     *  leaves it null and the frames are dropped. */
+    this.onNotification = null;
+    this._callTimeoutMs = callTimeoutMs;
+    this._nextId = 0;
+    this._buf = "";
+    this._waiters = [];
+    this._closed = null;
+    sock.setEncoding("utf8");
+    sock.on("data", (chunk) => this._onData(chunk));
+    sock.on("error", (e) => this._fail(new MeshbenchError(e.message)));
+    sock.on("close", () => this._fail(new MeshbenchError("connection closed")));
+  }
+
+  /** Open one, declaring nothing: the handshake is the Workbench's business,
+   *  because a session probe wants a socket and not a paired client. */
+  static open({ address, connectTimeoutMs = DEFAULT_CALL_TIMEOUT_MS,
+    callTimeoutMs = DEFAULT_CALL_TIMEOUT_MS, token = "", rendezvous = "" } = {}) {
+    const where = address || defaultAddress();
+    let made;
+    try {
+      made = plan(where, token, rendezvous);
+    } catch (e) {
+      return Promise.reject(e);
+    }
+    return new Promise((resolve, reject) => {
+      const sock = net.connect(made.connect);
+      const timer = setTimeout(() => {
+        sock.destroy();
+        reject(new MeshbenchError(
+          `timed out connecting to ${where} after ${connectTimeoutMs} ms`));
+      }, connectTimeoutMs);
+      sock.once("error", (e) => {
+        clearTimeout(timer);
+        reject(new MeshbenchError(`connecting to ${where}: ${e.message}`));
+      });
+      sock.once("connect", () => {
+        clearTimeout(timer);
+        sock.removeAllListeners("error");
+        // The token first, before anything else on the wire, where the OS has
+        // no unix socket to stand as the access control. Unix skips it, and
+        // declares the same two things on its first request instead.
+        if (made.token) {
+          sock.write(JSON.stringify(
+            { token: made.token, protocol: PROTOCOL, release: RELEASE }) + "\n");
+        }
+        resolve(new Connection(sock, where, callTimeoutMs));
+      });
+    });
+  }
+
+  /** Send one verb and resolve with its result, or reject with the refusal.
+   *
+   *  Pass `null` for `timeoutMs` to wait indefinitely, for a call known to take
+   *  a while; anything else uses the connection's own budget. */
+  call(verb, params, timeoutMs) {
+    if (this._closed) return Promise.reject(this._closed);
+    const id = ++this._nextId;
+    const req = { id, method: verb };
+    if (id === 1) {
+      // Declared on the frame this client was already sending, so a workbench
+      // that cannot serve this client refuses before any verb runs and without
+      // a round trip of its own. Only the first: neither answer can change
+      // while the connection is open.
+      req.protocol = PROTOCOL;
+      req.release = RELEASE;
+    }
+    if (params !== undefined && params !== null) req.params = params;
+    const budget = timeoutMs === undefined ? this._callTimeoutMs : timeoutMs;
+    return new Promise((resolve, reject) => {
+      const waiter = { id, verb, resolve, reject, timer: null };
+      if (budget) {
+        waiter.timer = setTimeout(() => {
+          const i = this._waiters.indexOf(waiter);
+          if (i >= 0) this._waiters.splice(i, 1);
+          reject(new MeshbenchError(`${verb} did not answer within ${budget} ms`));
+        }, budget);
+        // Never hold the process open only to time out a call nobody is
+        // waiting on any more.
+        if (typeof waiter.timer.unref === "function") waiter.timer.unref();
+      }
+      this._waiters.push(waiter);
+      this._sock.write(JSON.stringify(req) + "\n");
+    });
+  }
+
+  /** Hang up. Calls still in flight reject rather than wait on a socket nobody
+   *  will answer on, so a script that closes early fails where it closed
+   *  instead of hanging until its timeout. */
+  close() {
+    if (!this._closed) this._fail(new MeshbenchError("connection closed by caller"));
+    this._sock.end();
+    this._sock.destroy();
+  }
+
+  _onData(chunk) {
+    this._buf += chunk;
+    let nl;
+    while ((nl = this._buf.indexOf("\n")) >= 0) {
+      const line = this._buf.slice(0, nl);
+      this._buf = this._buf.slice(nl + 1);
+      if (line.trim() === "") continue;
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        continue; // a frame this client cannot parse is not a reply to fail on
+      }
+      this._deliver(msg);
+    }
+  }
+
+  _deliver(msg) {
+    // A frame that answers no request and carries an error is the connection
+    // itself being refused: the token line on loopback TCP is turned away that
+    // way, before any request exists to answer, so the refusal comes back with
+    // id 0. Dropping it turned a sentence naming both releases into "connection
+    // closed", which is the confusion the declaration exists to end. Failed
+    // rather than delivered to a waiter, because there is no connection left to
+    // make a second call on.
+    if (!msg.id && msg.error) {
+      this._fail(refusal("", msg.error, msg.code));
+      return;
+    }
+    if (msg.id === undefined || msg.id === null) {
+      if (this.onNotification) this.onNotification(msg);
+      return;
+    }
+    const i = this._waiters.findIndex((w) => w.id === msg.id);
+    if (i < 0) return;
+    const [w] = this._waiters.splice(i, 1);
+    if (w.timer) clearTimeout(w.timer);
+    if (msg.error) w.reject(refusal(w.verb, msg.error, msg.code));
+    else w.resolve(msg.result);
+  }
+
+  _fail(err) {
+    if (this._closed) return;
+    this._closed = err;
+    const waiters = this._waiters;
+    this._waiters = [];
+    for (const w of waiters) {
+      if (w.timer) clearTimeout(w.timer);
+      w.reject(err);
+    }
+    if (this.onNotification) this.onNotification(null);
+  }
+}
+
+/** Whether something is already answering there.
+ *
+ *  A connect rather than a stat: a socket file existing says nothing about
+ *  whether anybody is behind it, and that difference is the whole question. */
+export async function isLive(address, token = "", rendezvous = "") {
+  try {
+    const conn = await Connection.open(
+      { address, token, rendezvous, connectTimeoutMs: 250 });
+    conn.close();
+    return true;
+  } catch {
+    return false;
+  }
+}

package/lib/subscribe.mjs

@@ -0,0 +1,86 @@
+// Being told, rather than asking.
+//
+// The socket is request/reply, and stays that way: a script sends a verb and
+// reads its answer. A subscription is the other shape - the workbench writing a
+// line when something changes, unbidden - and it does not fit a call, so it is
+// given a connection of its own to stream on. A client that never subscribes
+// sees exactly the request/reply protocol it always did.
+//
+// Each notification is {"event": ..., "data": ...} with no id. The absent id is
+// the whole distinction: a reply carries the id it answered, a notification
+// never does, so the two can never be confused for one another on the wire.
+
+import { Connection } from "./socket.mjs";
+
+/** The verb that opens a subscription on a connection. */
+export const SUBSCRIBE = "session.subscribe";
+
+/** A live stream of notifications on a connection of its own.
+ *
+ *  Iterate it with `for await`: it waits until the next notification arrives and
+ *  ends when the workbench hangs up. Close it, so the extra connection does not
+ *  outlive the interest.
+ *
+ *  Each notification is `{topic, data, dropped}`, where `dropped` is how many
+ *  snapshot notifications the server coalesced away before this one - zero for
+ *  every other topic. */
+export class Subscription {
+  constructor(conn) {
+    this._conn = conn;
+    this._queue = [];
+    this._waiting = [];
+    this._done = false;
+    conn.onNotification = (msg) => this._push(msg);
+  }
+
+  /** Open one to the given topics - "status", "snapshot", and whatever else the
+   *  workbench publishes. */
+  static async open(address, topics = []) {
+    // No call timeout: a stream waits as long as it must between events, where
+    // a call would rather fail than hang.
+    const conn = await Connection.open({ address, callTimeoutMs: 0 });
+    const sub = new Subscription(conn);
+    try {
+      await conn.call(SUBSCRIBE, { topics }, 30_000);
+    } catch (e) {
+      conn.close();
+      throw e;
+    }
+    return sub;
+  }
+
+  _push(msg) {
+    const note = msg === null ? null : {
+      topic: msg.event || "", data: msg.data, dropped: msg.dropped || 0,
+    };
+    if (note === null) this._done = true;
+    const waiter = this._waiting.shift();
+    if (waiter) {
+      waiter(note);
+      return;
+    }
+    this._queue.push(note);
+  }
+
+  /** The next notification, or null once the workbench has hung up. */
+  next() {
+    if (this._queue.length) return Promise.resolve(this._queue.shift());
+    if (this._done) return Promise.resolve(null);
+    return new Promise((resolve) => this._waiting.push(resolve));
+  }
+
+  async *[Symbol.asyncIterator]() {
+    for (;;) {
+      const note = await this.next();
+      if (note === null) return;
+      yield note;
+    }
+  }
+
+  /** Hang up the stream. An iterator waiting on the next notification is
+   *  released rather than left waiting for one that is not coming. */
+  close() {
+    this._conn.close();
+    this._push(null);
+  }
+}

package/lib/values.mjs

@@ -0,0 +1,66 @@
+// The few values this client builds rather than passes through.
+//
+// Everything the socket answers with reaches a script as the object the
+// workbench sent, keys and all: a translation layer that renamed `height_m` to
+// `heightM` would be a second vocabulary to keep in step with the wire, and it
+// would go stale the week a verb grew a field. What is here instead is the
+// handful of values that carry behaviour a caller would otherwise write out -
+// the caveats that must travel with a number, and the two names a build has.
+
+/** What a measurement was measured under.
+ *
+ *  Carried with any result that is a number about the world, because a scripted
+ *  number gets pasted into a report with the caveats stripped. The caveats have
+ *  to be in the value. */
+export class Provenance {
+  constructor({ rf_mode = "", excess_loss_db = 0, calibrated = false, seed = 0 } = {}) {
+    /** "calculated" or "waveform". */
+    this.rfMode = rf_mode;
+    /** The calibration term in force, and whether it was fitted against real
+     *  receptions rather than left at the default. */
+    this.excessLossDb = excess_loss_db;
+    this.calibrated = calibrated;
+    this.seed = seed;
+  }
+
+  /** One line, meant to be printed above any number a script emits. */
+  toString() {
+    const fit = this.calibrated
+      ? "excess loss fitted to real receptions"
+      : "default excess loss";
+    return `MeshBench: ${this.rfMode} reception, ${fit} - a best case; ` +
+      "no multipath, no body loss, no oscillator error";
+  }
+}
+
+/** What a fetch found, before anything has been changed.
+ *
+ *  `skipped_no_position` and `uncertain` are the two worth reading before
+ *  committing. A node with no position cannot be simulated at all, and an
+ *  uncertain one is being placed to within kilometres - the answer it gives is
+ *  that vague too, however confident the rest of the output looks. */
+export class ImportPreview {
+  constructor(raw = {}) {
+    this.records = raw.records || 0;
+    this.nodes = raw.nodes || 0;
+    this.skippedNoPosition = raw.skipped_no_position || 0;
+    this.uncertain = raw.uncertain || 0;
+  }
+
+  toString() {
+    let out = `${this.records} records, ${this.nodes} usable`;
+    if (this.skippedNoPosition) out += `, ${this.skippedNoPosition} with no position`;
+    if (this.uncertain) out += `, ${this.uncertain} placed only roughly`;
+    return out;
+  }
+}
+
+/** How a build is named where a person will read it.
+ *
+ *  Version, board and role travel together because a board image is not a build
+ *  on its own: "wadamesh" means nothing until it is wadamesh for a LilyGo_TDeck,
+ *  built as a companion. A host build carries neither of the other two. */
+export function describeBuild(build) {
+  if (!build || !build.board) return (build && build.version) || "";
+  return `${build.board} - ${build.role} ${build.version}`;
+}

package/lib/wait.mjs

@@ -0,0 +1,68 @@
+// Waiting, in one place.
+//
+// Every wait in this package is a method, never a sleep in a script. That is
+// not tidiness: tools/soak hand-wrote the same poll loop three times in
+// seventy-two lines, each with its own interval and its own timeout, and its
+// own header records having sampled the wrong moment because of it.
+//
+// They poll. When the socket learns to push, this file changes and no caller
+// does - which is the whole reason the clients are built before the events.
+//
+// # Which clock
+//
+// Two clocks appear in this API and they are not the same one. Simulated is the
+// mesh's own: `sim.run`, `schedule.add`, `sim.waitUntil`. Wall is yours: every
+// `timeoutMs`. Both are milliseconds, so the name is what tells them apart, and
+// nothing that means the mesh's clock is called a timeout.
+
+import { Timeout } from "./errors.mjs";
+
+/** Firmware coming up on a whole mesh. Real firmware is minutes; emulated
+ *  boards are longer. */
+export const FIRMWARE_WAIT_MS = 10 * 60_000;
+
+/** A run of simulated time finishing, measured on your clock. */
+export const RUN_WAIT_MS = 30 * 60_000;
+
+/** A long job - a warm, a download, a build - finishing. */
+export const JOB_WAIT_MS = 30 * 60_000;
+
+/** One event arriving. */
+export const EVENT_WAIT_MS = 5 * 60_000;
+
+/** Where a wait's polling starts and the slowest it gets.
+ *
+ *  It backs off between the two. Something about to happen is noticed promptly;
+ *  something that takes ten minutes is not asked four thousand times on the
+ *  way. nodes.stats in particular costs a /proc read per node, so polling it at
+ *  ten hertz on a 155-node mesh is fifteen hundred reads a second - during
+ *  firmware startup, which is the busiest moment there is. */
+export const POLL_FIRST_MS = 50;
+export const POLL_SLOWEST_MS = 1000;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Poll until `check` says yes, or the time runs out.
+ *
+ *  `check` resolves to `[done, saw]`: whether it is finished and, if not, what
+ *  it saw - which is what the Timeout reports. A rejection from `check` stops
+ *  the wait rather than being retried: a verb refusing because a node does not
+ *  exist will refuse the same way in ten seconds. */
+export async function waitFor(check, timeoutMs, what) {
+  const deadline = Date.now() + timeoutMs;
+  let interval = POLL_FIRST_MS;
+  let last = "";
+  for (;;) {
+    const [done, saw] = await check();
+    if (done) return;
+    if (saw) last = saw;
+    if (Date.now() > deadline) throw new Timeout(what, timeoutMs, last);
+    await sleep(interval);
+    interval = Math.min(interval * 1.5, POLL_SLOWEST_MS);
+  }
+}
+
+/** A simulated moment, said the way a person reads it. */
+export function secs(ms) {
+  return `${(ms / 1000).toFixed(1)}s`;
+}