signalk-questdb 2.2.3 → 2.3.1

package/dist/gpx-import-session.d.ts

@@ -0,0 +1,69 @@
+import type { IncomingHttpHeaders } from "node:http";
+import type { GpxImportStatus } from "./api-contract.js";
+import type { GpxImport } from "./gpx-import.js";
+/** The largest slice one request may carry. */
+export declare const MAX_SLICE_BYTES: number;
+/** An import nobody has sent a slice to for this long is abandoned. */
+export declare const IDLE_TIMEOUT_MS: number;
+/** The request does not fit the import's state; carries where it stands. */
+export declare class GpxImportConflict extends Error {
+    readonly status: GpxImportStatus | null;
+    constructor(message: string, status: GpxImportStatus | null);
+}
+export declare class SliceTooLarge extends Error {
+}
+export declare class GpxImportSession {
+    readonly filename: string;
+    readonly size: number;
+    private readonly importer;
+    /** Resolves once QuestDB has applied everything the import wrote. */
+    private readonly applied;
+    private readonly now;
+    readonly id: `${string}-${string}-${string}-${string}-${string}`;
+    private state;
+    private received;
+    private error;
+    private busy;
+    private readonly startedAt;
+    private updatedAt;
+    private lastActivity;
+    constructor(filename: string, size: number, importer: GpxImport, 
+    /** Resolves once QuestDB has applied everything the import wrote. */
+    applied: () => Promise<void>, now?: () => number);
+    get status(): GpxImportStatus;
+    get active(): boolean;
+    /** Receiving, but nothing has arrived for IDLE_TIMEOUT_MS. */
+    get idle(): boolean;
+    append(offset: number, bytes: Uint8Array): Promise<GpxImportStatus>;
+    finish(): Promise<GpxImportStatus>;
+    /** End the import. What it already wrote stays; dedup absorbs a re-run. */
+    abort(reason?: string): void;
+    private expectReceiving;
+    private fail;
+    private touch;
+}
+/**
+ * One import at a time: they share the ILP writer, and two progress bars
+ * against one writer would tell the user nothing. The last import's status
+ * stays readable after it ends, so a panel opened later can show its result.
+ */
+export declare class GpxImports {
+    private current;
+    start(create: () => GpxImportSession): GpxImportSession;
+    get(id: string): GpxImportSession | null;
+    latest(): GpxImportStatus | null;
+    /** An import holds the writer: receiving, or finishing what it received. */
+    get active(): boolean;
+    /** The plugin is stopping: the writer the import uses is going away. */
+    abortAll(): void;
+    private reapIdle;
+}
+/**
+ * The body of a slice request, refused past `limit` bytes. Read here rather
+ * than by a body parser: signalk-server parses JSON and form bodies only, so
+ * an octet-stream arrives untouched.
+ */
+export declare function readSlice(req: NodeJS.ReadableStream & {
+    headers: IncomingHttpHeaders;
+    readableEnded?: boolean;
+}, limit?: number): Promise<Buffer>;

package/dist/gpx-import-session.js

