@signalk/tracks-plugin 3.1.1 → 3.2.0

package/dist/index.js

@@ -1,6 +1,7 @@
-import { C as uncoveredBetween, S as thinToBudget, _ as validateParameters, a as contextName, b as segment, c as createMatcher, d as resolveContext, f as rfc8187, g as unwrapString, h as trackLabel, i as clipToBounds, l as gpxFilename, m as toIsoTimes, n as SelfPositionUnavailableError, o as createDistanceTo, r as asciiFilename, s as createInBounds, t as QueryParameterError, u as historyRowPosition, v as TimeWindowError, x as thin, y as parseTrackQuery } from "./utils-CGIGp4Xf.js";
+import { C as thinToBudget, S as thin, _ as unwrapString, a as contextName, b as parseTrackQuery, c as createMatcher, d as longitudeSpan, f as resolveContext, g as trackLabel, h as toIsoTimes, i as clipToBounds, l as gpxFilename, n as SelfPositionUnavailableError, o as createDistanceTo, p as rfc8187, r as asciiFilename, s as createInBounds, t as QueryParameterError, u as historyRowPosition, v as validateParameters, w as uncoveredBetween, x as segment, y as TimeWindowError } from "./utils-C0VkiidM.js";
 import { Temporal } from "@js-temporal/polyfill";
 import { join } from "node:path";
+import { randomUUID } from "node:crypto";
 import { Worker } from "node:worker_threads";
 import { DOMParser } from "@xmldom/xmldom";
 import { BehaviorSubject, ReplaySubject, Subject, combineLatest, connectable, firstValueFrom } from "rxjs";
@@ -116,6 +117,173 @@ 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
+* in separate id spaces, so no import can ever address a recorded track.
+*/
+var IMPORTED_PREFIX = "imported:";
+var isImportedId = (id) => id.startsWith(IMPORTED_PREFIX);
+/**
+* The track the server handed over, as this plugin stores it.
+*
+* Times are sorted within each segment, the way `fromGpx` reads a file: the
+* 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.
+*/
+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];
+			return time === void 0 ? { position: [lat, lon] } : {
+				position: [lat, lon],
+				timestamp: Date.parse(time)
+			};
+		});
+		return coordTimes === void 0 ? points : points.sort((a, b) => a.timestamp - b.timestamp);
+	});
+	return {
+		id,
+		...context === void 0 ? {} : { context },
+		...name === void 0 ? {} : { name },
+		metadata,
+		segments
+	};
+}
+/**
+* A track read from a GPX file, as this plugin stores it, with the number of
+* points left out.
+*
+* `fromGpx` dates a point with no `<time>` to 0. A file with no times at all
+* 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
+	} : { position })).filter((points) => points.length > 0);
+	const kept = segments.reduce((sum, points) => sum + points.length, 0);
+	return {
+		track: {
+			id,
+			...context === void 0 ? {} : { context },
+			name: gpx.name,
+			metadata: {},
+			segments
+		},
+		skippedPoints: all.length - kept
+	};
+}
+/** Whether the track's points carry times; an import is timed throughout or not at all. */
+var isTimed = (track) => track.segments[0]?.[0]?.timestamp !== void 0;
+/**
+* The track as one list of points for the shared pipeline, each posted segment
+* after the first starting a new line.
+*
+* Narrowed to the window and clipped per segment, so a line never joins two
+* segments: not where the window empties the start of one, nor through the
+* point just outside the box that a clipped stretch keeps, which must come
+* from its own segment. An untimed point gets timestamp 0, which only the
+* time-free paths of the pipeline ever see.
+*/
+function positionsOf(track, clipTo, window) {
+	const result = [];
+	for (const segment of track.segments) {
+		let points = segment.map(({ position, timestamp }) => ({
+			position,
+			timestamp: timestamp ?? 0
+		}));
+		if (window) points = points.filter(({ timestamp }) => window.inclusiveEnd ? timestamp >= window.from && timestamp <= window.to : timestamp >= window.from && timestamp < window.to);
+		const kept = clipTo ? clipToBounds(points, clipTo) : points;
+		for (const [i, point] of kept.entries()) result.push(i === 0 && result.length > 0 ? {
+			...point,
+			breakBefore: true
+		} : point);
+	}
+	return result;
+}
+/**
+* At most `maxPoints` evenly chosen points of a track without times, keeping
+* the first and the last. A point that starts a new line passes that on to
+* the next point kept, so dropping it does not join two segments.
+*/
+function decimate(points, maxPoints) {
+	if (points.length <= maxPoints) return points;
+	if (maxPoints < 2) return points.slice(0, Math.max(0, maxPoints));
+	const step = (points.length - 1) / (maxPoints - 1);
+	const result = [];
+	let previous = -1;
+	for (let k = 0; k < maxPoints; k++) {
+		const index = Math.round(k * step);
+		const breaks = points.slice(previous + 1, index + 1).some(({ breakBefore }) => breakBefore);
+		const point = points[index];
+		result.push(breaks && result.length > 0 ? {
+			...point,
+			breakBefore: true
+		} : point);
+		previous = index;
+	}
+	return result;
+}
+//#endregion
+//#region src/recycleBin.ts
+/**
+* Prefix of a recorded track's id. The rest is the vessel's context: a vessel
+* has one recording, so its context is all an id needs, and a provider may
+* derive the id from it, as the server's Track API foresees.
+*/
+var RECORDED_PREFIX = "recorded:";
+var recordedId = (context) => `${RECORDED_PREFIX}${context}`;
+/** The context a recorded track's id names, or undefined for any other id. */
+var recordedContext = (id) => id.startsWith("recorded:") && id.length > 9 ? id.slice(9) : void 0;
+/**
+* The points outside every deleted span.
+*
+* Applied to what a history provider returns, which this plugin cannot delete
+* from: without it the next query would fill a deleted span back in. A
+* history point stands for a bucket starting at its timestamp, and the fix it
+* carries can lie anywhere in that bucket, so a bucket that overlaps a span at
+* all is dropped; the store's own points answer for the rest of it.
+*/
+function outsideSpans(points, spans) {
+	if (spans.length === 0) return points;
+	return points.filter(({ timestamp, span = 0 }) => !spans.some((deleted) => overlaps(timestamp, span, deleted)));
+}
+/** Whether `[start, start + width)`, or the instant `start` when `width` is 0, meets `[from, to]`. */
+function overlaps(start, width, { from, to }) {
+	if (start > to) return false;
+	if (from === void 0) return true;
+	return width > 0 ? start + width > from : start >= from;
+}
+//#endregion
 //#region src/trackProvider.ts
 /** v2 sends `[west, south, east, north]`; a bounds here is `[lat, lng]` corners. */
 var toGeoBounds = (bbox) => {
@@ -202,36 +370,6 @@ var boundsOf = (points) => {
 		north
 	];
 };
