signalk-edge-link 2.4.0 → 2.4.1

package/lib/instance.js

@@ -22,6 +22,7 @@ const dgram_1 = __importDefault(require("dgram"));
 const crypto_1 = require("./crypto");
 const ping_monitor_1 = __importDefault(require("ping-monitor"));
 const metrics_1 = __importDefault(require("./metrics"));
+const source_replication_1 = require("./source-replication");
 const pipeline_1 = __importDefault(require("./pipeline"));
 const pipeline_v2_client_1 = require("./pipeline-v2-client");
 const pipeline_v2_server_1 = require("./pipeline-v2-server");
@@ -32,8 +33,10 @@ const config_io_1 = require("./config-io");
 const config_watcher_1 = require("./config-watcher");
 const metadata_1 = require("./metadata");
 const delta_sanitizer_1 = require("./delta-sanitizer");
+const source_snapshot_1 = require("./source-snapshot");
 const DELTA_SEND_MAX_RETRIES = 1;
 const DELTA_SEND_RETRY_BACKOFF_MS = 100;
+const SOURCE_SNAPSHOT_INTERVAL_MS = 60000;
 // ── Helpers ──────────────────────────────────────────────────────────────────
 /**
  * Derive a URL-safe identifier from a human-readable name.
@@ -102,10 +105,12 @@ function createInstance(app, options, instanceId, pluginId, onStatusChange) {
         processDelta: null,
         metaConfig: null,
         metaTimer: null,
+        sourceSnapshotTimer: null,
         metaDiffBuffer: [],
         metaDiffFlushTimer: null,
         metaSnapshotTimers: [],
-        lastMetaRequestAt: 0
+        lastMetaRequestAt: 0,
+        sourceRegistry: (0, source_replication_1.createSourceRegistry)(app)
     };
     const metricsApi = (0, metrics_1.default)();
     const { metrics, recordError, resetMetrics } = metricsApi;
@@ -378,6 +383,40 @@ function createInstance(app, options, instanceId, pluginId, onStatusChange) {
             app.debug(`[${instanceId}] META_REQUEST snapshot failed: ${msg}`);
         });
     }
+    async function sendSourceSnapshot() {
+        if (state.stopped ||
+            !state.readyToSend ||
+            !state.pipeline ||
+            typeof state.pipeline.sendSourceSnapshot !== "function" ||
+            !options.secretKey ||
+            !options.udpAddress) {
+            return;
+        }
+        const sources = (0, source_snapshot_1.collectSourceSnapshot)(appProxy);
+        if (!sources || Object.keys(sources).length === 0) {
+            return;
+        }
+        try {
+            await state.pipeline.sendSourceSnapshot(sources, options.secretKey, options.udpAddress, options.udpPort);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            app.debug(`[${instanceId}] source snapshot send failed: ${msg}`);
+        }
+    }
+    function restartSourceSnapshotTimer() {
+        clearInterval(state.sourceSnapshotTimer ?? undefined);
+        state.sourceSnapshotTimer = null;
+        if ((options.protocolVersion ?? 0) < 2) {
+            return;
+        }
+        state.sourceSnapshotTimer = setInterval(() => {
+            sendSourceSnapshot().catch((err) => {
+                const msg = err instanceof Error ? err.message : String(err);
+                app.debug(`[${instanceId}] periodic source snapshot failed: ${msg}`);
+            });
+        }, SOURCE_SNAPSHOT_INTERVAL_MS);
+    }
     /** Thin wrapper around the parser in `metadata.ts` so the instance log
      *  line is tagged with this connection's instanceId. Errors from the
      *  shared parser already have the `[meta-config]` prefix. */
