signalk-siparu 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-siparu",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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/config.js

@@ -34,6 +34,23 @@ exports.INTERNAL = {
     samplePeriodMs: 2000,
     /** A path value older than this loses priority in fallback merges (TWS, depth). */
     staleMs: 30_000,
+    /**
+     * On the recording path only: a value whose source last spoke longer ago than
+     * this is written as null rather than standing in for a measurement nobody
+     * took. The live screen keeps showing it (last-known-wins) and ages it there.
+     *
+     * Deliberately not staleMs: 30s is the fallback-priority threshold, and at the
+     * default snapshotSeconds of 60 it would null a barometer that is merely
+     * unhurried. Two minutes is generous on purpose, because the server offers no
+     * guarantee to be precise against: subscribing with policy 'fixed' does not
+     * republish the last value every period - it buffers whatever actually arrives
+     * (bufferWithTime), so a silent source stays silent on the wire. What makes a
+     * healthy path keep reporting is the sensor itself resending its reading, which
+     * NMEA hardware does and a change-of-state source may not. So this is a
+     * deliberately loose assumption about instruments, not a tight read of a
+     * protocol: it is set to catch the sensor that died, and to let the slow one be.
+     */
+    fabricationHorizonMs: 120_000,
     /** Track segments implying speed above this are excluded from rollup distance. */
     rollupSpeedGuardKn: 80,
     /** No delta for this long -> /health reports degraded. */

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
@@ -102,8 +108,19 @@ module.exports = (app) => {
         if (!state || !store)
             return;
         const now = Date.now();
-        const snap = state.snapshot(now, true);
-        await store.append(snap);
+        // The horizon is what separates a record from a memory. Every field is gated on
+        // the age of its own source, so an instrument that went quiet leaves a gap here
+        // instead of a value wearing this row's timestamp: the live read below is free to
+        // keep showing the last one, but nothing measured it at `now`, and this row says
+        // it did. A voyage is built from these rows.
+        const snap = state.snapshot(now, true, config_1.INTERNAL.fabricationHorizonMs);
+        // 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, config_1.INTERNAL.fabricationHorizonMs);
+        const stored = Object.keys(numeric).length > 0 ? { ...snap, path_values: numeric } : snap;
+        await store.append(stored);
         if (voyages)
             await voyages.feed(snap);
         lastSnapshotTs = now;
@@ -148,12 +165,37 @@ module.exports = (app) => {
         if (!state)
             throw new Error('not started');
         const now = Date.now();
+        // No horizon here, deliberately: a screen showing the last known value is
+        // doing its job, and field_ages is how it says how old that value is. The
+        // recording path is the one that may not guess (writeSnapshot).
         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),
+            field_ages: state.coreFieldAges(now),
+            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 +243,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 +264,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 +284,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 +332,7 @@ module.exports = (app) => {
             unsubscribes = [];
             (0, rest_1.setRestDeps)(null);
             uplink?.stop();
+            liveUplink?.stop();
             if (voyages)
                 await voyages.flush();
             if (store)
@@ -280,6 +343,7 @@ module.exports = (app) => {
             query = null;
             voyages = null;
             uplink = null;
+            liveUplink = null;
             app.setPluginStatus('Stopped');
         },
         registerWithRouter(router) {
@@ -292,7 +356,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 +376,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))
+    };
+}