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

package/dist/src/config.js

@@ -0,0 +1,317 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginUiSchema = exports.pluginSchema = exports.resolveConfig = void 0;
+const integer = (value, fallback, minimum, maximum, name) => {
+    const resolved = value === undefined ? fallback : value;
+    if (typeof resolved !== "number" ||
+        !Number.isInteger(resolved) ||
+        resolved < minimum ||
+        resolved > maximum) {
+        throw new Error(`${name} must be an integer between ${minimum} and ${maximum}.`);
+    }
+    return resolved;
+};
+const finiteNumber = (value, minimum, maximum, name) => {
+    if (value === undefined || value === null || value === "") {
+        return null;
+    }
+    if (typeof value !== "number" ||
+        !Number.isFinite(value) ||
+        value < minimum ||
+        value > maximum) {
+        throw new Error(`${name} must be between ${minimum} and ${maximum}.`);
+    }
+    return value;
+};
+const isLocalDevelopmentHost = (hostname) => {
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    if (host === "localhost" ||
+        host.endsWith(".localhost") ||
+        host.endsWith(".local") ||
+        !host.includes(".") ||
+        host === "::1" ||
+        host.startsWith("fc") ||
+        host.startsWith("fd") ||
+        host.startsWith("fe80:")) {
+        return true;
+    }
+    const parts = host.split(".").map(Number);
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part))) {
+        return false;
+    }
+    return (parts[0] === 10 ||
+        parts[0] === 127 ||
+        (parts[0] === 169 && parts[1] === 254) ||
+        (parts[0] === 192 && parts[1] === 168) ||
+        (parts[0] === 172 &&
+            parts[1] !== undefined &&
+            parts[1] >= 16 &&
+            parts[1] <= 31));
+};
+const resolveConfig = (input) => {
+    const raw = input;
+    const targetUrl = typeof raw.targetUrl === "string" ? raw.targetUrl.trim() : "";
+    if (targetUrl === "") {
+        throw new Error("Aurora Blue target URL is required.");
+    }
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(targetUrl);
+    }
+    catch {
+        throw new Error("Aurora Blue target URL is invalid.");
+    }
+    if (!["http:", "https:"].includes(parsedUrl.protocol)) {
+        throw new Error("Aurora Blue target URL must use HTTP or HTTPS.");
+    }
+    if (parsedUrl.username !== "" || parsedUrl.password !== "") {
+        throw new Error("Aurora Blue target URL must not contain credentials.");
+    }
+    const allowInsecureHttp = raw.allowInsecureHttp === true;
+    if (parsedUrl.protocol === "http:" && !allowInsecureHttp) {
+        throw new Error("HTTPS is required unless insecure HTTP is explicitly enabled for local development.");
+    }
+    if (parsedUrl.protocol === "http:" &&
+        !isLocalDevelopmentHost(parsedUrl.hostname)) {
+        throw new Error("Insecure HTTP is limited to local development targets and cannot be enabled for cloud targets.");
+    }
+    if (parsedUrl.search !== "" || parsedUrl.hash !== "") {
+        throw new Error("Aurora Blue target URL must not contain a query or fragment.");
+    }
+    const retryMinimumMs = integer(raw.retryMinimumMs, 1_000, 250, 60_000, "Retry minimum");
+    const retryMaximumMs = integer(raw.retryMaximumMs, 60_000, 1_000, 900_000, "Retry maximum");
+    if (retryMaximumMs < retryMinimumMs) {
+        throw new Error("Retry maximum must be greater than or equal to retry minimum.");
+    }
+    const deviceName = typeof raw.deviceName === "string" ? raw.deviceName.trim() : "";
+    const operatingProfile = raw.operatingProfile ?? "underway";
+    if (!["anchored", "moored", "underway"].includes(String(operatingProfile))) {
+        throw new Error("Operating profile is invalid.");
+    }
+    const storageProfile = raw.storageProfile ?? "auto";
+    if (!["auto", "constrained", "standard", "extended", "custom"].includes(String(storageProfile))) {
+        throw new Error("Storage profile is invalid.");
+    }
+    const anchorAlarmEnabled = raw.anchorAlarmEnabled === true;
+    const anchorLatitude = finiteNumber(raw.anchorLatitude, -90, 90, "Anchor latitude");
+    const anchorLongitude = finiteNumber(raw.anchorLongitude, -180, 180, "Anchor longitude");
+    if (anchorAlarmEnabled &&
+        (anchorLatitude === null || anchorLongitude === null)) {
+        throw new Error("Anchor latitude and longitude are required when the anchor alarm is enabled.");
+    }
+    const anchorRadiusMeters = integer(raw.anchorRadiusMeters, 30, 5, 2_000, "Anchor radius");
+    const anchorHysteresisMeters = integer(raw.anchorHysteresisMeters, 5, 0, 500, "Anchor hysteresis");
+    if (anchorHysteresisMeters >= anchorRadiusMeters) {
+        throw new Error("Anchor hysteresis must be smaller than the anchor radius.");
+    }
+    return {
+        targetUrl: parsedUrl.toString().replace(/\/$/, ""),
+        deviceName: deviceName || "Aurora Blue Signal K",
+        pairingCode: typeof raw.pairingCode === "string" && raw.pairingCode.trim() !== ""
+            ? raw.pairingCode.trim()
+            : undefined,
+        allowInsecureHttp,
+        batchSize: integer(raw.batchSize, 250, 1, 500, "Batch size"),
+        flushIntervalMs: integer(raw.flushIntervalMs, 5_000, 250, 60_000, "Flush interval"),
+        samplePeriodMs: integer(raw.samplePeriodMs, 1_000, 250, 60_000, "Sample period"),
+        aisEnabled: raw.aisEnabled !== false,
+        aisSamplePeriodMs: integer(raw.aisSamplePeriodMs, 5_000, 1_000, 120_000, "AIS sample period"),
+        safetySamplePeriodMs: integer(raw.safetySamplePeriodMs, 250, 100, 5_000, "Safety sample period"),
+        requestTimeoutMs: integer(raw.requestTimeoutMs, 10_000, 1_000, 120_000, "Request timeout"),
+        retryMinimumMs,
+        retryMaximumMs,
+        storageProfile: storageProfile,
+        maxBufferEvents: integer(raw.maxBufferEvents, 1_000_000, 500, 1_000_000, "Buffer event safety limit"),
+        maxBufferBytes: integer(raw.maxBufferMegabytes, 64, 4, 1_024, "Buffer size in megabytes") *
+            1024 *
+            1024,
+        storageReserveBytes: integer(raw.storageReserveMegabytes, 256, 32, 16_384, "Storage reserve in megabytes") *
+            1024 *
+            1024,
+        storageMaximumFraction: integer(raw.storageMaximumPercent, 5, 1, 50, "Maximum storage percentage") / 100,
+        bufferSegmentBytes: integer(raw.bufferSegmentKilobytes, 256, 64, 2_048, "Buffer segment size in kilobytes") * 1024,
+        compressionEnabled: raw.compressionEnabled !== false,
+        compressionThresholdBytes: integer(raw.compressionThresholdBytes, 1_024, 256, 65_536, "Compression threshold"),
+        adaptiveTelemetryEnabled: raw.adaptiveTelemetryEnabled !== false,
+        operatingProfile: operatingProfile,
+        anchorAlarm: {
+            enabled: anchorAlarmEnabled,
+            anchor: anchorLatitude === null || anchorLongitude === null
+                ? null
+                : { latitude: anchorLatitude, longitude: anchorLongitude },
+            radiusMeters: anchorRadiusMeters,
+            hysteresisMeters: anchorHysteresisMeters,
+            confirmationMs: integer(raw.anchorConfirmationSeconds, 10, 0, 300, "Anchor confirmation") * 1_000,
+            stalePositionMs: integer(raw.anchorStalePositionSeconds, 30, 5, 600, "Anchor stale-position timeout") * 1_000,
+        },
+    };
+};
+exports.resolveConfig = resolveConfig;
+exports.pluginSchema = {
+    type: "object",
+    required: ["targetUrl"],
+    properties: {
+        targetUrl: {
+            type: "string",
+            title: "Aurora Blue target URL",
+            description: "Base URL of Aurora Blue Server or Aurora Blue Cloud. [Open connector status](/aurora-blue-signalk-connector/).",
+        },
+        deviceName: {
+            type: "string",
+            title: "Device name",
+            default: "Aurora Blue Signal K",
+        },
+        pairingCode: {
+            type: "string",
+            title: "Pairing code",
+            description: "Short-lived code from Aurora Blue. Cleared after successful pairing.",
+        },
+        allowInsecureHttp: {
+            type: "boolean",
+            title: "Allow insecure HTTP for local development",
+            default: false,
+        },
+        batchSize: {
+            type: "integer",
+            title: "Maximum events per batch",
+            minimum: 1,
+            maximum: 500,
+            default: 250,
+        },
+        samplePeriodMs: {
+            type: "integer",
+            title: "Signal K sample period in milliseconds",
+            minimum: 250,
+            maximum: 60000,
+            default: 1000,
+        },
+        aisEnabled: {
+            type: "boolean",
+            title: "Collect AIS targets",
+            description: "Collect selected dynamic and identity data for other vessels with conservative transfer reduction.",
+            default: true,
+        },
+        aisSamplePeriodMs: {
+            type: "integer",
+            title: "AIS sample period in milliseconds",
+            minimum: 1000,
+            maximum: 120000,
+            default: 5000,
+        },
+        adaptiveTelemetryEnabled: {
+            type: "boolean",
+            title: "Reduce telemetry by change or heartbeat",
+            default: true,
+        },
+        operatingProfile: {
+            type: "string",
+            title: "Telemetry operating profile",
+            enum: ["anchored", "moored", "underway"],
+            default: "underway",
+        },
+        storageProfile: {
+            type: "string",
+            title: "Offline storage profile",
+            description: "Auto selects a capacity class from the filesystem size. Explicit profiles use capacity-oriented limits and custom uses the advanced limits below.",
+            enum: ["auto", "constrained", "standard", "extended", "custom"],
+            enumNames: [
+                "Auto (recommended)",
+                "Constrained flash",
+                "Standard embedded storage",
+                "Extended or external storage",
+                "Custom",
+            ],
+            default: "auto",
+        },
+        anchorAlarmEnabled: {
+            type: "boolean",
+            title: "Enable experimental local anchor alarm",
+            description: "Evaluation remains local, but this development version is not approved as a sole safety device.",
+            default: false,
+        },
+        anchorLatitude: {
+            type: "number",
+            title: "Anchor latitude",
+            minimum: -90,
+            maximum: 90,
+        },
+        anchorLongitude: {
+            type: "number",
+            title: "Anchor longitude",
+            minimum: -180,
+            maximum: 180,
+        },
+        anchorRadiusMeters: {
+            type: "integer",
+            title: "Anchor radius in meters",
+            minimum: 5,
+            maximum: 2000,
+            default: 30,
+        },
+        anchorHysteresisMeters: {
+            type: "integer",
+            title: "Anchor clear hysteresis in meters",
+            minimum: 0,
+            maximum: 500,
+            default: 5,
+        },
+        anchorConfirmationSeconds: {
+            type: "integer",
+            title: "Seconds outside radius before alarm",
+            minimum: 0,
+            maximum: 300,
+            default: 10,
+        },
+        anchorStalePositionSeconds: {
+            type: "integer",
+            title: "Seconds without position before alarm",
+            minimum: 5,
+            maximum: 600,
+            default: 30,
+        },
+        maxBufferEvents: {
+            type: "integer",
+            title: "Custom event safety limit",
+            description: "Absolute secondary safety limit for the custom profile. The effective event limit is derived from the byte budget and measured event size.",
+            minimum: 500,
+            maximum: 1000000,
+            default: 1000000,
+        },
+        maxBufferMegabytes: {
+            type: "integer",
+            title: "Custom maximum journal size in megabytes",
+            minimum: 4,
+            maximum: 1024,
+            default: 64,
+        },
+        storageReserveMegabytes: {
+            type: "integer",
+            title: "Custom free-space reserve in megabytes",
+            minimum: 32,
+            maximum: 16384,
+            default: 256,
+        },
+        storageMaximumPercent: {
+            type: "integer",
+            title: "Custom maximum filesystem percentage",
+            minimum: 1,
+            maximum: 50,
+            default: 5,
+        },
+        compressionEnabled: {
+            type: "boolean",
+            title: "Compress larger batches",
+            default: true,
+        },
+    },
+};
+exports.pluginUiSchema = {
+    targetUrl: {
+        "ui:options": {
+            enableMarkdownInDescription: true,
+        },
+    },
+    pairingCode: {
+        "ui:widget": "password",
+    },
+};