@@ -0,0 +1,218 @@
+// The upload side of a GPX import: the file arrives as numbered slices over
+// several requests, because one request carrying 1.5 GB outlasts Node's
+// five-minute request timeout on a boat's Wi-Fi and is refused by any proxy
+// with a body limit. Each slice names the byte offset it starts at, so a
+// client that lost a reply can ask where to resume instead of guessing, and a
+// slice sent twice is refused rather than imported twice.
+//
+// A slice's reply waits until its points are with the writer and the writer
+// has room again. That is the whole flow control: the browser sends the next
+// slice only when the server is ready for it.
+import { randomUUID } from "node:crypto";
+/** The largest slice one request may carry. */
+export const MAX_SLICE_BYTES = 8 * 1024 * 1024;
+/** An import nobody has sent a slice to for this long is abandoned. */
+export const IDLE_TIMEOUT_MS = 15 * 60 * 1000;
+/** The request does not fit the import's state; carries where it stands. */
+export class GpxImportConflict extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+export class SliceTooLarge extends Error {
+}
+export class GpxImportSession {
+    filename;
+    size;
+    importer;
+    applied;
+    now;
+    id = randomUUID();
+    state = "receiving";
+    received = 0;
+    error;
+    busy = false;
+    startedAt;
+    updatedAt;
+    lastActivity;
+    constructor(filename, size, importer, 
+    /** Resolves once QuestDB has applied everything the import wrote. */
+    applied, now = Date.now) {
+        this.filename = filename;
+        this.size = size;
+        this.importer = importer;
+        this.applied = applied;
+        this.now = now;
+        this.lastActivity = now();
+        this.startedAt = new Date(this.lastActivity).toISOString();
+        this.updatedAt = this.startedAt;
+    }
+    get status() {
+        return {
+            id: this.id,
+            filename: this.filename,
+            size: this.size,
+            received: this.received,
+            state: this.state,
+            summary: { ...this.importer.summary },
+            ...(this.error !== undefined ? { error: this.error } : {}),
+            startedAt: this.startedAt,
+            updatedAt: this.updatedAt,
+        };
+    }
+    get active() {
+        return this.state === "receiving" || this.state === "finishing";
+    }
+    /** Receiving, but nothing has arrived for IDLE_TIMEOUT_MS. */
+    get idle() {
+        return (this.state === "receiving" &&
+            !this.busy &&
+            this.now() - this.lastActivity > IDLE_TIMEOUT_MS);
+    }
+    async append(offset, bytes) {
+        this.expectReceiving();
+        if (offset !== this.received) {
+            throw new GpxImportConflict(`The next slice starts at byte ${this.received}, not ${offset}`, this.status);
+        }
+        if (this.received + bytes.length > this.size) {
+            throw new GpxImportConflict(`The slice runs past the announced size of ${this.size} bytes`, this.status);
+        }
+        this.busy = true;
+        try {
+            await this.importer.write(bytes);
+            this.received += bytes.length;
+        }
+        catch (err) {
+            this.fail(err);
+            throw err;
+        }
+        finally {
+            this.busy = false;
+            this.touch();
+        }
+        return this.status;
+    }
+    async finish() {
+        this.expectReceiving();
+        if (this.received !== this.size) {
+            throw new GpxImportConflict(`Only ${this.received} of ${this.size} bytes have arrived`, this.status);
+        }
+        this.state = "finishing";
+        this.busy = true;
+        this.touch();
+        try {
+            await this.importer.finish();
+            await this.applied();
+            // An abort while finishing has the last word.
+            if (this.state === "finishing")
+                this.state = "finished";
+        }
+        catch (err) {
+            this.fail(err);
+            throw err;
+        }
+        finally {
+            this.busy = false;
+            this.touch();
+        }
+        return this.status;
+    }
+    /** End the import. What it already wrote stays; dedup absorbs a re-run. */
+    abort(reason = "Aborted") {
+        if (!this.active)
+            return;
+        this.importer.cancel();
+        this.state = "aborted";
+        this.error = reason;
+        this.touch();
+    }
+    expectReceiving() {
+        if (this.state !== "receiving") {
+            throw new GpxImportConflict(`The import is ${this.state}`, this.status);
+        }
+        if (this.busy) {
+            throw new GpxImportConflict("The previous slice is still being imported", this.status);
+        }
+    }
+    fail(err) {
+        // An abort already set the final state and its reason.
+        if (this.state === "aborted")
+            return;
+        this.state = "failed";
+        this.error = err instanceof Error ? err.message : String(err);
+    }
+    touch() {
+        this.lastActivity = this.now();
+        this.updatedAt = new Date(this.lastActivity).toISOString();
+    }
+}
+/**
+ * One import at a time: they share the ILP writer, and two progress bars
+ * against one writer would tell the user nothing. The last import's status
+ * stays readable after it ends, so a panel opened later can show its result.
+ */
+export class GpxImports {
+    current = null;
+    start(create) {
+        this.reapIdle();
+        if (this.current?.active) {
+            throw new GpxImportConflict("A GPX import is already running", this.current.status);
+        }
+        this.current = create();
+        return this.current;
+    }
+    get(id) {
+        this.reapIdle();
+        return this.current?.id === id ? this.current : null;
+    }
+    latest() {
+        this.reapIdle();
+        return this.current?.status ?? null;
+    }
+    /** An import holds the writer: receiving, or finishing what it received. */
+    get active() {
+        this.reapIdle();
+        return this.current?.active ?? false;
+    }
+    /** The plugin is stopping: the writer the import uses is going away. */
+    abortAll() {
+        this.current?.abort("The plugin stopped");
+    }
+    reapIdle() {
+        if (this.current?.idle) {
+            this.current.abort(`No slice arrived for ${IDLE_TIMEOUT_MS / 60000} minutes`);
+        }
+    }
+}
+/**
+ * The body of a slice request, refused past `limit` bytes. Read here rather
+ * than by a body parser: signalk-server parses JSON and form bodies only, so
+ * an octet-stream arrives untouched.
+ */
+export function readSlice(req, limit = MAX_SLICE_BYTES) {
+    if (Number(req.headers["content-length"]) > limit) {
+        return Promise.reject(new SliceTooLarge(`A slice is at most ${limit} bytes`));
+    }
+    if (req.readableEnded) {
+        return Promise.reject(new Error("The request body was already read"));
+    }
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                reject(new SliceTooLarge(`A slice is at most ${limit} bytes`));
+                req.removeAllListeners("data");
+                req.resume();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+//# sourceMappingURL=gpx-import-session.js.map

package/dist/gpx-import-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpx-import-session.js","sourceRoot":"","sources":["../src/gpx-import-session.ts"],"names":[],"mappings":"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"}

package/dist/gpx-import.d.ts

@@ -0,0 +1,135 @@
+import type { QueryClient } from "./query-client.js";
+import type { ILPWriter } from "./ilp-writer.js";
+import type { GpxImportSummary } from "./api-contract.js";
+import { type ArchiveReader } from "./archive.js";
+/** The sourceRef imported positions are stored under. */
+export declare const IMPORT_SOURCE = "import.gpx";
+/**
+ * An attribute as an `xsd:decimal`, or NaN. `Number()` reads `0x10` and
+ * `1e1` too, which GPX does not allow and no exporter means.
+ */
+export declare function gpxDecimal(value: string | undefined): number;
+/**
+ * A `<time>` as epoch milliseconds, or NaN. GPX types it `xsd:dateTime`;
+ * `Date.parse` alone takes a bare year and rolls February 30th into March.
+ */
+export declare function gpxDateTime(value: string): number;
+/**
+ * A longitude brought into [-180, 180], or NaN when it is not one.
+ *
+ * Crossing the antimeridian, TimeZero writes the fixes just past it as
+ * -180.00002 rather than 179.99998. Those are real positions, so they are
+ * wrapped; a value beyond a full turn is not a position at all.
+ */
+export declare function antimeridian(longitude: number): number;
+export interface GpxImportOptions {
+    /**
+     * Names of the tracks to import, "" for a track without one.
+     *
+     * GPX has no field that says whose a track is, and a chartplotter's export
+     * mixes the own track with AIS targets and with passages imported from
+     * elsewhere — a TimeZero export put another boat's Fiji passage on the same
+     * day as the own track in Polynesia. Written into one series, those draw a
+     * line across the ocean, so the caller says which tracks are the vessel's.
+     */
+    tracks: ReadonlySet<string>;
+    /** One row per this many seconds; 0 keeps every point's own time. */
+    resolutionSeconds: number;
+    /** Write one own-vessel position, stamped `ms`. */
+    write(ms: number, latitude: number, longitude: number): void;
+    /** Resolves once the writer can take more; rejects if it never will. */
+    backpressure(): Promise<void>;
+    /**
+     * The five-minute intervals of a UTC day (by `floor(ms / 5 min)`) in which
+     * the vessel already has positions. Absent, every point is imported.
+     */
+    recorded?: (dayStartMs: number) => Promise<ReadonlySet<number>>;
+}
+/** The document is not well-formed XML; rows before the error are kept. */
+export declare class GpxParseError extends Error {
+}
+/** The import was aborted while a slice was being written. */
+export declare class GpxImportCancelled extends Error {
+}
+/**
+ * One import, fed the document slice by slice.
+ *
+ * Only GPX's own structure counts: a `trk` under `gpx`, a `trkseg` under it,
+ * a `trkpt` under that. A vendor `<trkseg>` inside `<extensions>` is not a
+ * segment, and a `<name>` inside a point is not the track's name.
+ */
+export declare class GpxImport {
+    private readonly options;
+    readonly summary: GpxImportSummary;
+    private readonly parser;
+    private readonly decoder;
+    private parseError;
+    private cancelled;
+    private readonly path;
+    private trackName;
+    private nameText;
+    private selected;
+    private segment;
+    private point;
+    private timeText;
+    private pending;
+    private lastSegment;
+    private last;
+    private lastBucket;
+    private readonly coverage;
+    private coveredDay;
+    private covered;
+    constructor(options: GpxImportOptions);
+    /**
+     * The instant of the row written last, or null before the first. Not
+     * `summary.to`: an export out of time order writes its latest row early.
+     */
+    get lastWritten(): number | null;
+    /** Stop writing: the slice in progress ends at its next point. */
+    cancel(): void;
+    /** Parse the next bytes of the document and write the points they hold. */
+    write(chunk: Uint8Array): Promise<void>;
+    /** The document has ended: anything left unclosed is an error. */
+    finish(): Promise<GpxImportSummary>;
+    private parse;
+    private throwParseError;
+    private at;
+    private open;
+    private text;
+    private close;
+    private name;
+    private recordedIn;
+    private drain;
+}
+type ImportWriter = Pick<ILPWriter, "pendingLines" | "enqueuedLineCount" | "settledLineCount" | "droppedLineCount">;
+/**
+ * What an import needs from the shared ILP writer: to wait while it is full,
+ * to know when everything written has left it, and to notice when it had to
+ * drop lines, which may have been the import's.
+ */
+export declare class WriterGate {
+    private readonly writer;
+    private readonly pollMs;
+    private readonly timeoutMs;
+    private readonly droppedAtStart;
+    constructor(writer: ImportWriter, pollMs?: number, timeoutMs?: number);
+    /** Resolves once the writer has room; rejects if it does not drain. */
+    room(): Promise<void>;
+    /** Resolves once every line enqueued so far has left the writer. */
+    settled(): Promise<void>;
+    private until;
+    private checkDrops;
+}
+/**
+ * The five-minute intervals of a day in which the own vessel has positions
+ * that did not come from an import, read from the base table and, where it
+ * covers the day, the archive.
+ */
+export declare function recordedIntervals(queryClient: Pick<QueryClient, "exec">, archive: ArchiveReader): (dayStartMs: number) => Promise<ReadonlySet<number>>;
+/**
+ * Wait until the imported row stamped `ms` reads back from the archive.
+ * Readable means QuestDB committed and applied it, and with it every row the
+ * writer sent before.
+ */
+export declare function waitForImportedRow(queryClient: Pick<QueryClient, "exec">, ms: number, timeoutMs: number, pollMs?: number): Promise<void>;
+export {};