-/**
-* The narrower of the two longitude intervals covering these points.
-*
-* A plain min/max describes a track spanning the antimeridian as almost the
-* whole globe: two fixes at 179 and -179 are two degrees apart, but min/max
-* reports 358. RFC 7946 says a box crossing the antimeridian is written with
-* west greater than east, so the wrap-around interval is expressible — pick it
-* whenever it is the shorter of the two.
-*
-* The widest gap between adjacent longitudes is the part of the globe the track
-* does not cover, so the complement of that gap is the tightest interval that
-* does.
-*/
-var longitudeSpan = (longitudes) => {
-	const sorted = [...longitudes].sort((a, b) => a - b);
-	const min = sorted[0];
-	const max = sorted[sorted.length - 1];
-	let widestGap = 360 - (max - min);
-	let west = min;
-	let east = max;
-	for (let i = 1; i < sorted.length; i++) {
-		const gap = sorted[i] - sorted[i - 1];
-		if (gap > widestGap) {
-			widestGap = gap;
-			west = sorted[i];
-			east = sorted[i - 1];
-		}
-	}
-	return [west, east];
-};
 function createTrackProvider(deps) {
 	const matching = async (query) => {
 		const store = deps.store();
@@ -274,42 +412,100 @@ function createTrackProvider(deps) {
 			resolution
 		};
 	};
+	/**
+	* Imported tracks the query matches, each with the points it returns.
+	*
+	* The same filters as a recorded track, applied to the import's own points:
+	* a context names the vessel it was imported for, a window needs times, a
+	* box needs a point inside it and clips like a recorded track. Never
+	* reconciled with history, which knows nothing of an import.
+	*/
+	const matchingImports = async (query) => {
+		const store = deps.store();
+		if (!store?.findImports) return [];
+		const window = toTimeWindow(query);
+		const resolution = query.resolution ? totalMilliseconds(query.resolution) : void 0;
+		const bounds = toGeoBounds(query.bbox);
+		const clipTo = query.clip === true ? bounds : null;
+		const inBounds = bounds ? createInBounds(bounds) : void 0;
+		const imports = await store.findImports({
+			...query.contexts?.length ? { contexts: [...new Set(query.contexts.map(resolveSelf(deps.selfContext())))] } : {},
+			...window ? { window } : {},
+			...bounds ? { bbox: bounds } : {}
+		});
+		const result = [];
+		for (const track of imports) {
+			const timed = isTimed(track);
+			if (inBounds && !positionsOf(track, null, window).some(({ position }) => inBounds(position))) continue;
+			let points = positionsOf(track, clipTo, window);
+			if (timed) points = thin(points, resolution);
+			if (points.length > 0) result.push({
+				track,
+				points,
+				timed
+			});
+		}
+		return result;
+	};
+	/** What names an imported track: its id, name and vessel, over what it was posted with. */
+	const importIdentity = (track) => {
+		const contextName = track.context === void 0 ? void 0 : deps.contextName(track.context);
+		return {
+			...track.metadata,
+			id: track.id,
+			...track.name === void 0 ? {} : { name: track.name },
+			...track.context === void 0 ? {} : {
+				context: track.context,
+				isSelf: track.context === deps.selfContext(),
+				...contextName === void 0 ? {} : { contextName }
+			}
+		};
+	};
+	/** 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");
+		return store;
+	};
+	/** The recorded feature's identity, which `getTracks` and `getTrack` share. */
+	const recordedIdentity = (context) => {
+		const name = deps.contextName(context);
+		return {
+			id: recordedId(context),
+			context,
+			isSelf: context === deps.selfContext(),
+			...name === void 0 ? {} : { contextName: name }
+		};
+	};
+	/**
+	* Move a vessel's recording within the span to the recycle bin, resolving
+	* false for a vessel neither the store nor history knows.
+	*
+	* `to` is the moment of the delete, never the end of time: recording goes
+	* on, and what it records afterwards is a new track, not a deleted one.
+	*/
+	const deleteRecorded = async (context, from, to) => {
+		const now = Date.now();
+		const end = Math.min(to ?? now, now);
+		const historyKnown = await deps.historyKnows(context);
+		const keepEmpty = historyKnown && (from === void 0 || from <= end);
+		const { known } = await writableStore().binRecorded(context, from, end, now, keepEmpty);
+		deps.deleted();
+		return known || historyKnown;
+	};
 	return {
 		async getTracks(query) {
 			const { tracks: matched, resolution: requested } = await matching(query);
 			const gap = deps.segmentGap();
-			const selfContext = deps.selfContext();
 			const features = [];
 			for (const [context, all] of matched) {
-				const { points, resolution: appliedMs } = query.maxPoints === void 0 ? {
-					points: all,
-					resolution: requested
-				} : thinToBudget(all, query.maxPoints, requested);
-				if (points.length === 0) continue;
-				const chosenEpsilon = chooseEpsilon(points, query);
-				const segments = segment(points, gap).map((s) => chosenEpsilon === void 0 ? s : simplify(s, chosenEpsilon));
-				const shaped = segments.flat();
-				const bbox = boundsOf(shaped);
-				const name = deps.contextName(context);
-				features.push({
-					type: "Feature",
-					geometry: query.geometry === false ? null : {
-						type: "MultiLineString",
-						coordinates: segments.map((s) => s.map(({ position }) => toLngLat$1(position)))
-					},
-					properties: {
-						context,
-						isSelf: context === selfContext,
-						...name === void 0 ? {} : { contextName: name },
-						from: new Date(shaped[0].timestamp).toISOString(),
-						to: new Date(shaped[shaped.length - 1].timestamp).toISOString(),
-						...bbox ? { bbox } : {},
-						pointCount: shaped.length,
-						...appliedMs === void 0 ? {} : { resolution: msToDuration(appliedMs).toString() },
-						...chosenEpsilon === void 0 ? {} : { epsilon: chosenEpsilon },
-						...query.times ? { coordTimes: segments.map(toIsoTimes) } : {}
-					}
-				});
+				const feature = shapeFeature(all, gap, query, requested, recordedIdentity(context));
+				if (feature) features.push(feature);
+			}
+			const requestedForImports = query.resolution ? totalMilliseconds(query.resolution) : void 0;
+			for (const { track, points, timed } of await matchingImports(query)) {
+				const feature = shapeFeature(points, 0, query, timed ? requestedForImports : void 0, importIdentity(track), timed);
+				if (feature) features.push(feature);
 			}
 			return {
 				type: "FeatureCollection",
@@ -317,7 +513,95 @@ function createTrackProvider(deps) {
 			};
 		},
 		async getTrackContexts(query) {
-			return [...(await matching(query)).tracks.keys()];
+			const [recorded, imported] = await Promise.all([matching(query), matchingImports(query)]);
+			const contexts = new Set(recorded.tracks.keys());
+			for (const { track } of imported) if (track.context !== void 0) contexts.add(track.context);
+			return [...contexts];
+		},
+		async getTrack(id) {
+			const recorded = recordedContext(id);
+			if (recorded !== void 0) {
+				const context = resolveSelf(deps.selfContext())(recorded);
+				const query = {
+					contexts: [context],
+					times: true
+				};
+				const { tracks } = await matching(query);
+				const points = tracks.get(context);
+				return points && shapeFeature(points, deps.segmentGap(), query, void 0, recordedIdentity(context));
+			}
+			if (!isImportedId(id)) return;
+			const track = await writableStore().getImport(id);
+			if (!track) return;
+			const timed = isTimed(track);
+			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;
+		},
+		async deleteTrack(id) {
+			const recorded = recordedContext(id);
+			if (recorded !== void 0) return deleteRecorded(resolveSelf(deps.selfContext())(recorded), void 0, void 0);
+			if (!isImportedId(id)) return false;
+			return await writableStore().binImport(id, void 0, Date.now()) !== void 0;
+		},
+		async deleteTrackSpan(id, span) {
+			const from = span.from?.epochMilliseconds;
+			const to = span.to?.epochMilliseconds;
+			const recorded = recordedContext(id);
+			if (recorded !== void 0) return deleteRecorded(resolveSelf(deps.selfContext())(recorded), from, to);
+			if (!isImportedId(id)) return false;
+			const store = writableStore();
+			const track = await store.getImport(id);
+			if (!track) return false;
+			if (!isTimed(track)) throw new TrackRejectedError("This track has no times, so no part of it can be addressed by time");
+			await store.binImport(id, {
+				...from === void 0 ? {} : { from },
+				...to === void 0 ? {} : { to }
+			}, Date.now());
+			return true;
+		}
+	};
+}
+/**
+* One track as a Feature, or undefined when the budget leaves nothing to draw.
+*
+* `identity` is whatever names the track — context, vessel name — and comes
+* first, so the derived properties after it always describe the geometry
+* actually returned.
+*/
+function shapeFeature(all, gap, query, requested, identity, timed = true) {
+	const { points, resolution: appliedMs } = query.maxPoints === void 0 ? {
+		points: all,
+		resolution: requested
+	} : timed ? thinToBudget(all, query.maxPoints, requested) : {
+		points: decimate(all, query.maxPoints),
+		resolution: void 0
+	};
+	if (points.length === 0) return;
+	const chosenEpsilon = chooseEpsilon(points, query);
+	const segments = segment(points, gap).map((s) => chosenEpsilon === void 0 ? s : simplify(s, chosenEpsilon));
+	const shaped = segments.flat();
+	const bbox = boundsOf(shaped);
+	return {
+		type: "Feature",
+		geometry: query.geometry === false ? null : {
+			type: "MultiLineString",
+			coordinates: segments.map((s) => s.map(({ position }) => toLngLat$1(position)))
+		},
+		properties: {
+			...identity,
+			...timed ? {
+				from: new Date(shaped[0].timestamp).toISOString(),
+				to: new Date(shaped[shaped.length - 1].timestamp).toISOString()
+			} : {},
+			...bbox ? { bbox } : {},
+			pointCount: shaped.length,
+			...appliedMs === void 0 ? {} : { resolution: msToDuration(appliedMs).toString() },
+			...chosenEpsilon === void 0 ? {} : { epsilon: chosenEpsilon },
+			...query.times && timed ? { coordTimes: segments.map(toIsoTimes) } : {}
 		}
 	};
 }
@@ -483,8 +767,10 @@ var AsyncTrackStore = class {
 		this.queue = [];
 		this.pendingBytes = 0;
 	}
-	enqueue(method, args, write = false) {
+	enqueue(method, args, kind = "read") {
 		this.resumeIfDrained();
+		if (kind === "acknowledged") return this.acknowledged(method, args);
+		const write = kind === "write";
 		if (this.failed || this.closing && method !== "close" || write && this.statusError) {
 			if (write && this.overloaded) this.dropped++;
 			const error = new Error(this.statusError ?? "Track store is closing");
@@ -529,6 +815,37 @@ var AsyncTrackStore = class {
 		this.schedule();
 		return result;
 	}
+	/**
+	* A write whose caller waits for the commit: an imported track, or its
+	* deletion. Admitted outside the recording budget, which is sized for
+	* positions; an import of a few megabytes would otherwise pause recording,
+	* and then be dropped like a position. Refused once writes have failed,
+	* since that state lasts until a restart.
+	*/
+	acknowledged(method, args) {
+		if (this.failed || this.closing || this.writeFailed) return Promise.reject(new Error(this.statusError ?? "Track store cannot write"));
+		let copy;
+		try {
+			copy = structuredClone(args);
+		} catch (error) {
+			return Promise.reject(error instanceof Error ? error : new Error(String(error)));
+		}
+		const item = {
+			operation: {
+				id: ++this.sequence,
+				method,
+				args: copy
+			},
+			bytes: 0
+		};
+		const result = new Promise((resolve, reject) => Object.assign(item, {
+			resolve,
+			reject
+		}));
+		this.queue.push(item);
+		this.schedule();
+		return result;
+	}
 	schedule() {
 		if (this.scheduled || !this.initialized || this.active.length || this.failed) return;
 		this.scheduled = true;
@@ -614,7 +931,7 @@ var AsyncTrackStore = class {
 			context,
 			position,
 			timestamp
-		], true);
+		], "write");
 		if (this.sequence !== sequence && this.resolution > 0) this.admitted.set(context, timestamp);
 	}
 	recordName(context, name, timestamp = Date.now()) {
@@ -622,7 +939,7 @@ var AsyncTrackStore = class {
 			context,
 			name,
 			timestamp
-		], true);
+		], "write");
 	}
 	nameFor(context) {
 		return this.names.get(context);
@@ -633,7 +950,7 @@ var AsyncTrackStore = class {
 			context,
 			track,
 			timestamps
-		], true);
+		], "write");
 		if (this.sequence !== sequence) this.admitted.delete(context);
 	}
 	prune(maxAge, keep) {
@@ -643,7 +960,7 @@ var AsyncTrackStore = class {
 			maxAge,
 			keep,
 			now
-		], true);
+		], "write");
 		if (this.sequence !== sequence) {
 			for (const [context, timestamp] of this.admitted) if (context !== keep && timestamp < now - maxAge) this.admitted.delete(context);
 		}
