signalk-edge-link 2.8.0 → 2.9.1

package/lib/bonding.js

@@ -575,14 +575,15 @@ class BondingManager {
             return;
         }
         try {
+            // Emit a `$source` string rather than a structured `source` object:
+            // signalk-server derives `${label}.XX` from a label-only source object,
+            // which would split this notification across a spurious
+            // `signalk-edge-link.XX` bucket. See src/source-dispatch.ts.
             this.app.handleMessage(this.sourceLabel, {
                 context: "vessels.self",
                 updates: [
                     {
-                        source: {
-                            label: this.sourceLabel,
-                            type: "plugin"
-                        },
+                        $source: "signalk-edge-link",
                         timestamp: new Date().toISOString(),
                         values: [
                             {

package/lib/compact-delta.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeCompactDelta = encodeCompactDelta;
+exports.encodeCompactPayload = encodeCompactPayload;
+exports.decodeCompactDelta = decodeCompactDelta;
+exports.isCompactDeltaArray = isCompactDeltaArray;
+exports.decodeCompactDeltaArray = decodeCompactDeltaArray;
+// Update tuple position constants — keeps the encoder and decoder honest.
+const POS_SOURCE = 0;
+const POS_DOLLAR_SOURCE = 1;
+const POS_TIMESTAMP = 2;
+const POS_VALUES = 3;
+const POS_META = 4;
+// Length we always emit so positional access is stable.
+const UPDATE_TUPLE_LEN = 5;
+/**
+ * Encode a single update block into a positional 5-element array.
+ * Missing fields are encoded as `null` to keep positions stable.
+ */
+function encodeUpdate(update) {
+    const valuesArr = [];
+    if (Array.isArray(update.values)) {
+        for (const v of update.values) {
+            if (v && typeof v === "object" && v.path !== undefined) {
+                valuesArr.push([v.path, v.value]);
+            }
+        }
+    }
+    const metaArr = [];
+    if (Array.isArray(update.meta)) {
+        for (const m of update.meta) {
+            if (m && typeof m === "object" && m.path !== undefined) {
+                metaArr.push([m.path, m.value]);
+            }
+        }
+    }
+    // Use null for absent source/timestamp; null compresses to a single byte in msgpack.
+    return [
+        update.source ?? null,
+        update.$source ?? null,
+        update.timestamp ?? null,
+        valuesArr,
+        metaArr.length > 0 ? metaArr : null
+    ];
+}
+/**
+ * Encode a single Delta into a positional 2-element array.
+ *
+ *   [context, [updateTuple, updateTuple, ...]]
+ */
+function encodeCompactDelta(delta) {
+    const updates = Array.isArray(delta.updates) ? delta.updates : [];
+    return [delta.context ?? null, updates.map(encodeUpdate)];
+}
+/**
+ * Encode a Delta, Delta[], or Record<string, Delta> as a flat array of
+ * compact deltas. The shape (single / array / record) is collapsed to
+ * an array because the receiver pipeline already handles both array
+ * and object batch forms identically.
+ */
+function encodeCompactPayload(payload) {
+    if (Array.isArray(payload)) {
+        return payload.map(encodeCompactDelta);
+    }
+    if (payload && typeof payload === "object" && Array.isArray(payload.updates)) {
+        return [encodeCompactDelta(payload)];
+    }
+    // Record<string, Delta>
+    const out = [];
+    for (const d of Object.values(payload)) {
+        if (d && typeof d === "object") {
+            out.push(encodeCompactDelta(d));
+        }
+    }
+    return out;
+}
+// ── Decoding ─────────────────────────────────────────────────────────────────
+function decodeUpdate(tuple) {
+    if (!Array.isArray(tuple) || tuple.length < UPDATE_TUPLE_LEN)
+        return null;
+    const source = tuple[POS_SOURCE];
+    const dollarSource = tuple[POS_DOLLAR_SOURCE];
+    const timestamp = tuple[POS_TIMESTAMP];
+    const rawValues = tuple[POS_VALUES];
+    const rawMeta = tuple[POS_META];
+    const values = [];
+    if (Array.isArray(rawValues)) {
+        for (const vt of rawValues) {
+            if (Array.isArray(vt) && vt.length >= 2) {
+                values.push({ path: vt[0], value: vt[1] });
+            }
+        }
+    }
+    const update = { values };
+    if (source !== null && source !== undefined) {
+        update.source = source;
+    }
+    if (typeof dollarSource === "string") {
+        update.$source = dollarSource;
+    }
+    if (typeof timestamp === "string") {
+        update.timestamp = timestamp;
+    }
+    if (Array.isArray(rawMeta)) {
+        const meta = [];
+        for (const mt of rawMeta) {
+            if (Array.isArray(mt) && mt.length >= 2) {
+                meta.push({ path: mt[0], value: mt[1] });
+            }
+        }
+        if (meta.length > 0)
+            update.meta = meta;
+    }
+    return update;
+}
+/**
+ * Decode a single compact-encoded delta back into a Signal K Delta.
+ * Returns null for malformed input so the caller can drop it cleanly.
+ */
+function decodeCompactDelta(payload) {
+    if (!Array.isArray(payload) || payload.length < 2)
+        return null;
+    const context = payload[0];
+    const rawUpdates = payload[1];
+    if (!Array.isArray(rawUpdates))
+        return null;
+    const updates = [];
+    for (const u of rawUpdates) {
+        const decoded = decodeUpdate(u);
+        if (decoded)
+            updates.push(decoded);
+    }
+    const out = {
+        context: typeof context === "string" ? context : "",
+        updates
+    };
+    return out;
+}
+/**
+ * Detect whether a parsed message is compact-encoded (flat array of
+ * 2-element arrays) versus a standard Signal K Delta array. We use the
+ * first element's shape as the discriminator:
+ *   - compact:  [[ctx, [...updates]], ...]  → element 0 is itself a 2-tuple
+ *   - standard: [{context, updates}, ...]   → element 0 is an object
+ */
+function isCompactDeltaArray(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return false;
+    const first = value[0];
+    return (Array.isArray(first) && first.length >= 2 && Array.isArray(first[1]) // updates slot is itself an array
+    );
+}
+/**
+ * Decode a compact-encoded array of deltas into an array of standard
+ * Signal K Deltas. Skips entries that fail to decode.
+ */
+function decodeCompactDeltaArray(payload) {
+    if (!Array.isArray(payload))
+        return [];
+    const out = [];
+    for (const item of payload) {
+        const d = decodeCompactDelta(item);
+        if (d)
+            out.push(d);
+    }
+    return out;
+}

package/lib/connection-config.js

@@ -17,7 +17,13 @@ exports.VALID_CONNECTION_KEYS = [
     "secretKey",
     "stretchAsciiKey",
     "useMsgpack",
+    "useValueDedup",
+    "useCompactDeltas",
+    "pathFilter",
     "usePathDictionary",
+    "brotliQuality",
+    "pathPrecision",
+    "pathThrottle",
     "enableNotifications",
     "skipOwnData",
     "protocolVersion",
@@ -100,6 +106,98 @@ function validateConnectionConfig(connection, prefix = "") {
     if (conn.useMsgpack !== undefined && typeof conn.useMsgpack !== "boolean") {
         return `${p}useMsgpack must be a boolean`;
     }
+    if (conn.useValueDedup !== undefined && typeof conn.useValueDedup !== "boolean") {
+        return `${p}useValueDedup must be a boolean`;
+    }
+    if (conn.useCompactDeltas !== undefined && typeof conn.useCompactDeltas !== "boolean") {
+        return `${p}useCompactDeltas must be a boolean`;
+    }
+    const _pv = conn.protocolVersion ?? 1;
+    if (conn.useValueDedup === true && _pv < 2) {
+        return `${p}useValueDedup is only supported on protocolVersion 2 or 3`;
+    }
+    if (conn.useCompactDeltas === true) {
+        if (_pv < 2) {
+            return `${p}useCompactDeltas is only supported on protocolVersion 2 or 3`;
+        }
+        if (conn.useMsgpack !== true) {
+            return `${p}useCompactDeltas requires useMsgpack to be enabled`;
+        }
+    }
+    if (conn.pathFilter !== undefined) {
+        if (typeof conn.pathFilter !== "object" ||
+            conn.pathFilter === null ||
+            Array.isArray(conn.pathFilter)) {
+            return `${p}pathFilter must be an object`;
+        }
+        const pf = conn.pathFilter;
+        for (const key of Object.keys(pf)) {
+            if (key !== "allow" && key !== "deny") {
+                return `${p}pathFilter.${key} is not a supported property`;
+            }
+        }
+        for (const key of ["allow", "deny"]) {
+            if (pf[key] !== undefined) {
+                if (!Array.isArray(pf[key])) {
+                    return `${p}pathFilter.${key} must be an array of strings`;
+                }
+                const arr = pf[key];
+                for (let i = 0; i < arr.length; i++) {
+                    if (typeof arr[i] !== "string" || arr[i].length === 0) {
+                        return `${p}pathFilter.${key}[${i}] must be a non-empty string`;
+                    }
+                }
+            }
+        }
+    }
+    if (conn.brotliQuality !== undefined) {
+        const q = conn.brotliQuality;
+        if (!Number.isInteger(q) || q < 0 || q > 11) {
+            return `${p}brotliQuality must be an integer between 0 and 11`;
+        }
+    }
+    if (conn.pathPrecision !== undefined) {
+        if (typeof conn.pathPrecision !== "object" ||
+            conn.pathPrecision === null ||
+            Array.isArray(conn.pathPrecision)) {
+            return `${p}pathPrecision must be an object mapping path to integer 0..15`;
+        }
+        for (const [path, decimals] of Object.entries(conn.pathPrecision)) {
+            if (!Number.isInteger(decimals) || decimals < 0 || decimals > 15) {
+                return `${p}pathPrecision["${path}"] must be an integer between 0 and 15`;
+            }
+        }
+    }
+    if (conn.pathThrottle !== undefined) {
+        if (typeof conn.pathThrottle !== "object" ||
+            conn.pathThrottle === null ||
+            Array.isArray(conn.pathThrottle)) {
+            return `${p}pathThrottle must be an object mapping path to a rule`;
+        }
+        for (const [path, rule] of Object.entries(conn.pathThrottle)) {
+            if (typeof rule !== "object" || rule === null || Array.isArray(rule)) {
+                return `${p}pathThrottle["${path}"] must be an object`;
+            }
+            const r = rule;
+            for (const key of Object.keys(r)) {
+                if (key !== "minIntervalMs" && key !== "deadband") {
+                    return `${p}pathThrottle["${path}"].${key} is not a supported property`;
+                }
+            }
+            if (r.minIntervalMs !== undefined) {
+                if (!Number.isInteger(r.minIntervalMs) ||
+                    r.minIntervalMs < 0 ||
+                    r.minIntervalMs > 3600000) {
+                    return `${p}pathThrottle["${path}"].minIntervalMs must be an integer between 0 and 3600000`;
+                }
+            }
+            if (r.deadband !== undefined) {
+                if (!isFiniteNumber(r.deadband) || r.deadband < 0) {
+                    return `${p}pathThrottle["${path}"].deadband must be a non-negative number`;
+                }
+            }
+        }
+    }
     if (conn.usePathDictionary !== undefined && typeof conn.usePathDictionary !== "boolean") {
         return `${p}usePathDictionary must be a boolean`;
     }

package/lib/constants.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OUTBOUND_DUPLICATE_SUPPRESS_MS = exports.PATH_STATS_MAX_SIZE = exports.BANDWIDTH_HISTORY_MAX = exports.METRICS_PUBLISH_INTERVAL = exports.MAX_PARSE_PAYLOAD_SIZE = exports.MAX_DECOMPRESSED_SIZE = exports.UDP_RATE_LIMIT_MAX_PACKETS = exports.UDP_RATE_LIMIT_WINDOW = exports.MAX_CLIENT_SESSIONS = exports.BONDING_RTT_EMA_ALPHA = exports.BONDING_HEALTH_WINDOW_SIZE = exports.BONDING_FAILBACK_LOSS_HYSTERESIS = exports.BONDING_FAILBACK_RTT_HYSTERESIS = exports.BONDING_HEARTBEAT_TIMEOUT = exports.BONDING_FAILBACK_DELAY = exports.BONDING_LOSS_THRESHOLD = exports.BONDING_RTT_THRESHOLD = exports.BONDING_HEALTH_CHECK_INTERVAL = exports.CONGESTION_DECREASE_FACTOR = exports.CONGESTION_INCREASE_FACTOR = exports.CONGESTION_RTT_MULTIPLIER_HIGH = exports.CONGESTION_LOSS_THRESHOLD_HIGH = exports.CONGESTION_LOSS_THRESHOLD_LOW = exports.CONGESTION_SMOOTHING_FACTOR = exports.CONGESTION_MAX_ADJUSTMENT = exports.CONGESTION_ADJUST_INTERVAL = exports.CONGESTION_TARGET_RTT = exports.CONGESTION_MAX_DELTA_TIMER = exports.CONGESTION_MIN_DELTA_TIMER = exports.RATE_LIMIT_MAX_REQUESTS = exports.RATE_LIMIT_WINDOW = exports.SMART_BATCH_MAX_DELTAS = exports.SMART_BATCH_MIN_DELTAS = exports.SMART_BATCH_INITIAL_ESTIMATE = exports.SMART_BATCH_SMOOTHING = exports.SMART_BATCH_SAFETY_MARGIN = exports.UDP_SEND_TIMEOUT_MS = exports.UDP_RETRY_DELAY = exports.UDP_RETRY_MAX = exports.BROTLI_QUALITY_HIGH = exports.MAX_SAFE_UDP_PAYLOAD = exports.WATCHER_RECOVERY_DELAY = exports.CONTENT_HASH_ALGORITHM = exports.FILE_WATCH_DEBOUNCE_DELAY = exports.MAX_DELTAS_PER_PACKET = exports.DELTA_BUFFER_DROP_RATIO = exports.MAX_DELTAS_BUFFER_SIZE = exports.MILLISECONDS_PER_MINUTE = exports.PING_TIMEOUT_BUFFER = exports.DEFAULT_DELTA_TIMER = void 0;
-exports.PACKET_INSPECTOR_MAX_CLIENTS = exports.PACKET_CAPTURE_MAX_PACKETS = exports.MONITORING_ALERT_COOLDOWN = exports.MONITORING_PATH_LATENCY_WINDOW = exports.MONITORING_RETRANSMIT_HISTORY_SIZE = exports.MONITORING_HEATMAP_BUCKET_DURATION = exports.MONITORING_HEATMAP_BUCKETS = exports.HELLO_PAYLOAD_MAX_BYTES = exports.SNAPSHOT_REPLAY_CHUNK_SIZE = exports.DELTA_SEND_RETRY_BACKOFF_MS = exports.DELTA_SEND_MAX_RETRIES = exports.SOURCE_SNAPSHOT_MAX_OBJECT_KEYS = exports.SOURCE_SNAPSHOT_MAX_ARRAY_LENGTH = exports.SOURCE_SNAPSHOT_MAX_DEPTH = exports.SOURCE_SNAPSHOT_MAX_STRING_LENGTH = exports.SOURCE_SNAPSHOT_MAX_KEY_LENGTH = exports.SOURCE_SNAPSHOT_MAX_PROVIDERS = exports.SOURCE_SNAPSHOT_INTERVAL_MS = exports.SOURCE_REGISTRY_TTL_MS = exports.SOURCE_REGISTRY_MAX_RECORDS = exports.OUTBOUND_DEDUPE_MAX_ENTRIES = exports.OUTBOUND_DEDUPE_CLEANUP_INTERVAL_MS = exports.SUPPRESSED_DUPLICATE_STATS_MAX_SIZE = void 0;
+exports.BANDWIDTH_HISTORY_MAX = exports.METRICS_PUBLISH_INTERVAL = exports.MAX_PARSE_PAYLOAD_SIZE = exports.MAX_DECOMPRESSED_SIZE = exports.UDP_RATE_LIMIT_MAX_PACKETS = exports.UDP_RATE_LIMIT_WINDOW = exports.MAX_CLIENT_SESSIONS = exports.BONDING_RTT_EMA_ALPHA = exports.BONDING_HEALTH_WINDOW_SIZE = exports.BONDING_FAILBACK_LOSS_HYSTERESIS = exports.BONDING_FAILBACK_RTT_HYSTERESIS = exports.BONDING_HEARTBEAT_TIMEOUT = exports.BONDING_FAILBACK_DELAY = exports.BONDING_LOSS_THRESHOLD = exports.BONDING_RTT_THRESHOLD = exports.BONDING_HEALTH_CHECK_INTERVAL = exports.CONGESTION_DECREASE_FACTOR = exports.CONGESTION_INCREASE_FACTOR = exports.CONGESTION_RTT_MULTIPLIER_HIGH = exports.CONGESTION_LOSS_THRESHOLD_HIGH = exports.CONGESTION_LOSS_THRESHOLD_LOW = exports.CONGESTION_SMOOTHING_FACTOR = exports.CONGESTION_MAX_ADJUSTMENT = exports.CONGESTION_ADJUST_INTERVAL = exports.CONGESTION_TARGET_RTT = exports.CONGESTION_MAX_DELTA_TIMER = exports.CONGESTION_MIN_DELTA_TIMER = exports.RATE_LIMIT_MAX_REQUESTS = exports.RATE_LIMIT_WINDOW = exports.SMART_BATCH_MAX_DELTAS = exports.SMART_BATCH_MIN_DELTAS = exports.SMART_BATCH_INITIAL_ESTIMATE = exports.SMART_BATCH_SMOOTHING = exports.SMART_BATCH_SAFETY_MARGIN = exports.UDP_SEND_TIMEOUT_MS = exports.UDP_RETRY_DELAY = exports.UDP_RETRY_MAX = exports.BROTLI_QUALITY_MAX = exports.BROTLI_QUALITY_MIN = exports.BROTLI_QUALITY_HIGH = exports.MAX_SAFE_UDP_PAYLOAD = exports.WATCHER_RECOVERY_DELAY = exports.CONTENT_HASH_ALGORITHM = exports.FILE_WATCH_DEBOUNCE_DELAY = exports.MAX_DELTAS_PER_PACKET = exports.DELTA_BUFFER_DROP_RATIO = exports.MAX_DELTAS_BUFFER_SIZE = exports.MILLISECONDS_PER_MINUTE = exports.PING_TIMEOUT_BUFFER = exports.DEFAULT_DELTA_TIMER = void 0;
+exports.PACKET_INSPECTOR_MAX_CLIENTS = exports.PACKET_CAPTURE_MAX_PACKETS = exports.MONITORING_ALERT_COOLDOWN = exports.MONITORING_PATH_LATENCY_WINDOW = exports.MONITORING_RETRANSMIT_HISTORY_SIZE = exports.MONITORING_HEATMAP_BUCKET_DURATION = exports.MONITORING_HEATMAP_BUCKETS = exports.HELLO_PAYLOAD_MAX_BYTES = exports.SNAPSHOT_REPLAY_CHUNK_SIZE = exports.DELTA_SEND_RETRY_BACKOFF_MS = exports.DELTA_SEND_MAX_RETRIES = exports.SOURCE_SNAPSHOT_MAX_OBJECT_KEYS = exports.SOURCE_SNAPSHOT_MAX_ARRAY_LENGTH = exports.SOURCE_SNAPSHOT_MAX_DEPTH = exports.SOURCE_SNAPSHOT_MAX_STRING_LENGTH = exports.SOURCE_SNAPSHOT_MAX_KEY_LENGTH = exports.SOURCE_SNAPSHOT_MAX_PROVIDERS = exports.SOURCE_SNAPSHOT_INTERVAL_MS = exports.SOURCE_REGISTRY_TTL_MS = exports.SOURCE_REGISTRY_MAX_RECORDS = exports.OUTBOUND_DEDUPE_MAX_ENTRIES = exports.OUTBOUND_DEDUPE_CLEANUP_INTERVAL_MS = exports.SUPPRESSED_DUPLICATE_STATS_MAX_SIZE = exports.OUTBOUND_DUPLICATE_SUPPRESS_MS = exports.PATH_THROTTLE_STATE_MAX = exports.VALUE_DEDUP_CACHE_MAX = exports.PATH_STATS_MAX_SIZE = void 0;
 exports.calculateMaxDeltasPerBatch = calculateMaxDeltasPerBatch;
+exports.clampBytesPerDeltaSample = clampBytesPerDeltaSample;
 // Delta and timing
 exports.DEFAULT_DELTA_TIMER = 1000; // milliseconds
 exports.PING_TIMEOUT_BUFFER = 10000; // milliseconds - extra buffer for ping timeout
@@ -17,6 +18,8 @@ exports.WATCHER_RECOVERY_DELAY = 5000; // milliseconds
 // UDP and network
 exports.MAX_SAFE_UDP_PAYLOAD = 1400; // Maximum safe UDP payload size (avoid fragmentation)
 exports.BROTLI_QUALITY_HIGH = 6; // Balanced quality: ~90% of max compression at ~10% of the CPU cost
+exports.BROTLI_QUALITY_MIN = 0; // Fastest, lowest ratio
+exports.BROTLI_QUALITY_MAX = 11; // Highest ratio, ~3-5× more CPU than quality 6
 exports.UDP_RETRY_MAX = 3; // Maximum UDP send retries
 exports.UDP_RETRY_DELAY = 100; // milliseconds - base retry delay
 exports.UDP_SEND_TIMEOUT_MS = 5000; // Maximum ms to wait for socket.send() callback
@@ -66,6 +69,13 @@ exports.MAX_PARSE_PAYLOAD_SIZE = 512 * 1024; // 512 KB
 exports.METRICS_PUBLISH_INTERVAL = 1000; // Interval (ms) for publishing metrics to Signal K
 exports.BANDWIDTH_HISTORY_MAX = 60; // Keep 60 data points (5 minutes at 5s intervals)
 exports.PATH_STATS_MAX_SIZE = 500; // Max tracked paths in pathStats Map (prevent unbounded growth)
+// Outbound bandwidth-optimization per-(context,path) caches. Bounded with
+// LRU eviction so a link that sees many distinct paths (e.g. N2K source-address
+// churn or many vessel contexts) cannot grow these maps without limit. The
+// cap is far above the unique-path count of a normal boat, so eviction is a
+// safety valve rather than a routine event.
+exports.VALUE_DEDUP_CACHE_MAX = 10000; // Max (context,path) entries in the dedup cache
+exports.PATH_THROTTLE_STATE_MAX = 10000; // Max (context,path) entries in the throttle state
 // Outbound delta deduplication. signalk-server's subscriptionmanager can
 // deliver the same cached/live pair about one fixed-policy window apart;
 // 1500 ms catches that without suppressing legitimate periodic resends.
@@ -113,3 +123,21 @@ function calculateMaxDeltasPerBatch(avgBytes) {
     const raw = Math.floor((exports.MAX_SAFE_UDP_PAYLOAD * exports.SMART_BATCH_SAFETY_MARGIN) / avgBytes);
     return Math.max(exports.SMART_BATCH_MIN_DELTAS, Math.min(exports.SMART_BATCH_MAX_DELTAS, raw));
 }
+/**
+ * Clamp a single bytes-per-delta observation before it feeds the smart-batch
+ * EMA. Aggressive per-path throttling/dedup can collapse a batch to a single
+ * delta whose packet is dominated by fixed overhead (compression header,
+ * crypto IV + auth tag) or that is itself oversized. Without a bound, one such
+ * outlier sample can drag the rolling average to an extreme and keep the
+ * batcher mis-sized long after the burst passes. Clamping each sample to
+ * [1, MAX_SAFE_UDP_PAYLOAD] keeps the EMA stable while still letting it track
+ * genuine payload-size shifts.
+ *
+ * @param bytesPerDelta - Raw observation (packet bytes / deltas in packet)
+ * @returns Sample clamped to a sane range
+ */
+function clampBytesPerDeltaSample(bytesPerDelta) {
+    if (!Number.isFinite(bytesPerDelta) || bytesPerDelta < 1)
+        return 1;
+    return Math.min(exports.MAX_SAFE_UDP_PAYLOAD, bytesPerDelta);
+}