package/dist/src/connector.d.ts

@@ -0,0 +1,69 @@
+import type { Delta, ServerAPI } from "@signalk/server-api";
+import { type ConnectorConfig } from "./config";
+import { type SubscriptionScope } from "./delta";
+import { type AuroraBlueClient } from "./http-client";
+import { StateStore } from "./state-store";
+import type { ConnectorStatus } from "./types";
+export { CONNECTOR_VERSION } from "./version";
+export interface ConnectorRuntimeOptions {
+    now?: () => string;
+    uuid?: () => string;
+    random?: () => number;
+    client?: AuroraBlueClient;
+    autoSchedule?: boolean;
+    monotonicNow?: () => number;
+}
+export declare class ConnectorRuntime {
+    private readonly app;
+    private readonly store;
+    private readonly config;
+    private readonly bootId;
+    private readonly now;
+    private readonly random;
+    private readonly unsubscribes;
+    private timer;
+    private safetyTimer;
+    private runtimeConfigurationTimer;
+    private stopped;
+    private retryAttempt;
+    private droppedEvents;
+    private suppressedEvents;
+    private transferNotice;
+    private operatingMode;
+    private runtimeConfigurationPollMs;
+    private runtimeConfigurationState;
+    private runtimeConfigurationUpdatedAt;
+    private client;
+    private readonly autoSchedule;
+    private readonly anchorAlarm;
+    private readonly telemetryReducer;
+    private readonly monotonicNow;
+    private filesystemCapacity;
+    private nextCapacityRefreshAt;
+    private storageBudget;
+    private readonly emissionTimes;
+    private captureTail;
+    private pendingCaptureEvents;
+    private nextCaptureStatusAt;
+    constructor(app: ServerAPI, store: StateStore, config: ConnectorConfig, options?: ConnectorRuntimeOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    capture(delta: Delta, subscriptionScope?: SubscriptionScope): Promise<void>;
+    private captureEvents;
+    status(): Promise<ConnectorStatus>;
+    flush(): Promise<void>;
+    private configureSubscriptions;
+    private subscribeToContext;
+    private startSafetyTimer;
+    private publishAnchorTransition;
+    private publishAnchorState;
+    private schedule;
+    private scheduleRuntimeConfigurationPoll;
+    private pollRuntimeConfiguration;
+    private applyRuntimeConfiguration;
+    private updateStatus;
+    private storageBudgetPolicy;
+    private refreshStorageBudget;
+    private recordEmission;
+    private emittedPerHour;
+}