@@ -673,6 +990,43 @@ var AsyncTrackStore = class {
 			query
 		]);
 	}
+	storeImport(track) {
+		return this.enqueue("storeImport", [track], "acknowledged");
+	}
+	binRecorded(context, from, to, deletedAt, keepEmpty) {
+		return this.enqueue("binRecorded", [
+			context,
+			from,
+			to,
+			deletedAt,
+			keepEmpty
+		], "acknowledged");
+	}
+	binImport(importId, span, deletedAt) {
+		return this.enqueue("binImport", [
+			importId,
+			span,
+			deletedAt
+		], "acknowledged");
+	}
+	restoreFromBin(id) {
+		return this.enqueue("restoreFromBin", [id], "acknowledged");
+	}
+	purgeFromBin(id) {
+		return this.enqueue("purgeFromBin", [id], "acknowledged");
+	}
+	binEntries() {
+		return this.enqueue("binEntries", []);
+	}
+	deletedSpans() {
+		return this.enqueue("deletedSpans", []);
+	}
+	getImport(id) {
+		return this.enqueue("getImport", [id]);
+	}
+	findImports(filter) {
+		return this.enqueue("findImports", [filter]);
+	}
 	close() {
 		if (!this.closePromise) {
 			this.closing = true;
@@ -1143,7 +1497,12 @@ function toGpx(tracks, now = /* @__PURE__ */ new Date()) {
 		for (const points of segments) {
 			lines.push("    <trkseg>");
 			for (const { position, timestamp } of points) {
-				lines.push(`      <trkpt lat="${coordinate(position[LAT])}" lon="${coordinate(position[LNG])}">`);
+				const at = `lat="${coordinate(position[LAT])}" lon="${coordinate(position[LNG])}"`;
+				if (timestamp === void 0) {
+					lines.push(`      <trkpt ${at}/>`);
+					continue;
+				}
+				lines.push(`      <trkpt ${at}>`);
 				lines.push(`        <time>${iso(timestamp)}</time>`);
 				lines.push("      </trkpt>");
 			}
@@ -1376,6 +1735,53 @@ function inRange(latitude, longitude) {
 	return Number.isFinite(latitude) && Number.isFinite(longitude) && latitude >= -90 && latitude <= 90 && longitude >= -180 && longitude <= 180;
 }
 //#endregion
+//#region src/upload.ts
+/** The largest GPX file the upload route reads, so one request cannot exhaust memory. */
+var MAX_UPLOAD_BYTES = 26214400;
+var UploadTooLargeError = class extends Error {
+	constructor(limit) {
+		super(`The file is larger than ${Math.round(limit / 1048576)} MB`);
+	}
+};
+/** A body the server already parsed as something other than a file. */
+var UploadTypeError = class extends Error {
+	constructor() {
+		super("Send the file as the request body, with Content-Type application/gpx+xml");
+	}
+};
+/** XML allows a byte-order mark, and the GPX parser does not skip one. */
+var withoutBom = (text) => text.startsWith("") ? text.slice(1) : text;
+/**
+* A request's body as UTF-8 text, refused past `limit` bytes.
+*
+* Read here rather than by a body parser because the server parses only JSON
+* and form bodies, and a GPX file arrives as XML. A body some other middleware
+* has already read as text is taken as it is; one it read as anything else is
+* refused, since the stream it came from is spent.
+*/
+function readText(req, limit = MAX_UPLOAD_BYTES) {
+	const parsed = req.body;
+	if (typeof parsed === "string") return Buffer.byteLength(parsed) > limit ? Promise.reject(new UploadTooLargeError(limit)) : Promise.resolve(withoutBom(parsed));
+	if (req.readableEnded) return Promise.reject(new UploadTypeError());
+	if (Number(req.headers["content-length"]) > limit) return Promise.reject(new UploadTooLargeError(limit));
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let size = 0;
+		req.on("data", (chunk) => {
+			size += chunk.length;
+			if (size > limit) {
+				reject(new UploadTooLargeError(limit));
+				req.removeAllListeners("data");
+				req.resume();
+				return;
+			}
+			chunks.push(chunk);
+		});
+		req.on("end", () => resolve(withoutBom(Buffer.concat(chunks).toString("utf8"))));
+		req.on("error", reject);
+	});
+}
+//#endregion
 //#region src/tracks.ts
 /**
 * The in-memory store: a bounded sliding window of positions per context, held
@@ -1539,9 +1945,13 @@ var fetchTrack = (context) => {
 };
 //#endregion
 //#region src/index.ts
+/** The plugin's id, which the server also uses as its Track API provider id. */
+var PLUGIN_ID = "tracks";
 var toLngLat = ([lat, lng]) => [lng, lat];
 var DEFAULT_RESOLUTION = 6e4;
 var DEFAULT_AIS_RETENTION_DAYS = 30;
+var DEFAULT_RECYCLE_BIN_DAYS = 180;
+var DAY_MS = 864e5;
 var PRUNE_INTERVAL_MS = 36e5;
 var DEFAULT_SEGMENT_GAP_MINUTES = 0;
 var SOURCE_STATUS_INTERVAL_MS = 3e4;
@@ -1893,6 +2303,45 @@ function ThePlugin(app) {
 	*/
 	let storageError;
 	let storeResolution = DEFAULT_RESOLUTION;
+	let binRetentionMs = DEFAULT_RECYCLE_BIN_DAYS * DAY_MS;
+	/**
+	* The deleted spans of recorded tracks by context, loaded once and dropped
+	* whenever a delete, restore or purge changes them. Read for every history
+	* reconciliation, which would otherwise ask the store each time.
+	*/
+	let deletedSpans;
+	/** A vessel's deleted spans, purged ones included. */
+	async function deletedSpansOf(context) {
+		const store = tracks;
+		if (!store?.deletedSpans) return [];
+		const loading = deletedSpans ??= Promise.resolve(store.deletedSpans()).then((spans) => {
+			const byContext = /* @__PURE__ */ new Map();
+			for (const { context: owner, ...span } of spans) byContext.set(owner, [...byContext.get(owner) ?? [], span]);
+			return byContext;
+		});
+		try {
+			return (await loading).get(context) ?? [];
+		} catch (err) {
+			if (deletedSpans === loading) deletedSpans = void 0;
+			throw err;
+		}
+	}
+	/**
+	* What history holds for a context, without what was deleted from it.
+	*
+	* The plugin cannot delete from a history provider, so a deleted span is
+	* cut out of every answer it gives; the store's own rows went to the
+	* recycle bin and are not read at all.
+	*/
+	async function visibleHistory(context, window, resolutionMs) {
+		const history = await historyPositions(app, context, window, resolutionMs, app.debug);
+		if (history.points.length === 0) return history;
+		const spans = await deletedSpansOf(context);
+		return spans.length === 0 ? history : {
+			...history,
+			points: outsideSpans(history.points, spans)
+		};
+	}
 	const sourceWatch = new SourceWatch();
 	let glitchFilter = new GlitchFilter({ maxSpeedKnots: 100 });
 	let stateGate = new StateGate(app.selfContext, DEFAULT_PAUSE_STATES);
@@ -1925,6 +2374,8 @@ function ThePlugin(app) {
 			storeResolution = toNumber(config.resolution) ?? DEFAULT_RESOLUTION;
 			const segmentGapMinutes = toNumber(config.segmentGapMinutes) ?? DEFAULT_SEGMENT_GAP_MINUTES;
 			segmentGap = segmentGapMinutes > 0 ? segmentGapMinutes * 60 * 1e3 : 0;
+			binRetentionMs = Math.max(1, toNumber(config.recycleBinDays) ?? DEFAULT_RECYCLE_BIN_DAYS) * DAY_MS;
+			deletedSpans = void 0;
 			glitchFilter = new GlitchFilter({ maxSpeedKnots: toNumber(config.maxSpeedKnots) ?? 100 });
 			stateGate = new StateGate(app.selfContext, Array.isArray(config.pauseWhenState) ? config.pauseWhenState : DEFAULT_PAUSE_STATES);
 			const dataDir = app.getDataDirPath?.();
@@ -1938,6 +2389,7 @@ function ThePlugin(app) {
 					file: join(dataDir, "tracks.db"),
 					resolution: toNumber(resolution) ?? DEFAULT_RESOLUTION,
 					retention: 0,
+					binRetention: binRetentionMs,
 					segmentGap
 				}, app.debug, (error) => {
 					if (tracks !== starting) return;
@@ -1991,9 +2443,13 @@ function ThePlugin(app) {
 				segmentGap: () => segmentGap,
 				contextName: (context) => contextName(context, remembering(() => tracks)),
 				historyContexts: (window) => historyContextsIn(app, window, app.debug, knownContexts),
+				historyKnows: (context) => historyKnowsContext(app, context, app.debug, knownContexts),
+				deleted: () => {
+					deletedSpans = void 0;
+				},
 				reconcileWithHistory: async (context, stored, window, resolutionMs) => {
 					const effective = resolutionMs ?? storeResolution;
-					return withHistory(await historyPositions(app, context, window ?? windowSpanning(stored, WINDOWLESS_HISTORY_SPAN_MS), effective, app.debug), stored);
+					return withHistory(await visibleHistory(context, window ?? windowSpanning(stored, WINDOWLESS_HISTORY_SPAN_MS), effective), stored);
 				}
 			}));
 			return starting.ready.catch(async () => {
@@ -2043,7 +2499,7 @@ function ThePlugin(app) {
 					points: [],
 					known: false
 				}));
-				const history = await historyPositions(app, context, query.window ?? windowSpanning(stored, WINDOWLESS_HISTORY_SPAN_MS), effectiveResolution, app.debug);
+				const history = await visibleHistory(context, query.window ?? windowSpanning(stored, WINDOWLESS_HISTORY_SPAN_MS), effectiveResolution);
 				const points = withHistory(history, stored);
 				if (points.length === 0) {
 					if (!(known || await historyKnowsContext(app, context, app.debug, knownContexts))) return;
@@ -2202,8 +2658,193 @@ function ThePlugin(app) {
 			router.get("/tracks/*", allTracksHandler);
 			return router;
 		},
+		registerWithRouter: function(router) {
+			/** An import as the webapp lists it, in the shape of a v2 track's properties. */
+			const importSummary = (track) => {
+				const name = track.context === void 0 ? void 0 : contextName(track.context, remembering(() => tracks));
+				let pointCount = 0;
+				let from = Infinity;
+				let to = -Infinity;
+				for (const segment of track.segments) for (const { timestamp } of segment) {
+					pointCount++;
+					if (timestamp !== void 0) {
+						from = Math.min(from, timestamp);
+						to = Math.max(to, timestamp);
+					}
+				}
+				return {
+					id: `${PLUGIN_ID}:${track.id}`,
+					providerId: PLUGIN_ID,
+					...track.name === void 0 ? {} : { name: track.name },
+					...track.context === void 0 ? {} : {
+						context: track.context,
+						isSelf: track.context === app.selfContext
+					},
+					...name === void 0 ? {} : { contextName: name },
+					...from > to ? {} : {
+						from: new Date(from).toISOString(),
+						to: new Date(to).toISOString()
+					},
+					pointCount
+				};
+			};
+			const binEntryJson = (entry) => {
+				const name = entry.context === void 0 ? void 0 : contextName(entry.context, remembering(() => tracks));
+				const iso = (ms) => ms === void 0 ? void 0 : new Date(ms).toISOString();
+				return {
+					id: entry.id,
+					trackId: entry.importId ?? recordedId(entry.context),
+					kind: entry.importId === void 0 ? "recorded" : "imported",
+					...entry.context === void 0 ? {} : {
+						context: entry.context,
+						isSelf: entry.context === app.selfContext
+					},
+					...name === void 0 ? {} : { contextName: name },
+					...entry.name === void 0 ? {} : { name: entry.name },
+					whole: entry.whole,
+					...entry.from === void 0 ? {} : { from: iso(entry.from) },
+					...entry.to === void 0 ? {} : { to: iso(entry.to) },
+					deletedAt: iso(entry.deletedAt),
+					purgeAt: iso(entry.deletedAt + binRetentionMs),
+					pointCount: entry.pointCount
+				};
+			};
+			/** The bin entry an `:id` names, or undefined after answering 400 or 404. */
+			const binStore = (req, res) => {
+				const store = tracks;
+				if (!store?.binEntries || !store.restoreFromBin || !store.purgeFromBin) {
+					notAvailable(res);
+					return;
+				}
+				const id = Number(req.params.id);
+				if (!Number.isSafeInteger(id) || id <= 0) {
+					res.status(400).json({ message: `Recycle bin entry '${req.params.id}' is not an id` });
+					return;
+				}
+				return {
+					store,
+					id
+				};
+			};
+			const failed = (res) => (err) => {
+				app.error(`Recycle bin: ${errorDetail(err)}`);
+				res.status(500).json({ message: "Track storage failed" });
+			};
+			const readable = router.access?.("readonly") ?? router;
+			readable.get("/imports", (_req, res) => {
+				const store = tracks;
+				if (!store?.findImports) {
+					notAvailable(res);
+					return;
+				}
+				Promise.resolve(store.findImports()).then((imports) => res.json(imports.map(importSummary))).catch((err) => {
+					app.error(`Listing imports: ${errorDetail(err)}`);
+					res.status(500).json({ message: "Track storage failed" });
+				});
+			});
+			(router.access?.("readwrite") ?? router).post("/imports", (req, res) => {
+				const store = tracks;
+				if (!store?.storeImport) {
+					notAvailable(res);
+					return;
+				}
+				const storeImport = store.storeImport.bind(store);
+				const context = req.query.self === "true" ? app.selfContext : void 0;
+				(async () => {
+					let text;
+					try {
+						text = await readText(req);
+					} catch (err) {
+						if (err instanceof UploadTooLargeError) res.status(413).json({ message: err.message });
+						else if (err instanceof UploadTypeError) res.status(415).json({ message: err.message });
+						else res.status(400).json({ message: "The file could not be read" });
+						return;
+					}
+					const read = fromGpx(text);
+					if (read.length === 0) {
+						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;
+					}
+					try {
+						for (const { track } of converted) await storeImport(track);
+					} 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}`),
+						skippedPoints: converted.reduce((sum, { skippedPoints }) => sum + skippedPoints, 0)
+					});
+				})();
+			});
+			readable.get("/imports/:id/track.gpx", (req, res) => {
+				const store = tracks;
+				if (!store?.getImport) {
+					notAvailable(res);
+					return;
+				}
+				const id = String(req.params.id);
+				if (!isImportedId(id)) {
+					res.status(404).json({ message: `No imported track '${id}'` });
+					return;
+				}
+				Promise.resolve(store.getImport(id)).then((track) => {
+					if (!track) {
+						res.status(404).json({ message: `No imported track '${id}'` });
+						return;
+					}
+					const label = track.name?.trim() || (track.context === void 0 ? "Imported track" : trackLabel(track.context, app.selfContext, remembering(() => tracks)));
+					const filename = gpxFilename(label);
+					res.type("application/gpx+xml");
+					res.setHeader("Content-Disposition", `attachment; filename="${asciiFilename(filename)}"; filename*=UTF-8''${rfc8187(filename)}`);
+					res.send(toGpx([{
+						name: label,
+						...track.context === void 0 ? {} : { context: track.context },
+						segments: track.segments
+					}]));
+				}).catch((err) => {
+					app.error(`Could not export GPX for ${id}: ${errorDetail(err)}`);
+					if (!res.headersSent) res.status(500).json({ message: `Could not export the track ${id}` });
+				});
+			});
+			router.get("/recycle-bin", (_req, res) => {
+				const store = tracks;
+				if (!store?.binEntries) {
+					notAvailable(res);
+					return;
+				}
+				Promise.resolve(store.binEntries()).then((entries) => res.json(entries.map(binEntryJson))).catch(failed(res));
+			});
+			router.post("/recycle-bin/:id/restore", (req, res) => {
+				const found = binStore(req, res);
+				if (!found) return;
+				Promise.resolve(found.store.restoreFromBin(found.id)).then((result) => {
+					deletedSpans = void 0;
+					if (result === "restored") res.json({});
+					else if (result === "missing") res.status(404).json({ message: "No such entry in the recycle bin" });
+					else res.status(409).json({ message: "The whole track is in the recycle bin too; restore it first" });
+				}).catch(failed(res));
+			});
+			router.delete("/recycle-bin/:id", (req, res) => {
+				const found = binStore(req, res);
+				if (!found) return;
+				Promise.resolve(found.store.purgeFromBin(found.id)).then((purged) => {
+					if (purged) res.json({});
+					else res.status(404).json({ message: "No such entry in the recycle bin" });
+				}).catch(failed(res));
+			});
+			return router;
+		},
 		getTracks: () => tracks,
-		id: "tracks",
+		id: PLUGIN_ID,
 		name: "Tracks",
 		enabledByDefault: true,
 		description: "Record vessel tracks to SQLite and serve them through the track API",
@@ -2229,6 +2870,13 @@ function ThePlugin(app) {
 					description: "A gap longer than this starts a new track segment, so a stop overnight or a spell out of AIS range does not draw a straight line across it. 0 (the default) returns the track as a single line, as before. Note that slow-updating AIS targets can legitimately go many minutes between fixes, so a low value will fragment their tracks.",
 					default: DEFAULT_SEGMENT_GAP_MINUTES
 				},
+				recycleBinDays: {
+					type: "integer",
+					minimum: 1,
+					title: "Days to keep a deleted track in the recycle bin",
+					description: "A deleted track, or part of one, can be restored from the recycle bin in the Tracks webapp until it is purged after this many days.",
+					default: DEFAULT_RECYCLE_BIN_DAYS
+				},
 				maxSpeedKnots: {
 					type: "integer",
 					title: "Discard positions implying a speed above this (knots)",