@signalk/tracks-plugin 3.2.0 → 3.3.0

package/README.md

@@ -49,25 +49,34 @@ other track, filtered by vessel, time window and area, but as a feature of its o
 it names a vessel the plugin also records. It is never merged with a history provider's data,
 never removed by the retention settings, and never returned by the v1 routes, which answer
 where vessels are now. Its own name and any other properties it was posted with come back as
-posted.
-
-A track needs times (`coordTimes`) or a vessel (`context`). One with neither is refused:
-it would match no time window, and a query across every vessel needs one, so it could
-only be found again by its id.
+posted. It carries `imported: true`, which a recorded track does not, so a client drawing a
+vessel's recording can leave the import out of it.
+
+A timed track of the own vessel is the exception: it is the boat's own passage, logged before
+the plugin was installed or by another plotter, so it is written into the own vessel's
+recording instead of being kept as an import, and the answer is the recording's id,
+`tracks:recorded:<context>`. It replaces what was recorded over the same time: the positions
+this plugin stored there go to the recycle bin first, one entry per segment, and a history
+provider's data over that time is hidden while the entry is there. Restoring the entry brings
+both back. An untimed track of the own vessel stays an import, since it cannot be placed in
+time.
+
+A track with neither times (`coordTimes`) nor a vessel (`context`) is kept too. No time
+window or vessel query matches it, but `GET /plugins/tracks/imports` lists it with every other
+import, and `GET /signalk/v2/api/tracks/<id>` returns it.
 
 ### Importing a GPX file
 
 The Tracks webapp imports a GPX file from the **Import** form, and a client can do the same
 with `POST /plugins/tracks/imports`, the file as the request body with `Content-Type:
-application/gpx+xml`. Each track in the file
-becomes an imported track as above. Ticking **Tracks of my own vessel** (`?self=true`) files
-them under the own vessel; otherwise a track names a vessel only if the file says which, as
+application/gpx+xml`. Each track in the file becomes an imported track as above. Ticking
+**Tracks of my own vessel** (`?self=true`) files them under the own vessel, which writes a
+timed one into the recording; otherwise a track names a vessel only if the file says which, as
 the plugin's own GPX export does.
 
-A file with a track that cannot be kept is refused whole: if any track in it has neither times
-nor a vessel, nothing is stored and the reason is shown. In a timed track, points without a time are
-skipped, and the answer says how many. The route needs write access on a Signal K server that
-lets a plugin say so, and administrator rights on an older one.
+In a timed track, points without a time are skipped, and the answer says how many. The route
+needs write access on a Signal K server that lets a plugin say so, and administrator rights on
+an older one.
 
 The webapp lists every imported track, however old and whether or not it has times, next to
 the last 30 days of recorded ones, so a passage imported from years ago can be found there. It

package/dist/asyncTrackStore.d.ts

@@ -1,6 +1,6 @@
 import { TrackStore } from './store.js';
 import { SqliteStoreConfig } from './sqliteStore.js';
-import { Debug, Context, ImportedTrack, ImportFilter, LatLngTuple, TimeWindow, TrackParams } from './types.js';
+import { Debug, Context, ImportedTrack, ImportFilter, LatLngTuple, TimedPosition, TimeWindow, TrackParams } from './types.js';
 import { TrackQuery } from './timeWindow.js';
 interface Limits {
     maxItems?: number;
@@ -58,7 +58,7 @@ export declare class AsyncTrackStore implements TrackStore {
     initialTrack(context: Context, track: LatLngTuple[], timestamps?: number[]): void;
     prune(maxAge: number, keep?: Context): void;
     get(context: Context, window?: TimeWindow): Promise<LatLngTuple[]>;
-    getTimed(context: Context, window?: TimeWindow): Promise<import('./types.js').TimedPosition[]>;
+    getTimed(context: Context, window?: TimeWindow): Promise<TimedPosition[]>;
     getAllTracks(query?: TrackQuery): Promise<{
         context: string;
         track: LatLngTuple[];
@@ -70,6 +70,7 @@ export declare class AsyncTrackStore implements TrackStore {
         id?: number;
         known: boolean;
     }>;
+    recordTrack(context: Context, segments: TimedPosition[][], deletedAt: number, keepEmpty: boolean): Promise<number[]>;
     binImport(importId: string, span: {
         from?: number;
         to?: number;

package/dist/importedTracks.d.ts

@@ -14,9 +14,8 @@ export declare const isImportedId: (id: string) => boolean;
  * thinning and window code assume time order, and a segment boundary is a gap
  * in recording, so segments are never merged or reordered.
  *
- * Refuses a track with neither times nor a vessel. Such a track answers no
- * time window, and the server refuses a query across all vessels without one,
- * so it could only ever be found again by an id the client would have to keep.
+ * A track with neither times nor a vessel answers no time window and no
+ * vessel query; the plugin's import list and its id are what find it again.
  */
 export declare function toImportedTrack(track: TrackImport, id?: string): ImportedTrack;
 /**
@@ -27,7 +26,6 @@ export declare function toImportedTrack(track: TrackImport, id?: string): Import
  * becomes an untimed import; a file with some keeps only its timed points,
  * because an import is timed throughout or not at all, and its times are what
  * let a query find it. `context` names the vessel in place of the file's own.
- * Refused, like any import, when it ends up with neither times nor a vessel.
  */
 export declare function fromGpxTrack(gpx: GpxTrack, context?: string | undefined, id?: string): {
     track: ImportedTrack;

package/dist/index.js

@@ -117,22 +117,6 @@ function nearestLongitude(lng, origin) {
 	return lng - 360 * Math.round((lng - origin) / 360);
 }
 //#endregion
-//#region src/trackApi.ts
-/**
-* Thrown by `storeTrack` when this provider will not keep the track, which
-* the server answers with a 400 rather than a 500.
-*
-* The server recognises it by `isTrackRejected` rather than by class, since
-* this is a copy of its own.
-*/
-var TrackRejectedError = class extends Error {
-	isTrackRejected = true;
-	constructor(message) {
-		super(message);
-		this.name = "TrackRejectedError";
-	}
-};
-//#endregion
 //#region src/importedTracks.ts
 /**
 * Prefix of every imported track's id. It keeps imported and recorded tracks
@@ -147,13 +131,11 @@ var isImportedId = (id) => id.startsWith(IMPORTED_PREFIX);
 * thinning and window code assume time order, and a segment boundary is a gap
 * in recording, so segments are never merged or reordered.
 *
-* Refuses a track with neither times nor a vessel. Such a track answers no
-* time window, and the server refuses a query across all vessels without one,
-* so it could only ever be found again by an id the client would have to keep.
+* A track with neither times nor a vessel answers no time window and no
+* vessel query; the plugin's import list and its id are what find it again.
 */
 function toImportedTrack(track, id = `${IMPORTED_PREFIX}${randomUUID()}`) {
 	const { coordTimes, name, context, ...metadata } = track.properties;
-	if (coordTimes === void 0 && context === void 0) throw new TrackRejectedError("A track with neither coordTimes nor a context could not be listed again; send one of them");
 	const segments = track.geometry.coordinates.map((segment, i) => {
 		const points = segment.map(([lon, lat], j) => {
 			const time = coordTimes?.[i]?.[j];
@@ -180,12 +162,10 @@ function toImportedTrack(track, id = `${IMPORTED_PREFIX}${randomUUID()}`) {
 * becomes an untimed import; a file with some keeps only its timed points,
 * because an import is timed throughout or not at all, and its times are what
 * let a query find it. `context` names the vessel in place of the file's own.
-* Refused, like any import, when it ends up with neither times nor a vessel.
 */
 function fromGpxTrack(gpx, context = gpx.context, id = `${IMPORTED_PREFIX}${randomUUID()}`) {
 	const all = gpx.segments.flat();
 	const timed = all.some(({ timestamp }) => timestamp !== 0);
-	if (!timed && context === void 0) throw new TrackRejectedError(`Track '${gpx.name}' has neither times nor a vessel, so it could not be listed again; choose a vessel for it`);
 	const segments = gpx.segments.map((points) => points.filter(({ timestamp }) => !timed || timestamp !== 0).map(({ position, timestamp }) => timed ? {
 		position,
 		timestamp
@@ -284,6 +264,22 @@ function overlaps(start, width, { from, to }) {
 	return width > 0 ? start + width > from : start >= from;
 }
 //#endregion
+//#region src/trackApi.ts
+/**
+* Thrown by `storeTrack` when this provider will not keep the track, which
+* the server answers with a 400 rather than a 500.
+*
+* The server recognises it by `isTrackRejected` rather than by class, since
+* this is a copy of its own.
+*/
+var TrackRejectedError = class extends Error {
+	isTrackRejected = true;
+	constructor(message) {
+		super(message);
+		this.name = "TrackRejectedError";
+	}
+};
+//#endregion
 //#region src/trackProvider.ts
 /** v2 sends `[west, south, east, north]`; a bounds here is `[lat, lng]` corners. */
 var toGeoBounds = (bbox) => {
@@ -447,12 +443,16 @@ function createTrackProvider(deps) {
 		}
 		return result;
 	};
-	/** What names an imported track: its id, name and vessel, over what it was posted with. */
+	/**
+	* What names an imported track: its id, name and vessel, over what it was posted with.
+	* `imported` tells it apart from the recording of the same vessel, which it is listed beside.
+	*/
 	const importIdentity = (track) => {
 		const contextName = track.context === void 0 ? void 0 : deps.contextName(track.context);
 		return {
 			...track.metadata,
 			id: track.id,
+			imported: true,
 			...track.name === void 0 ? {} : { name: track.name },
 			...track.context === void 0 ? {} : {
 				context: track.context,
@@ -464,7 +464,7 @@ function createTrackProvider(deps) {
 	/** The store, when it can keep and delete tracks; an ordinary failure otherwise. */
 	const writableStore = () => {
 		const store = deps.store();
-		if (!store?.storeImport || !store.getImport || !store.binImport || !store.binRecorded) throw new Error("Track storage is not available");
+		if (!store?.storeImport || !store.recordTrack || !store.getImport || !store.binImport || !store.binRecorded) throw new Error("Track storage is not available");
 		return store;
 	};
 	/** The recorded feature's identity, which `getTracks` and `getTrack` share. */
@@ -537,9 +537,12 @@ function createTrackProvider(deps) {
 			return shapeFeature(positionsOf(track, null), 0, { times: timed }, void 0, importIdentity(track), timed);
 		},
 		async storeTrack(track) {
-			const imported = toImportedTrack(track);
-			await writableStore().storeImport(imported);
-			return imported.id;
+			return keepTrack(toImportedTrack(track), {
+				store: writableStore(),
+				selfContext: deps.selfContext(),
+				historyKnows: deps.historyKnows,
+				deleted: deps.deleted
+			});
 		},
 		async deleteTrack(id) {
 			const recorded = recordedContext(id);
@@ -669,6 +672,30 @@ function extentEpsilon([west, south, east, north]) {
 	const width = (east >= west ? east - west : east + 360 - west) * M_PER_DEG * Math.cos(midLat * Math.PI / 180);
 	return Math.max(Math.hypot(width, height) / AUTO_EPSILON_DIVISOR, MIN_AUTO_EPSILON);
 }
+/**
+* Keep a client's track, resolving to the id that addresses it.
+*
+* A timed track of the own vessel is the vessel's own passage, from before
+* the plugin recorded it or from another plotter, so it is written into the
+* recording in place of what was recorded over the same time and answers
+* as `recorded:<context>`. Everything else is kept as an import: another
+* vessel's track is not this boat's recording, and an untimed one cannot be
+* placed in it.
+*/
+async function keepTrack(track, deps) {
+	const context = track.context === void 0 ? void 0 : resolveSelf(deps.selfContext)(track.context);
+	if (context === deps.selfContext && isTimed(track)) {
+		const segments = track.segments.map((points) => points.map(({ position, timestamp }) => ({
+			position,
+			timestamp
+		})));
+		await deps.store.recordTrack(context, segments, Date.now(), await deps.historyKnows(context));
+		deps.deleted();
+		return recordedId(context);
+	}
+	await deps.store.storeImport(track);
+	return track.id;
+}
 /** v2 accepts the `self` alias; the store keys on the qualified context. */
 var resolveSelf = (selfContext) => (context) => context === "self" || context === "vessels.self" ? selfContext : context;
 //#endregion
@@ -1002,6 +1029,14 @@ var AsyncTrackStore = class {
 			keepEmpty
 		], "acknowledged");
 	}
+	recordTrack(context, segments, deletedAt, keepEmpty) {
+		return this.enqueue("recordTrack", [
+			context,
+			segments,
+			deletedAt,
+			keepEmpty
+		], "acknowledged");
+	}
 	binImport(importId, span, deletedAt) {
 		return this.enqueue("binImport", [
 			importId,
@@ -2744,11 +2779,14 @@ function ThePlugin(app) {
 			});
 			(router.access?.("readwrite") ?? router).post("/imports", (req, res) => {
 				const store = tracks;
-				if (!store?.storeImport) {
+				if (!store?.storeImport || !store.recordTrack) {
 					notAvailable(res);
 					return;
 				}
-				const storeImport = store.storeImport.bind(store);
+				const writableStore = {
+					storeImport: store.storeImport.bind(store),
+					recordTrack: store.recordTrack.bind(store)
+				};
 				const context = req.query.self === "true" ? app.selfContext : void 0;
 				(async () => {
 					let text;
@@ -2765,22 +2803,24 @@ function ThePlugin(app) {
 						res.status(400).json({ message: "No track found: the file is not GPX, or has no track with points" });
 						return;
 					}
-					let converted;
-					try {
-						converted = read.map((gpx) => fromGpxTrack(gpx, context ?? gpx.context));
-					} catch (err) {
-						res.status(400).json({ message: err instanceof TrackRejectedError ? err.message : String(err) });
-						return;
-					}
+					const converted = read.map((gpx) => fromGpxTrack(gpx, context ?? gpx.context));
+					const ids = [];
 					try {
-						for (const { track } of converted) await storeImport(track);
+						for (const { track } of converted) ids.push(await keepTrack(track, {
+							store: writableStore,
+							selfContext: app.selfContext,
+							historyKnows: (vessel) => historyKnowsContext(app, vessel, app.debug, knownContexts),
+							deleted: () => {
+								deletedSpans = void 0;
+							}
+						}));
 					} catch (err) {
 						app.error(`GPX import: ${errorDetail(err)}`);
 						res.status(500).json({ message: "Track storage failed" });
 						return;
 					}
 					res.status(201).json({
-						ids: converted.map(({ track }) => `${PLUGIN_ID}:${track.id}`),
+						ids: ids.map((id) => `${PLUGIN_ID}:${id}`),
 						skippedPoints: converted.reduce((sum, { skippedPoints }) => sum + skippedPoints, 0)
 					});
 				})();