@signalk/tracks-plugin 3.0.0-beta.5 → 3.0.0-beta.7

package/README.md

@@ -106,6 +106,13 @@ _`timespan` and `timespanOffset` are also accepted for Freeboard-SK compatibilit
 `timespan=23h&timespanOffset=1` means "23 hours ending an hour ago". They are not part of
 the proposed track API and are expected to be superseded by `from`/`to`._
 
+_A parameter these routes do not read is rejected with `400` rather than ignored, so a
+typo such as `?duratoin=6h` fails rather than quietly returning the whole retained track.
+`bbox` and `radius` are **not** accepted here: they select which vessels to return and so
+belong to `/tracks` below. To ask whether one vessel's track passed through a box, use the
+v2 Track API, which matches any position in the window ([being designed in
+SignalK/signalk-server#2504](https://github.com/SignalK/signalk-server/issues/2504))._
+
 ---
 
 **Reduce the number of points returned:**

package/app-icon.svg

@@ -0,0 +1,42 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" role="img" aria-label="Tracks">
+  <defs>
+    <linearGradient id="sea" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#1b6ea8"/>
+      <stop offset="1" stop-color="#0b3a5e"/>
+    </linearGradient>
+    <clipPath id="card">
+      <rect x="0" y="0" width="128" height="128" rx="22"/>
+    </clipPath>
+  </defs>
+
+  <g clip-path="url(#card)">
+    <rect width="128" height="128" fill="url(#sea)"/>
+
+    <!-- Chart grid, as on the sibling plugins' icons. -->
+    <g stroke="#bee3f4" stroke-opacity="0.28" stroke-width="1" fill="none">
+      <path d="M0 32 H128 M0 64 H128 M0 96 H128"/>
+      <path d="M32 0 V128 M64 0 V128 M96 0 V128"/>
+    </g>
+
+    <!-- The track itself: the recorded path, drawn through its own points. -->
+    <path d="M24 102 C 40 94, 42 72, 58 64 S 84 58, 94 44"
+          fill="none" stroke="#0b3a5e" stroke-opacity="0.45"
+          stroke-width="9" stroke-linecap="round"/>
+    <path d="M24 102 C 40 94, 42 72, 58 64 S 84 58, 94 44"
+          fill="none" stroke="#ffd76a" stroke-width="5"
+          stroke-linecap="round" stroke-linejoin="round"/>
+
+    <!-- Position fixes. The track is a series of recorded points, not a
+         drawn line, and the icon should read that way at 32px too. -->
+    <g fill="#fffaf0" stroke="#0b3a5e" stroke-opacity="0.5" stroke-width="1.5">
+      <circle cx="24" cy="102" r="4.5"/>
+      <circle cx="49" cy="74" r="4"/>
+      <circle cx="72" cy="61" r="4"/>
+    </g>
+
+    <!-- The vessel, at the newest fix, heading along the track. -->
+    <path d="M94 34 L102 52 L94 47 L86 52 Z" fill="#fffaf0"
+          stroke="#0b3a5e" stroke-opacity="0.5" stroke-width="1.5"
+          stroke-linejoin="round"/>
+  </g>
+</svg>

package/dist/index.js

@@ -135,6 +135,20 @@ function nearestLongitude(lng, origin) {
 * `resolution` is shared by both and expresses the minimum spacing between
 * returned points, thinning the track for wide time ranges.
 */
+/**
+* The query keys these routes read. Kept beside the schema so the two cannot
+* drift: a key added to one without the other either fails validation or is
+* rejected as unknown.
+*/
+var QUERY_KEYS = [
+	"from",
+	"to",
+	"duration",
+	"timespan",
+	"timespanOffset",
+	"resolution",
+	"times"
+];
 var QuerySchema = Type.Object({
 	from: Type.Optional(Type.String()),
 	to: Type.Optional(Type.String()),
@@ -200,7 +214,12 @@ function firstString(value) {
 * `timespan`/`timespanOffset` pair. Absent all of them, no window is applied
 * and the whole retained track is returned, as before.
 */
-function parseTrackQuery(query, now = Date.now()) {
+function parseTrackQuery(query, now = Date.now(), alsoAllowed = []) {
+	const unknown = Object.keys(query).filter((key) => !QUERY_KEYS.includes(key) && !alsoAllowed.includes(key));
+	if (unknown.length > 0) {
+		const allowed = [...QUERY_KEYS, ...alsoAllowed].join(", ");
+		throw new TimeWindowError(`Unknown query parameter${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")}; accepted: ${allowed}`);
+	}
 	const raw = {
 		from: firstString(query.from),
 		to: firstString(query.to),
@@ -411,21 +430,44 @@ function toFiniteNumber(value) {
 	const parsed = Number(trimmed);
 	return Number.isFinite(parsed) ? parsed : void 0;
 }
+/**
+* A query parameter was present but malformed.
+*
+* Distinct from absent: a filter nobody asked for is not an error, but one
+* that cannot be honoured must not quietly widen the query. Carries its own
+* message so the handler can hand it to the client, the way `TimeWindowError`
+* already does for the time window.
+*/
+var QueryParameterError = class extends Error {};
+/**
+* A well-formed query the server cannot currently answer.
+*
+* `radius` measures from the own vessel, so it needs a self position. Not
+* having one is an outage, not a client mistake -- the same distinction the
+* single-vessel route already draws for a history provider it cannot read.
+*/
+var SelfPositionUnavailableError = class extends Error {};
 function validateParameters(params, defaultMaxRadius) {
 	let bbox = null;
 	const rawBbox = firstValue(params.bbox);
 	if (rawBbox !== void 0) {
 		const b = rawBbox.split(",").map(toFiniteNumber);
 		const [west, south, east, north] = b;
-		if (b.length === 4 && west !== void 0 && south !== void 0 && east !== void 0 && north !== void 0) bbox = {
+		if (b.length !== 4 || west === void 0 || south === void 0 || east === void 0 || north === void 0) throw new QueryParameterError("bbox must be four comma-separated numbers: west,south,east,north");
+		if (south > north) throw new QueryParameterError(`bbox south (${south}) must not be greater than north (${north})`);
+		bbox = {
 			sw: [south, west],
 			ne: [north, east]
 		};
 	}
 	let radius = null;
 	const rawRadius = firstValue(params.radius);
-	if (rawRadius !== void 0) radius = toFiniteNumber(rawRadius) ?? null;
-	else if (defaultMaxRadius) radius = defaultMaxRadius;
+	if (rawRadius !== void 0) {
+		const parsed = toFiniteNumber(rawRadius);
+		if (parsed === void 0) throw new QueryParameterError(`radius must be a number in meters, got '${rawRadius}'`);
+		if (parsed < 0) throw new QueryParameterError(`radius must not be negative, got ${parsed}`);
+		radius = parsed;
+	} else if (defaultMaxRadius) radius = defaultMaxRadius;
 	return {
 		bbox,
 		radius
@@ -463,7 +505,7 @@ function createMatcher(params, selfPosition, debug) {
 		const inBounds = createInBounds(params.bbox);
 		return params.intersects ? (track) => track.some(inBounds) : (track) => inBounds(lastPoint(track));
 	} else if (params.radius !== null) {
-		if (!selfPosition) throw new Error("No self position to calculate radius values");
+		if (!selfPosition) throw new SelfPositionUnavailableError("No self position to calculate radius values");
 		const radius = params.radius;
 		const distanceFromSelf = createDistanceTo(selfPosition, debug);
 		return (track) => distanceFromSelf(lastPoint(track)) < radius;
@@ -12135,6 +12177,8 @@ var DEFAULT_SEGMENT_GAP = 3e5;
 var SqliteTrackStore = class {
 	db;
 	insert;
+	insertName;
+	selectName;
 	maxCells;
 	segmentGap;
 	retention;
@@ -12160,8 +12204,20 @@ var SqliteTrackStore = class {
       );
       CREATE INDEX IF NOT EXISTS idx_s2cell ON positions(s2cell);
       CREATE INDEX IF NOT EXISTS idx_context_timestamp ON positions(context, timestamp);
+      -- A separate table rather than a column on positions: this store has no
+      -- migration mechanism, so a new table appears harmlessly on a database
+      -- written by an older version, where an ALTER TABLE would not.
+      CREATE TABLE IF NOT EXISTS names (
+        context   TEXT PRIMARY KEY,
+        name      TEXT NOT NULL,
+        timestamp INTEGER NOT NULL
+      );
     `);
 		this.insert = this.db.prepare("INSERT INTO positions (context, timestamp, lat, lon, s2cell) VALUES (?, ?, ?, ?, ?)");
+		this.insertName = this.db.prepare(`INSERT INTO names (context, name, timestamp) VALUES (?, ?, ?)
+       ON CONFLICT(context) DO UPDATE SET name = excluded.name, timestamp = excluded.timestamp
+       WHERE excluded.timestamp >= names.timestamp`);
+		this.selectName = this.db.prepare("SELECT name FROM names WHERE context = ?");
 	}
 	newPosition(context, position, timestamp = Date.now()) {
 		if (this.resolution > 0) {
@@ -12288,10 +12344,19 @@ var SqliteTrackStore = class {
 		if (current.length > 0) result.push(current);
 		return result;
 	}
+	recordName(context, name, timestamp = Date.now()) {
+		const trimmed = name.trim();
+		if (trimmed === "") return;
+		this.insertName.run(context, trimmed, timestamp);
+	}
+	nameFor(context) {
+		return this.selectName.get(context)?.name;
+	}
 	prune(maxAge, keep) {
 		const cutoff = Date.now() - maxAge;
 		const dropped = this.db.prepare("SELECT context FROM positions GROUP BY context HAVING MAX(timestamp) < ? AND context IS NOT ?").all(cutoff, keep ?? null);
 		this.db.prepare("DELETE FROM positions WHERE context IN (SELECT context FROM positions GROUP BY context HAVING MAX(timestamp) < ?) AND context IS NOT ?").run(cutoff, keep ?? null);
+		for (const { context } of dropped) this.db.prepare("DELETE FROM names WHERE context = ?").run(context);
 		for (const { context } of dropped) this.lastStored.delete(context);
 		if (this.retention > 0) {
 			const oldest = Date.now() - this.retention;
@@ -13043,12 +13108,34 @@ var Tracks = class {
 			return acc;
 		}, {});
 	}
+	/**
+	* Remembered names, by context.
+	*
+	* In memory only: this store is the client-side accumulator, so there is no
+	* restart for a stored name to survive. It implements the same contract so
+	* the two stores stay interchangeable and the plugin needs no special case.
+	*/
+	names = /* @__PURE__ */ new Map();
+	recordName(context, name, timestamp = Date.now()) {
+		const trimmed = name.trim();
+		if (trimmed === "") return;
+		const seen = this.names.get(context);
+		if (seen && seen.timestamp > timestamp) return;
+		this.names.set(context, {
+			name: trimmed,
+			timestamp
+		});
+	}
+	nameFor(context) {
+		return this.names.get(context)?.name;
+	}
 	prune(maxAge, keep) {
 		const cutoff = Date.now() - maxAge;
 		const deleted = [];
 		Object.entries(this.tracks).forEach(([key, value]) => {
 			if (key !== keep && value.latestLatLngTuple < cutoff) {
 				delete this.tracks[key];
+				this.names.delete(key);
 				deleted.push(key);
 			}
 		});
@@ -13357,6 +13444,21 @@ var historyRowTimestamp = (row) => {
 	return Number.isNaN(parsed) ? 0 : parsed;
 };
 function ThePlugin(app) {
+	/**
+	* The server's own lookup, falling back to what the store remembers.
+	*
+	* Live wins whenever the data model has an answer, which keeps the rule the
+	* resolvers were written for: an AIS static report arriving late must be
+	* able to correct or replace what was known. The stored value only covers
+	* the window where the model knows nothing -- after a restart, or for a
+	* vessel that has since sailed out of range.
+	*/
+	const remembering = (store) => (path) => {
+		const live = app.getPath?.(path);
+		if (live !== void 0) return live;
+		const match = /^(.*)\.name$/.exec(path);
+		return match ? store()?.nameFor(match[1]) : void 0;
+	};
 	let onStop = [];
 	let tracks = void 0;
 	let segmentGap = 0;
@@ -13420,6 +13522,8 @@ function ThePlugin(app) {
 			onStop.push(app.streambundle.getBus("navigation.position").onValue((update) => {
 				if (!update.value || update.value.latitude == null || update.value.longitude == null) return;
 				sourceWatch.add(update.context, update.$source);
+				const live = unwrapString(app.getPath?.(`${update.context}.name`));
+				if (live !== void 0) tracks?.recordName(update.context, live);
 				const recorded = update.timestamp === void 0 ? void 0 : Date.parse(update.timestamp);
 				const timestamp = recorded !== void 0 && !Number.isNaN(recorded) ? recorded : void 0;
 				const position = [update.value.latitude, update.value.longitude];
@@ -13449,7 +13553,7 @@ function ThePlugin(app) {
 				store: () => tracks,
 				selfContext: () => app.selfContext,
 				segmentGap: () => segmentGap,
-				contextName: (context) => contextName(context, (path) => app.getPath?.(path)),
+				contextName: (context) => contextName(context, remembering(() => tracks)),
 				reconcileWithHistory: async (context, stored, window, resolutionMs) => {
 					const effective = resolutionMs ?? storeResolution;
 					const history = await historyPositions(app, context, window ?? windowSpanning(stored, WINDOWLESS_HISTORY_SPAN_MS), effective, app.debug);
@@ -13479,7 +13583,7 @@ function ThePlugin(app) {
 			}
 		},
 		signalKApiRoutes: function(router) {
-			const nameOf = (context) => trackLabel(context, app.selfContext, (path) => app.getPath?.(path));
+			const nameOf = (context) => trackLabel(context, app.selfContext, remembering(() => tracks));
 			/**
 			* The points of one context, reconciled with history and segmented.
 			*
@@ -13605,6 +13709,8 @@ function ThePlugin(app) {
 			router.get("/vessels/:vesselId/track.gpx", gpxHandler((req) => resolveContext(String(req.params.vesselId), app.selfContext)));
 			router.get("/self/track.gpx", gpxHandler(() => app.selfContext));
 			router.get("/self/track", singleTrackHandler(() => app.selfContext));
+			/** Only the collection route filters spatially; see AGENTS.md on v1 vs v2. */
+			const SPATIAL_PARAMS = ["bbox", "radius"];
 			const allTracksHandler = (req, res) => {
 				app.debug(req.query);
 				if (!tracks) {
@@ -13612,14 +13718,15 @@ function ThePlugin(app) {
 					return;
 				}
 				let query;
+				let params;
 				try {
-					query = parseTrackQuery(req.query);
+					query = parseTrackQuery(req.query, Date.now(), SPATIAL_PARAMS);
+					params = validateParameters(req.query, void 0);
 				} catch (err) {
 					res.status(400);
-					res.json({ message: err instanceof TimeWindowError ? err.message : "Invalid query parameters" });
+					res.json({ message: err instanceof TimeWindowError || err instanceof QueryParameterError ? err.message : "Invalid query parameters" });
 					return;
 				}
-				const params = validateParameters(req.query, void 0);
 				const selfPosition = getVesselPosition();
 				(query.times ? tracks.getFilteredTimedTracks(params, selfPosition, app.debug, query).then((tc) => Object.entries(tc).reduce((acc, [context, points]) => {
 					const segments = segment(points, segmentGap);
@@ -13641,7 +13748,12 @@ function ThePlugin(app) {
 					return acc;
 				}, {}))).then((trks) => {
 					res.json(trks);
-				}).catch(() => {
+				}).catch((err) => {
+					if (err instanceof SelfPositionUnavailableError) {
+						res.status(503);
+						res.json({ message: "No position for the own vessel, so radius cannot be measured" });
+						return;
+					}
 					res.status(404);
 					res.json({ message: `No track available for vessels.` });
 				});