@signalk/tracks-plugin 3.0.0-beta.1 → 3.0.0-beta.3

package/README.md

@@ -2,21 +2,17 @@
 
 Signal K server plugin that accumulates vessel positions into tracks and implements the track API.
 
-Positions are accumulated into a per-vessel sliding window using a configured time resolution. The
-**Where tracks come from after a restart** setting chooses what happens to them:
+Positions are recorded to a SQLite file in the plugin's data directory, at a configured time
+resolution, so tracks survive a restart with no other plugin required. The plugin is enabled on
+install and needs no configuration to start recording.
 
-| Setting   | Behaviour                                                                                                                                                  |
-| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `history` | _(default)_ Held in memory, and the own vessel's track is refilled on startup from a history provider such as `signalk-to-influxdb2` or `signalk-questdb`. |
-| `sqlite`  | Recorded to a database file in the plugin's data directory, so every vessel's track survives a restart with no other plugin required.                      |
-| `memory`  | Held in memory only; tracks start empty after a restart.                                                                                                   |
+| Setting                                        | Behaviour                                                                      |
+| ---------------------------------------------- | ------------------------------------------------------------------------------ |
+| Track resolution                               | Minimum spacing between recorded positions.                                    |
+| Days of the own vessel's track to keep         | Trims only the own vessel. 0 keeps everything; it is never dropped for idling. |
+| Days to keep another vessel after its last fix | Drops a vessel that has gone quiet. 0 keeps every vessel indefinitely.         |
 
-All three work with no other plugin installed — with `history` and no provider present, tracks simply
-build up from live data. `sqlite` also takes a retention setting, in days, for how long to keep
-positions.
-
-This replaces the earlier `bootstrapFromHistory` checkbox. Existing configurations keep working:
-the setting is still read, with `false` mapping to `memory` and anything else to `history`.
+The plugin's configuration page shows the current defaults, and is the authority on them.
 
 The package also exports a client side `TrackAccumulator` class that manages the track for a single
 vessel, exposing the result as `Observable<LatLngTuple[]>`.