@@ -950,6 +989,10 @@ function createInstance(app, options, instanceId, pluginId, onStatusChange) {
                             state.readyToSend = true;
                             _setStatus("UDP socket recovered", true);
                             app.debug(`[${instanceId}] UDP socket recovered`);
+                            sendSourceSnapshot().catch((err) => {
+                                const msg = err instanceof Error ? err.message : String(err);
+                                app.debug(`[${instanceId}] recovery source snapshot failed: ${msg}`);
+                            });
                             // A socket-level recovery is the strongest local signal that the
                             // remote receiver may have restarted. Re-prime its meta cache
                             // with a full snapshot so it doesn't have to wait a full
@@ -1027,6 +1070,11 @@ function createInstance(app, options, instanceId, pluginId, onStatusChange) {
                 state.heartbeatHandle = v2Pipeline.startHeartbeat(options.udpAddress ?? "", options.udpPort, {
                     heartbeatInterval: options.heartbeatInterval
                 });
+                restartSourceSnapshotTimer();
+                sendSourceSnapshot().catch((err) => {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    app.debug(`[${instanceId}] initial source snapshot failed: ${msg}`);
+                });
                 state.socketUdp.on("message", (msg, rinfo) => {
                     v2Pipeline.handleControlPacket(msg, rinfo).catch((err) => {
                         const errMsg = err instanceof Error ? err.message : String(err);
@@ -1104,6 +1152,8 @@ function createInstance(app, options, instanceId, pluginId, onStatusChange) {
         state.helloMessageSender = null;
         clearInterval(state.metaTimer ?? undefined);
         state.metaTimer = null;
+        clearInterval(state.sourceSnapshotTimer ?? undefined);
+        state.sourceSnapshotTimer = null;
         clearTimeout(state.metaDiffFlushTimer ?? undefined);
         state.metaDiffFlushTimer = null;
         for (const handle of state.metaSnapshotTimers) {

package/lib/metadata.js

@@ -49,6 +49,37 @@ function stableStringify(value) {
 function hashMeta(meta) {
     return (0, crypto_1.createHash)("sha1").update(stableStringify(meta)).digest("hex");
 }
+const STRIP_UNSET = Symbol("strip-unset");
+/**
+ * Deep-clone a metadata payload while removing unset placeholders.
+ *
+ * Explicit `null` values are preserved so metadata clear operations
+ * (`{ someField: null }`) can propagate to receivers.
+ *
+ * Returns a private sentinel when no useful data remains.
+ */
+function stripUnsetDeep(value) {
+    if (value === undefined) {
+        return STRIP_UNSET;
+    }
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        const cleaned = value
+            .map((item) => stripUnsetDeep(item))
+            .filter((item) => item !== STRIP_UNSET);
+        return cleaned.length > 0 ? cleaned : STRIP_UNSET;
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        const cleaned = stripUnsetDeep(v);
+        if (cleaned !== STRIP_UNSET) {
+            out[k] = cleaned;
+        }
+    }
+    return Object.keys(out).length > 0 ? out : STRIP_UNSET;
+}
 /**
  * Cache of the last-sent meta value (hash) per `context+path` pair.
  *
@@ -137,7 +168,13 @@ function walkMeta(node, pathParts, onMeta) {
     }
     const obj = node;
     if (obj.meta && typeof obj.meta === "object" && !Array.isArray(obj.meta)) {
-        onMeta(pathParts.join("."), obj.meta);
+        const cleanedMeta = stripUnsetDeep(obj.meta);
+        if (cleanedMeta !== STRIP_UNSET &&
+            cleanedMeta &&
+            typeof cleanedMeta === "object" &&
+            !Array.isArray(cleanedMeta)) {
+            onMeta(pathParts.join("."), cleanedMeta);
+        }
     }
     for (const key of Object.keys(obj)) {
         // Signal K "value", "timestamp", "$source" are leaves, not sub-paths.
@@ -377,10 +414,17 @@ function extractLiveMeta(delta, config, selfContext) {
             else {
                 context = rawContext;
             }
+            const cleanedMeta = stripUnsetDeep(m.value);
+            if (cleanedMeta === STRIP_UNSET ||
+                !cleanedMeta ||
+                typeof cleanedMeta !== "object" ||
+                Array.isArray(cleanedMeta)) {
+                continue;
+            }
             out.push({
                 context,
                 path: m.path,
-                meta: m.value
+                meta: cleanedMeta
             });
         }
     }

package/lib/pipeline-v2-client.js

@@ -107,6 +107,7 @@ function createPipelineV2Client(app, state, metricsApi) {
     // layer that knows how to build a snapshot from `app.signalk.retrieve()`.
     let metaRequestHandler = null;
     let metaEnvelopeSeq = 0;
+    let sourceEnvelopeSeq = 0;
     // Seed all four meta bandwidth counters so downstream consumers (metrics
     // publishers, prometheus exporter, tests) always see numeric zeros rather
     // than undefined on a fresh pipeline. Uses || 0 at write sites elsewhere as
@@ -398,6 +399,128 @@ function createPipelineV2Client(app, state, metricsApi) {
             throw error;
         }
     }
+    function isSourceRecord(value) {
+        return value !== null && typeof value === "object" && !Array.isArray(value);
+    }
+    function mergeSourcePatch(target, patch) {
+        for (const [key, value] of Object.entries(patch)) {
+            const current = target[key];
+            if (isSourceRecord(current) && isSourceRecord(value)) {
+                mergeSourcePatch(current, value);
+            }
+            else {
+                target[key] = value;
+            }
+        }
+    }
+    function buildSourcePatch(path, value) {
+        let patch = value;
+        for (let i = path.length - 1; i >= 0; i--) {
+            patch = { [path[i]]: patch };
+        }
+        return patch;
+    }
+    function flattenSourcePatches(value, path = []) {
+        if (!isSourceRecord(value)) {
+            return path.length > 0 ? [buildSourcePatch(path, value)] : [];
+        }
+        const entries = Object.entries(value);
+        if (path.length > 0 && entries.length === 0) {
+            return [buildSourcePatch(path, {})];
+        }
+        const patches = [];
+        for (const [key, entry] of entries) {
+            patches.push(...flattenSourcePatches(entry, path.concat(key)));
+        }
+        return patches;
+    }
+    function buildSourceChunk(patches) {
+        const out = {};
+        for (const patch of patches) {
+            mergeSourcePatch(out, patch);
+        }
+        return out;
+    }
+    async function buildSourceSnapshotPacket(sources, envelopeSeq, idx, total, useMsgpack, secretKey) {
+        const envelope = {
+            v: 1,
+            kind: "sources",
+            seq: envelopeSeq >>> 0,
+            idx,
+            total,
+            sources
+        };
+        const serialized = (0, pipeline_utils_1.deltaBuffer)(envelope, useMsgpack);
+        const compressed = await (0, pipeline_utils_1.compressPayload)(serialized, useMsgpack);
+        const encrypted = (0, crypto_1.encryptBinary)(compressed, secretKey, { stretchAsciiKey });
+        return packetBuilder.buildMetadataPacket(encrypted, {
+            compressed: true,
+            encrypted: true,
+            messagepack: useMsgpack,
+            pathDictionary: false
+        });
+    }
+    async function chunkSourceSnapshot(sources, envelopeSeq, useMsgpack, secretKey) {
+        const sourcePatches = flattenSourcePatches(sources);
+        const chunks = [];
+        let currentPatches = [];
+        for (const patch of sourcePatches) {
+            const candidatePatches = currentPatches.concat([patch]);
+            const candidate = buildSourceChunk(candidatePatches);
+            const candidatePacket = await buildSourceSnapshotPacket(candidate, envelopeSeq, sourcePatches.length, sourcePatches.length, useMsgpack, secretKey);
+            if (currentPatches.length > 0 && candidatePacket.length > constants_1.MAX_SAFE_UDP_PAYLOAD) {
+                chunks.push(currentPatches);
+                currentPatches = [patch];
+            }
+            else {
+                currentPatches = candidatePatches;
+            }
+        }
+        if (currentPatches.length > 0) {
+            chunks.push(currentPatches);
+        }
+        let finalChunks = chunks;
+        while (true) {
+            const packets = [];
+            let splitIndex = -1;
+            for (let i = 0; i < finalChunks.length; i++) {
+                const patchChunk = finalChunks[i];
+                const sourceChunk = buildSourceChunk(patchChunk);
+                const packet = await buildSourceSnapshotPacket(sourceChunk, envelopeSeq, i, finalChunks.length, useMsgpack, secretKey);
+                packets.push({ sources: sourceChunk, packet });
+                if (packet.length > constants_1.MAX_SAFE_UDP_PAYLOAD && patchChunk.length > 1) {
+                    splitIndex = i;
+                    break;
+                }
+            }
+            if (splitIndex === -1) {
+                return packets;
+            }
+            const patchesToSplit = finalChunks[splitIndex];
+            const midpoint = Math.ceil(patchesToSplit.length / 2);
+            finalChunks = [
+                ...finalChunks.slice(0, splitIndex),
+                patchesToSplit.slice(0, midpoint),
+                patchesToSplit.slice(midpoint),
+                ...finalChunks.slice(splitIndex + 1)
+            ];
+        }
+    }
+    function recordSentMetadataPacket(packet, udpAddress, udpPort) {
+        if (monitoringHooks) {
+            const rinfo = { address: udpAddress, port: udpPort };
+            if (monitoringHooks.packetCapture) {
+                monitoringHooks.packetCapture.capture(packet, "send", rinfo);
+            }
+            if (monitoringHooks.packetInspector) {
+                monitoringHooks.packetInspector.inspect(packet, "send", rinfo);
+            }
+        }
+        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++;
+    }
     /**
      * Send a batch of Signal K metadata entries to the receiver as one or more
      * METADATA (0x06) packets. Mirrors the compress → encrypt → packet-build
@@ -446,19 +569,7 @@ function createPipelineV2Client(app, state, metricsApi) {
                     metrics.smartBatching.oversizedPackets++;
                 }
                 await udpSendAsync(packet, udpAddress, udpPort);
-                if (monitoringHooks) {
-                    const rinfo = { address: udpAddress, port: udpPort };
-                    if (monitoringHooks.packetCapture) {
-                        monitoringHooks.packetCapture.capture(packet, "send", rinfo);
-                    }
-                    if (monitoringHooks.packetInspector) {
-                        monitoringHooks.packetInspector.inspect(packet, "send", rinfo);
-                    }
-                }
-                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++;
+                recordSentMetadataPacket(packet, udpAddress, udpPort);
             }
             // Count one envelope per call (a multi-chunk envelope is logically one
             // snapshot/diff, even though it shows up in metaPacketsOut as N).
@@ -481,6 +592,35 @@ function createPipelineV2Client(app, state, metricsApi) {
             throw error instanceof Error ? error : new Error(msg);
         }
     }
+    async function sendSourceSnapshot(sources, secretKey, udpAddress, udpPort) {
+        try {
+            if (!state.options) {
+                app.debug("sendSourceSnapshot called but plugin is stopped, ignoring");
+                return;
+            }
+            if (!sources || Object.keys(sources).length === 0) {
+                return;
+            }
+            const useMsgpack = !!state.options.useMsgpack;
+            const envelopeSeq = sourceEnvelopeSeq++ >>> 0;
+            const chunks = await chunkSourceSnapshot(sources, envelopeSeq, useMsgpack, secretKey);
+            for (const { packet } of chunks) {
+                if (packet.length > constants_1.MAX_SAFE_UDP_PAYLOAD) {
+                    app.debug(`Warning: v2 source snapshot packet size ${packet.length} bytes exceeds safe MTU (${constants_1.MAX_SAFE_UDP_PAYLOAD}), may fragment.`);
+                    metrics.smartBatching.oversizedPackets++;
+                }
+                await udpSendAsync(packet, udpAddress, udpPort);
+                recordSentMetadataPacket(packet, udpAddress, udpPort);
+            }
+            app.debug(`v2 source snapshot sent: sources=${Object.keys(sources).length}, chunks=${chunks.length}, envSeq=${envelopeSeq}`);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            app.error(`v2 sendSourceSnapshot error: ${msg}`);
+            recordError("general", `v2 sendSourceSnapshot error: ${msg}`);
+            throw error;
+        }
+    }
     function setMetaRequestHandler(handler) {
         metaRequestHandler = handler;
     }
@@ -960,6 +1100,7 @@ function createPipelineV2Client(app, state, metricsApi) {
     return {
         sendDelta,
         sendMetadata,
+        sendSourceSnapshot,
         setMetaRequestHandler,
         getPacketBuilder,
         getRetransmitQueue,

package/lib/pipeline-v2-server.js

@@ -56,6 +56,8 @@ const msgpack = __importStar(require("@msgpack/msgpack"));
 const crypto_1 = require("./crypto");
 const pathDictionary_1 = require("./pathDictionary");
 const delta_sanitizer_1 = require("./delta-sanitizer");
+const source_dispatch_1 = require("./source-dispatch");
+const source_snapshot_1 = require("./source-snapshot");
 const packet_1 = require("./packet");
 const sequence_1 = require("./sequence");
 const metrics_publisher_1 = require("./metrics-publisher");
@@ -154,6 +156,8 @@ function createPipelineV2Server(app, state, metricsApi) {
             // packet can still be processed for this request without polluting state.
             return {
                 key,
+                sourceClientInstanceId: null,
+                clientId: null,
                 address: rinfo.address,
                 port: rinfo.port,
                 sequenceTracker: new sequence_1.SequenceTracker({
@@ -175,11 +179,15 @@ function createPipelineV2Server(app, state, metricsApi) {
                 rateLimitWindowStart: Date.now(),
                 metaRequested: false,
                 lastMetaEnvSeq: null,
-                seenMetaChunkIdx: new Set()
+                seenMetaChunkIdx: new Set(),
+                lastSourceEnvSeq: null,
+                seenSourceChunkIdx: new Set()
             };
         }
         const session = {
             key,
+            sourceClientInstanceId: null,
+            clientId: null,
             address: rinfo.address,
             port: rinfo.port,
             sequenceTracker: new sequence_1.SequenceTracker({
@@ -206,7 +214,9 @@ function createPipelineV2Server(app, state, metricsApi) {
             metaRequested: false,
             // Stale-envelope rejection for METADATA packets
             lastMetaEnvSeq: null,
-            seenMetaChunkIdx: new Set()
+            seenMetaChunkIdx: new Set(),
+            lastSourceEnvSeq: null,
+            seenSourceChunkIdx: new Set()
         };
         clientSessions.set(key, session);
         app.debug(`[v2-server] new client session: ${key}`);
@@ -252,6 +262,8 @@ function createPipelineV2Server(app, state, metricsApi) {
     let lastMetricsTime = Date.now();
     let lastBytesReceived = 0;
     let lastPacketsReceived = 0;
+    let previousSourceMissingIdentity = 0;
+    let previousSourceConflicts = 0;
     // Rate-limit operator-visible warnings for protocol-version mismatches so a
     // persistently misconfigured peer is noticeable in logs without flooding them.
     const PROTOCOL_VERSION_MISMATCH_WARN_INTERVAL_MS = 60000;
@@ -450,6 +462,61 @@ function createPipelineV2Server(app, state, metricsApi) {
             ackTimer = null;
         }
     }
+    function shouldDropEnvelopeBySeq(session, env, channel) {
+        if (!session || typeof env.seq !== "number" || !Number.isFinite(env.seq)) {
+            return false;
+        }
+        const envSeq = env.seq >>> 0;
+        const envIdx = typeof env.idx === "number" && Number.isFinite(env.idx) ? env.idx >>> 0 : 0;
+        const isSource = channel === "source snapshot";
+        const seenChunkIdx = isSource ? session.seenSourceChunkIdx : session.seenMetaChunkIdx;
+        let lastEnvSeq = isSource ? session.lastSourceEnvSeq : session.lastMetaEnvSeq;
+        const setLastEnvSeq = (value) => {
+            if (isSource) {
+                session.lastSourceEnvSeq = value;
+            }
+            else {
+                session.lastMetaEnvSeq = value;
+            }
+            lastEnvSeq = value;
+        };
+        // Sender-restart detection: the client's envelope sequence counter is
+        // initialised to 0 at process start, so an incoming envSeq of 0 with a
+        // sufficiently-advanced previous seq is a strong signal that the peer
+        // restarted. The threshold guards against first-packet replays.
+        if (lastEnvSeq !== null && envSeq === 0 && lastEnvSeq >= META_RESTART_THRESHOLD) {
+            app.debug(`[v2-server] ${channel} sender restart detected for ${session.key} ` +
+                `(last seq was ${lastEnvSeq}); resetting ${channel} state`);
+            setLastEnvSeq(null);
+            seenChunkIdx.clear();
+            if (!isSource) {
+                session.metaRequested = false;
+            }
+        }
+        if (lastEnvSeq !== null) {
+            const distance = (envSeq - lastEnvSeq) >>> 0;
+            if (distance !== 0 && distance >= 0x80000000) {
+                metrics.duplicatePackets = (metrics.duplicatePackets || 0) + 1;
+                app.debug(`[v2-server] stale ${channel} envelope seq=${envSeq} from ${session.key} (last=${lastEnvSeq}), dropping`);
+                return true;
+            }
+            if (distance !== 0) {
+                setLastEnvSeq(envSeq);
+                seenChunkIdx.clear();
+            }
+            else if (seenChunkIdx.has(envIdx)) {
+                metrics.duplicatePackets = (metrics.duplicatePackets || 0) + 1;
+                app.debug(`[v2-server] duplicate ${channel} chunk seq=${envSeq} idx=${envIdx} from ${session.key}, dropping`);
+                return true;
+            }
+        }
+        else {
+            setLastEnvSeq(envSeq);
+            seenChunkIdx.clear();
+        }
+        seenChunkIdx.add(envIdx);
+        return false;
+    }
     /**
      * Decrypt and dispatch a METADATA (0x06) packet.
      *
@@ -496,12 +563,20 @@ function createPipelineV2Server(app, state, metricsApi) {
                 return;
             }
             const env = content;
-            if (!Array.isArray(env.entries) || env.entries.length === 0) {
+            const hasSourceSnapshot = env.kind === "sources" &&
+                env.sources !== null &&
+                typeof env.sources === "object" &&
+                !Array.isArray(env.sources);
+            const entries = Array.isArray(env.entries) ? env.entries : [];
+            if (!hasSourceSnapshot && entries.length === 0) {
                 metrics.malformedPackets = (metrics.malformedPackets || 0) + 1;
                 app.debug("v2 META envelope has no entries, dropping");
                 recordError("general", "v2 META envelope has no entries");
                 return;
             }
+            if (hasSourceSnapshot && shouldDropEnvelopeBySeq(session, env, "source snapshot")) {
+                return;
+            }
             // Drop stale/duplicate envelopes that UDP reordered or replayed. The
             // inner envelope `seq` identifies a batch (shared across all chunks of
             // a multi-chunk snapshot/diff); the inner `idx` identifies a specific
@@ -510,7 +585,10 @@ function createPipelineV2Server(app, state, metricsApi) {
             //   - within the current batch, reject any (seq, idx) pair already
             //     processed ("exact replay"); other idx values for the same seq
             //     remain accepted so multi-chunk batches still apply in full.
-            if (session && typeof env.seq === "number" && Number.isFinite(env.seq)) {
+            if (!hasSourceSnapshot &&
+                session &&
+                typeof env.seq === "number" &&
+                Number.isFinite(env.seq)) {
                 const envSeq = env.seq >>> 0;
                 const envIdx = typeof env.idx === "number" && Number.isFinite(env.idx) ? env.idx >>> 0 : 0;
                 // Sender-restart detection: the client's meta sequence counter is
@@ -558,12 +636,17 @@ function createPipelineV2Server(app, state, metricsApi) {
                 }
                 session.seenMetaChunkIdx.add(envIdx);
             }
+            if (hasSourceSnapshot) {
+                const added = (0, source_snapshot_1.mergeSourceSnapshot)(app, env.sources);
+                app.debug(`v2 source snapshot received: sources=${Object.keys(env.sources || {}).length}, added=${added}, envSeq=${env.seq ?? "?"}`);
+                return;
+            }
             // Group entries by context so the local Signal K server sees one delta
             // per context rather than one per path. Reduces app.handleMessage
             // overhead on big snapshots without changing semantics.
             const nowIso = new Date().toISOString();
             const byContext = new Map();
-            for (const rawEntry of env.entries) {
+            for (const rawEntry of entries) {
                 if (!rawEntry || typeof rawEntry.meta !== "object" || !rawEntry.meta) {
                     continue;
                 }
@@ -605,7 +688,7 @@ function createPipelineV2Server(app, state, metricsApi) {
                 };
                 app.handleMessage("", deltaMessage);
             }
-            app.debug(`v2 meta received: kind=${env.kind ?? "?"}, entries=${env.entries.length}, contexts=${byContext.size}, envSeq=${env.v ?? "?"}`);
+            app.debug(`v2 meta received: kind=${env.kind ?? "?"}, entries=${entries.length}, contexts=${byContext.size}, envSeq=${env.seq ?? "?"}`);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -712,6 +795,16 @@ function createPipelineV2Server(app, state, metricsApi) {
                 try {
                     const info = JSON.parse(parsed.payload.toString());
                     app.debug(`v2 hello from client: ${JSON.stringify(info)}`);
+                    if (session && info && typeof info === "object") {
+                        const helloClientId = typeof info.clientId === "string" && info.clientId.trim()
+                            ? info.clientId.trim()
+                            : null;
+                        const helloInstanceId = typeof info.instanceId === "string" && info.instanceId.trim()
+                            ? info.instanceId.trim()
+                            : null;
+                        session.clientId = helloClientId;
+                        session.sourceClientInstanceId = helloInstanceId || helloClientId;
+                    }
                 }
                 catch (parseErr) {
                     app.error(`v2 failed to parse HELLO payload: ${parseErr instanceof Error ? parseErr.message : String(parseErr)}`);
@@ -879,12 +972,25 @@ function createPipelineV2Server(app, state, metricsApi) {
                     continue;
                 }
                 deltaMessage = sanitizedDelta;
+                deltaMessage = (0, source_dispatch_1.normalizeDeltaSourceRefs)(deltaMessage);
                 _ingestRemoteTelemetry(deltaMessage);
                 if (!Array.isArray(deltaMessage.updates) || deltaMessage.updates.length === 0) {
                     continue;
                 }
+                if (state.sourceRegistry && typeof state.sourceRegistry.upsertFromDelta === "function") {
+                    const deltaRecord = deltaMessage;
+                    const deltaSourceInstanceId = deltaMessage &&
+                        typeof deltaMessage === "object" &&
+                        typeof deltaRecord.sourceClientInstanceId === "string"
+                        ? deltaRecord.sourceClientInstanceId || null
+                        : null;
+                    const stableSourceClientId = (session && (session.sourceClientInstanceId || session.clientId)) ||
+                        deltaSourceInstanceId ||
+                        "unknown";
+                    state.sourceRegistry.upsertFromDelta(deltaMessage, stableSourceClientId);
+                }
                 trackPathStats(deltaMessage, decompressed.length / deltas.length);
-                app.handleMessage("", deltaMessage);
+                (0, source_dispatch_1.handleMessageBySource)(app, deltaMessage);
                 metrics.deltasReceived++;
             }
             app.debug(`v2 received: seq=${parsed.sequence}, ${deltaCount} deltas, ${packet.length} bytes`);
@@ -943,7 +1049,8 @@ function createPipelineV2Server(app, state, metricsApi) {
             sessions,
             totalSessions: clientSessions.size,
             acksSent: metrics.acksSent,
-            naksSent: metrics.naksSent
+            naksSent: metrics.naksSent,
+            sourceReplication: state.sourceRegistry ? state.sourceRegistry.getMetrics() : null
         };
     }
     /**
@@ -1027,6 +1134,16 @@ function createPipelineV2Server(app, state, metricsApi) {
         const effectiveQueueDepth = hasRemoteTelemetry ? remote.queueDepth || 0 : 0;
         const effectiveRetransmitRate = hasRemoteTelemetry ? remote.retransmitRate || 0 : 0;
         const effectiveActiveLink = hasRemoteTelemetry ? remote.activeLink || "primary" : "primary";
+        const sourceReplicationMetrics = state.sourceRegistry
+            ? state.sourceRegistry.getMetrics()
+            : { upserts: 0, noops: 0, missingIdentity: 0, conflicts: 0 };
+        const deltaMissing = sourceReplicationMetrics.missingIdentity - previousSourceMissingIdentity;
+        const deltaConflicts = sourceReplicationMetrics.conflicts - previousSourceConflicts;
+        if (deltaMissing > 0 || deltaConflicts > 0) {
+            app.debug(`[source-replication] +missingIdentity=${deltaMissing} +conflicts=${deltaConflicts} totalMissingIdentity=${sourceReplicationMetrics.missingIdentity} totalConflicts=${sourceReplicationMetrics.conflicts} size=${state.sourceRegistry.snapshot().size}`);
+        }
+        previousSourceMissingIdentity = sourceReplicationMetrics.missingIdentity;
+        previousSourceConflicts = sourceReplicationMetrics.conflicts;
         // Publish to Signal K
         metricsPublisher.publish({
             rtt: effectiveRtt,

package/lib/pipeline.js

@@ -36,6 +36,7 @@ const msgpack = __importStar(require("@msgpack/msgpack"));
 const crypto_1 = require("./crypto");
 const pathDictionary_1 = require("./pathDictionary");
 const delta_sanitizer_1 = require("./delta-sanitizer");
+const source_dispatch_1 = require("./source-dispatch");
 const pipeline_utils_1 = require("./pipeline-utils");
 const constants_1 = require("./constants");
 const metadata_1 = require("./metadata");
@@ -294,9 +295,10 @@ function createPipeline(app, state, metricsApi) {
                     app.debug(`Skipping delta with no valid Signal K values at index ${i}`);
                     continue;
                 }
+                deltaMessage = (0, source_dispatch_1.normalizeDeltaSourceRefs)(deltaMessage);
                 // Track path stats for server-side analytics
                 trackPathStats(deltaMessage, decompressed.length / deltas.length);
-                app.handleMessage("", deltaMessage);
+                (0, source_dispatch_1.handleMessageBySource)(app, deltaMessage);
                 // Log a compact summary only — never log full delta values which may
                 // contain sensitive data (position, fuel, MMSI) in plaintext logs.
                 app.debug(`delta ctx=${deltaMessage.context ?? "?"} updates=${Array.isArray(deltaMessage.updates) ? deltaMessage.updates.length : 0}`);

package/lib/routes/metrics.js

@@ -9,7 +9,7 @@ const prometheus_1 = require("../prometheus");
  * @param ctx - Shared route context (helpers, middleware, registry)
  */
 function register(router, ctx) {
-    const { rateLimitMiddleware, instanceRegistry, getFirstBundle, getEffectiveNetworkQuality, getActiveMetricsPublisher, buildFullMetricsResponse } = ctx;
+    const { rateLimitMiddleware, instanceRegistry, getFirstBundle, getEffectiveNetworkQuality, getActiveMetricsPublisher, buildFullMetricsResponse, managementAuthMiddleware } = ctx;
     router.get("/metrics", rateLimitMiddleware, (req, res) => {
         try {
             const bundle = getFirstBundle();
@@ -124,4 +124,28 @@ function register(router, ctx) {
             res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
         }
     });
+    router.get("/sources", rateLimitMiddleware, managementAuthMiddleware("sources.read"), (req, res) => {
+        try {
+            const serverBundle = instanceRegistry
+                .getAll()
+                .find((bundle) => bundle.state && bundle.state.isServerMode && bundle.state.sourceRegistry) || null;
+            const bundle = serverBundle || getFirstBundle();
+            if (!bundle) {
+                return res.status(503).json({ error: "Plugin not started" });
+            }
+            const { state } = bundle;
+            if (!state.sourceRegistry) {
+                return res.json({
+                    schemaVersion: 1,
+                    size: 0,
+                    sources: [],
+                    legacy: { byLabel: {}, bySourceRef: {} }
+                });
+            }
+            return res.json(state.sourceRegistry.snapshot());
+        }
+        catch (err) {
+            return res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
 }

package/lib/routes.js

@@ -442,6 +442,12 @@ function createRoutes(app, instanceRegistry, pluginRef) {
                     timestamp: metrics.lastErrorTime,
                     timeAgo: metrics.lastErrorTime ? Date.now() - metrics.lastErrorTime : null
                 }
+                : null,
+            sourceReplication: state.sourceRegistry
+                ? {
+                    metrics: state.sourceRegistry.getMetrics(),
+                    registry: null
+                }
                 : null
         };
         return metricsData;

package/lib/source-dispatch.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeDeltaSourceRefs = normalizeDeltaSourceRefs;
+exports.handleMessageBySource = handleMessageBySource;
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function getSourceLabel(update) {
+    const source = isRecord(update.source) ? update.source : null;
+    const label = source && typeof source.label === "string" ? source.label.trim() : "";
+    return label.length > 0 ? label : "";
+}
+function hasStaleEdgeLinkSourceRef(update) {
+    const sourceLabel = getSourceLabel(update);
+    const sourceRef = typeof update.$source === "string" ? update.$source.trim() : "";
+    if (!sourceLabel || !sourceRef || sourceLabel === "signalk-edge-link") {
+        return false;
+    }
+    return (sourceRef === "signalk-edge-link" ||
+        sourceRef.startsWith("signalk-edge-link.") ||
+        sourceRef.startsWith("signalk-edge-link:"));
+}
+function normalizeUpdateSourceRef(update) {
+    if (!hasStaleEdgeLinkSourceRef(update)) {
+        return update;
+    }
+    const cloned = { ...update };
+    delete cloned.$source;
+    return cloned;
+}
+function cloneUpdate(update) {
+    const normalized = normalizeUpdateSourceRef(update);
+    const cloned = {
+        ...normalized,
+        source: isRecord(normalized.source)
+            ? { ...normalized.source }
+            : normalized.source,
+        values: Array.isArray(normalized.values)
+            ? normalized.values.map((value) => ({ ...value }))
+            : normalized.values,
+        meta: Array.isArray(normalized.meta)
+            ? normalized.meta.map((entry) => ({ ...entry }))
+            : normalized.meta
+    };
+    return cloned;
+}
+function normalizeDeltaSourceRefs(delta) {
+    if (!delta || !Array.isArray(delta.updates)) {
+        return delta;
+    }
+    let changed = false;
+    const updates = delta.updates.map((update) => {
+        const normalized = normalizeUpdateSourceRef(update);
+        if (normalized !== update) {
+            changed = true;
+        }
+        return normalized;
+    });
+    return changed ? { ...delta, updates } : delta;
+}
+/**
+ * Signal K's app.handleMessage(providerId, delta) rewrites update.source.label
+ * to providerId before applying the delta. Remote updates can contain several
+ * original source labels, so dispatch them under their original label. Stale
+ * edge-link `$source` values are removed separately before dispatch so Signal K
+ * can recompute them from the structured source object.
+ */
+function handleMessageBySource(app, delta) {
+    if (!delta || !Array.isArray(delta.updates) || delta.updates.length === 0) {
+        return;
+    }
+    const grouped = new Map();
+    let hasOriginalSourceLabel = false;
+    for (const update of delta.updates) {
+        const sourceLabel = getSourceLabel(update);
+        if (sourceLabel) {
+            hasOriginalSourceLabel = true;
+        }
+        const providerId = sourceLabel || "";
+        const updates = grouped.get(providerId);
+        if (updates) {
+            updates.push(update);
+        }
+        else {
+            grouped.set(providerId, [update]);
+        }
+    }
+    if (!hasOriginalSourceLabel) {
+        app.handleMessage("", delta);
+        return;
+    }
+    for (const [providerId, updates] of grouped) {
+        app.handleMessage(providerId, {
+            ...delta,
+            updates: updates.map(cloneUpdate)
+        });
+    }
+}

package/lib/source-replication.js

@@ -0,0 +1,241 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SOURCE_REPLICATION_SCHEMA_VERSION = void 0;
+exports.createSourceRegistry = createSourceRegistry;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+exports.SOURCE_REPLICATION_SCHEMA_VERSION = 1;
+function normalizeText(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function sanitizeKeyPart(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9._:-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 128);
+}
+function toCanonicalIdentity(update, sourceClientInstanceId) {
+    const source = update.source && typeof update.source === "object"
+        ? update.source
+        : undefined;
+    const sourceRef = normalizeText(update.$source);
+    const label = normalizeText(source?.label) || (sourceRef ? `legacy:${sourceRef}` : undefined);
+    const type = normalizeText(source?.type) || (sourceRef ? "legacy" : "unknown");
+    const src = normalizeText(source?.src);
+    const instance = normalizeText(source?.instance);
+    const pgn = Number.isFinite(Number(source?.pgn)) ? Number(source?.pgn) : undefined;
+    const parsedDeviceId = normalizeText(source?.deviceId);
+    const hasMetadata = !!label ||
+        !!sourceRef ||
+        src !== undefined ||
+        instance !== undefined ||
+        pgn !== undefined ||
+        parsedDeviceId !== undefined;
+    if (!label &&
+        !sourceRef &&
+        src === undefined &&
+        instance === undefined &&
+        pgn === undefined &&
+        parsedDeviceId === undefined) {
+        return null;
+    }
+    return {
+        label: label || "unknown-source",
+        type: normalizeText(type) || "unknown",
+        src,
+        instance,
+        pgn,
+        deviceId: parsedDeviceId ||
+            (hasMetadata && sourceClientInstanceId ? sanitizeKeyPart(sourceClientInstanceId) : undefined)
+    };
+}
+function createSourceKey(update, identity) {
+    const sourceRef = normalizeText(update.$source);
+    if (sourceRef) {
+        return `source-ref:${sanitizeKeyPart(sourceRef)}`;
+    }
+    if (identity) {
+        const canonicalIdentity = JSON.stringify({
+            type: identity.type || "",
+            label: identity.label || "",
+            src: identity.src || "",
+            instance: identity.instance || "",
+            pgn: identity.pgn ?? "",
+            deviceId: identity.deviceId || ""
+        });
+        const identityHash = node_crypto_1.default.createHash("sha256").update(canonicalIdentity).digest("hex");
+        return `source-identity:${identityHash}`;
+    }
+    return "source-identity:unknown";
+}
+function canonicalizeForHash(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => canonicalizeForHash(entry));
+    }
+    if (value && typeof value === "object") {
+        const input = value;
+        const out = {};
+        for (const key of Object.keys(input).sort()) {
+            out[key] = canonicalizeForHash(input[key]);
+        }
+        return out;
+    }
+    return value;
+}
+function toMergeHash(record) {
+    const stablePayload = {
+        schemaVersion: record.schemaVersion,
+        key: record.key,
+        identity: record.identity,
+        metadata: record.metadata,
+        provenance: record.provenance,
+        raw: record.raw
+    };
+    const canonical = canonicalizeForHash(stablePayload);
+    return node_crypto_1.default.createHash("sha1").update(JSON.stringify(canonical)).digest("hex");
+}
+function chooseValue(current, incoming, currentTs, incomingTs, conflicts) {
+    if (incoming === undefined || incoming === null || incoming === "") {
+        return current;
+    }
+    if (current === undefined || current === null || current === "") {
+        return incoming;
+    }
+    if (JSON.stringify(current) === JSON.stringify(incoming)) {
+        return current;
+    }
+    conflicts.count++;
+    return incomingTs >= currentTs ? incoming : current;
+}
+function createSourceRegistry(app) {
+    const records = new Map();
+    let lastLoggedRegistrySize = 0;
+    const metrics = {
+        upserts: 0,
+        noops: 0,
+        missingIdentity: 0,
+        conflicts: 0
+    };
+    function upsertFromDelta(delta, sourceClientInstanceId) {
+        if (!delta || !Array.isArray(delta.updates)) {
+            return;
+        }
+        for (const update of delta.updates) {
+            if (!update || typeof update !== "object") {
+                continue;
+            }
+            const identity = toCanonicalIdentity(update, sourceClientInstanceId);
+            if (!identity) {
+                metrics.missingIdentity++;
+                continue;
+            }
+            const sourceRef = normalizeText(update.$source);
+            const key = createSourceKey(update, identity);
+            const nowIso = new Date().toISOString();
+            const updateTs = normalizeText(update.timestamp);
+            const parsedIncomingTs = updateTs ? Date.parse(updateTs) : NaN;
+            const updateTsMs = Number.isFinite(parsedIncomingTs) ? parsedIncomingTs : Date.now();
+            const sourceObj = update.source && typeof update.source === "object"
+                ? { ...update.source }
+                : undefined;
+            const existing = records.get(key);
+            const mergedBase = {
+                schemaVersion: exports.SOURCE_REPLICATION_SCHEMA_VERSION,
+                key,
+                identity: {
+                    label: identity.label,
+                    type: identity.type,
+                    src: identity.src,
+                    instance: identity.instance,
+                    pgn: identity.pgn,
+                    deviceId: identity.deviceId
+                },
+                metadata: {},
+                firstSeenAt: existing ? existing.firstSeenAt : nowIso,
+                lastSeenAt: existing ? existing.lastSeenAt : nowIso,
+                lastUpdatedAt: existing ? existing.lastUpdatedAt : nowIso,
+                provenance: {
+                    lastUpdatedBy: sourceObj ? "source" : update.$source ? "$source" : "merge",
+                    sourceClientInstanceId,
+                    updateTimestamp: updateTs
+                },
+                raw: {
+                    source: sourceObj,
+                    $source: sourceRef
+                }
+            };
+            if (existing) {
+                const conflictCounter = { count: 0 };
+                const existingUpdateTs = normalizeText(existing.provenance?.updateTimestamp);
+                const parsedExistingTs = existingUpdateTs ? Date.parse(existingUpdateTs) : NaN;
+                const parsedExistingUpdatedAt = Date.parse(existing.lastUpdatedAt);
+                const currentTs = Number.isFinite(parsedExistingTs)
+                    ? parsedExistingTs
+                    : Number.isFinite(parsedExistingUpdatedAt)
+                        ? parsedExistingUpdatedAt
+                        : Date.now();
+                mergedBase.identity.label = chooseValue(existing.identity.label, mergedBase.identity.label, currentTs, updateTsMs, conflictCounter);
+                mergedBase.identity.type = chooseValue(existing.identity.type, mergedBase.identity.type, currentTs, updateTsMs, conflictCounter);
+                mergedBase.identity.src = chooseValue(existing.identity.src, mergedBase.identity.src, currentTs, updateTsMs, conflictCounter);
+                mergedBase.identity.instance = chooseValue(existing.identity.instance, mergedBase.identity.instance, currentTs, updateTsMs, conflictCounter);
+                mergedBase.identity.pgn = chooseValue(existing.identity.pgn, mergedBase.identity.pgn, currentTs, updateTsMs, conflictCounter);
+                mergedBase.identity.deviceId = chooseValue(existing.identity.deviceId, mergedBase.identity.deviceId, currentTs, updateTsMs, conflictCounter);
+                const incomingMeta = mergedBase.metadata;
+                const allKeys = new Set([...Object.keys(existing.metadata), ...Object.keys(incomingMeta)]);
+                for (const metaKey of allKeys) {
+                    mergedBase.metadata[metaKey] = chooseValue(existing.metadata[metaKey], incomingMeta[metaKey], currentTs, updateTsMs, conflictCounter);
+                }
+                metrics.conflicts += conflictCounter.count;
+            }
+            const mergeHash = toMergeHash(mergedBase);
+            if (existing && existing.mergeHash === mergeHash) {
+                existing.lastSeenAt = nowIso;
+                metrics.noops++;
+                continue;
+            }
+            mergedBase.lastSeenAt = nowIso;
+            mergedBase.lastUpdatedAt = nowIso;
+            records.set(key, { ...mergedBase, mergeHash });
+            metrics.upserts++;
+        }
+        if (records.size % 50 === 0 && records.size > 0 && records.size !== lastLoggedRegistrySize) {
+            app.debug(`[source-replication] registry-size=${records.size}`);
+            lastLoggedRegistrySize = records.size;
+        }
+    }
+    function snapshot() {
+        const sources = [...records.values()].sort((a, b) => a.key.localeCompare(b.key));
+        const legacyByLabel = {};
+        const legacyBySourceRef = {};
+        for (const source of sources) {
+            legacyByLabel[source.identity.label] = source.key;
+            if (source.raw.$source) {
+                legacyBySourceRef[source.raw.$source] = source.key;
+            }
+        }
+        return {
+            schemaVersion: exports.SOURCE_REPLICATION_SCHEMA_VERSION,
+            size: sources.length,
+            sources,
+            legacy: {
+                byLabel: legacyByLabel,
+                bySourceRef: legacyBySourceRef
+            }
+        };
+    }
+    function getMetrics() {
+        return { ...metrics };
+    }
+    return {
+        upsertFromDelta,
+        snapshot,
+        getMetrics
+    };
+}

package/lib/source-snapshot.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectSourceSnapshot = collectSourceSnapshot;
+exports.mergeSourceSnapshot = mergeSourceSnapshot;
+const BLOCKED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function clonePlain(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => clonePlain(entry));
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (!BLOCKED_KEYS.has(key)) {
+            out[key] = clonePlain(entry);
+        }
+    }
+    return out;
+}
+function mergePlain(target, incoming) {
+    for (const [key, incomingValue] of Object.entries(incoming)) {
+        if (BLOCKED_KEYS.has(key)) {
+            continue;
+        }
+        const currentValue = target[key];
+        if (isRecord(currentValue) && isRecord(incomingValue)) {
+            mergePlain(currentValue, incomingValue);
+        }
+        else {
+            target[key] = clonePlain(incomingValue);
+        }
+    }
+}
+function getSignalKRoot(app) {
+    const signalk = app.signalk;
+    if (!signalk || typeof signalk.retrieve !== "function") {
+        return null;
+    }
+    const root = signalk.retrieve();
+    return isRecord(root) ? root : null;
+}
+function collectSourceSnapshot(app) {
+    const root = getSignalKRoot(app);
+    if (!root || !isRecord(root.sources)) {
+        return null;
+    }
+    return clonePlain(root.sources);
+}
+function mergeSourceSnapshot(app, sources) {
+    if (!isRecord(sources)) {
+        return 0;
+    }
+    const root = getSignalKRoot(app);
+    if (!root) {
+        return 0;
+    }
+    if (!isRecord(root.sources)) {
+        root.sources = {};
+    }
+    const target = root.sources;
+    const before = Object.keys(target).length;
+    mergePlain(target, sources);
+    return Object.keys(target).length - before;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-edge-link",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "SignalK Edge Link. Secure UDP link for data exchange.",
   "main": "lib/index.js",
   "files": [