@signalk/tracks-plugin 3.0.0-beta.6 → 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/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;
@@ -13667,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) {
@@ -13674,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);
@@ -13703,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.` });
 				});