@@ -28,9 +24,13 @@ With a history provider installed — [signalk-questdb](https://www.npmjs.com/pa
 both it and the plugin's own store: the provider is the finer record for as long as its retention
 reaches, and the store is what remains of everything older or of any period the provider missed.
 
-Nothing needs configuring for this, and the plugin works exactly as before with no provider
-installed. See [docs/history-and-storage.md](docs/history-and-storage.md) for what that means in
-practice.
+Nothing needs configuring for this, and the plugin works fully with no provider installed. Its own
+store is a SQLite file in the plugin's data directory, so tracks survive a restart on their own.
+See [docs/history-and-storage.md](docs/history-and-storage.md) for what that means in practice.
+
+The own vessel is kept indefinitely by default. Other vessels are kept for 30 days after their last
+fix — a harbour puts hundreds of AIS targets past a receiver in a day, and keeping every one of them
+forever is rarely what anybody wants. Both are settings.
 
 ## Glitch filtering
 
@@ -45,17 +45,18 @@ vessel, and glitches usually miss it by orders of magnitude rather than by a lit
 speed rather than distance, so a track resuming after a long gap — a passage with the plugin
 stopped, or an AIS target reappearing — is not filtered. Set it to 0 to record everything.
 
-The same check runs over positions loaded from a history provider at startup, since those carry
-the same glitches.
+Positions a history provider supplies are not filtered here — they are that provider's record, and
+it is the one that decides what to keep.
 
 ## Pausing while not under way
 
 A boat on a mooring for the winter emits a position every second and travels nowhere. Setting
 **Pause recording while navigation.state is one of** stops those months costing any rows.
 
-Off by default, and it needs `navigation.state` to be set — by
-[signalk-autostate](https://github.com/meri-imperiumi/signalk-autostate) or by hand. A vessel
-that reports no state is always recorded, so nothing changes for an install that has not opted in.
+On by default for `moored`, `not-under-way` and `aground`. It needs `navigation.state` to be set —
+by [signalk-autostate](https://github.com/meri-imperiumi/signalk-autostate) or by hand — and a
+vessel that reports no state is always recorded, so an install with no state source behaves as
+though this were off. Clear the list to record regardless of state.
 
 Two limits are deliberate. **`anchored` is offered but rarely wanted**: an anchor alarm watches
 exactly the track a vessel makes while swinging on its rode, so pausing there would break it.
@@ -132,7 +133,8 @@ so thinning never shortens the track._
   ],
   "times": [["2026-08-14T09:00:00.000Z", "2026-08-14T09:01:00.000Z"]],
   "context": "vessels.urn:mrn:imo:mmsi:123456789",
-  "isSelf": true
+  "isSelf": true,
+  "name": "Own Ship"
 }
 ```
 
@@ -145,16 +147,21 @@ _`context` is the fully qualified context the track belongs to, and `isSelf` say
 the own vessel. Asking for `self` resolves the alias, so the response tells you which vessel
 `self` actually is._
 
+_`name` is a display label, the way a chart plotter shows one: `Own Ship`, or `AIS <shipname>`
+falling back to `AIS <mmsi>` and finally the raw context. It is for putting in a list — the v2
+Track API's `contextName` carries the undecorated vessel name instead, and is absent for a
+vessel that has not sent one._
+
 ---
 
 **Retrieve tracks for all vessels:**
 
 `/signalk/v1/api/tracks`
 
-_If `maxRadius` is specified only vessels with last track position within this distance are returned._
+_Every vessel the plugin holds a track for. Add `?radius=` to narrow it to vessels near your own._
 
 _Each entry carries `isSelf`, so the own vessel can be told from an AIS target without
-string-matching the context against the server's self identity._
+string-matching the context against the server's self-identity, and `name` for display._
 
 _`?times` works here too, adding a `times` array to every vessel's entry. Note that asking for
 times also segments each track on the gap threshold, so `coordinates` and `times` line up;
@@ -166,7 +173,7 @@ without `times` each vessel keeps its single unsegmented line._
 
 `/signalk/v1/api/tracks?radius=50000`
 
-_Note: This value overrides the `maxRadius` value specified in plugin configuration._
+_Distance from the own vessel's current position, matched against each track's **last** position — "which vessels are near me now". The v2 Track API asks a different question and matches any position in the window._
 
 ---
 
@@ -203,10 +210,10 @@ npm run format     # prettier --write
 Signal K server against it and feeds positions as deltas — so it covers plugin loading, route
 mounting and the delta path, none of which the unit suite can. It needs a built server checkout;
 set `SIGNALK_SERVER_DIR` if yours is not at `~/dev/xxx_signalk-server`. A second tier installs a
-real history provider (signalk-questdb) into that server and exercises the startup bootstrap
-through it; it skips itself if no QuestDB is reachable at `QUESTDB_URL`. Neither tier runs in CI.
+real history provider (signalk-questdb) into that server and exercises the reconciliation through
+it; it skips itself if no QuestDB is reachable at `QUESTDB_URL`. Neither tier runs in CI.
 
 The package is ESM only and targets Node >= 22.5.0, the release that added `node:sqlite`. ESM alone
 would only need 20.19, the first release in which the Signal K server's `require()`-based plugin
-loader can load an ES module, but the sqlite track source raises the floor. The server itself
+loader can load an ES module, but recording to SQLite raises the floor. The server itself
 requires Node >= 22, so this rules out nothing that could have run the plugin anyway.

package/dist/e2e.test-utils.d.ts

@@ -30,11 +30,21 @@ export interface E2EOptions {
      * Other plugins to install and enable alongside this one, as
      * `{ 'npm-package-name': pluginConfiguration }`.
      *
-     * Used to stand up a real history provider so the bootstrap can be exercised
-     * through `getHistoryApi()` — the interface this plugin actually depends on —
-     * rather than against a provider's private storage.
+     * Used to stand up a real history provider so the reconciliation can be
+     * exercised through `getHistoryApi()` — the interface this plugin actually
+     * depends on — rather than against a provider's private storage.
      */
     plugins?: Record<string, Record<string, unknown>>;
+    /**
+     * Plugin id to pin as the server's default history provider.
+     *
+     * The server takes the *first* provider that registers as the default, so a
+     * second one installed in the server checkout — KIP registers as a history
+     * provider, and a dev checkout usually has it — silently wins and answers
+     * every unqualified history query with nothing. Naming the one the test
+     * installed makes the run independent of whatever else is lying around.
+     */
+    historyProvider?: string;
     /** Port to boot on, when a test needs its own server. */
     port?: number;
 }

package/dist/gpx.d.ts

@@ -0,0 +1,59 @@
+import { TimedPosition } from './types.js';
+/** Identity of the vessel a track belongs to, as far as it is known. */
+export interface GpxTrackIdentity {
+    /** Display label, e.g. `Own Ship` or `AIS Ariadne`. Becomes `<name>`. */
+    name: string;
+    /** Fully qualified Signal K context, when there is one. */
+    context?: string;
+}
+export interface GpxTrack extends GpxTrackIdentity {
+    /** Segments as `segment()` produces them: a recording gap starts a new one. */
+    segments: TimedPosition[][];
+}
+/**
+ * Serialise tracks as a GPX 1.1 document.
+ *
+ * Several tracks go in one file, each as its own `<trk>`. GPX allows it, and
+ * it is what makes "select three trips, export" produce one file rather than
+ * three — TimeZero writes one file per vessel, which is a choice rather than a
+ * constraint of the format.
+ *
+ * The Signal K context travels in `<extensions>`. TimeZero puts an opaque
+ * GUID there and drops the MMSI entirely, so its exports cannot round-trip an
+ * identity; carrying the context means ours can, while staying readable by
+ * anything else, since `<extensions>` is ignorable by specification.
+ */
+export declare function toGpx(tracks: GpxTrack[], now?: Date): string;
+/**
+ * Parse a GPX document into tracks.
+ *
+ * Structure follows GPX's own hierarchy: the root is `<gpx>`, tracks are its
+ * children, segments are a track's, points are a segment's. Anything else —
+ * a `<trkseg>` inside an `<extensions>` payload, a `<trk>` below the root — is
+ * not track data, and a namespace check alone cannot tell the difference,
+ * since a payload declaring no namespace inherits GPX's own.
+ *
+ * Deliberately forgiving about structure and strict about values: elements it
+ * does not recognise are ignored rather than rejected, but a coordinate that is
+ * not an `xsd:decimal` in range, or a time that is not an `xsd:dateTime`, is
+ * refused. One NaN reaching the store stretches every bounding box that track
+ * appears in.
+ *
+ * **Points are sorted by time within each segment.** TimeZero paginates its
+ * export in blocks of 150 and the block seams overlap: the last point of a
+ * block can be a few milliseconds newer than the first point of the next. Out
+ * of 5,550 points in a real export, 16 pairs are out of order, every one on a
+ * 150-point boundary. Anything downstream that assumes ordering — time-window
+ * queries, the history reconciliation — would quietly misbehave on such a file.
+ *
+ * Sorting stops at the segment boundary, deliberately: a segment is a stretch
+ * of continuous recording, and reordering points across a gap would merge two
+ * passages into one line. So `segments.flat()` is not globally sorted for a
+ * file whose segments interleave in time, and a caller that needs that must
+ * sort for itself.
+ *
+ * A document the parser rejects yields no tracks rather than throwing: this
+ * reads files the plugin did not write, and an import that fails should say so
+ * by returning nothing rather than by taking the caller down.
+ */
+export declare function fromGpx(xml: string): GpxTrack[];

package/dist/harness.test-utils.d.ts

@@ -26,7 +26,7 @@ export interface TestHarness {
     statuses: string[];
     /**
      * Install a track with explicit timestamps, bypassing the throttled bus. This
-     * is the entry point the History API bootstrap uses.
+     * bypasses the throttle, which is what makes a back-dated track testable.
      */
     seedTrack: (context: string, positions: LatLngTuple[], timestamps: number[]) => void;
     /** Self position as reported by `getSelfPath`, used for radius filtering. */
@@ -34,6 +34,20 @@ export interface TestHarness {
     /** The own vessel's navigation.state, as reported by `getSelfPath`. */
     setSelfState: (state: string | undefined) => void;
     stop: () => void;
+    /**
+     * Start the same plugin instance again, with the config it was built with.
+     *
+     * A fresh harness would not do: what a restart has to show is the state the
+     * instance drops on `stop()`, which a new instance never had.
+     */
+    restart: () => void;
+    /**
+     * How many positions the plugin's bus subscription has accepted.
+     *
+     * Observable after stop(), when the store itself is closed and unreadable —
+     * which is how a test can still tell that the subscription was torn down.
+     */
+    emitted: () => number;
     errors: unknown[][];
     /**
      * The v2 Track API provider the plugin registered, or undefined when the
@@ -50,10 +64,71 @@ export interface HarnessOptions {
     selfPosition?: LatLngTuple;
     /** Initial navigation.state for the own vessel. */
     selfState?: string;
+    /**
+     * Data-model entries other vessels' paths resolve to, keyed by full path
+     * (e.g. `vessels.urn:...:244813000.name`). Omit to stand in for an older
+     * server with no `getPath`, where track naming falls back to the MMSI.
+     */
+    paths?: Record<string, unknown>;
     /**
      * Stand in for a server without the v2 Track API, to check the plugin still
      * starts when `registerTrackApiProvider` is absent.
      */
     withoutTrackApi?: boolean;
+    /**
+     * A history provider for the plugin to reconcile against.
+     *
+     * `contexts` is what `getContexts` lists, and `rows` what `getValues`
+     * returns — separately, because the difference between them is the whole
+     * point of the existence probe: a provider can know a vessel and still have
+     * no rows inside the asked window.
+     *
+     * `contextsSince` back-dates those contexts: a real provider filters its
+     * context list by the asked range (questdb builds a `WHERE` from it), so a
+     * stub that answers regardless of range cannot show what the probe misses.
+     * `getContextsRejects` and `getContextsHangs` cover the other two ways a
+     * provider can fail to answer.
+     */
+    history?: {
+        /** Read on every `getContexts` call, so a getter can count the probes. */
+        contexts?: string[];
+        contextsSince?: number;
+        rows?: unknown[];
+        withoutGetContexts?: boolean;
+        getContextsRejects?: boolean;
+        getContextsHangs?: boolean;
+        /**
+         * Hold every `getContexts` call open until the returned release is run.
+         *
+         * A provider that answers immediately cannot distinguish sharing an
+         * in-flight query from reusing a cached result: the first caller would
+         * have filled the cache before the rest arrived. Deferring the answer
+         * parks every caller inside the probe at once, so only sharing can
+         * collapse them.
+         */
+        deferContexts?: {
+            release: () => void;
+            wait: Promise<void>;
+        };
+        /** Fail the windowed read, leaving the provider unable to answer at all. */
+        getValuesRejects?: boolean;
+        /**
+         * Reject `getHistoryApi` itself, as the server does when no provider is
+         * registered — the default install, and not an outage.
+         */
+        noProvider?: boolean;
+        /** Never resolve `getHistoryApi`: a registered provider that wedges. */
+        providerHangs?: boolean;
+    };
 }
+/**
+ * A promise held open until a test releases it.
+ *
+ * Lets a test observe that every request has reached the provider before any
+ * answer exists, which a timed wait can only assume.
+ */
+export declare function deferred(): {
+    release: () => void;
+    wait: Promise<void>;
+};
 export declare function createHarness(options?: HarnessOptions): TestHarness;

package/dist/index.d.ts

@@ -29,6 +29,19 @@ interface HistoryValuesQuery {
 }
 interface HistoryApi {
     getValues(query: HistoryValuesQuery): Promise<HistoryValuesResponse>;
+    /**
+     * Contexts the provider holds data for, within a time range.
+     *
+     * Optional here though the upstream interface requires it: a provider
+     * registered against an older server-api may not implement it, and a missing
+     * method must degrade rather than throw.
+     */
+    getContexts?(query: HistoryContextsQuery): Promise<unknown[]>;
+}
+/** `ContextsRequest` upstream: a time range, with Instants rather than strings. */
+interface HistoryContextsQuery {
+    from: Temporal.Instant;
+    to: Temporal.Instant;
 }
 interface HistoryValuesResponse {
     context: string;
@@ -49,6 +62,14 @@ interface App {
         };
     };
     getSelfPath: (path: string) => unknown;
+    /**
+     * Read any path in the full data model, including other vessels'.
+     *
+     * `getSelfPath` only reaches the own vessel, so naming an AIS track needs
+     * this. Optional: absent on older servers, where tracks fall back to the
+     * MMSI parsed out of the context.
+     */
+    getPath?: (path: string) => unknown;
     selfContext: string;
     /** Shown against the plugin in the server's dashboard. Absent on older servers. */
     setPluginStatus?: (msg: string) => void;
@@ -74,6 +95,8 @@ interface App {
 }
 interface Plugin {
     start: (c: TracksPluginConfig) => void;
+    /** Enable on install, without waiting for a visit to the plugin config page. */
+    enabledByDefault: boolean;
     stop: () => void;
     signalKApiRoutes: (r: Router) => Router;
     id: string;
@@ -89,28 +112,12 @@ interface Plugin {
      */
     getTracks: () => TrackStore | undefined;
 }
-/**
- * Where tracks come from when the server starts.
- *
- * - `memory`: start empty, accumulate from the position bus only.
- * - `history`: refill from a History provider at startup, then accumulate.
- * - `sqlite`: persist to disk, so a restart resumes from what was recorded.
- *
- * One setting rather than a boolean per source: they are alternatives, and as
- * independent booleans a user could enable two and have the same positions
- * loaded twice.
- */
-export type TrackSource = 'memory' | 'history' | 'sqlite';
 interface TracksPluginConfig {
     resolution?: number;
-    pointsToKeep?: number;
-    maxAge?: number;
-    maxRadius?: number;
-    source?: TrackSource;
-    /** @deprecated superseded by `source`; still honoured for existing configs. */
-    bootstrapFromHistory?: boolean;
-    /** Days of history to keep when `source` is `sqlite`. 0 keeps everything. */
+    /** Days of the own vessel's track to keep. 0 keeps everything. */
     retentionDays?: number;
+    /** Days another vessel is kept after its last fix. 0 keeps every vessel. */
+    aisRetentionDays?: number;
     /** Minutes without a fix that start a new track segment. 0 disables. */
     segmentGapMinutes?: number;
     /** Speed above which a position is treated as a glitch. 0 disables. */
@@ -118,17 +125,9 @@ interface TracksPluginConfig {
     /** navigation.state values that pause recording of the own vessel. */
     pauseWhenState?: string[];
 }
-/**
- * Resolve the effective source, honouring the setting this replaced.
- *
- * `bootstrapFromHistory` shipped as a boolean defaulting to true, so an
- * installed plugin has it saved in its config either way. Reading `source`
- * first and only then falling back keeps those installs working: an explicit
- * `false` still means "do not touch the History API", and everything else
- * lands on the old default of `history`.
- */
-export declare const resolveSource: (config: TracksPluginConfig) => TrackSource;
 export default function ThePlugin(app: App): Plugin;
+export { fromGpx, toGpx } from './gpx.js';
+export type { GpxTrack, GpxTrackIdentity } from './gpx.js';
 export { Tracks, TrackAccumulator } from './tracks.js';
 export type { TracksConfig } from './tracks.js';
 export type { TrackStore } from './store.js';

package/dist/index.html

@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Tracks</title>
+    <link rel="stylesheet" href="./style.css" />
+  </head>
+  <body>
+    <header>
+      <h1>Tracks</h1>
+      <p id="status" role="status">Loading…</p>
+    </header>
+    <main>
+      <table id="tracks" hidden>
+        <thead>
+          <tr>
+            <th scope="col">Vessel</th>
+            <th scope="col">From</th>
+            <th scope="col">To</th>
+            <th scope="col" class="num">Points</th>
+            <th scope="col">Export</th>
+          </tr>
+        </thead>
+        <tbody></tbody>
+      </table>
+    </main>
+    <script type="module" src="./tracks.js"></script>
+  </body>
+</html>