signalk-siparu 0.1.21 → 0.1.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-siparu",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "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 dashboard.",
   "keywords": [
     "signalk-node-server-plugin",

package/plugin/dist/contract.d.ts

@@ -189,6 +189,59 @@ export type SnapshotsResponse = {
         message: string;
     };
 };
+/**
+ * The voyages RPC, a third sibling on the same live socket. Where history asks for one gauge's
+ * series and snapshots for whole rows over a window, this asks for the boat's recent voyages -
+ * the list the local /voyages REST serves. It carries no query, only how many of the newest to
+ * return; like its siblings it is a read of the boat's own store and reaches nothing near
+ * Signal K. The boat clamps the count, so a request cannot ask for more than she will give.
+ */
+export interface VoyagesRequest {
+    type: 'voyages';
+    id: string;
+    /** How many of the newest voyages to return. Clamped boat-side to the REST bounds. */
+    limit: number;
+}
+/** The boat's answer to one VoyagesRequest. The voyages or a reason, never both. */
+export type VoyagesResponse = {
+    type: 'voyages';
+    id: string;
+    result: VoyageListResult;
+} | {
+    type: 'voyages';
+    id: string;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+/**
+ * The track RPC, a fourth sibling on the same live socket. Where voyages asks for the list, this
+ * asks for one voyage's recorded path - the fixes the local /voyages/:id/track REST serves,
+ * drawn as a line on a chart ashore. It carries the voyage's id and nothing else; like its
+ * siblings it is a read of the boat's own store and reaches nothing near Signal K. The boat
+ * decimates a long track before she sends it, so a request cannot pull an unbounded stream over
+ * the wire (a day under way at 1 Hz is tens of thousands of fixes).
+ */
+export interface TrackRequest {
+    type: 'track';
+    id: string;
+    /** Which voyage to draw, by its Voyage.id. */
+    voyageId: number;
+}
+/** The boat's answer to one TrackRequest. The path or a reason, never both. */
+export type TrackResponse = {
+    type: 'track';
+    id: string;
+    result: TrackResult;
+} | {
+    type: 'track';
+    id: string;
+    error: {
+        code: string;
+        message: string;
+    };
+};
 export interface LiveResult extends Snapshot {
     /** Seconds since the newest delta touched any subscribed path; null before first delta. */
     data_age_s: number | null;
@@ -295,6 +348,10 @@ export interface Voyage {
     end_port: string | null;
     status: 'open' | 'closed';
 }
+/** The boat's answer to one VoyagesRequest: her recent voyages, newest first. */
+export interface VoyageListResult {
+    voyages: Voyage[];
+}
 /** One aggregation window on the voyage stats card. */
 export interface VoyageWindowStats {
     distance_nm: number;
@@ -315,6 +372,15 @@ export interface TrackPoint {
     /** Knots, rounded; null when unavailable. */
     sog: number | null;
 }
+/**
+ * The boat's answer to one TrackRequest: one voyage's path, oldest fix first.
+ * `decimated` is true when the boat thinned a long track before sending it, so a reader can say
+ * the line is a faithful shape but not every recorded fix.
+ */
+export interface TrackResult {
+    track: TrackPoint[];
+    decimated: boolean;
+}
 /** One nearby AIS vessel, sanitized and distance-filtered server-side. */
 export interface AisTarget {
     mmsi: string;

package/plugin/dist/index.js

@@ -62,6 +62,7 @@ const rollup_1 = require("./rollup");
 const store_1 = require("./store");
 const time_1 = require("./time");
 const live_1 = require("./live");
+const track_1 = require("./track");
 const uplink_1 = require("./uplink");
 const voyagelog_1 = require("./voyagelog");
 const PLUGIN_ID = 'siparu';
@@ -349,6 +350,15 @@ module.exports = (app) => {
                     // Her whole recorded rows over a window, the logbook read - the same store the local
                     // /snapshots serves, reached here and nowhere near Signal K.
                     onSnapshotsQuery: (q) => qs.snapshots(q, Date.now()),
+                    // Her recent voyages, the list the local /voyages serves. The count is clamped to the
+                    // same 1..500 bounds the REST route enforces, since vl.list does not clamp its own.
+                    onVoyagesQuery: async (limit) => ({
+                        voyages: vl.list(Math.min(Math.max(1, limit || 50), 500))
+                    }),
+                    // One voyage's path, the line the local /voyages/:id/track serves. Decimated before it
+                    // crosses the wire: vl.track returns every recorded fix (a long voyage is tens of
+                    // thousands), which the local REST may serve but a single timed socket reply may not.
+                    onTrackQuery: (voyageId) => vl.track(voyageId, Date.now()).then(track_1.decimateTrack),
                     debug: (msg) => app.debug(msg)
                 });
                 liveUplink = ws;

package/plugin/dist/live.d.ts

@@ -16,7 +16,7 @@
  * fleet, and every owner would have to walk down to their boat to fix a bug that was ours.
  */
 import type { RemoteLink } from './remotelink';
-import type { PathSeriesResult, SnapshotsQuery, SnapshotsResult } from './contract';
+import type { PathSeriesResult, SnapshotsQuery, SnapshotsResult, TrackResult, VoyageListResult } from './contract';
 /**
  * How often a frame goes up while the socket is open, when she is under way.
  *
@@ -99,6 +99,20 @@ export interface LiveDeps {
      * so an old relay or a boat wired without it simply never grows the ear.
      */
     onSnapshotsQuery?: (query: SnapshotsQuery) => Promise<SnapshotsResult>;
+    /**
+     * Answers a shore voyages request - her recent voyages, the list the local REST /voyages
+     * serves - from the same store. A third sibling of onHistoryQuery: a read, never a command,
+     * and it never reaches Signal K. Absent leaves the socket deaf to voyages requests, so an old
+     * relay or a boat wired without it simply never grows the ear.
+     */
+    onVoyagesQuery?: (limit: number) => Promise<VoyageListResult>;
+    /**
+     * Answers a shore track request - one voyage's recorded path, the line the local REST
+     * /voyages/:id/track serves - from the same store. A fourth sibling of onHistoryQuery: a read,
+     * never a command, and it never reaches Signal K. Absent leaves the socket deaf to track
+     * requests, so an old relay or a boat wired without it simply never grows the ear.
+     */
+    onTrackQuery?: (voyageId: number) => Promise<TrackResult>;
     debug: (msg: string) => void;
     /** Injected in tests. In production this is the `ws` adapter at the bottom of the file. */
     connect?: (url: string, token: string) => LiveSocket;
@@ -186,9 +200,24 @@ export declare class LiveUplink {
      */
     private handleSnapshots;
     /**
-     * Send a history or snapshots 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 asked.
+     * A voyages request from the shore, answered from the boat's own store - a third sibling of
+     * handleHistory, and just as narrow. Parse, act only if it is a voyages request, and read the
+     * store, never Signal K. The boat clamps the count before it reads, so a request cannot ask
+     * her for more than she will give.
+     */
+    private handleVoyages;
+    /**
+     * A track request from the shore, answered from the boat's own store - a fourth sibling of
+     * handleHistory, and just as narrow. Parse, act only if it is a track request, and read the
+     * store, never Signal K. The boat decimates a long path before it answers, so a request cannot
+     * pull an unbounded stream over the wire.
+     */
+    private handleTrack;
+    /**
+     * Send a history, snapshots, voyages or track 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 asked.
      */
     private reply;
     private keepalive;

package/plugin/dist/live.js

@@ -202,11 +202,14 @@ class LiveUplink {
                 return;
             }
             // Beyond a pong, the shore may ask the boat to send back her own recorded history: one
-            // gauge's series (handleHistory) or whole snapshot rows (handleSnapshots). Neither is a
-            // command; each drops in silence anything that is not its own request, and anything that
-            // is neither is not acted on at all, because the shore may not steer a boat.
+            // gauge's series (handleHistory), whole snapshot rows (handleSnapshots), her recent voyages
+            // (handleVoyages) or one voyage's path (handleTrack). None is a command; each drops in
+            // silence anything that is not its own request, and anything that is none is not acted on
+            // at all, because the shore may not steer a boat.
             this.handleHistory(gen, data);
             this.handleSnapshots(gen, data);
+            this.handleVoyages(gen, data);
+            this.handleTrack(gen, data);
         });
         sock.onClose((code) => {
             if (gen !== this.gen)
@@ -353,9 +356,68 @@ class LiveUplink {
         });
     }
     /**
-     * Send a history or snapshots 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 asked.
+     * A voyages request from the shore, answered from the boat's own store - a third sibling of
+     * handleHistory, and just as narrow. Parse, act only if it is a voyages request, and read the
+     * store, never Signal K. The boat clamps the count before it reads, so a request cannot ask
+     * her for more than she will give.
+     */
+    handleVoyages(gen, data) {
+        const handler = this.deps.onVoyagesQuery;
+        if (!handler)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(data);
+        }
+        catch {
+            return;
+        }
+        if (!isVoyagesRequest(msg))
+            return;
+        const { id, limit } = msg;
+        handler(limit).then((result) => this.reply(gen, { type: 'voyages', id, result }), (err) => {
+            this.deps.debug(`voyages query failed: ${String(err)}`);
+            this.reply(gen, {
+                type: 'voyages',
+                id,
+                error: { code: 'VOYAGES_FAILED', message: 'voyages query failed' }
+            });
+        });
+    }
+    /**
+     * A track request from the shore, answered from the boat's own store - a fourth sibling of
+     * handleHistory, and just as narrow. Parse, act only if it is a track request, and read the
+     * store, never Signal K. The boat decimates a long path before it answers, so a request cannot
+     * pull an unbounded stream over the wire.
+     */
+    handleTrack(gen, data) {
+        const handler = this.deps.onTrackQuery;
+        if (!handler)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(data);
+        }
+        catch {
+            return;
+        }
+        if (!isTrackRequest(msg))
+            return;
+        const { id, voyageId } = msg;
+        handler(voyageId).then((result) => this.reply(gen, { type: 'track', id, result }), (err) => {
+            this.deps.debug(`track query failed: ${String(err)}`);
+            this.reply(gen, {
+                type: 'track',
+                id,
+                error: { code: 'TRACK_FAILED', message: 'track query failed' }
+            });
+        });
+    }
+    /**
+     * Send a history, snapshots, voyages or track 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 asked.
      */
     reply(gen, msg) {
         if (gen !== this.gen || !this.sock)
@@ -493,6 +555,28 @@ function isSnapshotsRequest(m) {
         typeof o.query === 'object' &&
         o.query !== null);
 }
