signalk-siparu 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-siparu",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Kept aboard, proven ashore. An impartial, timestamped record of every voyage: position, wind, depth and logbook, written on the boat and readable from anywhere. A read-only Signal K plugin with a built-in PWA.",
   "keywords": [
     "signalk-node-server-plugin",
@@ -37,10 +37,14 @@
     "build:all": "npm run build && npm run build:webapp",
     "ci:build": "npm --prefix webapp ci && npm run build:all"
   },
+  "dependencies": {
+    "ws": "^8.21.0"
+  },
   "devDependencies": {
     "@signalk/server-api": "^2.30.0",
     "@types/express": "^4.17.21",
     "@types/node": "^20.19.0",
+    "@types/ws": "^8.18.1",
     "typescript": "^5.9.0",
     "vitest": "^4.1.0"
   }

package/plugin/dist/index.js

@@ -39,10 +39,14 @@ var __importStar = (this && this.__importStar) || (function () {
  * PUT requests. It subscribes to self paths, records history to
  * NDJSON + materialized rollups, and serves a read-only REST API.
  *
- * Runtime dependencies: none. Types come from @signalk/server-api and
- * express as devDependencies - keep every import from them `import type`,
- * a value import would crash on the boat (AppStore installs with
- * --ignore-scripts and without devDependencies).
+ * One runtime dependency: ws, for the live uplink, and it is one on purpose. It carries no
+ * install script and no dependency of its own, and its two native helpers are optional peers -
+ * which is what lets the AppStore install this plugin with --ignore-scripts and have it work.
+ * Anything with a node-gyp step in it breaks on the boat rather than here; check before adding.
+ *
+ * Everything else - @signalk/server-api, express - is types only, and stays a devDependency:
+ * keep every import from them `import type`, because a value import would crash on a boat the
+ * AppStore installed without devDependencies.
  */
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -56,6 +60,7 @@ const rest_1 = require("./rest");
 const rollup_1 = require("./rollup");
 const store_1 = require("./store");
 const time_1 = require("./time");
+const live_1 = require("./live");
 const uplink_1 = require("./uplink");
 const voyagelog_1 = require("./voyagelog");
 const PLUGIN_ID = 'siparu';
@@ -76,6 +81,7 @@ module.exports = (app) => {
     let query = null;
     let voyages = null;
     let uplink = null;
+    let liveUplink = null;
     let timer = null;
     let unsubscribes = [];
     // Bumped on every start/stop; a stale async init aborts instead of leaking
@@ -103,7 +109,13 @@ module.exports = (app) => {
             return;
         const now = Date.now();
         const snap = state.snapshot(now, true);
-        await store.append(snap);
+        // Dynamic gauge history rides the same NDJSON row, but only on the store path:
+        // the voyage engine below reads the core snapshot and has no use for it, and the
+        // live frame builds its own `paths` separately. Added here, it reaches disk and
+        // the rollups without touching either.
+        const numeric = state.numericDynamicPaths(now);
+        const stored = Object.keys(numeric).length > 0 ? { ...snap, path_values: numeric } : snap;
+        await store.append(stored);
         if (voyages)
             await voyages.feed(snap);
         lastSnapshotTs = now;
@@ -151,9 +163,30 @@ module.exports = (app) => {
         const snap = state.snapshot(now, false);
         return {
             ...snap,
-            data_age_s: state.lastDeltaTs === null ? null : Math.round((now - state.lastDeltaTs) / 1000)
+            data_age_s: state.lastDeltaTs === null ? null : Math.round((now - state.lastDeltaTs) / 1000),
+            paths: state.dynamicPaths(now),
+            path_ages: state.dynamicPathAges(now)
         };
     }
+    /**
+     * The dynamic paths this boat exposes right now, read straight from the
+     * server's model (not just what has arrived as a delta), narrowed to the
+     * families the dashboard understands. Reported live and retained nowhere:
+     * ashore it exists only while the boat is connected.
+     */
+    function inventory() {
+        const available = app.streambundle.getAvailablePaths?.() ?? [];
+        const paths = [];
+        for (const p of available) {
+            if (!metrics_1.DYNAMIC_PREFIXES.some((pre) => p.startsWith(pre)))
+                continue;
+            const node = app.getSelfPath(p);
+            const rawUnits = node && typeof node === 'object' ? node.meta?.units : undefined;
+            paths.push({ path: p, units: typeof rawUnits === 'string' ? rawUnits : null });
+        }
+        paths.sort((a, b) => a.path.localeCompare(b.path));
+        return { paths };
+    }
     const plugin = {
         id: PLUGIN_ID,
         name: 'Siparu',
@@ -201,7 +234,9 @@ module.exports = (app) => {
                 app.subscriptionmanager.subscribe({
                     // Cast: server-api brands Context/Path as nominal string types.
                     context: 'vessels.self',
-                    subscribe: metrics_1.SUBSCRIBED_PATHS.map((p) => ({
+                    // Core paths by name, plus one wildcard per dynamic family so
+                    // engine/tank/generator paths flow in without naming each one.
+                    subscribe: [...metrics_1.SUBSCRIBED_PATHS, ...metrics_1.DYNAMIC_PREFIXES.map((p) => `${p}*`)].map((p) => ({
                         path: p,
                         period: config_1.INTERNAL.samplePeriodMs,
                         policy: 'fixed'
@@ -220,6 +255,7 @@ module.exports = (app) => {
                 }, opts.snapshotSeconds * 1000);
                 (0, rest_1.setRestDeps)({
                     live,
+                    inventory,
                     health,
                     snapshots: (q) => qs.snapshots(q, Date.now()),
                     voyages: async (limit) => vl.list(limit),
@@ -239,12 +275,29 @@ module.exports = (app) => {
                 //
                 // Started even when she is not paired - it sends nothing until she is, and it
                 // means pairing her mid-passage starts the feed without a restart.
-                const up = new uplink_1.Uplink({
+                // The socket, and the minute-by-minute POST behind it. Both are started, and only
+                // one of them speaks at a time: the POST path stands down while the socket is up
+                // and carries her the moment it is not. It is not a fallback that gets switched on
+                // when something notices a failure - it is already running when the failure happens.
+                const ws = new live_1.LiveUplink({
                     relayUrl: opts.relayUrl,
                     getRemote: () => opts.remote,
                     frame: () => live(),
+                    // The one thing the shore may ask of her: her own recorded history for a gauge,
+                    // read from the same store the local /snapshots serves. It reaches this query
+                    // service and nowhere near Signal K - a read, never a command.
+                    onHistoryQuery: (p, q) => qs.pathSeries(p, q, Date.now()),
                     debug: (msg) => app.debug(msg)
                 });
+                liveUplink = ws;
+                ws.start();
+                const up = new uplink_1.Uplink({
+                    relayUrl: opts.relayUrl,
+                    getRemote: () => opts.remote,
+                    frame: () => live(),
+                    debug: (msg) => app.debug(msg),
+                    liveHealthy: () => ws.healthy()
+                });
                 uplink = up;
                 up.start();
                 app.setPluginStatus('Recording - waiting for first snapshot');
@@ -270,6 +323,7 @@ module.exports = (app) => {
             unsubscribes = [];
             (0, rest_1.setRestDeps)(null);
             uplink?.stop();
+            liveUplink?.stop();
             if (voyages)
                 await voyages.flush();
             if (store)
@@ -280,6 +334,7 @@ module.exports = (app) => {
             query = null;
             voyages = null;
             uplink = null;
+            liveUplink = null;
             app.setPluginStatus('Stopped');
         },
         registerWithRouter(router) {
@@ -292,7 +347,7 @@ module.exports = (app) => {
                 app,
                 relayUrl: opts?.relayUrl ?? config_1.DEFAULTS.relayUrl,
                 boatName: () => opts?.boatName || String(app.getSelfPath('name') ?? ''),
-                uplinkStatus: () => uplink?.status() ?? null,
+                uplinkStatus: () => (0, uplink_1.reportedStatus)(liveUplink?.status(), uplink?.status() ?? null),
                 // The vessel's MMSI or UUID urn. Typed as a plain string, but the server only
                 // assigns it when the boat has one or the other, so at runtime it can be
                 // undefined - which is fine, because nothing is authorised by it: it is reported
@@ -312,6 +367,7 @@ module.exports = (app) => {
                     // by a fresh pairing must not leave "rejected" on the screen of a boat that is
                     // now streaming perfectly well.
                     uplink?.reset();
+                    liveUplink?.reset();
                 }
             });
         }

package/plugin/dist/live.js

@@ -0,0 +1,427 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveUplink = exports.PING_EVERY_MS = exports.FRAME_EVERY_MS = void 0;
+/**
+ * How often a frame goes up while the socket is open.
+ *
+ * The relay drops anything faster than one frame per 500ms, so this sits well clear of the
+ * floor. It is also what the shore's idea of "live" costs: at two seconds a boat at six knots
+ * has moved six metres between frames, which is under the width of the boat, and the Durable
+ * Object bills for the frames rather than for the season she is connected.
+ */
+exports.FRAME_EVERY_MS = 2_000;
+/**
+ * Starlink sits behind CGNAT, which drops an idle flow in around a minute. The relay answers
+ * this without waking the Durable Object at all, so it costs nothing to send and everything
+ * to leave out.
+ */
+exports.PING_EVERY_MS = 25_000;
+/** A boat with no uplink must not knock every five seconds for a fortnight. */
+const RECONNECT_BASE_MS = 5_000;
+const RECONNECT_CEILING_MS = 15 * 60_000;
+/**
+ * What she waits after being told something that redialling cannot fix: an unknown token, or a
+ * newer socket of hers taking over. Long, deliberately - see the close handler.
+ */
+const STAND_OFF_MS = 15 * 60_000;
+/** Not paired yet. She looks again, so that pairing her mid-passage needs no restart. */
+const UNPAIRED_RECHECK_MS = 60_000;
+/**
+ * The relay closes a socket with a reason, and the reason decides what she does next.
+ *
+ * 1012 is measured, not assumed: connect twice with one token against the live relay and the
+ * first socket is closed with exactly this. 1008 is the narrow case - the token was revoked
+ * while she was connected. A token that was already unknown when she dialled never reaches a
+ * close code at all: the relay refuses the handshake with a 401, which arrives as a refusal
+ * rather than a closure, and is handled there.
+ */
+const CLOSE_UNKNOWN_TOKEN = 1008;
+const CLOSE_REPLACED = 1012;
+/** HTTP, not WebSocket: this one comes back instead of an upgrade. */
+const REFUSED_UNKNOWN_TOKEN = 401;
+/**
+ * A handshake that never finishes. The TCP connection is up, so nothing errors and nothing
+ * closes - a captive portal or a CGNAT black hole simply never answers, and without this the
+ * dial hangs forever with no timer left running to rescue it.
+ */
+const HANDSHAKE_TIMEOUT_MS = 15_000;
+class LiveUplink {
+    deps;
+    sock = null;
+    connected = false;
+    stopped = true;
+    /**
+     * Which socket is the current one. Every handler carries the generation it was born in and
+     * does nothing if it is not the one in hand: a socket that has already been replaced still
+     * delivers its close event, and acting on it would schedule a redial on top of the
+     * connection she already has - one drop becoming two sockets.
+     */
+    gen = 0;
+    frameTimer = null;
+    pingTimer = null;
+    redialTimer = null;
+    /** A ping went out and nothing came back yet. Two of those in a row is a dead line. */
+    awaitingPong = false;
+    failures = 0;
+    lastFrameTs = null;
+    rejected = false;
+    lastError = null;
+    frameEveryMs;
+    pingEveryMs;
+    constructor(deps) {
+        this.deps = deps;
+        this.frameEveryMs = deps.frameEveryMs ?? exports.FRAME_EVERY_MS;
+        this.pingEveryMs = deps.pingEveryMs ?? exports.PING_EVERY_MS;
+    }
+    start() {
+        if (!this.stopped)
+            return;
+        this.stopped = false;
+        this.dial();
+    }
+    stop() {
+        this.stopped = true;
+        this.gen++; // whatever is in flight is no longer hers
+        this.clearTimers();
+        this.connected = false;
+        const sock = this.sock;
+        this.sock = null;
+        try {
+            sock?.close(1000, 'plugin stopping');
+        }
+        catch {
+            // Already gone. Signal K restarts a plugin on every config save, so this is routine.
+        }
+    }
+    /**
+     * Whether the shore is genuinely being fed from here. The HTTP uplink stands down while this
+     * is true and takes over the moment it is false, so it must never be optimistic: a live
+     * uplink that lies about its health takes the fallback down with it and the boat goes silent
+     * altogether.
+     */
+    healthy() {
+        return !this.stopped && this.connected;
+    }
+    status() {
+        return {
+            connected: this.connected,
+            lastFrameTs: this.lastFrameTs,
+            failures: this.failures,
+            rejected: this.rejected,
+            lastError: this.lastError
+        };
+    }
+    /**
+     * A new pairing starts a new life: the previous link's failures are not hers.
+     *
+     * And it dials again at once. Pairing her again is the cure the screen prescribes for a
+     * rejected token - so the cure must not sit out the punishment. The stand-off left by the
+     * old link is a quarter of an hour long, and without this the owner would fix the problem,
+     * watch the boat stay dark for fifteen minutes, and conclude that it did not work.
+     */
+    reset() {
+        this.failures = 0;
+        this.rejected = false;
+        this.lastError = null;
+        this.lastFrameTs = null;
+        if (this.stopped)
+            return;
+        const old = this.sock;
+        this.gen++;
+        this.clearTimers();
+        this.connected = false;
+        this.sock = null;
+        if (old)
+            this.kill(old);
+        this.dial();
+    }
+    dial() {
+        if (this.stopped)
+            return;
+        const remote = this.deps.getRemote();
+        if (!remote) {
+            // Nothing to send and nobody to send it to. She looks again rather than giving up, so
+            // that pairing her at sea starts the feed without a restart.
+            this.redialTimer = setTimeout(() => this.dial(), UNPAIRED_RECHECK_MS);
+            return;
+        }
+        const gen = ++this.gen;
+        const url = `${this.deps.relayUrl.replace(/^http/, 'ws')}/live/boat`;
+        const connect = this.deps.connect ?? wsConnect;
+        let sock;
+        try {
+            sock = connect(url, remote.boatToken);
+        }
+        catch (e) {
+            this.failed(gen, `Cannot reach Siparu. Is the boat online?`, e);
+            return;
+        }
+        this.sock = sock;
+        sock.onOpen(() => {
+            if (gen !== this.gen)
+                return;
+            this.connected = true;
+            this.failures = 0;
+            this.rejected = false;
+            this.lastError = null;
+            this.awaitingPong = false;
+            // At once, not in two seconds: the shore's whole reason for wanting this socket is to
+            // know she is there, and making it wait would be theatre.
+            this.sendFrame(gen);
+            this.frameTimer = setInterval(() => this.sendFrame(gen), this.frameEveryMs);
+            this.pingTimer = setInterval(() => this.keepalive(gen), this.pingEveryMs);
+        });
+        sock.onMessage((data) => {
+            if (gen !== this.gen)
+                return;
+            if (data === 'pong') {
+                this.awaitingPong = false;
+                return;
+            }
+            // The one thing beyond a pong that the shore may say: asking the boat to send back her
+            // own recorded history. It is not a command - see handleHistory - and anything that is
+            // not one of these two is not acted on, because the shore may not steer a boat.
+            this.handleHistory(gen, data);
+        });
+        sock.onClose((code) => {
+            if (gen !== this.gen)
+                return;
+            this.closed(gen, code);
+        });
+        sock.onError((e) => {
+            if (gen !== this.gen)
+                return;
+            // An error is followed by a close on a real socket, but not always, and not on every
+            // implementation. Destroying it here makes the two paths one.
+            this.deps.debug(`live uplink error: ${String(e)}`);
+            this.kill(sock);
+            this.closed(gen, 1006);
+        });
+        // The relay looked at her token and would not even open the socket. This is the ordinary
+        // way an unknown token is refused - a boat whose owner unlinked her dials, and is turned
+        // away at the door rather than let in and shown out. Telling her "the boat is offline"
+        // here, which is what a bare connection error would have said, would send a skipper to
+        // check an aerial that is working perfectly.
+        sock.onRefused((status) => {
+            if (gen !== this.gen)
+                return;
+            this.kill(sock);
+            this.closed(gen, status === REFUSED_UNKNOWN_TOKEN ? CLOSE_UNKNOWN_TOKEN : 1006);
+        });
+    }
+    /** The only thing that reliably ends a socket that may already be broken. */
+    kill(sock) {
+        try {
+            sock.terminate();
+        }
+        catch {
+            // Already gone, which is the outcome we wanted.
+        }
+    }
+    sendFrame(gen) {
+        if (gen !== this.gen || !this.sock)
+            return;
+        try {
+            this.sock.send(JSON.stringify(this.deps.frame()));
+            this.lastFrameTs = Date.now();
+        }
+        catch (e) {
+            // The socket died under her. Treat it as the drop it is, rather than throwing inside a
+            // timer where nobody is listening.
+            this.deps.debug(`live uplink send failed: ${String(e)}`);
+            this.kill(this.sock);
+            this.closed(gen, 1006);
+        }
+    }
+    /**
+     * A history request from the shore, answered from the boat's own store.
+     *
+     * This is the whole of the inbound surface, and it is deliberately narrow: parse the
+     * message, and act only if it is a history request. A command, a PUT, a malformed line -
+     * anything else - is dropped in silence, because there is no other thing the shore is
+     * allowed to ask and answering would be a reply to make of a surface. The query goes to the
+     * store, never to Signal K, and the store read is already clamped (today-only for raw, a
+     * hard row cap for rollups), so a request cannot ask the boat for more than she will give.
+     */
+    handleHistory(gen, data) {
+        const handler = this.deps.onHistoryQuery;
+        if (!handler)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(data);
+        }
+        catch {
+            return;
+        }
+        if (!isHistoryRequest(msg))
+            return;
+        const { id, path, query } = msg;
+        handler(path, query).then((result) => this.replyHistory(gen, { type: 'history', id, result }), (err) => {
+            // The caught text stays here, in the debug log - it can hold a data-dir path, and the
+            // reply crosses the wire to the shore. What the shore gets is that the query failed,
+            // which is all a screen waiting on a chart needs to stop waiting.
+            this.deps.debug(`history query failed: ${String(err)}`);
+            this.replyHistory(gen, {
+                type: 'history',
+                id,
+                error: { code: 'HISTORY_FAILED', message: 'history query failed' }
+            });
+        });
+    }
+    /**
+     * Send a history answer, but only if it still belongs to the socket that asked. A query
+     * reads the disk while the line may drop and redial underneath it; the generation guard is
+     * what keeps a slow answer from landing on a fresh connection that never made the request.
+     */
+    replyHistory(gen, msg) {
+        if (gen !== this.gen || !this.sock)
+            return;
+        try {
+            this.sock.send(JSON.stringify(msg));
+        }
+        catch (e) {
+            // The socket died between the query starting and its answer arriving. The close handler
+            // has the redial; here there is nothing to do but not throw inside a promise callback.
+            this.deps.debug(`history reply send failed: ${String(e)}`);
+        }
+    }
+    keepalive(gen) {
+        if (gen !== this.gen || !this.sock)
+            return;
+        // A half-open connection looks exactly like a healthy one from this side: the sends
+        // succeed and nothing ever comes back. The only way to tell is to ask, and to notice that
+        // the last question was never answered.
+        if (this.awaitingPong) {
+            this.deps.debug('live uplink: no answer to the last keepalive - the line is dead');
+            // Destroyed, not closed. There is nobody left to complete a closing handshake with, and
+            // asking for one on a dead line is how the socket ends up held open forever.
+            this.kill(this.sock);
+            this.closed(gen, 1006);
+            return;
+        }
+        try {
+            this.awaitingPong = true;
+            this.sock.send('ping');
+        }
+        catch (e) {
+            this.kill(this.sock);
+            this.closed(gen, 1006);
+            this.deps.debug(`live uplink keepalive failed: ${String(e)}`);
+        }
+    }
+    closed(gen, code) {
+        if (gen !== this.gen)
+            return;
+        this.gen++; // this socket is finished; nothing it does from here counts
+        this.clearTimers();
+        this.connected = false;
+        this.sock = null;
+        if (this.stopped)
+            return;
+        if (code === CLOSE_UNKNOWN_TOKEN) {
+            // She does not unpair herself. See the file header: a relay that answers "unknown" by
+            // mistake would otherwise take the whole fleet off the air, permanently, and the cure
+            // would run on every boat rather than on our own server.
+            this.rejected = true;
+            this.lastError = 'Siparu no longer recognises this boat. Pair her again.';
+            this.deps.debug(`live uplink: ${this.lastError}`);
+            this.redial(STAND_OFF_MS);
+            return;
+        }
+        if (code === CLOSE_REPLACED) {
+            // A newer socket carrying this same token took over. Redialling would displace THAT
+            // one, which would redial and displace this one, and two instances of the plugin would
+            // flap against each other forever - waking the Durable Object on every round and
+            // billing for it. She stands well back. If the other one is the real boat, she is being
+            // reported already; if it dies, this one comes back on its own.
+            this.lastError = 'Another copy of this boat is connected to Siparu.';
+            this.deps.debug(`live uplink: ${this.lastError}`);
+            this.redial(STAND_OFF_MS);
+            return;
+        }
+        this.failures++;
+        this.lastError = 'Cannot reach Siparu. Is the boat online?';
+        this.redial(this.backoffMs());
+    }
+    failed(gen, message, e) {
+        if (gen !== this.gen)
+            return;
+        this.connected = false;
+        this.sock = null;
+        this.failures++;
+        this.lastError = message;
+        // Offline is the normal state of a boat, not an incident. Debug, never error: a week in an
+        // anchorage must not fill the Signal K log with red.
+        this.deps.debug(`live uplink unreachable: ${String(e)}`);
+        this.redial(this.backoffMs());
+    }
+    backoffMs() {
+        return Math.min(RECONNECT_BASE_MS * 2 ** Math.max(0, this.failures - 1), RECONNECT_CEILING_MS);
+    }
+    redial(delayMs) {
+        if (this.stopped)
+            return;
+        if (this.redialTimer)
+            clearTimeout(this.redialTimer);
+        this.redialTimer = setTimeout(() => this.dial(), delayMs);
+    }
+    clearTimers() {
+        if (this.frameTimer)
+            clearInterval(this.frameTimer);
+        if (this.pingTimer)
+            clearInterval(this.pingTimer);
+        if (this.redialTimer)
+            clearTimeout(this.redialTimer);
+        this.frameTimer = null;
+        this.pingTimer = null;
+        this.redialTimer = null;
+    }
+}
+exports.LiveUplink = LiveUplink;
+/**
+ * Whether a parsed shore message is a history request and nothing else. Strict on purpose:
+ * the type tag is the gate that keeps a command from being read as a request, so a message
+ * missing it, or carrying a non-string path, or no query object, is not one. The query's own
+ * contents (bucket, range) are the store's to validate - it rejects a bad bucket - so they
+ * are not re-checked here.
+ */
+function isHistoryRequest(m) {
+    if (typeof m !== 'object' || m === null)
+        return false;
+    const o = m;
+    return (o.type === 'history' &&
+        typeof o.id === 'string' &&
+        typeof o.path === 'string' &&
+        typeof o.query === 'object' &&
+        o.query !== null);
+}
+/**
+ * The real socket.
+ *
+ * `ws` is here rather than the platform's own WebSocket because the compatibility floor is Node
+ * 20, where the global one is behind a flag. It carries no install script and no runtime
+ * dependency of its own, and its two native helpers are optional peers - which is what lets the
+ * Signal K AppStore install this plugin with --ignore-scripts and have it work.
+ */
+function wsConnect(url, token) {
+    // Required lazily so that a test - and a boat that never pairs - never loads it at all.
+    const WS = require('ws');
+    const sock = new WS(url, {
+        headers: { authorization: `Bearer ${token}` },
+        // Opt-in, and without it a handshake that is never answered is never abandoned either.
+        handshakeTimeout: HANDSHAKE_TIMEOUT_MS
+    });
+    return {
+        send: (data) => sock.send(data),
+        close: (code, reason) => sock.close(code, reason),
+        terminate: () => sock.terminate(),
+        onOpen: (cb) => sock.on('open', cb),
+        onMessage: (cb) => sock.on('message', (d) => cb(String(d))),
+        onClose: (cb) => sock.on('close', (code) => cb(code)),
+        onError: (cb) => sock.on('error', cb),
+        // ws reports a refused upgrade here first, and only then as an error. Taking it here is
+        // what lets a 401 be read as "she is not paired any more" rather than "the boat is offline".
+        onRefused: (cb) => sock.on('unexpected-response', (_req, res) => cb(res.statusCode ?? 0))
+    };
+}

package/plugin/dist/metrics.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MetricsState = exports.SUBSCRIBED_PATHS = void 0;
+exports.MetricsState = exports.DYNAMIC_PREFIXES = exports.SUBSCRIBED_PATHS = void 0;
 const config_1 = require("./config");
 /** Paths mapped 1:1 onto a snapshot field. */
 const DIRECT_PATHS = {
@@ -35,6 +35,19 @@ exports.SUBSCRIBED_PATHS = [
     ...DEPTH_PATHS,
     ...Object.keys(DIRECT_PATHS)
 ];
+/**
+ * Dynamic path families beyond the fixed core: engine, tank and generator
+ * data a boat may expose. Subscribed by wildcard and carried on the live
+ * frame under their plain SK path name (contract LiveResult.paths). The core
+ * navigation/wind/depth paths keep their own hand-tuned handling; these ride
+ * the same source-resolution machinery but are never mixed into a Snapshot.
+ */
+exports.DYNAMIC_PREFIXES = ['propulsion.', 'tanks.', 'electrical.generators.'];
+/** Core paths get bespoke handling; anything else in state is a dynamic path. */
+const CORE_PATH_SET = new Set(exports.SUBSCRIBED_PATHS);
+function isDynamicPath(path) {
+    return !CORE_PATH_SET.has(path) && exports.DYNAMIC_PREFIXES.some((p) => path.startsWith(p));
+}
 const STRING_FIELDS = new Set(['nav_state', 'ais_class']);
 const TWS_SET = new Set(TWS_PATHS);
 class MetricsState {
@@ -61,13 +74,25 @@ class MetricsState {
         else {
             const field = DIRECT_PATHS[path];
             const isConceptPath = TWS_SET.has(path) || DEPTH_PATHS.includes(path);
-            if (!field && !isConceptPath)
+            const dynamic = !field && !isConceptPath && isDynamicPath(path);
+            if (!field && !isConceptPath && !dynamic)
                 return false;
             if (field && STRING_FIELDS.has(field)) {
                 if (typeof value !== 'string')
                     return false;
                 stored = value;
             }
+            else if (dynamic) {
+                // A dynamic gauge value is a number (rpm, temperature, level) or a
+                // short string (engine/generator state). Objects, booleans and the
+                // like are not gauge readings and are dropped.
+                if (typeof value === 'number' && Number.isFinite(value))
+                    stored = value;
+                else if (typeof value === 'string')
+                    stored = value;
+                else
+                    return false;
+            }
             else {
                 if (typeof value !== 'number' || !Number.isFinite(value))
                     return false;
@@ -204,6 +229,60 @@ class MetricsState {
             ais_class: this.str('sensors.ais.class', now)
         };
     }
+    /**
+     * Live values of the dynamic (non-core) paths, keyed by SK path name, each
+     * resolved through the same winning-source logic as the core fields. Only
+     * number/string values surface; a path with no fresh usable value is absent.
+     */
+    dynamicPaths(now) {
+        const out = {};
+        for (const path of this.paths.keys()) {
+            if (!isDynamicPath(path))
+                continue;
+            const r = this.resolveSource(path, now);
+            if (r && (typeof r.entry.value === 'number' || typeof r.entry.value === 'string')) {
+                out[path] = r.entry.value;
+            }
+        }
+        return out;
+    }
+    /**
+     * Age in seconds of each dynamic path's on-screen value: how long ago the
+     * winning source last spoke. The key set matches dynamicPaths exactly - a
+     * path with no usable value has no age. This is what lets the shore fade a
+     * single frozen gauge on its own: the boat-wide data_age_s stays near zero
+     * as long as any subscribed path (a live GPS) is still moving, so it cannot
+     * see one instrument going quiet while the boat sails on.
+     */
+    dynamicPathAges(now) {
+        const out = {};
+        for (const path of this.paths.keys()) {
+            if (!isDynamicPath(path))
+                continue;
+            const r = this.resolveSource(path, now);
+            if (r && (typeof r.entry.value === 'number' || typeof r.entry.value === 'string')) {
+                out[path] = Math.round((now - r.entry.ts) / 1000);
+            }
+        }
+        return out;
+    }
+    /**
+     * Numeric-only dynamic path values, for the history snapshot. String gauges
+     * (engine state) are dropped: history exists to be graphed and rolled up, and
+     * min/max/avg have no meaning for "started". Live display keeps strings
+     * (dynamicPaths); history does not.
+     */
+    numericDynamicPaths(now) {
+        const out = {};
+        for (const path of this.paths.keys()) {
+            if (!isDynamicPath(path))
+                continue;
+            const r = this.resolveSource(path, now);
+            if (r && typeof r.entry.value === 'number')
+                out[path] = r.entry.value;
+        }
+        return out;
+    }
     /** Per-path freshness + winning source, for /health micro-diagnosis. */
     pathAges(now) {
         const out = {};

package/plugin/dist/query.js

@@ -27,6 +27,41 @@ const ALL_FIELDS = [
 ];
 exports.LIMIT_DEFAULT = 200;
 exports.LIMIT_MAX = 5000;
+/**
+ * Core Snapshot fields a Bridge gauge can graph, keyed by the plain SK path the shore asks
+ * with. Wind and barometer live in the fixed Snapshot fields (and each rollup's `metrics`),
+ * not in the dynamic `path_values`/`path_metrics` maps - so pathSeries reads them from there
+ * instead. True wind is a concept (speedTrue with speedOverGround as fallback) already folded
+ * into `wind_speed_true`; speedTrue is its canonical name. Still read-only: this reads history
+ * the boat already recorded, exactly as the dynamic gauges do.
+ *
+ * These SK paths must stay in step with the portal's CORE_NUMERIC (format.ts), which scales
+ * exactly these paths for the axis. Add a third core gauge in both places or the shore asks for
+ * a series this never serves.
+ */
+const CORE_SERIES_FIELDS = {
+    'environment.wind.speedTrue': 'wind_speed_true',
+    'environment.outside.pressure': 'air_pressure_pa'
+};
+/** The aggregate for a series in one rollup: a core metric is in `metrics`, a dynamic gauge in `path_metrics`. */
+function aggFor(r, coreField, pathName) {
+    return coreField ? r.metrics[coreField] : r.path_metrics?.[pathName];
+}
+/**
+ * A rollup aggregate as a graph point, or nothing if this bucket did not carry the
+ * path (so flatMap drops it). A gauge added mid-history is simply absent from earlier
+ * buckets rather than a fabricated zero.
+ */
+function aggToPoint(ts, agg) {
+    if (!agg ||
+        typeof agg.min !== 'number' ||
+        typeof agg.max !== 'number' ||
+        typeof agg.avg !== 'number' ||
+        typeof agg.last !== 'number') {
+        return [];
+    }
+    return [{ ts, min: agg.min, max: agg.max, avg: agg.avg, last: agg.last }];
+}
 function rollupToRow(r) {
     const row = { ts: r.last_ts };
     for (const field of ALL_FIELDS) {
@@ -88,6 +123,59 @@ class QueryService {
             clamped = true;
         return { rows, clamped };
     }
+    /**
+     * One dynamic gauge's history, shaped for a graph. Same bucketing as snapshots():
+     * bucket=1 reads raw (today only, clamped), the rest read rollups. A raw sample
+     * becomes a point with min = max = avg = last; a rollup carries its real aggregate,
+     * so a chart can draw a band. A path a rollup does not carry simply yields no point.
+     */
+    async pathSeries(pathName, q, now) {
+        const limit = Math.min(Math.max(1, q.limit ?? exports.LIMIT_DEFAULT), exports.LIMIT_MAX);
+        const offset = Math.max(0, q.offset ?? 0);
+        const order = q.order ?? 'desc';
+        const to = q.to ?? now;
+        const coreField = CORE_SERIES_FIELDS[pathName];
+        let clamped = false;
+        let points;
+        if (q.bucket === 1) {
+            const todayStart = (0, time_1.startOfUtcDay)(now);
+            const from = Math.max(q.from ?? todayStart, todayStart);
+            if ((q.from ?? todayStart) < todayStart || to < todayStart)
+                clamped = true;
+            points = [];
+            for (const r of await this.readRawToday(now, from, to)) {
+                const v = coreField ? r[coreField] : r.path_values?.[pathName];
+                if (typeof v === 'number')
+                    points.push({ ts: r.ts, min: v, max: v, avg: v, last: v });
+            }
+        }
+        else if (q.bucket === 60) {
+            const from = q.from ?? 0;
+            points = (await this.rollups.readHourly(from, to)).flatMap((h) => aggToPoint(h.last_ts, aggFor(h, coreField, pathName)));
+        }
+        else if (q.bucket === 360) {
+            const from = q.from ?? 0;
+            const byWindow = new Map();
+            for (const h of await this.rollups.readHourly(from, to)) {
+                byWindow.set(Math.floor(h.last_ts / (6 * 3_600_000)), h); // hours ascending; latest wins
+            }
+            points = [...byWindow.values()].flatMap((h) => aggToPoint(h.last_ts, aggFor(h, coreField, pathName)));
+        }
+        else if (q.bucket === 1440) {
+            const from = q.from ?? 0;
+            points = (await this.rollups.readDaily(from, to)).flatMap((d) => aggToPoint(d.last_ts, aggFor(d, coreField, pathName)));
+        }
+        else {
+            throw new QueryError('BAD_BUCKET', 'bucket must be one of 1, 60, 360, 1440');
+        }
+        points = points.filter((p) => p.ts >= (q.bucket === 1 ? 0 : q.from ?? 0) && p.ts <= to);
+        points.sort((a, b) => (order === 'asc' ? a.ts - b.ts : b.ts - a.ts));
+        const total = points.length;
+        points = points.slice(offset, offset + limit);
+        if (offset + points.length < total)
+            clamped = true;
+        return { path: pathName, points, clamped };
+    }
     async readRawToday(now, fromTs, toTs) {
         const today = (0, time_1.dayKey)(now);
         const keys = (await this.store.listRawKeys()).filter((k) => k.startsWith(today));

package/plugin/dist/rest.js

@@ -76,6 +76,11 @@ function registerRoutes(router) {
             return sendError(res, 503, 'NOT_STARTED', 'plugin is not started');
         res.json(deps.live());
     });
+    router.get('/inventory', (_req, res) => {
+        if (!deps)
+            return sendError(res, 503, 'NOT_STARTED', 'plugin is not started');
+        res.json(deps.inventory());
+    });
     router.get('/snapshots', (req, res) => {
         if (!deps)
             return sendError(res, 503, 'NOT_STARTED', 'plugin is not started');

package/plugin/dist/rollup.js

@@ -134,6 +134,37 @@ function aggregateLinear(values) {
     }
     return { min, max, avg: sum / values.length, n: values.length, last: values[values.length - 1] ?? null };
 }
+/** Merge already-aggregated linear buckets (hour rollups) into one. */
+function mergeLinearAggs(aggs) {
+    let min = Infinity;
+    let max = -Infinity;
+    let sum = 0;
+    let n = 0;
+    let last = null;
+    for (const m of aggs) {
+        if (typeof m.min !== 'number' || typeof m.max !== 'number' || typeof m.avg !== 'number')
+            continue;
+        const mn = m.n ?? 1;
+        if (m.min < min)
+            min = m.min;
+        if (m.max > max)
+            max = m.max;
+        sum += m.avg * mn;
+        n += mn;
+        if (m.last !== null && m.last !== undefined)
+            last = m.last;
+    }
+    return n > 0 ? { min, max, avg: sum / n, n, last } : null;
+}
+/** Union of dynamic path names across a set of snapshots, in first-seen order. */
+function pathKeysOf(rows) {
+    const keys = new Set();
+    for (const r of rows)
+        if (r.path_values)
+            for (const k of Object.keys(r.path_values))
+                keys.add(k);
+    return [...keys];
+}
 function buildHourRollup(hour, rows) {
     const sorted = [...rows].sort((a, b) => a.ts - b.ts);
     const metrics = {};
@@ -143,6 +174,18 @@ function buildHourRollup(hour, rows) {
         if (agg)
             metrics[field] = agg;
     }
+    // Dynamic gauges: each SK path a boat exposed this hour, aggregated like a linear
+    // metric. Absent (not empty) when the boat carries none, so a nav-only boat's rollup
+    // line is unchanged.
+    const path_metrics = {};
+    for (const key of pathKeysOf(sorted)) {
+        const values = sorted
+            .map((r) => r.path_values?.[key])
+            .filter((v) => typeof v === 'number');
+        const agg = aggregateLinear(values);
+        if (agg)
+            path_metrics[key] = agg;
+    }
     for (const field of LAST_ONLY_FIELDS) {
         for (let i = sorted.length - 1; i >= 0; i--) {
             const v = sorted[i]?.[field];
@@ -163,7 +206,8 @@ function buildHourRollup(hour, rows) {
         distance_nm: trackDistanceNm(sorted),
         pos_first: first ? { lat: first.lat, lon: first.lon } : null,
         pos_last: last ? { lat: last.lat, lon: last.lon } : null,
-        metrics
+        metrics,
+        ...(Object.keys(path_metrics).length > 0 ? { path_metrics } : {})
     };
 }
 function buildDayRollup(date, hours) {
@@ -201,6 +245,19 @@ function buildDayRollup(date, hours) {
             }
         }
     }
+    // Dynamic gauges: merge each path's hourly aggregates into the day, weighting the
+    // average by sample count, same as the linear fields above.
+    const path_metrics = {};
+    const dayPathKeys = new Set();
+    for (const h of sorted)
+        if (h.path_metrics)
+            for (const k of Object.keys(h.path_metrics))
+                dayPathKeys.add(k);
+    for (const key of dayPathKeys) {
+        const agg = mergeLinearAggs(sorted.map((h) => h.path_metrics?.[key]).filter((m) => m !== undefined));
+        if (agg)
+            path_metrics[key] = agg;
+    }
     const firstPos = sorted.map((h) => h.pos_first).find((p) => p !== null) ?? null;
     const lastPos = [...sorted]
         .reverse()
@@ -230,7 +287,8 @@ function buildDayRollup(date, hours) {
         distance_nm: distance,
         pos_first: firstPos,
         pos_last: lastPos,
-        metrics
+        metrics,
+        ...(Object.keys(path_metrics).length > 0 ? { path_metrics } : {})
     };
 }
 class RollupEngine {

package/plugin/dist/uplink.js

@@ -1,6 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Uplink = void 0;
+exports.reportedStatus = reportedStatus;
+/**
+ * What the boat's own screen is told, out of the two uplinks she has.
+ *
+ * Whichever one is carrying her. While the socket is up the POST path never sends, so its
+ * "last sent" stays null and its failure count stays frozen at whatever it last was - and
+ * reporting that would tell an owner her boat has never sent a frame, or cannot reach the
+ * relay at all, while it is in fact streaming to her perfectly. The panel is there to answer
+ * "is she getting through", and there are two ways for her to be getting through.
+ *
+ * The socket has to be CONNECTED to speak for her, not merely present: everything else - a
+ * dial in progress, a stand-off, a dead line - means the POST path is the one being relied on,
+ * and so it is the one whose troubles are worth showing.
+ */
+function reportedStatus(socket, post) {
+    if (socket?.connected) {
+        return { lastSentTs: socket.lastFrameTs, failures: 0, rejected: false, lastError: null };
+    }
+    return post;
+}
 const DEFAULT_INTERVAL_MS = 60_000;
 /**
  * A boat on a marginal uplink (Starlink through a squall, a phone hotspot at the
@@ -77,6 +97,14 @@ class Uplink {
                 this.schedule(this.intervalMs);
             return;
         }
+        // The socket has it covered. Keep the timer running rather than stopping this uplink: the
+        // socket drops without warning and often, and the fallback has to be already ticking when
+        // it does - not started by whoever notices.
+        if (this.deps.liveHealthy?.()) {
+            if (!this.stopped)
+                this.schedule(this.intervalMs);
+            return;
+        }
         await this.send(remote);
         // stop() may have landed while the request was in the air. Rescheduling now would
         // resurrect a stopped uplink, so check before doing it - this is the guard the