@aurora-blue/signalk-connector 0.2.0-dev.20

package/dist/src/state-store.js

@@ -0,0 +1,491 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StateStore = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const types_1 = require("./types");
+const METADATA_FILE = "metadata.json";
+const LEGACY_STATE_FILE = "state.json";
+const LEGACY_BACKUP_FILE = "state.v1.backup.json";
+const SEGMENT_PATTERN = /^segment-(\d{12})\.jsonl$/;
+const initialState = () => ({
+    version: 2,
+    protocol_version: types_1.PROTOCOL_VERSION,
+    device_id: null,
+    access_token: null,
+    next_sequence: 1,
+    accepted_through: 0,
+    events: [],
+    pending_batch: null,
+    last_success_at: null,
+    operating_mode: "active",
+});
+const isPositiveInteger = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0;
+const isSupportedProtocolVersion = (value) => typeof value === "string" &&
+    types_1.SUPPORTED_PROTOCOL_VERSIONS.some((version) => version === value);
+const isOperatingMode = (value) => value === "active" || value === "standby" || value === "disabled";
+const assertState = (state) => {
+    if (state.version !== 2 ||
+        !isSupportedProtocolVersion(state.protocol_version) ||
+        !isPositiveInteger(state.accepted_through) ||
+        !isPositiveInteger(state.next_sequence) ||
+        state.next_sequence < 1 ||
+        !Array.isArray(state.events) ||
+        !isOperatingMode(state.operating_mode) ||
+        (state.device_id === null) !== (state.access_token === null)) {
+        throw new Error("Aurora Blue connector state is invalid.");
+    }
+    const expectedFirst = state.accepted_through + 1;
+    for (const [index, event] of state.events.entries()) {
+        if (event.sequence !== expectedFirst + index) {
+            throw new Error("Aurora Blue connector event sequence is not contiguous.");
+        }
+    }
+    const expectedNext = expectedFirst + state.events.length;
+    if (state.next_sequence !== expectedNext) {
+        throw new Error("Aurora Blue connector next sequence is inconsistent.");
+    }
+    if (state.pending_batch !== null) {
+        const pending = state.pending_batch;
+        const expectedEvents = state.events.slice(0, pending.events.length);
+        if (!isSupportedProtocolVersion(pending.protocol_version) ||
+            pending.device_id !== state.device_id ||
+            expectedEvents.length !== pending.events.length ||
+            pending.first_sequence !== pending.events[0]?.sequence ||
+            pending.last_sequence !== pending.events.at(-1)?.sequence ||
+            expectedEvents.some((event, index) => event.sequence !== pending.events[index]?.sequence)) {
+            throw new Error("Aurora Blue connector pending batch is inconsistent.");
+        }
+    }
+};
+const assertLegacyState = (state) => {
+    assertState({
+        ...state,
+        version: 2,
+        operating_mode: isOperatingMode(state.operating_mode)
+            ? state.operating_mode
+            : "active",
+    });
+};
+const checksum = (event) => (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(event)).digest("hex");
+const encodeRecord = (event) => `${JSON.stringify({ checksum: checksum(event), event })}\n`;
+const metadataFrom = (state) => ({
+    version: 2,
+    protocol_version: state.protocol_version,
+    device_id: state.device_id,
+    access_token: state.access_token,
+    next_sequence: state.next_sequence,
+    accepted_through: state.accepted_through,
+    pending_batch: state.pending_batch,
+    last_success_at: state.last_success_at,
+    operating_mode: state.operating_mode,
+});
+class StateStore {
+    directory;
+    metadataPath;
+    now;
+    uuid;
+    segmentMaximumBytes;
+    capacityProvider;
+    state = initialState();
+    segments = [];
+    journalBytes = 0;
+    tail = Promise.resolve();
+    constructor(directory, options = {}) {
+        this.directory = directory;
+        this.metadataPath = (0, node_path_1.join)(directory, METADATA_FILE);
+        this.now = options.now ?? (() => new Date().toISOString());
+        this.uuid = options.uuid ?? node_crypto_1.randomUUID;
+        this.segmentMaximumBytes = options.segmentMaximumBytes ?? 256 * 1024;
+        this.capacityProvider =
+            options.filesystemCapacity ?? (() => this.readFilesystemCapacity());
+    }
+    async load() {
+        await (0, promises_1.mkdir)(this.directory, { recursive: true, mode: 0o700 });
+        await (0, promises_1.chmod)(this.directory, 0o700);
+        if (!(await this.exists(this.metadataPath))) {
+            const legacyPath = (0, node_path_1.join)(this.directory, LEGACY_STATE_FILE);
+            if (await this.exists(legacyPath)) {
+                await this.migrateLegacy(legacyPath);
+            }
+            else {
+                this.state = initialState();
+                await this.persistMetadata();
+            }
+        }
+        const metadata = await this.readMetadata();
+        const journal = await this.readJournal(metadata.accepted_through);
+        this.state = {
+            ...metadata,
+            protocol_version: types_1.PROTOCOL_VERSION,
+            events: journal,
+            next_sequence: metadata.accepted_through + journal.length + 1,
+        };
+        assertState(this.state);
+        await (0, promises_1.chmod)(this.metadataPath, 0o600);
+        await this.removeAcknowledgedSegments(this.state.accepted_through);
+        await this.preserveLegacyBackup();
+        await this.removeStaleTemporaryFiles();
+        if (metadata.protocol_version !== types_1.PROTOCOL_VERSION) {
+            await this.persistMetadata();
+        }
+    }
+    async snapshot() {
+        await this.tail;
+        return structuredClone(this.state);
+    }
+    async summary() {
+        await this.tail;
+        const { pending_batch: _, ...metadata } = metadataFrom(this.state);
+        return { ...metadata, bufferedEvents: this.state.events.length };
+    }
+    async journalMetrics() {
+        await this.tail;
+        return {
+            events: this.state.events.length,
+            bytes: this.journalBytes,
+            averageRecordBytes: this.state.events.length === 0
+                ? null
+                : this.journalBytes / this.state.events.length,
+        };
+    }
+    async filesystemCapacity() {
+        await this.tail;
+        return this.capacityProvider();
+    }
+    async setPairing(pairing) {
+        await this.serialized(async () => {
+            if (this.state.device_id !== null || this.state.events.length > 0) {
+                throw new Error("Connector is already paired or contains buffered events.");
+            }
+            this.state.device_id = pairing.device_id;
+            this.state.access_token = pairing.access_token;
+            this.state.operating_mode = pairing.runtime_configuration.operating_mode;
+            await this.persistMetadata();
+        });
+    }
+    async setOperatingMode(operatingMode) {
+        await this.serialized(async () => {
+            this.state.operating_mode = operatingMode;
+            await this.persistMetadata();
+        });
+    }
+    async append(event, eventLimit, byteLimit = Number.MAX_SAFE_INTEGER) {
+        let result = null;
+        await this.serialized(async () => {
+            if (this.state.device_id === null || this.state.access_token === null) {
+                throw new Error("Connector must be paired before buffering events.");
+            }
+            const buffered = { ...event, sequence: this.state.next_sequence };
+            const payload = encodeRecord(buffered);
+            const payloadBytes = Buffer.byteLength(payload);
+            if (this.state.events.length >= eventLimit ||
+                this.journalBytes + payloadBytes > byteLimit) {
+                return;
+            }
+            await this.appendRecord(buffered, payload, payloadBytes);
+            this.state.events.push(buffered);
+            this.state.next_sequence += 1;
+            // load() validates the complete journal. This append preserves its
+            // contiguous sequence without rescanning every previous record.
+            result = structuredClone(buffered);
+        });
+        return result;
+    }
+    async pendingBatch(maximumEvents) {
+        let result = null;
+        await this.serialized(async () => {
+            if (this.state.pending_batch !== null) {
+                result = structuredClone(this.state.pending_batch);
+                return;
+            }
+            if (this.state.device_id === null || this.state.events.length === 0) {
+                return;
+            }
+            const firstBoot = this.state.events[0]?.boot_id;
+            const selected = [];
+            for (const event of this.state.events.slice(0, maximumEvents)) {
+                if (event.boot_id !== firstBoot) {
+                    break;
+                }
+                selected.push(event);
+            }
+            if (selected.length === 0 || firstBoot === undefined) {
+                return;
+            }
+            const events = selected.map(({ boot_id: _, ...event }) => event);
+            const firstSequence = events[0]?.sequence;
+            const lastSequence = events.at(-1)?.sequence;
+            if (firstSequence === undefined || lastSequence === undefined) {
+                return;
+            }
+            this.state.pending_batch = {
+                protocol_version: types_1.PROTOCOL_VERSION,
+                device_id: this.state.device_id,
+                boot_id: firstBoot,
+                batch_id: this.uuid(),
+                first_sequence: firstSequence,
+                last_sequence: lastSequence,
+                created_at: this.now(),
+                events,
+            };
+            assertState(this.state);
+            await this.persistMetadata();
+            result = structuredClone(this.state.pending_batch);
+        });
+        return result;
+    }
+    async acknowledge(acceptedThrough) {
+        await this.serialized(async () => {
+            const pending = this.state.pending_batch;
+            if (pending === null || acceptedThrough !== pending.last_sequence) {
+                throw new Error("Aurora Blue acknowledgement does not match the pending batch.");
+            }
+            this.state.events = this.state.events.filter((event) => event.sequence > acceptedThrough);
+            this.state.accepted_through = acceptedThrough;
+            this.state.pending_batch = null;
+            this.state.last_success_at = this.now();
+            assertState(this.state);
+            await this.persistMetadata();
+            await this.removeAcknowledgedSegments(acceptedThrough);
+        });
+    }
+    async serialized(operation) {
+        const current = this.tail.then(operation);
+        this.tail = current.catch(() => undefined);
+        await current;
+    }
+    async appendRecord(event, payload, payloadBytes) {
+        let segment = this.segments.at(-1);
+        if (segment === undefined ||
+            (segment.bytes > 0 &&
+                segment.bytes + payloadBytes > this.segmentMaximumBytes)) {
+            const path = (0, node_path_1.join)(this.directory, `segment-${String(event.sequence).padStart(12, "0")}.jsonl`);
+            segment = {
+                path,
+                firstSequence: event.sequence,
+                lastSequence: event.sequence - 1,
+                bytes: 0,
+            };
+            this.segments.push(segment);
+        }
+        const file = await (0, promises_1.open)(segment.path, "a", 0o600);
+        try {
+            await file.writeFile(payload, "utf8");
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await (0, promises_1.chmod)(segment.path, 0o600);
+        segment.lastSequence = event.sequence;
+        segment.bytes += payloadBytes;
+        this.journalBytes += payloadBytes;
+    }
+    async readMetadata() {
+        let parsed;
+        try {
+            parsed = JSON.parse(await (0, promises_1.readFile)(this.metadataPath, "utf8"));
+        }
+        catch (error) {
+            throw new Error("Aurora Blue connector metadata cannot be read safely.", {
+                cause: error,
+            });
+        }
+        const parsedMetadata = parsed;
+        const metadata = {
+            ...parsedMetadata,
+            operating_mode: isOperatingMode(parsedMetadata.operating_mode)
+                ? parsedMetadata.operating_mode
+                : "active",
+        };
+        if (metadata.version !== 2 ||
+            !isSupportedProtocolVersion(metadata.protocol_version) ||
+            !isPositiveInteger(metadata.accepted_through) ||
+            !isPositiveInteger(metadata.next_sequence) ||
+            !isOperatingMode(metadata.operating_mode) ||
+            (metadata.device_id === null) !== (metadata.access_token === null)) {
+            throw new Error("Aurora Blue connector metadata is invalid.");
+        }
+        return metadata;
+    }
+    async readJournal(acceptedThrough) {
+        const names = (await (0, promises_1.readdir)(this.directory))
+            .filter((name) => SEGMENT_PATTERN.test(name))
+            .sort();
+        const events = [];
+        this.segments = [];
+        this.journalBytes = 0;
+        for (const name of names) {
+            const match = SEGMENT_PATTERN.exec(name);
+            if (match === null) {
+                continue;
+            }
+            const path = (0, node_path_1.join)(this.directory, name);
+            const segmentEvents = await this.readSegment(path);
+            const details = await (0, promises_1.stat)(path);
+            const firstSequence = Number(match[1]);
+            const lastSequence = segmentEvents.at(-1)?.sequence ?? firstSequence - 1;
+            this.segments.push({
+                path,
+                firstSequence,
+                lastSequence,
+                bytes: details.size,
+            });
+            this.journalBytes += details.size;
+            events.push(...segmentEvents.filter((event) => event.sequence > acceptedThrough));
+        }
+        return events;
+    }
+    async readSegment(path) {
+        let payload = await (0, promises_1.readFile)(path, "utf8");
+        if (payload !== "" && !payload.endsWith("\n")) {
+            const lastComplete = payload.lastIndexOf("\n") + 1;
+            await (0, promises_1.truncate)(path, Buffer.byteLength(payload.slice(0, lastComplete)));
+            payload = payload.slice(0, lastComplete);
+        }
+        const events = [];
+        for (const line of payload.split("\n")) {
+            if (line === "") {
+                continue;
+            }
+            let record;
+            try {
+                record = JSON.parse(line);
+            }
+            catch (error) {
+                throw new Error("Aurora Blue connector journal is corrupted.", {
+                    cause: error,
+                });
+            }
+            if (typeof record.checksum !== "string" ||
+                record.event === null ||
+                typeof record.event !== "object" ||
+                checksum(record.event) !== record.checksum) {
+                throw new Error("Aurora Blue connector journal checksum is invalid.");
+            }
+            events.push(record.event);
+        }
+        return events;
+    }
+    async removeAcknowledgedSegments(acceptedThrough) {
+        const retained = [];
+        for (const segment of this.segments) {
+            if (segment.lastSequence >= segment.firstSequence &&
+                segment.lastSequence <= acceptedThrough) {
+                await (0, promises_1.unlink)(segment.path);
+                this.journalBytes -= segment.bytes;
+            }
+            else {
+                retained.push(segment);
+            }
+        }
+        this.segments = retained;
+    }
+    async migrateLegacy(path) {
+        let legacy;
+        try {
+            legacy = JSON.parse(await (0, promises_1.readFile)(path, "utf8"));
+            assertLegacyState(legacy);
+        }
+        catch (error) {
+            throw new Error("Legacy Aurora Blue connector state is invalid.", {
+                cause: error,
+            });
+        }
+        for (const name of await (0, promises_1.readdir)(this.directory)) {
+            if (SEGMENT_PATTERN.test(name)) {
+                await (0, promises_1.unlink)((0, node_path_1.join)(this.directory, name));
+            }
+        }
+        this.segments = [];
+        this.journalBytes = 0;
+        this.state = {
+            ...legacy,
+            version: 2,
+            protocol_version: types_1.PROTOCOL_VERSION,
+            operating_mode: isOperatingMode(legacy.operating_mode)
+                ? legacy.operating_mode
+                : "active",
+        };
+        for (const event of legacy.events) {
+            const payload = encodeRecord(event);
+            await this.appendRecord(event, payload, Buffer.byteLength(payload));
+        }
+        await this.persistMetadata();
+        await (0, promises_1.rename)(path, (0, node_path_1.join)(this.directory, LEGACY_BACKUP_FILE));
+    }
+    async preserveLegacyBackup() {
+        const legacyPath = (0, node_path_1.join)(this.directory, LEGACY_STATE_FILE);
+        const backupPath = (0, node_path_1.join)(this.directory, LEGACY_BACKUP_FILE);
+        if ((await this.exists(legacyPath)) && !(await this.exists(backupPath))) {
+            await (0, promises_1.rename)(legacyPath, backupPath);
+        }
+    }
+    async removeStaleTemporaryFiles() {
+        for (const name of await (0, promises_1.readdir)(this.directory)) {
+            if (/^\.(?:state|metadata)-.+\.tmp$/.test(name)) {
+                await (0, promises_1.unlink)((0, node_path_1.join)(this.directory, name));
+            }
+        }
+    }
+    async persistMetadata() {
+        const temporaryPath = (0, node_path_1.join)(this.directory, `.metadata-${this.uuid()}.tmp`);
+        const payload = `${JSON.stringify(metadataFrom(this.state))}\n`;
+        await (0, promises_1.writeFile)(temporaryPath, payload, {
+            encoding: "utf8",
+            flag: "wx",
+            mode: 0o600,
+        });
+        const temporary = await (0, promises_1.open)(temporaryPath, "r");
+        try {
+            await temporary.sync();
+        }
+        finally {
+            await temporary.close();
+        }
+        await (0, promises_1.rename)(temporaryPath, this.metadataPath);
+        await (0, promises_1.chmod)(this.metadataPath, 0o600);
+        try {
+            const directory = await (0, promises_1.open)(this.directory, "r");
+            try {
+                await directory.sync();
+            }
+            finally {
+                await directory.close();
+            }
+        }
+        catch {
+            // Directory fsync is not available on every supported platform.
+        }
+    }
+    async exists(path) {
+        try {
+            await (0, promises_1.access)(path, node_fs_1.constants.F_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async readFilesystemCapacity() {
+        try {
+            const details = await (0, promises_1.statfs)(this.directory);
+            const totalBytes = details.blocks * details.bsize;
+            const freeBytes = details.bavail * details.bsize;
+            if (!Number.isFinite(totalBytes) ||
+                !Number.isFinite(freeBytes) ||
+                totalBytes <= 0 ||
+                freeBytes < 0) {
+                return null;
+            }
+            return { totalBytes, freeBytes };
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.StateStore = StateStore;

package/dist/src/storage-budget.d.ts

@@ -0,0 +1,35 @@
+export type StorageProfile = "auto" | "constrained" | "standard" | "extended" | "custom";
+export type ResolvedStorageProfile = Exclude<StorageProfile, "auto">;
+export type BufferPressure = "normal" | "elevated" | "critical" | "emergency";
+export interface FilesystemCapacity {
+    totalBytes: number;
+    freeBytes: number;
+}
+export interface JournalMetrics {
+    events: number;
+    bytes: number;
+    averageRecordBytes: number | null;
+}
+export interface StorageBudgetPolicy {
+    requestedProfile: StorageProfile;
+    customMaximumBytes: number;
+    customReserveBytes: number;
+    customMaximumFraction: number;
+    eventSafetyLimit: number;
+}
+export interface StorageBudget {
+    requestedProfile: StorageProfile;
+    resolvedProfile: ResolvedStorageProfile;
+    byteLimit: number;
+    eventLimit: number;
+    reserveBytes: number;
+    maximumFraction: number;
+    utilization: number;
+    pressure: BufferPressure;
+    remainingBytes: number;
+    remainingEvents: number;
+    averageRecordBytes: number;
+    filesystem: FilesystemCapacity | null;
+}
+export declare const pressureForUtilization: (utilization: number) => BufferPressure;
+export declare const resolveStorageBudget: (policy: StorageBudgetPolicy, journal: JournalMetrics, filesystem: FilesystemCapacity | null) => StorageBudget;

package/dist/src/storage-budget.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveStorageBudget = exports.pressureForUtilization = void 0;
+const MEBIBYTE = 1024 * 1024;
+const GIBIBYTE = 1024 * MEBIBYTE;
+const ASSUMED_RECORD_BYTES = 384;
+const PROFILE_POLICIES = {
+    constrained: {
+        maximumBytes: 16 * MEBIBYTE,
+        reserveBytes: 128 * MEBIBYTE,
+        maximumFraction: 0.02,
+    },
+    standard: {
+        maximumBytes: 64 * MEBIBYTE,
+        reserveBytes: 256 * MEBIBYTE,
+        maximumFraction: 0.03,
+    },
+    extended: {
+        maximumBytes: 256 * MEBIBYTE,
+        reserveBytes: 512 * MEBIBYTE,
+        maximumFraction: 0.05,
+    },
+};
+const autoProfile = (filesystem) => {
+    if (filesystem === null || filesystem.totalBytes <= 8 * GIBIBYTE) {
+        return "constrained";
+    }
+    return filesystem.totalBytes <= 128 * GIBIBYTE ? "standard" : "extended";
+};
+const profilePolicy = (policy, filesystem) => {
+    const resolvedProfile = policy.requestedProfile === "auto"
+        ? autoProfile(filesystem)
+        : policy.requestedProfile;
+    if (resolvedProfile === "custom") {
+        return {
+            resolvedProfile,
+            limits: {
+                maximumBytes: policy.customMaximumBytes,
+                reserveBytes: policy.customReserveBytes,
+                maximumFraction: policy.customMaximumFraction,
+            },
+        };
+    }
+    return { resolvedProfile, limits: PROFILE_POLICIES[resolvedProfile] };
+};
+const pressureForUtilization = (utilization) => {
+    if (utilization >= 0.9) {
+        return "emergency";
+    }
+    if (utilization >= 0.75) {
+        return "critical";
+    }
+    return utilization >= 0.5 ? "elevated" : "normal";
+};
+exports.pressureForUtilization = pressureForUtilization;
+const resolveStorageBudget = (policy, journal, filesystem) => {
+    const { resolvedProfile, limits } = profilePolicy(policy, filesystem);
+    let byteLimit = limits.maximumBytes;
+    if (filesystem !== null) {
+        const fractionLimit = Math.floor(filesystem.totalBytes * limits.maximumFraction);
+        const reserveLimit = Math.max(0, filesystem.freeBytes + journal.bytes - limits.reserveBytes);
+        byteLimit = Math.min(byteLimit, fractionLimit, reserveLimit);
+    }
+    byteLimit = Math.max(journal.bytes, Math.floor(byteLimit), 1);
+    const averageRecordBytes = journal.averageRecordBytes === null || journal.averageRecordBytes <= 0
+        ? ASSUMED_RECORD_BYTES
+        : journal.averageRecordBytes;
+    const byteDerivedEventLimit = Math.max(1, Math.floor(byteLimit / averageRecordBytes));
+    const eventLimit = Math.max(journal.events, Math.min(policy.eventSafetyLimit, byteDerivedEventLimit));
+    const byteUtilization = journal.bytes / byteLimit;
+    const eventUtilization = journal.events / eventLimit;
+    const utilization = Math.min(1, Math.max(byteUtilization, eventUtilization));
+    return {
+        requestedProfile: policy.requestedProfile,
+        resolvedProfile,
+        byteLimit,
+        eventLimit,
+        reserveBytes: limits.reserveBytes,
+        maximumFraction: limits.maximumFraction,
+        utilization,
+        pressure: (0, exports.pressureForUtilization)(utilization),
+        remainingBytes: Math.max(0, byteLimit - journal.bytes),
+        remainingEvents: Math.max(0, eventLimit - journal.events),
+        averageRecordBytes,
+        filesystem,
+    };
+};
+exports.resolveStorageBudget = resolveStorageBudget;

package/dist/src/telemetry-catalog.d.ts

@@ -0,0 +1,19 @@
+import type { EventContext } from "./types";
+export type TelemetryScope = "self" | "ais";
+export type ValueKind = "number" | "position" | "string" | "aisShipType";
+export type ChangeKind = "scalar" | "angle" | "position" | "identity";
+export interface TelemetryDefinition {
+    scope: TelemetryScope;
+    path: string;
+    valueKind: ValueKind;
+    changeKind: ChangeKind;
+    minimumIntervalMs: number;
+    maximumHeartbeatMs: number;
+    changeThreshold: number;
+}
+export declare const SELF_TELEMETRY: readonly TelemetryDefinition[];
+export declare const AIS_TELEMETRY: readonly TelemetryDefinition[];
+export declare const SELF_SUBSCRIPTION_PATHS: string[];
+export declare const AIS_SUBSCRIPTION_PATHS: string[];
+export declare const isAisContext: (context: string) => context is EventContext;
+export declare const telemetryDefinition: (context: string, path: string) => TelemetryDefinition | null;