signalk-edge-link 2.2.0 → 2.3.0

package/lib/metadata.js

@@ -0,0 +1,467 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetaCache = void 0;
+exports.collectSnapshot = collectSnapshot;
+exports.parseMetaConfig = parseMetaConfig;
+exports.resolveSelfContext = resolveSelfContext;
+exports.extractLiveMeta = extractLiveMeta;
+exports.isLikelyUnsafePathFilter = isLikelyUnsafePathFilter;
+exports.splitIntoPackets = splitIntoPackets;
+exports.buildMetaEnvelope = buildMetaEnvelope;
+/**
+ * Signal K Edge Link - Metadata Streaming
+ *
+ * Collects Signal K path metadata (units, descriptions, zones, display names, ...)
+ * and packages it for transmission alongside the main delta stream.
+ *
+ * Meta is deliberately separated from deltas on the wire:
+ *   - the existing delta encoder strips `updates[].meta[]` via pathDictionary
+ *     `transformDelta`, so meta has never flowed through the pipeline; and
+ *   - sending meta on every delta would multiply bandwidth for values that
+ *     essentially never change.
+ *
+ * Strategy: snapshot once at startup from `app.signalk.retrieve()`, forward
+ * runtime changes via `extractLiveMeta`, and periodically re-broadcast the
+ * full snapshot so a restarted receiver recovers within one interval.
+ *
+ * @module lib/metadata
+ */
+const crypto_1 = require("crypto");
+/**
+ * Produces a stable JSON representation of a meta object for change detection.
+ * Sorts object keys recursively so `{units:"m",description:"x"}` and
+ * `{description:"x",units:"m"}` hash identically.
+ */
+function stableStringify(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return "[" + value.map(stableStringify).join(",") + "]";
+    }
+    const keys = Object.keys(value).sort();
+    return ("{" +
+        keys
+            .map((k) => JSON.stringify(k) + ":" + stableStringify(value[k]))
+            .join(",") +
+        "}");
+}
+function hashMeta(meta) {
+    return (0, crypto_1.createHash)("sha1").update(stableStringify(meta)).digest("hex");
+}
+/**
+ * Cache of the last-sent meta value (hash) per `context+path` pair.
+ *
+ * `diff` returns only the entries whose hashed value has changed since the
+ * last call, so periodic snapshot re-broadcasts stay cheap when the fleet's
+ * meta is stable.
+ */
+class MetaCache {
+    constructor() {
+        this.hashes = new Map();
+    }
+    keyFor(entry) {
+        return entry.context + "|" + entry.path;
+    }
+    /**
+     * Returns only the entries whose meta has changed (or is new) relative to
+     * this cache, and simultaneously updates the cache.
+     */
+    diff(entries) {
+        const changed = [];
+        for (const entry of entries) {
+            const key = this.keyFor(entry);
+            const h = hashMeta(entry.meta);
+            if (this.hashes.get(key) !== h) {
+                this.hashes.set(key, h);
+                changed.push(entry);
+            }
+        }
+        return changed;
+    }
+    /**
+     * Non-mutating variant of {@link diff}. Returns the subset of entries that
+     * are new or whose meta has changed without updating the internal cache.
+     * Used by the send pipeline so the cache is only updated after a
+     * successful transmission — a failed send leaves the cache untouched and
+     * the entries will be re-attempted on the next diff.
+     */
+    computeDiff(entries) {
+        const changed = [];
+        for (const entry of entries) {
+            const key = this.keyFor(entry);
+            const h = hashMeta(entry.meta);
+            if (this.hashes.get(key) !== h) {
+                changed.push(entry);
+            }
+        }
+        return changed;
+    }
+    /**
+     * Mark the supplied entries as sent by updating their hashes in the cache.
+     * Call this only after a successful send so future diffs don't re-emit
+     * the same content.
+     */
+    commit(entries) {
+        for (const entry of entries) {
+            this.hashes.set(this.keyFor(entry), hashMeta(entry.meta));
+        }
+    }
+    /**
+     * Overwrite the cache with the supplied entries. Used after a successful
+     * full-snapshot send so the next diff is computed against the transmitted
+     * state.
+     */
+    replaceAll(entries) {
+        this.hashes.clear();
+        for (const entry of entries) {
+            this.hashes.set(this.keyFor(entry), hashMeta(entry.meta));
+        }
+    }
+    clear() {
+        this.hashes.clear();
+    }
+    size() {
+        return this.hashes.size;
+    }
+}
+exports.MetaCache = MetaCache;
+/**
+ * Walks the value recursively and calls `onMeta(path, metaValue)` for every
+ * subtree that has a `meta` child. Arrays are left alone — Signal K meta
+ * lives inside regular path nodes only.
+ */
+function walkMeta(node, pathParts, onMeta) {
+    if (!node || typeof node !== "object" || Array.isArray(node)) {
+        return;
+    }
+    const obj = node;
+    if (obj.meta && typeof obj.meta === "object" && !Array.isArray(obj.meta)) {
+        onMeta(pathParts.join("."), obj.meta);
+    }
+    for (const key of Object.keys(obj)) {
+        // Signal K "value", "timestamp", "$source" are leaves, not sub-paths.
+        if (key === "meta" ||
+            key === "value" ||
+            key === "values" ||
+            key === "timestamp" ||
+            key === "$source" ||
+            key === "sentence") {
+            continue;
+        }
+        walkMeta(obj[key], pathParts.concat(key), onMeta);
+    }
+}
+/**
+ * Build a full metadata snapshot from the Signal K app state tree.
+ *
+ * Iterates `app.signalk.retrieve()` (when available) and collects every node
+ * that has a `meta` object. Returns entries scoped to the "self" vessel plus
+ * any other contexts present. Applies the `includePathsMatching` regex
+ * filter when configured.
+ *
+ * On signalk-server versions where `app.signalk` is not exposed to plugins,
+ * returns an empty array — live meta will still trickle in through
+ * `extractLiveMeta` once providers emit meta updates.
+ */
+function collectSnapshot(app, config) {
+    if (!config || !config.enabled) {
+        return [];
+    }
+    if (!app.signalk || typeof app.signalk.retrieve !== "function") {
+        return [];
+    }
+    let tree;
+    try {
+        tree = app.signalk.retrieve();
+    }
+    catch {
+        return [];
+    }
+    if (!tree || typeof tree !== "object") {
+        return [];
+    }
+    const filter = buildPathFilter(config.includePathsMatching);
+    const entries = [];
+    for (const contextGroup of Object.keys(tree)) {
+        // `tree.self` is an alias string pointing to the local vessel URN, and
+        // `tree.version` is a server version string; both are leaves, not
+        // context containers, so skip them outright.
+        if (contextGroup === "self" || contextGroup === "version") {
+            continue;
+        }
+        const group = tree[contextGroup];
+        if (!group || typeof group !== "object") {
+            continue;
+        }
+        for (const contextId of Object.keys(group)) {
+            const contextNode = group[contextId];
+            if (!contextNode || typeof contextNode !== "object") {
+                continue;
+            }
+            const contextLabel = `${contextGroup}.${contextId}`;
+            walkMeta(contextNode, [], (path, meta) => {
+                if (!filter(path)) {
+                    return;
+                }
+                entries.push({ context: contextLabel, path, meta });
+            });
+        }
+    }
+    return entries;
+}
+const META_CONFIG_LOG_PREFIX = "[meta-config]";
+const META_DEFAULT_INTERVAL_SEC = 300;
+const META_DEFAULT_MAX_PATHS = 500;
+const META_INTERVAL_MIN = 30;
+const META_INTERVAL_MAX = 86400;
+const META_MAX_PATHS_MIN = 10;
+const META_MAX_PATHS_MAX = 5000;
+/**
+ * Parse the `meta` block out of a subscription.json document.
+ *
+ * Returns null when meta is absent, malformed, or explicitly disabled.
+ * Out-of-range numeric fields and unsafe `includePathsMatching` patterns
+ * fall back to defaults / null and report a `[meta-config]`-prefixed error
+ * via `report` so log analysis can grep for misconfiguration in one place.
+ *
+ * Lives here (not in `instance.ts`) so it can be unit-tested directly without
+ * spinning up an entire instance. The same parser is also used as the
+ * single source of truth for the plugin runtime via instance.ts.
+ */
+function parseMetaConfig(raw, report, context = "") {
+    if (!raw || typeof raw !== "object") {
+        return null;
+    }
+    const obj = raw;
+    const m = obj.meta;
+    if (!m || typeof m !== "object") {
+        return null;
+    }
+    const mo = m;
+    if (mo.enabled !== true) {
+        return null;
+    }
+    const tag = context ? `${META_CONFIG_LOG_PREFIX} [${context}]` : META_CONFIG_LOG_PREFIX;
+    let intervalSec = META_DEFAULT_INTERVAL_SEC;
+    if (mo.intervalSec !== undefined) {
+        if (typeof mo.intervalSec === "number" &&
+            Number.isFinite(mo.intervalSec) &&
+            mo.intervalSec >= META_INTERVAL_MIN &&
+            mo.intervalSec <= META_INTERVAL_MAX) {
+            intervalSec = mo.intervalSec;
+        }
+        else {
+            report(`${tag} meta.intervalSec ${String(mo.intervalSec)} out of range ` +
+                `[${META_INTERVAL_MIN},${META_INTERVAL_MAX}]; using default ${META_DEFAULT_INTERVAL_SEC}s`);
+        }
+    }
+    let maxPathsPerPacket = META_DEFAULT_MAX_PATHS;
+    if (mo.maxPathsPerPacket !== undefined) {
+        if (typeof mo.maxPathsPerPacket === "number" &&
+            Number.isFinite(mo.maxPathsPerPacket) &&
+            mo.maxPathsPerPacket >= META_MAX_PATHS_MIN &&
+            mo.maxPathsPerPacket <= META_MAX_PATHS_MAX) {
+            maxPathsPerPacket = mo.maxPathsPerPacket;
+        }
+        else {
+            report(`${tag} meta.maxPathsPerPacket ${String(mo.maxPathsPerPacket)} out of range ` +
+                `[${META_MAX_PATHS_MIN},${META_MAX_PATHS_MAX}]; using default ${META_DEFAULT_MAX_PATHS}`);
+        }
+    }
+    let includePathsMatching = null;
+    if (typeof mo.includePathsMatching === "string" && mo.includePathsMatching.length > 0) {
+        const pattern = mo.includePathsMatching;
+        if (pattern.length > MAX_PATH_FILTER_PATTERN_LENGTH) {
+            report(`${tag} meta.includePathsMatching exceeds ${MAX_PATH_FILTER_PATTERN_LENGTH} chars; ignoring filter`);
+        }
+        else if (isLikelyUnsafePathFilter(pattern)) {
+            report(`${tag} meta.includePathsMatching "${pattern}" has a nested unbounded quantifier (ReDoS shape); ignoring filter`);
+        }
+        else {
+            try {
+                new RegExp(pattern);
+                includePathsMatching = pattern;
+            }
+            catch (err) {
+                report(`${tag} meta.includePathsMatching "${pattern}" failed to compile: ${err instanceof Error ? err.message : String(err)}; ignoring filter`);
+            }
+        }
+    }
+    return {
+        enabled: true,
+        intervalSec,
+        includePathsMatching,
+        maxPathsPerPacket
+    };
+}
+/**
+ * Resolve the local vessel's context string (e.g. `vessels.urn:mrn:...`) from
+ * the Signal K app. Used to normalize `delta.context === "vessels.self"` in
+ * the live meta stream to the same concrete URN `collectSnapshot` emits, so
+ * `MetaCache` can dedupe snapshot and diff entries against the same key.
+ *
+ * Returns `null` when the self URN is not yet known — a fallback to the
+ * literal `"vessels.self"` would reintroduce the snapshot/live-meta key
+ * mismatch. Callers should treat null as "self not resolvable yet" and
+ * decline to emit `vessels.self` live entries until a concrete URN arrives.
+ */
+function resolveSelfContext(app) {
+    try {
+        const self = app.getSelfPath?.("");
+        if (self && typeof self === "object") {
+            const id = self.mmsi ?? self.uuid;
+            if (typeof id === "string" && id.length > 0) {
+                const prefix = self.mmsi
+                    ? "urn:mrn:imo:mmsi:"
+                    : "urn:mrn:signalk:uuid:";
+                return `vessels.${prefix}${id}`;
+            }
+        }
+        if (app.signalk && typeof app.signalk.retrieve === "function") {
+            const tree = app.signalk.retrieve();
+            const alias = tree?.self;
+            if (typeof alias === "string" && alias.length > 0) {
+                return `vessels.${alias}`;
+            }
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    if (typeof app.debug === "function") {
+        app.debug("[metadata] self URN not yet resolvable; vessels.self live meta will be skipped");
+    }
+    return null;
+}
+/**
+ * Extract any `updates[].meta[]` entries from a live delta without mutating
+ * the delta object. Callers should invoke this BEFORE the delta is passed to
+ * the pipeline encoder (which silently drops meta).
+ */
+function extractLiveMeta(delta, config, selfContext) {
+    if (!config || !config.enabled) {
+        return [];
+    }
+    if (!delta || !Array.isArray(delta.updates) || delta.updates.length === 0) {
+        return [];
+    }
+    const filter = buildPathFilter(config.includePathsMatching);
+    const out = [];
+    for (const update of delta.updates) {
+        const metaArr = update.meta;
+        if (!Array.isArray(metaArr) || metaArr.length === 0) {
+            continue;
+        }
+        for (const m of metaArr) {
+            if (!m || typeof m.path !== "string" || !m.value || typeof m.value !== "object") {
+                continue;
+            }
+            if (!filter(m.path)) {
+                continue;
+            }
+            const rawContext = delta.context || "vessels.self";
+            // Normalize "vessels.self" to the concrete self URN so MetaCache keys
+            // match snapshot keys exactly. If the self URN isn't known yet, skip
+            // the entry rather than emit it under a context that will never match
+            // collectSnapshot's output — otherwise the receiver would see two
+            // copies (one under vessels.self, one under the real URN) and the
+            // local MetaCache diff logic would never dedupe them.
+            let context;
+            if (rawContext === "vessels.self") {
+                if (!selfContext) {
+                    continue;
+                }
+                context = selfContext;
+            }
+            else {
+                context = rawContext;
+            }
+            out.push({
+                context,
+                path: m.path,
+                meta: m.value
+            });
+        }
+    }
+    return out;
+}
+/** Maximum operator-supplied regex length. A typical path-matching regex is
+ *  well under 100 chars; refusing huge patterns is a cheap safeguard against
+ *  the obvious catastrophic-backtracking shapes (hundreds of nested `(a+)*`
+ *  groups, etc.) without pulling in a re2 dependency. */
+const MAX_PATH_FILTER_PATTERN_LENGTH = 256;
+/**
+ * Heuristic detector for the most common ReDoS shape: nested unbounded
+ * quantifiers such as `(a+)+`, `(.*)+`, `(a*)*`, `(.+)*`.
+ *
+ * The check is deliberately narrow — it does not attempt a full ReDoS
+ * analysis (which would require pulling in `safe-regex2` or `re2`) — but it
+ * catches the specific failure mode that is easy to accidentally write and
+ * easy to verify by eye. Callers should also enforce
+ * {@link MAX_PATH_FILTER_PATTERN_LENGTH} and wrap regex compilation in
+ * try/catch so invalid patterns fail safely.
+ *
+ * Exported so the config parser can reject unsafe patterns at load time
+ * with a descriptive error rather than silently dropping to allow-all at
+ * runtime, which would hide operator mistakes.
+ */
+function isLikelyUnsafePathFilter(pattern) {
+    // Matches a group whose body ends in an unbounded quantifier (* or +,
+    // optionally with ? for lazy), immediately followed by another unbounded
+    // quantifier. This is the classic (a+)+ / (a*)* / (a+)* / (a*)+ family.
+    const nested = /\([^()]*[*+][*+?]?\s*\)\s*[*+][*+?]?/;
+    return nested.test(pattern);
+}
+/**
+ * Build a path-inclusion predicate from the user-supplied regex string.
+ * Falsy / empty string / null ⇒ always-true. Invalid or oversized regex
+ * ⇒ always-true (silent fallback — operators see no filtering rather
+ * than hitting a hard error, which matches the existing behaviour).
+ */
+function buildPathFilter(pattern) {
+    if (!pattern) {
+        return () => true;
+    }
+    if (pattern.length > MAX_PATH_FILTER_PATTERN_LENGTH) {
+        return () => true;
+    }
+    try {
+        const re = new RegExp(pattern);
+        return (p) => re.test(p);
+    }
+    catch {
+        return () => true;
+    }
+}
+/**
+ * Split a list of meta entries into packet-sized chunks.
+ * `max` is clamped to at least 1.
+ */
+function splitIntoPackets(entries, max) {
+    const size = Math.max(1, Math.floor(max) || 1);
+    if (entries.length === 0) {
+        return [];
+    }
+    const chunks = [];
+    for (let i = 0; i < entries.length; i += size) {
+        chunks.push(entries.slice(i, i + size));
+    }
+    return chunks;
+}
+/**
+ * Construct an on-wire envelope for a single chunk of meta entries.
+ *
+ * The envelope is then JSON- or msgpack-serialized, compressed, encrypted,
+ * and wrapped in a METADATA (0x06) packet by the client pipeline.
+ */
+function buildMetaEnvelope(entries, kind, seq, idx, total) {
+    return {
+        v: 1,
+        kind,
+        seq: seq >>> 0,
+        idx,
+        total,
+        entries
+    };
+}

package/lib/metrics.js

@@ -32,6 +32,10 @@ function createMetrics() {
         lastError: null,
         lastErrorTime: null,
         packetLoss: 0,
+        dataPacketsReceived: 0,
+        rateLimitedPackets: 0,
+        droppedDeltaBatches: 0,
+        droppedDeltaCount: 0,
         remoteNetworkQuality: {
             rtt: 0,
             jitter: 0,
@@ -55,6 +59,13 @@ function createMetrics() {
             rateOut: 0,
             rateIn: 0,
             compressionRatio: 0,
+            metaBytesOut: 0,
+            metaPacketsOut: 0,
+            metaBytesIn: 0,
+            metaPacketsIn: 0,
+            metaSnapshotsSent: 0,
+            metaDiffsSent: 0,
+            metaRateLimitedPackets: 0,
             // Explicit generic parameter so the type matches BandwidthMetrics.history
             // and removes the need for the `as any` cast on the whole object.
             history: new CircularBuffer(constants_1.BANDWIDTH_HISTORY_MAX)
@@ -142,7 +153,10 @@ function createMetrics() {
             acksSent: 0,
             naksSent: 0,
             duplicatePackets: 0,
-            dataPacketsReceived: 0
+            dataPacketsReceived: 0,
+            rateLimitedPackets: 0,
+            droppedDeltaBatches: 0,
+            droppedDeltaCount: 0
         });
         Object.assign(metrics.bandwidth, {
             bytesOut: 0,
@@ -157,6 +171,13 @@ function createMetrics() {
             rateOut: 0,
             rateIn: 0,
             compressionRatio: 0,
+            metaBytesOut: 0,
+            metaPacketsOut: 0,
+            metaBytesIn: 0,
+            metaPacketsIn: 0,
+            metaSnapshotsSent: 0,
+            metaDiffsSent: 0,
+            metaRateLimitedPackets: 0,
             history: new CircularBuffer(constants_1.BANDWIDTH_HISTORY_MAX)
         });
         metrics.pathStats.clear();

package/lib/packet.js

@@ -53,7 +53,9 @@ const PacketType = Object.freeze({
     ACK: 0x02,
     NAK: 0x03,
     HEARTBEAT: 0x04,
-    HELLO: 0x05
+    HELLO: 0x05,
+    METADATA: 0x06,
+    META_REQUEST: 0x07
 });
 exports.PacketType = PacketType;
 /**
@@ -125,6 +127,11 @@ class PacketBuilder {
      */
     constructor(config = {}) {
         this._sequence = config.initialSequence ?? 0;
+        // METADATA lives in its own sequence space. DATA sequencing drives the
+        // cumulative ACK/NAK protocol on the server; mixing METADATA into it
+        // would create apparent gaps (receivers don't track METADATA sequences)
+        // and trigger spurious NAKs / retransmit churn for real data traffic.
+        this._metaSequence = 0;
         this._protocolVersion = normalizeProtocolVersion(config.protocolVersion);
         this._secretKey = config.secretKey || null;
         this._stretchAsciiKey = !!config.stretchAsciiKey;
@@ -144,6 +151,31 @@ class PacketBuilder {
         this._advanceSequence();
         return packet;
     }
+    /**
+     * Build a METADATA packet. Shares the flag set and the build/encrypt
+     * pipeline with buildDataPacket but uses packet type 0x06 and its own
+     * sequence space so that METADATA never steals DATA sequence numbers.
+     *
+     * METADATA is not ACKed/NAKed on the wire — recovery is handled by the
+     * application-level periodic snapshot and by META_REQUEST (0x07). The
+     * separate sequence counter exists purely so a receiver can detect
+     * duplicate or reordered METADATA packets within a single snapshot burst.
+     */
+    buildMetadataPacket(payload, flags = {}) {
+        const packet = this._buildPacket(PacketType.METADATA, payload, flags, {
+            sequence: this._metaSequence
+        });
+        this._metaSequence = (this._metaSequence + 1) >>> 0;
+        return packet;
+    }
+    /**
+     * Build a META_REQUEST control packet (receiver → client).
+     * Payload is empty; control-packet authentication/CRC is applied by
+     * _buildPacket the same way as ACK/NAK.
+     */
+    buildMetaRequestPacket(options = {}) {
+        return this._buildPacket(PacketType.META_REQUEST, Buffer.alloc(0), {}, options);
+    }
     /**
      * Build an ACK packet
      * @param {number} ackedSequence - Sequence number being acknowledged
@@ -226,6 +258,7 @@ class PacketBuilder {
         const header = Buffer.alloc(HEADER_SIZE);
         const payloadBuffer = Buffer.isBuffer(payload) ? payload : Buffer.from(payload || "");
         const protocolVersion = normalizeProtocolVersion(options.protocolVersion ?? this._protocolVersion);
+        const sequence = (options.sequence ?? this._sequence) >>> 0;
         // Magic bytes
         header[0] = MAGIC[0];
         header[1] = MAGIC[1];
@@ -248,13 +281,15 @@ class PacketBuilder {
             flagByte |= PacketFlags.PATH_DICTIONARY;
         }
         header[4] = flagByte;
-        // Sequence number (uint32 big-endian)
-        header.writeUInt32BE(this._sequence, 5);
+        // Sequence number (uint32 big-endian) — DATA uses this._sequence, METADATA
+        // uses this._metaSequence, control packets inherit this._sequence.
+        header.writeUInt32BE(sequence, 5);
         let finalPayload = payloadBuffer;
-        // DATA packets are authenticated by AES-256-GCM. v2 control packets use a
-        // trailing CRC for corruption detection; v3 control packets use an HMAC tag
-        // so ACK/NAK/HEARTBEAT/HELLO cannot be forged off-path.
-        if (type !== PacketType.DATA) {
+        // DATA and METADATA packets are authenticated by AES-256-GCM (their payload
+        // is already an AEAD ciphertext). v2 control packets use a trailing CRC for
+        // corruption detection; v3 control packets use an HMAC tag so
+        // ACK/NAK/HEARTBEAT/HELLO/META_REQUEST cannot be forged off-path.
+        if (type !== PacketType.DATA && type !== PacketType.METADATA) {
             if (usesAuthenticatedControl(protocolVersion)) {
                 const secretKey = options.secretKey || this._secretKey;
                 if (!secretKey) {
@@ -351,7 +386,7 @@ class PacketParser {
         }
         // Extract payload
         let payload = packet.subarray(HEADER_SIZE);
-        if (type !== PacketType.DATA) {
+        if (type !== PacketType.DATA && type !== PacketType.METADATA) {
             if (usesAuthenticatedControl(version)) {
                 if (payload.length < crypto_1.CONTROL_AUTH_TAG_LENGTH) {
                     throw new Error("Control packet authentication tag missing");
@@ -369,11 +404,11 @@ class PacketParser {
                 payload = payloadData;
             }
             else {
-                // HEARTBEAT packets carry a 0-byte payload with no CRC — accept as-is.
-                // ACK / NAK / HELLO must include a 2-byte CRC16 trailer; reject
-                // undersized payloads so forged control frames cannot slip through
-                // unverified.
-                if (type !== PacketType.HEARTBEAT) {
+                // HEARTBEAT and META_REQUEST packets carry a 0-byte payload with no CRC
+                // — accept as-is. ACK / NAK / HELLO must include a 2-byte CRC16 trailer;
+                // reject undersized payloads so forged control frames cannot slip
+                // through unverified.
+                if (type !== PacketType.HEARTBEAT && type !== PacketType.META_REQUEST) {
                     if (payload.length < 2) {
                         throw new Error(`Control packet payload too short for CRC: ${payload.length} byte(s)`);
                     }
@@ -467,7 +502,9 @@ function getTypeName(type) {
         [PacketType.ACK]: "ACK",
         [PacketType.NAK]: "NAK",
         [PacketType.HEARTBEAT]: "HEARTBEAT",
-        [PacketType.HELLO]: "HELLO"
+        [PacketType.HELLO]: "HELLO",
+        [PacketType.METADATA]: "METADATA",
+        [PacketType.META_REQUEST]: "META_REQUEST"
     };
     return names[type] || "UNKNOWN";
 }

package/lib/pathDictionary.js

@@ -5,6 +5,8 @@ exports.encodePath = encodePath;
 exports.decodePath = decodePath;
 exports.encodeDelta = encodeDelta;
 exports.decodeDelta = decodeDelta;
+exports.encodeMetaEntry = encodeMetaEntry;
+exports.decodeMetaEntry = decodeMetaEntry;
 exports.getAllPaths = getAllPaths;
 exports.getPathsByCategory = getPathsByCategory;
 exports.getDictionarySize = getDictionarySize;
@@ -394,7 +396,10 @@ function transformDelta(delta, pathTransform, shouldTransform) {
             transformedValues = new Array(values.length);
             for (let j = 0; j < values.length; j++) {
                 const value = values[j];
-                if (shouldTransform(value)) {
+                if (!value || typeof value !== "object") {
+                    transformedValues[j] = value;
+                }
+                else if (shouldTransform(value)) {
                     const transformedPath = pathTransform(value.path);
                     transformedValues[j] = { ...value, path: transformedPath };
                 }
@@ -432,6 +437,20 @@ function encodeDelta(delta) {
 function decodeDelta(delta) {
     return transformDelta(delta, decodePath, (value) => value.path !== undefined);
 }
+/**
+ * Encode the `path` field of a metadata entry using the path dictionary.
+ * The `meta` payload itself is intentionally not touched — dictionary
+ * compression applies to the path strings only.
+ */
+function encodeMetaEntry(entry) {
+    return { ...entry, path: encodePath(entry.path) };
+}
+/**
+ * Decode the `path` field of a metadata entry. Inverse of encodeMetaEntry.
+ */
+function decodeMetaEntry(entry) {
+    return { ...entry, path: decodePath(entry.path) };
+}
 /**
  * Get all known paths as an array
  * @returns Array of all known SignalK paths