signalk-siparu 0.1.21 → 0.1.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-siparu",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "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,32 @@ 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;
+    };
+};
 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 +321,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;

package/plugin/dist/index.js

@@ -349,6 +349,11 @@ 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))
+                    }),
                     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, VoyageListResult } from './contract';
 /**
  * How often a frame goes up while the socket is open, when she is under way.
  *
@@ -99,6 +99,13 @@ 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>;
     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 +193,17 @@ 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;
+    /**
+     * Send a history, snapshots or voyages 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,13 @@ 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) or her recent
+            // voyages (handleVoyages). 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);
         });
         sock.onClose((code) => {
             if (gen !== this.gen)
@@ -353,9 +355,39 @@ 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' }
+            });
+        });
+    }
+    /**
+     * Send a history, snapshots or voyages 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 +525,17 @@ 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';
+}
 /**
  * The real socket.
  *