+/**
+ * A voyages request, told apart the same way: the type tag is the gate. It carries no query,
+ * only a count - so the tag, the id and a numeric limit are checked. The limit's bounds are the
+ * boat's to enforce (she clamps it before reading), so they are not re-checked here.
+ */
+function isVoyagesRequest(m) {
+    if (typeof m !== 'object' || m === null)
+        return false;
+    const o = m;
+    return o.type === 'voyages' && typeof o.id === 'string' && typeof o.limit === 'number';
+}
+/**
+ * A track request, told apart the same way: the type tag is the gate. It carries a voyage id, so
+ * the tag, the id and a numeric voyageId are checked. Whether that voyage exists is the store's
+ * to answer (an unknown id reads back an empty path), so it is not re-checked here.
+ */
+function isTrackRequest(m) {
+    if (typeof m !== 'object' || m === null)
+        return false;
+    const o = m;
+    return o.type === 'track' && typeof o.id === 'string' && typeof o.voyageId === 'number';
+}
 /**
  * The real socket.
  *

package/plugin/dist/track.d.ts

@@ -0,0 +1,16 @@
+import type { TrackPoint, TrackResult } from './contract';
+/**
+ * The most fixes a track carries over the wire.
+ *
+ * A day under way at roughly 1 Hz is tens of thousands of fixes; a line on a chart needs a small
+ * fraction of that, and the shore's request waits on a single reply with a fixed timeout. The
+ * local REST is left untouched - a browser aboard has no such limit and can ask for every fix -
+ * so this caps only what crosses the wire.
+ */
+export declare const MAX_TRACK_POINTS = 2000;
+/**
+ * Thin a track to at most `max` fixes at an even stride, always keeping the first and last so the
+ * line still starts and ends where the voyage did. Returns the track untouched when it already
+ * fits, with a flag saying whether anything was dropped - a faithful shape, not every fix.
+ */
+export declare function decimateTrack(points: TrackPoint[], max?: number): TrackResult;

