signalk-edge-link 2.2.1 → 2.3.0

package/lib/pipeline.js

@@ -35,8 +35,18 @@ var __importStar = (this && this.__importStar) || (function () {
 const msgpack = __importStar(require("@msgpack/msgpack"));
 const crypto_1 = require("./crypto");
 const pathDictionary_1 = require("./pathDictionary");
+const delta_sanitizer_1 = require("./delta-sanitizer");
 const pipeline_utils_1 = require("./pipeline-utils");
 const constants_1 = require("./constants");
+const metadata_1 = require("./metadata");
+/** Leading magic that distinguishes v1 meta payloads from v1 deltas, placed
+ *  inside the encrypted plaintext so existing v1 receivers (which do not
+ *  recognise it) simply reject the packet rather than misinterpreting it. */
+const V1_META_MAGIC = Buffer.from("SKM1", "ascii");
+/** Threshold for v1 sender-restart detection — see the v2 server's
+ *  META_RESTART_THRESHOLD comment. envSeq=0 is treated as a restart only when
+ *  the last accepted seq has moved beyond this small reorder window. */
+const META_RESTART_THRESHOLD_V1 = 8;
 /**
  * Creates the data processing pipeline (compress, encrypt, send / receive, decrypt, decompress).
  * @param app - SignalK app object (for logging)
@@ -47,6 +57,12 @@ const constants_1 = require("./constants");
 function createPipeline(app, state, metricsApi) {
     const { metrics, recordError, trackPathStats } = metricsApi;
     const setStatus = app.setPluginStatus || app.setProviderStatus || (() => { });
+    let metaEnvelopeSeqV1 = 0;
+    // Last accepted inner-envelope seq on the receive side. v1 has no
+    // per-session concept (one socket per pipeline instance), so a single
+    // closure variable is sufficient. Used to drop stale/duplicate envelopes
+    // that UDP reorders or replays.
+    let lastIngestedMetaEnvSeqV1 = null;
     /**
      * Compresses, encrypts, and sends delta data via UDP.
      * Pipeline: Serialize -> Compress -> Encrypt (AES-256-GCM) -> Send
@@ -131,6 +147,73 @@ function createPipeline(app, state, metricsApi) {
             }
         }
     }
+    /**
+     * Sends Signal K path metadata to the receiver using the v1 wire format on a
+     * separate UDP port.
+     *
+     * v1 has no packet-type byte so we cannot multiplex meta with deltas on the
+     * existing port without breaking every deployed v1 receiver. To keep the
+     * change backward-compatible, meta is sent on `udpMetaPort` with a 4-byte
+     * `SKM1` magic prefix inside the encrypted plaintext — a v1 receiver that
+     * has not been upgraded will fail to JSON-parse the payload and simply drop
+     * it without side effects.
+     */
+    async function packCryptMeta(entries, kind, secretKey, udpAddress, udpMetaPort) {
+        try {
+            if (!state.options) {
+                app.debug("packCryptMeta called but plugin is stopped, ignoring");
+                return;
+            }
+            if (!udpMetaPort || udpMetaPort <= 0) {
+                app.debug("packCryptMeta: no udpMetaPort configured, meta disabled on v1");
+                return;
+            }
+            if (entries.length === 0) {
+                return;
+            }
+            const usePathDict = !!state.options.usePathDictionary;
+            const useMsgpack = !!state.options.useMsgpack;
+            const maxPerPacket = state.metaConfig?.maxPathsPerPacket ?? 500;
+            const chunks = (0, metadata_1.splitIntoPackets)(entries, maxPerPacket);
+            const envelopeSeq = metaEnvelopeSeqV1++ >>> 0;
+            for (let i = 0; i < chunks.length; i++) {
+                const chunk = chunks[i];
+                const processed = usePathDict ? chunk.map(pathDictionary_1.encodeMetaEntry) : chunk;
+                const envelope = (0, metadata_1.buildMetaEnvelope)(processed, kind, envelopeSeq, i, chunks.length);
+                const serialized = (0, pipeline_utils_1.deltaBuffer)(envelope, useMsgpack);
+                const withMagic = Buffer.concat([V1_META_MAGIC, serialized]);
+                const compressed = await (0, pipeline_utils_1.compressPayload)(withMagic, useMsgpack);
+                const packet = (0, crypto_1.encryptBinary)(compressed, secretKey, {
+                    stretchAsciiKey: !!state.options.stretchAsciiKey
+                });
+                if (packet.length > constants_1.MAX_SAFE_UDP_PAYLOAD) {
+                    app.debug(`Warning: v1 meta packet size ${packet.length} bytes exceeds safe MTU (${constants_1.MAX_SAFE_UDP_PAYLOAD})`);
+                }
+                await udpSendAsync(packet, udpAddress, udpMetaPort);
+                metrics.bandwidth.metaBytesOut = (metrics.bandwidth.metaBytesOut || 0) + packet.length;
+                metrics.bandwidth.metaPacketsOut = (metrics.bandwidth.metaPacketsOut || 0) + 1;
+                metrics.bandwidth.bytesOut += packet.length;
+                metrics.bandwidth.packetsOut++;
+            }
+            if (kind === "snapshot") {
+                metrics.bandwidth.metaSnapshotsSent = (metrics.bandwidth.metaSnapshotsSent || 0) + 1;
+            }
+            else {
+                metrics.bandwidth.metaDiffsSent = (metrics.bandwidth.metaDiffsSent || 0) + 1;
+            }
+            app.debug(`v1 meta sent: kind=${kind}, entries=${entries.length}, chunks=${chunks.length}, envSeq=${envelopeSeq}`);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            app.error(`packCryptMeta error: ${msg}`);
+            recordError("general", `packCryptMeta error: ${msg}`);
+            // Re-throw so the caller (sendMetaEntries) can tell the send failed
+            // and refrain from committing the MetaCache. Without this, a broken
+            // socket/encryption/compression would silently suppress every future
+            // diff for the affected paths.
+            throw error instanceof Error ? error : new Error(msg);
+        }
+    }
     /**
      * Decompresses, decrypts, and processes received UDP data.
      * Pipeline: Receive -> Decrypt (AES-256-GCM) -> Decompress -> Parse -> Process
@@ -206,6 +289,11 @@ function createPipeline(app, state, metricsApi) {
                     app.debug(`Skipping null delta message after decoding at index ${i}`);
                     continue;
                 }
+                deltaMessage = (0, delta_sanitizer_1.sanitizeDeltaForSignalK)(deltaMessage);
+                if (deltaMessage === null) {
+                    app.debug(`Skipping delta with no valid Signal K values at index ${i}`);
+                    continue;
+                }
                 // Track path stats for server-side analytics
                 trackPathStats(deltaMessage, decompressed.length / deltas.length);
                 app.handleMessage("", deltaMessage);
@@ -267,6 +355,138 @@ function createPipeline(app, state, metricsApi) {
             }
         });
     }
-    return { packCrypt, unpackDecrypt };
+    /**
+     * Receive-side counterpart to `packCryptMeta` for v1. Decrypts a packet
+     * arrived on `udpMetaPort`, verifies the 4-byte `SKM1` magic inside the
+     * plaintext (packets without the magic are dropped — v1 has no packet-type
+     * byte, so the magic is the only signal that this is a meta payload and not
+     * a corrupted delta), and dispatches each entry as a minimal Signal K delta
+     * with `updates[].meta[]` via `app.handleMessage`.
+     */
+    async function unpackDecryptMeta(packet, secretKey) {
+        try {
+            if (!state.options) {
+                app.debug("unpackDecryptMeta called but plugin is stopped, ignoring");
+                return;
+            }
+            // Bump bytesIn/packetsIn AND the meta-scoped counters at the same
+            // gate — any packet that reached this code is a meta packet (the
+            // separate udpMetaPort ensures that), so bytesIn should always equal
+            // metaBytesIn for this pipeline path. Keeping them in lockstep lets
+            // consumers cross-check: bytesIn === dataBytesIn + metaBytesIn.
+            metrics.bandwidth.bytesIn += packet.length;
+            metrics.bandwidth.packetsIn++;
+            metrics.bandwidth.metaBytesIn = (metrics.bandwidth.metaBytesIn || 0) + packet.length;
+            metrics.bandwidth.metaPacketsIn = (metrics.bandwidth.metaPacketsIn || 0) + 1;
+            const decrypted = (0, crypto_1.decryptBinary)(packet, secretKey, {
+                stretchAsciiKey: !!state.options.stretchAsciiKey
+            });
+            const decompressed = (await (0, pipeline_utils_1.brotliDecompressAsync)(decrypted, {
+                maxOutputLength: constants_1.MAX_DECOMPRESSED_SIZE
+            }));
+            if (decompressed.length < V1_META_MAGIC.length) {
+                app.debug("v1 meta: decompressed payload too short, ignoring");
+                return;
+            }
+            // Reject anything that isn't prefixed with the SKM1 magic so a stray
+            // non-meta packet on the meta port (misconfiguration, replay, attacker)
+            // cannot be misinterpreted. The magic lives INSIDE the encrypted
+            // plaintext, so this check is authenticated.
+            if (decompressed.subarray(0, V1_META_MAGIC.length).compare(V1_META_MAGIC) !== 0) {
+                app.debug("v1 meta: missing SKM1 magic, dropping");
+                return;
+            }
+            const body = decompressed.subarray(V1_META_MAGIC.length);
+            if (body.length > constants_1.MAX_PARSE_PAYLOAD_SIZE) {
+                app.error(`v1 meta: payload too large to parse: ${body.length} bytes`);
+                return;
+            }
+            let content;
+            if (state.options.useMsgpack) {
+                try {
+                    content = msgpack.decode(body);
+                }
+                catch {
+                    content = JSON.parse(body.toString());
+                }
+            }
+            else {
+                content = JSON.parse(body.toString());
+            }
+            if (!content || typeof content !== "object" || Array.isArray(content)) {
+                app.debug("v1 meta: envelope was not an object, dropping");
+                return;
+            }
+            const env = content;
+            if (!Array.isArray(env.entries) || env.entries.length === 0) {
+                return;
+            }
+            // Drop stale/duplicate envelopes. The inner envelope `seq` is shared
+            // across all chunks of the same batch, so equal-seq chunks are still
+            // accepted; only earlier batches are rejected. Uint32-wrap aware so a
+            // long-running sender's wrap doesn't trigger mass-rejection.
+            //
+            // Sender-restart detection: the v1 client's meta envelope counter
+            // initialises to 0 at process start. Treat envSeq=0 as a peer restart
+            // only once lastIngestedMetaEnvSeqV1 has advanced beyond a small
+            // reorder window — below the threshold, envSeq=0 is ambiguous with
+            // first-packet replay and falls through to normal dedup.
+            if (typeof env.seq === "number" && Number.isFinite(env.seq)) {
+                const envSeq = env.seq >>> 0;
+                if (lastIngestedMetaEnvSeqV1 !== null &&
+                    envSeq === 0 &&
+                    lastIngestedMetaEnvSeqV1 >= META_RESTART_THRESHOLD_V1) {
+                    app.debug(`v1 meta: sender restart detected (last seq was ${lastIngestedMetaEnvSeqV1}); resetting`);
+                    lastIngestedMetaEnvSeqV1 = null;
+                }
+                if (lastIngestedMetaEnvSeqV1 !== null) {
+                    const distance = (envSeq - lastIngestedMetaEnvSeqV1) >>> 0;
+                    if (distance !== 0 && distance >= 0x80000000) {
+                        app.debug(`v1 meta: stale envelope seq=${envSeq} (last=${lastIngestedMetaEnvSeqV1}), dropping`);
+                        return;
+                    }
+                    if (distance !== 0) {
+                        lastIngestedMetaEnvSeqV1 = envSeq;
+                    }
+                }
+                else {
+                    lastIngestedMetaEnvSeqV1 = envSeq;
+                }
+            }
+            const nowIso = new Date().toISOString();
+            const usePathDict = !!state.options.usePathDictionary;
+            for (const rawEntry of env.entries) {
+                if (!rawEntry || typeof rawEntry.meta !== "object" || !rawEntry.meta) {
+                    continue;
+                }
+                const entry = usePathDict
+                    ? (0, pathDictionary_1.decodeMetaEntry)(rawEntry)
+                    : rawEntry;
+                const path = typeof entry.path === "string" ? entry.path : String(entry.path ?? "");
+                if (!path) {
+                    continue;
+                }
+                const context = typeof rawEntry.context === "string" ? rawEntry.context : "vessels.self";
+                const delta = {
+                    context,
+                    updates: [
+                        {
+                            timestamp: nowIso,
+                            values: [],
+                            meta: [{ path, value: entry.meta }]
+                        }
+                    ]
+                };
+                app.handleMessage("", delta);
+            }
+            app.debug(`v1 meta received: kind=${env.kind ?? "?"}, entries=${env.entries.length}`);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            app.error(`unpackDecryptMeta error: ${msg}`);
+            recordError("general", `unpackDecryptMeta error: ${msg}`);
+        }
+    }
+    return { packCrypt, packCryptMeta, unpackDecrypt, unpackDecryptMeta };
 }
 module.exports = createPipeline;

package/lib/prometheus.js

@@ -42,6 +42,10 @@ function formatPrometheusMetrics(metrics, state, extra = {}, opts = {}) {
     // Delta counters
     counter("deltas_sent_total", "Total deltas sent", metrics.deltasSent);
     counter("deltas_received_total", "Total deltas received", metrics.deltasReceived);
+    counter("data_packets_received_total", "Total v2 data packets received", metrics.dataPacketsReceived || 0);
+    counter("rate_limited_packets_total", "Total packets dropped by rate limiting", metrics.rateLimitedPackets || 0);
+    counter("dropped_delta_batches_total", "Total delta batches dropped before send", metrics.droppedDeltaBatches || 0);
+    counter("dropped_deltas_total", "Total deltas dropped before send", metrics.droppedDeltaCount || 0);
     // Error counters
     counter("udp_send_errors_total", "Total UDP send errors", metrics.udpSendErrors);
     counter("udp_retries_total", "Total UDP send retries", metrics.udpRetries);
@@ -63,6 +67,13 @@ function formatPrometheusMetrics(metrics, state, extra = {}, opts = {}) {
     counter("bytes_in_raw_total", "Total bytes received (raw/uncompressed)", metrics.bandwidth.bytesInRaw);
     counter("packets_out_total", "Total packets sent", metrics.bandwidth.packetsOut);
     counter("packets_in_total", "Total packets received", metrics.bandwidth.packetsIn);
+    counter("metadata_bytes_out_total", "Total bytes sent as metadata packets", metrics.bandwidth.metaBytesOut || 0);
+    counter("metadata_bytes_in_total", "Total bytes received as metadata packets", metrics.bandwidth.metaBytesIn || 0);
+    counter("metadata_packets_out_total", "Total metadata packets sent", metrics.bandwidth.metaPacketsOut || 0);
+    counter("metadata_packets_in_total", "Total metadata packets received", metrics.bandwidth.metaPacketsIn || 0);
+    counter("metadata_snapshots_sent_total", "Total metadata snapshot envelopes sent", metrics.bandwidth.metaSnapshotsSent || 0);
+    counter("metadata_diffs_sent_total", "Total metadata diff envelopes sent", metrics.bandwidth.metaDiffsSent || 0);
+    counter("metadata_rate_limited_packets_total", "Total metadata packets dropped by rate limiting", metrics.bandwidth.metaRateLimitedPackets || 0);
     gauge("bandwidth_rate_out_bytes", "Current outbound bandwidth (bytes/s)", metrics.bandwidth.rateOut);
     gauge("bandwidth_rate_in_bytes", "Current inbound bandwidth (bytes/s)", metrics.bandwidth.rateIn);
     gauge("compression_ratio_percent", "Current compression ratio percentage", metrics.bandwidth.compressionRatio);

package/lib/routes/config-validation.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateRuntimeConfigBody = validateRuntimeConfigBody;
+const metadata_1 = require("../metadata");
+/** Upper bound on meta.includePathsMatching length. Same constant as the
+ *  metadata runtime — mirrored here so the validator rejects patterns at
+ *  save time rather than letting the runtime silently fall back to
+ *  allow-all. */
+const META_FILTER_MAX_LENGTH = 256;
 function validateRuntimeConfigBody(filename, body) {
     if (!body || typeof body !== "object" || Array.isArray(body)) {
         return "Request body must be a JSON object";
@@ -23,6 +29,49 @@ function validateRuntimeConfigBody(filename, body) {
                 }
             }
         }
+        if (body.meta !== undefined) {
+            if (body.meta === null || typeof body.meta !== "object" || Array.isArray(body.meta)) {
+                return "meta must be an object";
+            }
+            const m = body.meta;
+            if (m.enabled !== undefined && typeof m.enabled !== "boolean") {
+                return "meta.enabled must be a boolean";
+            }
+            if (m.intervalSec !== undefined &&
+                (typeof m.intervalSec !== "number" ||
+                    !Number.isFinite(m.intervalSec) ||
+                    m.intervalSec < 30 ||
+                    m.intervalSec > 86400)) {
+                return "meta.intervalSec must be a number between 30 and 86400";
+            }
+            if (m.includePathsMatching !== undefined && m.includePathsMatching !== null) {
+                if (typeof m.includePathsMatching !== "string") {
+                    return "meta.includePathsMatching must be a string or null";
+                }
+                // Same three checks the runtime applies, hoisted to save-time so
+                // persisted subscription.json cannot contain patterns the runtime
+                // would silently ignore. Keeps the API and the runtime in agreement.
+                if (m.includePathsMatching.length > META_FILTER_MAX_LENGTH) {
+                    return `meta.includePathsMatching must be at most ${META_FILTER_MAX_LENGTH} characters`;
+                }
+                if ((0, metadata_1.isLikelyUnsafePathFilter)(m.includePathsMatching)) {
+                    return "meta.includePathsMatching contains a nested unbounded quantifier (ReDoS shape); refused";
+                }
+                try {
+                    new RegExp(m.includePathsMatching);
+                }
+                catch (err) {
+                    return `meta.includePathsMatching failed to compile: ${err instanceof Error ? err.message : String(err)}`;
+                }
+            }
+            if (m.maxPathsPerPacket !== undefined &&
+                (typeof m.maxPathsPerPacket !== "number" ||
+                    !Number.isFinite(m.maxPathsPerPacket) ||
+                    m.maxPathsPerPacket < 10 ||
+                    m.maxPathsPerPacket > 5000)) {
+                return "meta.maxPathsPerPacket must be a number between 10 and 5000";
+            }
+        }
     }
     else if (filename === "sentence_filter.json") {
         if (body.excludedSentences !== undefined && !Array.isArray(body.excludedSentences)) {

package/lib/routes/metrics.js

@@ -37,6 +37,7 @@ function register(router, ctx) {
                 packetLoss: effectiveNetwork.packetLoss,
                 retransmissions: effectiveNetwork.retransmissions,
                 queueDepth: effectiveNetwork.queueDepth,
+                retransmitRate: effectiveNetwork.retransmitRate,
                 acksSent: metrics.acksSent || 0,
                 naksSent: metrics.naksSent || 0,
                 activeLink: effectiveNetwork.activeLink,

package/lib/routes.js

@@ -289,6 +289,12 @@ function createRoutes(app, instanceRegistry, pluginRef) {
             }
             return localVal ?? 0;
         }
+        const bondingManager = state.pipeline && state.pipeline.getBondingManager
+            ? state.pipeline.getBondingManager()
+            : null;
+        const localActiveLink = bondingManager
+            ? bondingManager.getActiveLinkName() || "primary"
+            : "primary";
         return {
             rtt: selectMetric(remote.rtt, metrics.rtt),
             jitter: selectMetric(remote.jitter, metrics.jitter),
@@ -296,7 +302,7 @@ function createRoutes(app, instanceRegistry, pluginRef) {
             retransmissions: selectMetric(remote.retransmissions, metrics.retransmissions),
             queueDepth: selectMetric(remote.queueDepth, metrics.queueDepth),
             retransmitRate: selectMetric(remote.retransmitRate, clientRetransmitRate),
-            activeLink: hasFreshRemote ? (remote.activeLink ?? "primary") : "primary",
+            activeLink: hasFreshRemote ? (remote.activeLink ?? "primary") : localActiveLink,
             dataSource: hasFreshRemote ? "remote-client" : "local",
             lastUpdate: hasFreshRemote ? remote.lastUpdate : 0
         };
@@ -336,6 +342,10 @@ function createRoutes(app, instanceRegistry, pluginRef) {
                 subscriptionErrors: metrics.subscriptionErrors,
                 duplicatePackets: metrics.duplicatePackets || 0,
                 malformedPackets: metrics.malformedPackets || 0,
+                dataPacketsReceived: metrics.dataPacketsReceived || 0,
+                rateLimitedPackets: metrics.rateLimitedPackets || 0,
+                droppedDeltaBatches: metrics.droppedDeltaBatches || 0,
+                droppedDeltaCount: metrics.droppedDeltaCount || 0,
                 errorCounts: { ...(metrics.errorCounts || {}) }
             },
             status: {
@@ -348,6 +358,8 @@ function createRoutes(app, instanceRegistry, pluginRef) {
                     : metrics.bandwidth.packetsOut;
                 const bytes = state.isServerMode ? metrics.bandwidth.bytesIn : metrics.bandwidth.bytesOut;
                 const avgPacketSize = packets > 0 ? Math.round(bytes / packets) : 0;
+                const metaBytesOut = metrics.bandwidth.metaBytesOut || 0;
+                const metaBytesIn = metrics.bandwidth.metaBytesIn || 0;
                 return {
                     bytesOut: metrics.bandwidth.bytesOut,
                     bytesIn: metrics.bandwidth.bytesIn,
@@ -356,6 +368,7 @@ function createRoutes(app, instanceRegistry, pluginRef) {
                     bytesOutFormatted: formatBytes(metrics.bandwidth.bytesOut),
                     bytesInFormatted: formatBytes(metrics.bandwidth.bytesIn),
                     bytesOutRawFormatted: formatBytes(metrics.bandwidth.bytesOutRaw),
+                    bytesInRawFormatted: formatBytes(metrics.bandwidth.bytesInRaw),
                     packetsOut: metrics.bandwidth.packetsOut,
                     packetsIn: metrics.bandwidth.packetsIn,
                     rateOut: metrics.bandwidth.rateOut,
@@ -365,6 +378,15 @@ function createRoutes(app, instanceRegistry, pluginRef) {
                     compressionRatio: metrics.bandwidth.compressionRatio,
                     avgPacketSize,
                     avgPacketSizeFormatted: avgPacketSize > 0 ? formatBytes(avgPacketSize) : "0 B",
+                    metaBytesOut,
+                    metaBytesIn,
+                    metaBytesOutFormatted: formatBytes(metaBytesOut),
+                    metaBytesInFormatted: formatBytes(metaBytesIn),
+                    metaPacketsOut: metrics.bandwidth.metaPacketsOut || 0,
+                    metaPacketsIn: metrics.bandwidth.metaPacketsIn || 0,
+                    metaSnapshotsSent: metrics.bandwidth.metaSnapshotsSent || 0,
+                    metaDiffsSent: metrics.bandwidth.metaDiffsSent || 0,
+                    metaRateLimitedPackets: metrics.bandwidth.metaRateLimitedPackets || 0,
                     history: metrics.bandwidth.history.toArray().slice(-30)
                 };
             })(),
@@ -387,16 +409,15 @@ function createRoutes(app, instanceRegistry, pluginRef) {
                     packetLoss: effectiveNetwork.packetLoss,
                     retransmissions: effectiveNetwork.retransmissions,
                     queueDepth: effectiveNetwork.queueDepth,
+                    retransmitRate: effectiveNetwork.retransmitRate,
                     acksSent: metrics.acksSent || 0,
                     naksSent: metrics.naksSent || 0,
+                    activeLink: effectiveNetwork.activeLink,
                     dataSource: effectiveNetwork.dataSource
                 };
                 if (state.isServerMode && effectiveNetwork.lastUpdate > 0) {
                     networkData.lastRemoteUpdate = effectiveNetwork.lastUpdate;
                 }
-                if (state.isServerMode) {
-                    networkData.activeLink = effectiveNetwork.activeLink;
-                }
                 const publisher = getActiveMetricsPublisher(state);
                 if (publisher) {
                     networkData.linkQuality = publisher.calculateLinkQuality({