package/plugin/dist/track.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TRACK_POINTS = void 0;
+exports.decimateTrack = decimateTrack;
+/**
+ * The most fixes a track carries over the wire.
+ *
+ * A day under way at roughly 1 Hz is tens of thousands of fixes; a line on a chart needs a small
+ * fraction of that, and the shore's request waits on a single reply with a fixed timeout. The
+ * local REST is left untouched - a browser aboard has no such limit and can ask for every fix -
+ * so this caps only what crosses the wire.
+ */
+exports.MAX_TRACK_POINTS = 2000;
+/**
+ * Thin a track to at most `max` fixes at an even stride, always keeping the first and last so the
+ * line still starts and ends where the voyage did. Returns the track untouched when it already
+ * fits, with a flag saying whether anything was dropped - a faithful shape, not every fix.
+ */
+function decimateTrack(points, max = exports.MAX_TRACK_POINTS) {
+    if (points.length <= max || max < 2)
+        return { track: points, decimated: false };
+    const stride = Math.ceil(points.length / max);
+    const out = [];
+    // length > max >= 2 here, so the first and last are always present.
+    for (let i = 0; i < points.length; i += stride)
+        out.push(points[i]);
+    const last = points[points.length - 1];
+    if (out[out.length - 1] !== last)
+        out.push(last);
+    return { track: out, decimated: true };
+}