@zlink-systems/stream-wire 0.26.0 → 0.28.0

package/dist/index.js

@@ -1,11 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZLINK_STREAM_FORMAT_MARKER = exports.ZlinkStreamCodec = void 0;
+exports.ZLINK_STREAM_FORMAT_MARKER = exports.ZlinkStreamContentType = exports.ZlinkStreamControlPacket = exports.ZLINK_STREAM_RESERVED_PACKET_NAME_PREFIX = exports.ZLINK_STREAM_MAX_METADATA_BYTES = exports.ZLINK_STREAM_MAX_PACKET_NAME_BYTES = exports.ZLINK_STREAM_FRAME_PREFIX_BYTES = exports.UINT32_MAX = exports.UINT64_MAX = exports.UINT64_BYTES = exports.ZlinkStreamCloseReasonCode = exports.ZlinkStreamHeaderFlags = exports.ZlinkStreamMessageKind = exports.ZlinkStreamCodec = exports.defaultMaxDecompressedPayloadSize = void 0;
+exports.isStreamWireMessageKind = isStreamWireMessageKind;
+exports.isStreamWireCodec = isStreamWireCodec;
+exports.encodeStreamWireActorBoundPayload = encodeStreamWireActorBoundPayload;
+exports.decodeStreamWireActorBoundPayload = decodeStreamWireActorBoundPayload;
+exports.encodeStreamWireActorUnboundPayload = encodeStreamWireActorUnboundPayload;
+exports.decodeStreamWireActorUnboundPayload = decodeStreamWireActorUnboundPayload;
+exports.encodeStreamWireSessionClosingPayload = encodeStreamWireSessionClosingPayload;
+exports.decodeStreamWireSessionClosing = decodeStreamWireSessionClosing;
+exports.splitStreamWireFrames = splitStreamWireFrames;
+exports.streamCodecContentType = streamCodecContentType;
+exports.streamCodecForContentType = streamCodecForContentType;
 exports.encodeStreamWireFrame = encodeStreamWireFrame;
 exports.decodeStreamWireFrame = decodeStreamWireFrame;
 exports.tryDecodeStreamWireFrame = tryDecodeStreamWireFrame;
 exports.encodeStreamWireHeader = encodeStreamWireHeader;
 exports.decodeStreamWireHeader = decodeStreamWireHeader;
+exports.streamWireMetadataSize = streamWireMetadataSize;
 exports.encodeStreamWireMetadata = encodeStreamWireMetadata;
 exports.decodeStreamWireMetadata = decodeStreamWireMetadata;
 exports.lz4PickleUncompressed = lz4PickleUncompressed;
@@ -13,7 +25,10 @@ exports.lz4PickledLength = lz4PickledLength;
 exports.lz4UnpicklePayload = lz4UnpicklePayload;
 exports.utf8Encode = utf8Encode;
 exports.utf8Decode = utf8Decode;
+exports.validateStreamWirePacketName = validateStreamWirePacketName;
 const lz4_pickle_1 = require("./lz4-pickle");
+var lz4_pickle_2 = require("./lz4-pickle");
+Object.defineProperty(exports, "defaultMaxDecompressedPayloadSize", { enumerable: true, get: function () { return lz4_pickle_2.defaultMaxDecompressedPayloadSize; } });
 /** Numeric payload codec values shared by browser and server wire paths. */
 var ZlinkStreamCodec;
 (function (ZlinkStreamCodec) {
@@ -22,76 +37,264 @@ var ZlinkStreamCodec;
     ZlinkStreamCodec[ZlinkStreamCodec["MessagePack"] = 2] = "MessagePack";
     ZlinkStreamCodec[ZlinkStreamCodec["Protobuf"] = 3] = "Protobuf";
 })(ZlinkStreamCodec || (exports.ZlinkStreamCodec = ZlinkStreamCodec = {}));
+var ZlinkStreamMessageKind;
+(function (ZlinkStreamMessageKind) {
+    ZlinkStreamMessageKind[ZlinkStreamMessageKind["Send"] = 1] = "Send";
+    ZlinkStreamMessageKind[ZlinkStreamMessageKind["Request"] = 2] = "Request";
+    ZlinkStreamMessageKind[ZlinkStreamMessageKind["Response"] = 3] = "Response";
+    ZlinkStreamMessageKind[ZlinkStreamMessageKind["Error"] = 4] = "Error";
+    ZlinkStreamMessageKind[ZlinkStreamMessageKind["Control"] = 5] = "Control";
+})(ZlinkStreamMessageKind || (exports.ZlinkStreamMessageKind = ZlinkStreamMessageKind = {}));
+var ZlinkStreamHeaderFlags;
+(function (ZlinkStreamHeaderFlags) {
+    ZlinkStreamHeaderFlags[ZlinkStreamHeaderFlags["None"] = 0] = "None";
+    ZlinkStreamHeaderFlags[ZlinkStreamHeaderFlags["HasRequestSeq"] = 1] = "HasRequestSeq";
+    ZlinkStreamHeaderFlags[ZlinkStreamHeaderFlags["HasMetadata"] = 2] = "HasMetadata";
+    ZlinkStreamHeaderFlags[ZlinkStreamHeaderFlags["PayloadCompressed"] = 4] = "PayloadCompressed";
+    ZlinkStreamHeaderFlags[ZlinkStreamHeaderFlags["HasCorrelationId"] = 8] = "HasCorrelationId";
+    ZlinkStreamHeaderFlags[ZlinkStreamHeaderFlags["HasFlowId"] = 16] = "HasFlowId";
+    ZlinkStreamHeaderFlags[ZlinkStreamHeaderFlags["HasActorSlot"] = 32] = "HasActorSlot";
+})(ZlinkStreamHeaderFlags || (exports.ZlinkStreamHeaderFlags = ZlinkStreamHeaderFlags = {}));
+var ZlinkStreamCloseReasonCode;
+(function (ZlinkStreamCloseReasonCode) {
+    ZlinkStreamCloseReasonCode[ZlinkStreamCloseReasonCode["ClientClose"] = 1] = "ClientClose";
+    ZlinkStreamCloseReasonCode[ZlinkStreamCloseReasonCode["IdleTimeout"] = 2] = "IdleTimeout";
+    ZlinkStreamCloseReasonCode[ZlinkStreamCloseReasonCode["HeartbeatTimeout"] = 3] = "HeartbeatTimeout";
+    ZlinkStreamCloseReasonCode[ZlinkStreamCloseReasonCode["ServerDrain"] = 4] = "ServerDrain";
+    ZlinkStreamCloseReasonCode[ZlinkStreamCloseReasonCode["ProtocolError"] = 5] = "ProtocolError";
+    ZlinkStreamCloseReasonCode[ZlinkStreamCloseReasonCode["TransportError"] = 6] = "TransportError";
+})(ZlinkStreamCloseReasonCode || (exports.ZlinkStreamCloseReasonCode = ZlinkStreamCloseReasonCode = {}));
+const unicodeWhiteSpaceOnly = /^\p{White_Space}*$/u;
+const validMessageKinds = new Set(Object.values(ZlinkStreamMessageKind).filter((value) => typeof value === 'number'));
+const validCodecs = new Set(Object.values(ZlinkStreamCodec).filter((value) => typeof value === 'number'));
+function isStreamWireMessageKind(value) {
+    return validMessageKinds.has(value);
+}
+function isStreamWireCodec(value) {
+    return validCodecs.has(value);
+}
+const UTF8_TWO_BYTE_MIN = 0x80;
+const UTF8_THREE_BYTE_MIN = 0x800;
+const UTF16_HIGH_SURROGATE_MIN = 0xd800;
+const UTF16_HIGH_SURROGATE_MAX = 0xdbff;
+const UTF16_LOW_SURROGATE_MIN = 0xdc00;
+const UTF16_LOW_SURROGATE_MAX = 0xdfff;
+const UINT8_MAX = 0xff;
+const UINT16_MAX = 0xffff;
+const UINT16_BYTES = 2;
+const UINT32_BYTES = 4;
+exports.UINT64_BYTES = 8;
+exports.UINT64_MAX = 0xffffffffffffffffn;
+exports.UINT32_MAX = 0xffff_ffff;
+exports.ZLINK_STREAM_FRAME_PREFIX_BYTES = UINT16_BYTES + UINT32_BYTES;
+exports.ZLINK_STREAM_MAX_PACKET_NAME_BYTES = UINT8_MAX;
+exports.ZLINK_STREAM_MAX_METADATA_BYTES = 1024;
+const FLOW_ID_BYTES = 36;
+const FLOW_FIELDS_BYTES = FLOW_ID_BYTES + 1;
+const HEADER_MIN_BYTES = 5;
+const HEADER_FLAG_MASK = ZlinkStreamHeaderFlags.HasRequestSeq |
+    ZlinkStreamHeaderFlags.HasMetadata |
+    ZlinkStreamHeaderFlags.PayloadCompressed |
+    ZlinkStreamHeaderFlags.HasCorrelationId |
+    ZlinkStreamHeaderFlags.HasFlowId |
+    ZlinkStreamHeaderFlags.HasActorSlot;
+const CONTROL_PAYLOAD_VERSION = 1;
+const ACTOR_SLOT_OFFSET = 1;
+const ACTOR_ID_LENGTH_OFFSET = ACTOR_SLOT_OFFSET + UINT16_BYTES;
+const ACTOR_BOUND_PREFIX_BYTES = ACTOR_ID_LENGTH_OFFSET + 1;
+const ACTOR_UNBOUND_BYTES = ACTOR_SLOT_OFFSET + UINT16_BYTES;
+const CLOSING_DIAGNOSTIC_LENGTH_OFFSET = 2;
+const CLOSING_PREFIX_BYTES = CLOSING_DIAGNOSTIC_LENGTH_OFFSET + UINT16_BYTES;
+const MAX_CLOSING_DIAGNOSTIC_BYTES = 512;
+function encodeStreamWireActorBoundPayload(actorSlot, actorId) {
+    const actorIdBytes = utf8Encode(actorId);
+    if (actorIdBytes.length < 1 || actorIdBytes.length > UINT8_MAX) {
+        throw new Error('Actor id length is invalid for a STREAM binding control packet.');
+    }
+    const payload = new Uint8Array(ACTOR_BOUND_PREFIX_BYTES + actorIdBytes.length);
+    payload[0] = CONTROL_PAYLOAD_VERSION;
+    writeUInt16BE(payload, ACTOR_SLOT_OFFSET, actorSlot);
+    payload[ACTOR_ID_LENGTH_OFFSET] = actorIdBytes.length;
+    payload.set(actorIdBytes, ACTOR_BOUND_PREFIX_BYTES);
+    return payload;
+}
+function decodeStreamWireActorBoundPayload(payload) {
+    if (payload.length < ACTOR_BOUND_PREFIX_BYTES + 1 || payload[0] !== CONTROL_PAYLOAD_VERSION) {
+        throw new Error('Actor bound payload is invalid.');
+    }
+    const slot = readUInt16BE(payload, ACTOR_SLOT_OFFSET);
+    const idLength = payload[ACTOR_ID_LENGTH_OFFSET];
+    if (slot === 0 || idLength === 0 || payload.length !== ACTOR_BOUND_PREFIX_BYTES + idLength) {
+        throw new Error('Actor bound payload is invalid.');
+    }
+    try {
+        return { slot, actorId: decodeControlText(payload.subarray(ACTOR_BOUND_PREFIX_BYTES)) };
+    }
+    catch (cause) {
+        throw new Error('Actor id is not valid UTF-8.', { cause });
+    }
+}
+function encodeStreamWireActorUnboundPayload(actorSlot) {
+    const payload = new Uint8Array(ACTOR_UNBOUND_BYTES);
+    payload[0] = CONTROL_PAYLOAD_VERSION;
+    writeUInt16BE(payload, ACTOR_SLOT_OFFSET, actorSlot);
+    return payload;
+}
+function decodeStreamWireActorUnboundPayload(payload) {
+    if (payload.length !== ACTOR_UNBOUND_BYTES || payload[0] !== CONTROL_PAYLOAD_VERSION) {
+        throw new Error('Actor unbound payload is invalid.');
+    }
+    return readUInt16BE(payload, ACTOR_SLOT_OFFSET);
+}
+function encodeStreamWireSessionClosingPayload(reasonCode, diagnostic = '') {
+    const bytes = utf8Encode(diagnostic);
+    if (bytes.length > MAX_CLOSING_DIAGNOSTIC_BYTES) {
+        throw new Error('Session-closing diagnostic is too large.');
+    }
+    const payload = new Uint8Array(CLOSING_PREFIX_BYTES + bytes.length);
+    payload[0] = CONTROL_PAYLOAD_VERSION;
+    payload[1] = reasonCode;
+    writeUInt16BE(payload, CLOSING_DIAGNOSTIC_LENGTH_OFFSET, bytes.length);
+    payload.set(bytes, CLOSING_PREFIX_BYTES);
+    return payload;
+}
+function decodeStreamWireSessionClosing(payload) {
+    if (payload.length < CLOSING_PREFIX_BYTES || payload[0] !== CONTROL_PAYLOAD_VERSION) {
+        throw new Error('Unsupported session-closing version.');
+    }
+    const closeReason = ZlinkStreamCloseReasonCode[payload[1]];
+    if (closeReason === undefined)
+        throw new Error('Unknown session-closing reason.');
+    const length = readUInt16BE(payload, CLOSING_DIAGNOSTIC_LENGTH_OFFSET);
+    if (length > MAX_CLOSING_DIAGNOSTIC_BYTES || payload.length !== CLOSING_PREFIX_BYTES + length) {
+        throw new Error('Invalid session-closing diagnostic length.');
+    }
+    const diagnostic = length === 0 ? undefined : decodeControlText(payload.subarray(CLOSING_PREFIX_BYTES));
+    return { closeReason, diagnostic };
+}
+function decodeControlText(value) {
+    return new TextDecoder('utf-8', { fatal: true }).decode(value);
+}
+function splitStreamWireFrames(chunk) {
+    if (chunk.length === 0)
+        throw new Error('Stream frame prefix is incomplete.');
+    const frames = [];
+    let offset = 0;
+    while (offset < chunk.length) {
+        const remaining = chunk.length - offset;
+        if (remaining < exports.ZLINK_STREAM_FRAME_PREFIX_BYTES) {
+            throw new Error('Stream frame prefix is incomplete.');
+        }
+        const headerLength = readUInt16BE(chunk, offset);
+        const payloadLength = readUInt32BE(chunk, offset + UINT16_BYTES);
+        const frameLength = exports.ZLINK_STREAM_FRAME_PREFIX_BYTES + headerLength + payloadLength;
+        if (frameLength > remaining)
+            throw new Error('Frame length does not match prefix.');
+        frames.push(chunk.subarray(offset, offset + frameLength));
+        offset += frameLength;
+    }
+    return frames;
+}
+/** @internal Reserved packet name prefix owned by the stream protocol. */
+exports.ZLINK_STREAM_RESERVED_PACKET_NAME_PREFIX = '$zlink.';
+exports.ZlinkStreamControlPacket = Object.freeze({
+    HeartbeatPing: `${exports.ZLINK_STREAM_RESERVED_PACKET_NAME_PREFIX}heartbeat.ping`,
+    HeartbeatPong: `${exports.ZLINK_STREAM_RESERVED_PACKET_NAME_PREFIX}heartbeat.pong`,
+    ActorBound: `${exports.ZLINK_STREAM_RESERVED_PACKET_NAME_PREFIX}actor.bound`,
+    ActorUnbound: `${exports.ZLINK_STREAM_RESERVED_PACKET_NAME_PREFIX}actor.unbound`,
+    SessionClosing: 'session-closing'
+});
+exports.ZlinkStreamContentType = Object.freeze({
+    Raw: 'application/octet-stream',
+    Json: 'application/json',
+    MessagePack: 'application/x-msgpack',
+    Protobuf: 'application/x-protobuf'
+});
+const contentTypesByCodec = new Map([
+    [ZlinkStreamCodec.Raw, exports.ZlinkStreamContentType.Raw],
+    [ZlinkStreamCodec.Json, exports.ZlinkStreamContentType.Json],
+    [ZlinkStreamCodec.MessagePack, exports.ZlinkStreamContentType.MessagePack],
+    [ZlinkStreamCodec.Protobuf, exports.ZlinkStreamContentType.Protobuf]
+]);
+const codecsByContentType = new Map(Array.from(contentTypesByCodec, ([codec, contentType]) => [contentType, codec]));
+function streamCodecContentType(codec) {
+    const contentType = contentTypesByCodec.get(codec);
+    if (contentType === undefined)
+        throw new TypeError(`Unsupported STREAM codec '${codec}'.`);
+    return contentType;
+}
+function streamCodecForContentType(contentType) {
+    const codec = codecsByContentType.get(contentType);
+    if (codec === undefined)
+        throw new TypeError(`Unsupported STREAM content type '${contentType}'.`);
+    return codec;
+}
 // The functions below resolve this inside their bodies rather than in a parameter
 // default. The browser IIFE build of this package is committed into the Unity
 // WebGL adapter as an emscripten pre-js, and emscripten's dead-code pass does not
 // walk parameter default initializers: a binding whose only references are
 // defaults is deleted, and the player fails at runtime with "not defined".
 const defaultHeaderFlags = {
-    hasRequestSeq: 0x01,
-    hasMetadata: 0x02,
-    hasCorrelationId: 0x08,
-    hasFlowId: 0x10,
-    hasActorSlot: 0x20
+    hasRequestSeq: ZlinkStreamHeaderFlags.HasRequestSeq,
+    hasMetadata: ZlinkStreamHeaderFlags.HasMetadata,
+    hasCorrelationId: ZlinkStreamHeaderFlags.HasCorrelationId,
+    hasFlowId: ZlinkStreamHeaderFlags.HasFlowId,
+    hasActorSlot: ZlinkStreamHeaderFlags.HasActorSlot
 };
 exports.ZLINK_STREAM_FORMAT_MARKER = 0xf2;
-const ZLINK_STREAM_RESPONSE_KIND = 3;
-const ZLINK_STREAM_ERROR_KIND = 4;
 function encodeStreamWireFrame(header, payload) {
-    if (header.length > 0xffff) {
+    if (header.length > UINT16_MAX) {
         throw new Error('Stream header is too large.');
     }
-    if (payload.length > 0xffffffff) {
+    if (payload.length > exports.UINT32_MAX) {
         throw new Error('Stream payload is too large.');
     }
-    const frame = new Uint8Array(6 + header.length + payload.length);
+    const frame = new Uint8Array(exports.ZLINK_STREAM_FRAME_PREFIX_BYTES + header.length + payload.length);
     writeUInt16BE(frame, 0, header.length);
-    writeUInt32BE(frame, 2, payload.length);
-    frame.set(header, 6);
-    frame.set(payload, 6 + header.length);
+    writeUInt32BE(frame, UINT16_BYTES, payload.length);
+    frame.set(header, exports.ZLINK_STREAM_FRAME_PREFIX_BYTES);
+    frame.set(payload, exports.ZLINK_STREAM_FRAME_PREFIX_BYTES + header.length);
     return frame;
 }
 function decodeStreamWireFrame(frame) {
-    if (frame.length < 6) {
+    if (frame.length < exports.ZLINK_STREAM_FRAME_PREFIX_BYTES) {
         throw new Error('Stream frame prefix is incomplete.');
     }
     const headerLength = readUInt16BE(frame, 0);
-    const payloadLength = readUInt32BE(frame, 2);
-    if (frame.length !== 6 + headerLength + payloadLength) {
+    const payloadLength = readUInt32BE(frame, UINT16_BYTES);
+    if (frame.length !== exports.ZLINK_STREAM_FRAME_PREFIX_BYTES + headerLength + payloadLength) {
         throw new Error('Stream frame length does not match prefix.');
     }
     return {
-        header: frame.slice(6, 6 + headerLength),
-        payload: frame.slice(6 + headerLength)
+        header: frame.slice(exports.ZLINK_STREAM_FRAME_PREFIX_BYTES, exports.ZLINK_STREAM_FRAME_PREFIX_BYTES + headerLength),
+        payload: frame.slice(exports.ZLINK_STREAM_FRAME_PREFIX_BYTES + headerLength)
     };
 }
 function tryDecodeStreamWireFrame(frame) {
-    if (frame.length < 6) {
+    if (frame.length < exports.ZLINK_STREAM_FRAME_PREFIX_BYTES) {
         return undefined;
     }
     const headerLength = readUInt16BE(frame, 0);
-    const payloadLength = readUInt32BE(frame, 2);
-    if (frame.length !== 6 + headerLength + payloadLength) {
+    const payloadLength = readUInt32BE(frame, UINT16_BYTES);
+    if (frame.length !== exports.ZLINK_STREAM_FRAME_PREFIX_BYTES + headerLength + payloadLength) {
         return undefined;
     }
     return {
-        header: frame.slice(6, 6 + headerLength),
-        payload: frame.slice(6 + headerLength)
+        header: frame.slice(exports.ZLINK_STREAM_FRAME_PREFIX_BYTES, exports.ZLINK_STREAM_FRAME_PREFIX_BYTES + headerLength),
+        payload: frame.slice(exports.ZLINK_STREAM_FRAME_PREFIX_BYTES + headerLength)
     };
 }
 function encodeStreamWireHeader(header, flagOverrides) {
     const flags = flagOverrides ?? defaultHeaderFlags;
     const reply = isReplyKind(header.kind);
     const packetName = reply ? '' : header.name;
-    if (!reply)
-        validateStreamWirePacketName(packetName);
-    const nameBytes = utf8Encode(packetName);
+    const nameBytes = reply ? new Uint8Array() : validateStreamWirePacketName(packetName);
     const hasRequestSeq = header.requestSeq !== undefined;
     const hasMetadata = header.metadata.size > 0;
     const correlationBytes = header.correlationId !== undefined && header.correlationId.length > 0
         ? utf8Encode(header.correlationId)
         : undefined;
-    if (correlationBytes !== undefined && correlationBytes.length > 0xff) {
+    if (correlationBytes !== undefined && correlationBytes.length > UINT8_MAX) {
         throw new Error('Stream correlation id is too large.');
     }
     const hasCorrelation = correlationBytes !== undefined;
@@ -106,7 +309,7 @@ function encodeStreamWireHeader(header, flagOverrides) {
         throw new Error('Stream flow origin is invalid.');
     }
     if (header.actorSlot !== undefined &&
-        (!Number.isInteger(header.actorSlot) || header.actorSlot < 1 || header.actorSlot > 0xffff)) {
+        (!Number.isInteger(header.actorSlot) || header.actorSlot < 1 || header.actorSlot > UINT16_MAX)) {
         throw new Error('Stream actor slot is invalid.');
     }
     let headerFlags = header.flags;
@@ -121,13 +324,13 @@ function encodeStreamWireHeader(header, flagOverrides) {
     headerFlags = hasActorSlot ? headerFlags | flags.hasActorSlot : headerFlags & ~flags.hasActorSlot;
     const metadataBytes = hasMetadata ? encodeStreamWireMetadata(header.metadata) : new Uint8Array();
     const size = 4 +
-        (hasRequestSeq ? 8 : 0) +
+        (hasRequestSeq ? exports.UINT64_BYTES : 0) +
         1 +
         nameBytes.length +
-        (hasMetadata ? 2 + metadataBytes.length : 0) +
+        (hasMetadata ? UINT16_BYTES + metadataBytes.length : 0) +
         (hasCorrelation ? 1 + correlationBytes.length : 0) +
-        (hasFlow ? 37 : 0) +
-        (hasActorSlot ? 2 : 0);
+        (hasFlow ? FLOW_FIELDS_BYTES : 0) +
+        (hasActorSlot ? UINT16_BYTES : 0);
     const buffer = new Uint8Array(size);
     let offset = 0;
     buffer[offset++] = exports.ZLINK_STREAM_FORMAT_MARKER;
@@ -139,14 +342,14 @@ function encodeStreamWireHeader(header, flagOverrides) {
             throw new Error('Request sequence must not be zero.');
         }
         writeBigUInt64BE(buffer, offset, header.requestSeq);
-        offset += 8;
+        offset += exports.UINT64_BYTES;
     }
     buffer[offset++] = nameBytes.length;
     buffer.set(nameBytes, offset);
     offset += nameBytes.length;
     if (hasMetadata) {
         writeUInt16BE(buffer, offset, metadataBytes.length);
-        offset += 2;
+        offset += UINT16_BYTES;
         buffer.set(metadataBytes, offset);
         offset += metadataBytes.length;
     }
@@ -157,7 +360,7 @@ function encodeStreamWireHeader(header, flagOverrides) {
     }
     if (hasFlow) {
         buffer.set(asciiEncode(header.flowId), offset);
-        offset += 36;
+        offset += FLOW_ID_BYTES;
         buffer[offset++] = header.flowOrigin;
     }
     if (hasActorSlot) {
@@ -168,7 +371,7 @@ function encodeStreamWireHeader(header, flagOverrides) {
 function decodeStreamWireHeader(header, flagOverrides, includeFlow = true) {
     const flags = flagOverrides ?? defaultHeaderFlags;
     let offset = 0;
-    if (header.length < 5) {
+    if (header.length < HEADER_MIN_BYTES) {
         throw new Error('Stream header is incomplete.');
     }
     if (header[offset++] !== exports.ZLINK_STREAM_FORMAT_MARKER) {
@@ -182,29 +385,29 @@ function decodeStreamWireHeader(header, flagOverrides, includeFlow = true) {
     const hasCorrelation = (headerFlags & flags.hasCorrelationId) !== 0;
     const hasFlow = (headerFlags & flags.hasFlowId) !== 0;
     const hasActorSlot = (headerFlags & flags.hasActorSlot) !== 0;
-    if ((headerFlags & ~0x3f) !== 0) {
+    if ((headerFlags & ~HEADER_FLAG_MASK) !== 0) {
         throw new Error('Unknown mandatory stream header flag.');
     }
     let requestSeq;
     if (hasRequestSeq) {
-        if (header.length - offset < 8) {
+        if (header.length - offset < exports.UINT64_BYTES) {
             throw new Error('Stream request sequence is incomplete.');
         }
         requestSeq = readBigUInt64BE(header, offset);
         if (requestSeq === 0n) {
             throw new Error('Request sequence must not be zero.');
         }
-        offset += 8;
+        offset += exports.UINT64_BYTES;
     }
     if (header.length - offset < 1) {
         throw new Error('Stream packet name length is missing.');
     }
     const nameLength = header[offset++];
-    if ((!isReplyKind(kind) && nameLength === 0) || header.length - offset < nameLength) {
+    if ((isReplyKind(kind) ? nameLength !== 0 : nameLength === 0) ||
+        header.length - offset < nameLength) {
         throw new Error('Stream packet name is invalid.');
     }
-    const decodedName = utf8Decode(header.subarray(offset, offset + nameLength));
-    const name = isReplyKind(kind) ? '' : decodedName;
+    const name = utf8Decode(header.subarray(offset, offset + nameLength));
     offset += nameLength;
     const decodedMetadata = hasMetadata
         ? decodeStreamWireHeaderMetadata(header, offset)
@@ -225,14 +428,14 @@ function decodeStreamWireHeader(header, flagOverrides, includeFlow = true) {
     let flowId;
     let flowOrigin;
     if (hasFlow) {
-        if (header.length - offset < 37) {
+        if (header.length - offset < FLOW_FIELDS_BYTES) {
             throw new Error('Stream flow fields are incomplete.');
         }
         if (includeFlow) {
-            flowId = asciiDecode(header.subarray(offset, offset + 36));
+            flowId = asciiDecode(header.subarray(offset, offset + FLOW_ID_BYTES));
             validateFlowId(flowId);
         }
-        offset += 36;
+        offset += FLOW_ID_BYTES;
         const decodedFlowOrigin = header[offset++];
         if (includeFlow && ![1, 2, 3, 4].includes(decodedFlowOrigin)) {
             throw new Error('Stream flow origin is invalid.');
@@ -241,14 +444,14 @@ function decodeStreamWireHeader(header, flagOverrides, includeFlow = true) {
     }
     let actorSlot;
     if (hasActorSlot) {
-        if (header.length - offset < 2) {
+        if (header.length - offset < UINT16_BYTES) {
             throw new Error('Stream actor slot is incomplete.');
         }
         actorSlot = readUInt16BE(header, offset);
         if (actorSlot === 0) {
             throw new Error('Stream actor slot must not be zero.');
         }
-        offset += 2;
+        offset += UINT16_BYTES;
     }
     if (offset !== header.length) {
         throw new Error('Stream header has trailing bytes.');
@@ -279,32 +482,37 @@ function asciiDecode(value) {
         throw new Error('Stream flow id must be ASCII.');
     return String.fromCharCode(...value);
 }
-function encodeStreamWireMetadata(metadata) {
-    if (metadata.size > 255) {
+/** Standalone metadata includes its count byte even when the map is empty. */
+function streamWireMetadataSize(metadata) {
+    if (metadata.size > UINT8_MAX) {
         throw new Error('Metadata entry count must not exceed 255.');
     }
     let size = 1;
-    const encoded = [...metadata].map(([key, value]) => {
-        const keyBytes = utf8Encode(key);
-        const valueBytes = utf8Encode(value);
-        if (keyBytes.length === 0 || keyBytes.length > 255) {
+    for (const [key, value] of metadata) {
+        const keySize = utf8Size(key);
+        const valueSize = utf8Size(value);
+        if (keySize === 0 || keySize > UINT8_MAX) {
             throw new Error('Metadata key length is invalid.');
         }
-        if (valueBytes.length > 0xffff) {
+        if (valueSize > UINT16_MAX) {
             throw new Error('Metadata value is too large.');
         }
-        size += 1 + keyBytes.length + 2 + valueBytes.length;
-        return { keyBytes, valueBytes };
-    });
-    const buffer = new Uint8Array(size);
+        size += 1 + keySize + UINT16_BYTES + valueSize;
+    }
+    return size;
+}
+function encodeStreamWireMetadata(metadata) {
+    const buffer = new Uint8Array(streamWireMetadataSize(metadata));
     let offset = 0;
     buffer[offset++] = metadata.size;
-    for (const { keyBytes, valueBytes } of encoded) {
+    for (const [key, value] of metadata) {
+        const keyBytes = utf8Encode(key);
+        const valueBytes = utf8Encode(value);
         buffer[offset++] = keyBytes.length;
         buffer.set(keyBytes, offset);
         offset += keyBytes.length;
         writeUInt16BE(buffer, offset, valueBytes.length);
-        offset += 2;
+        offset += UINT16_BYTES;
         buffer.set(valueBytes, offset);
         offset += valueBytes.length;
     }
@@ -333,11 +541,11 @@ function utf8Decode(value) {
     return new TextDecoder().decode(value);
 }
 function decodeStreamWireHeaderMetadata(header, offset) {
-    if (header.length - offset < 2) {
+    if (header.length - offset < UINT16_BYTES) {
         throw new Error('Stream metadata section is incomplete.');
     }
     const metadataLength = readUInt16BE(header, offset);
-    offset += 2;
+    offset += UINT16_BYTES;
     if (header.length - offset < metadataLength) {
         throw new Error('Stream metadata payload is incomplete.');
     }
@@ -363,7 +571,7 @@ function decodeStreamWireMetadataAt(source, offset, end) {
             throw new Error('Stream metadata value length is missing.');
         }
         const valueLength = readUInt16BE(source, offset);
-        offset += 2;
+        offset += UINT16_BYTES;
         if (end - offset < valueLength) {
             throw new Error('Stream metadata value is incomplete.');
         }
@@ -378,18 +586,20 @@ function decodeStreamWireMetadataAt(source, offset, end) {
     }
     return { metadata, offset };
 }
+/** @internal Shared packet name structure validation for the connector. */
 function validateStreamWirePacketName(name) {
     const nameBytes = utf8Encode(name);
-    if (name.trim().length === 0 || nameBytes.length > 255) {
+    if (unicodeWhiteSpaceOnly.test(name) || nameBytes.length > exports.ZLINK_STREAM_MAX_PACKET_NAME_BYTES) {
         throw new Error('Stream packet name is invalid.');
     }
+    return nameBytes;
 }
 function isReplyKind(kind) {
-    return kind === ZLINK_STREAM_RESPONSE_KIND || kind === ZLINK_STREAM_ERROR_KIND;
+    return kind === ZlinkStreamMessageKind.Response || kind === ZlinkStreamMessageKind.Error;
 }
 function writeUInt16BE(buffer, offset, value) {
-    buffer[offset] = (value >>> 8) & 0xff;
-    buffer[offset + 1] = value & 0xff;
+    buffer[offset] = (value >>> 8) & UINT8_MAX;
+    buffer[offset + 1] = value & UINT8_MAX;
 }
 function readUInt16BE(buffer, offset) {
     return (buffer[offset] << 8) | buffer[offset + 1];
@@ -399,10 +609,10 @@ function readUInt32BE(buffer, offset) {
         ((buffer[offset + 1] << 16) | (buffer[offset + 2] << 8) | buffer[offset + 3]));
 }
 function writeUInt32BE(buffer, offset, value) {
-    buffer[offset] = (value >>> 24) & 0xff;
-    buffer[offset + 1] = (value >>> 16) & 0xff;
-    buffer[offset + 2] = (value >>> 8) & 0xff;
-    buffer[offset + 3] = value & 0xff;
+    buffer[offset] = (value >>> 24) & UINT8_MAX;
+    buffer[offset + 1] = (value >>> 16) & UINT8_MAX;
+    buffer[offset + 2] = (value >>> 8) & UINT8_MAX;
+    buffer[offset + 3] = value & UINT8_MAX;
 }
 function writeBigUInt64BE(buffer, offset, value) {
     for (let index = 7; index >= 0; index -= 1) {
@@ -417,3 +627,25 @@ function readBigUInt64BE(buffer, offset) {
     }
     return value;
 }
+/** TextEncoder replaces lone surrogates with the three-byte replacement character. */
+function utf8Size(value) {
+    let size = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code < UTF8_TWO_BYTE_MIN)
+            size += 1;
+        else if (code < UTF8_THREE_BYTE_MIN)
+            size += 2;
+        else if (code >= UTF16_HIGH_SURROGATE_MIN &&
+            code <= UTF16_HIGH_SURROGATE_MAX &&
+            index + 1 < value.length &&
+            value.charCodeAt(index + 1) >= UTF16_LOW_SURROGATE_MIN &&
+            value.charCodeAt(index + 1) <= UTF16_LOW_SURROGATE_MAX) {
+            size += 4;
+            index += 1;
+        }
+        else
+            size += 3;
+    }
+    return size;
+}

package/dist/lz4-pickle.js

@@ -4,6 +4,10 @@ exports.defaultMaxDecompressedPayloadSize = void 0;
 exports.lz4PickleUncompressed = lz4PickleUncompressed;
 exports.lz4PickledLength = lz4PickledLength;
 exports.lz4UnpicklePayload = lz4UnpicklePayload;
+const LZ4_MIN_MATCH_LENGTH = 4;
+const LZ4_MATCH_OFFSET_BYTES = 2;
+const LZ4_EXTENDED_LENGTH_NIBBLE = 15;
+const LZ4_EXTENDED_LENGTH_BYTE = 255;
 // Resolved inside the function body rather than in a parameter default: see the
 // note on defaultHeaderFlags in index.ts. Emscripten's dead-code pass deletes a
 // binding whose only references are parameter defaults.
@@ -86,15 +90,15 @@ function decodeLz4Block(source, resultLength) {
         if (sourceOffset >= source.length) {
             break;
         }
-        if (source.length - sourceOffset < 2) {
+        if (source.length - sourceOffset < LZ4_MATCH_OFFSET_BYTES) {
             throw new Error('LZ4 match offset is incomplete.');
         }
         const matchOffset = source[sourceOffset] | (source[sourceOffset + 1] << 8);
-        sourceOffset += 2;
+        sourceOffset += LZ4_MATCH_OFFSET_BYTES;
         if (matchOffset === 0 || matchOffset > targetOffset) {
             throw new Error('LZ4 match offset is invalid.');
         }
-        const matchLength = readLz4Length(source, token & 0x0f, () => sourceOffset++) + 4;
+        const matchLength = readLz4Length(source, token & 0x0f, () => sourceOffset++) + LZ4_MIN_MATCH_LENGTH;
         if (target.length - targetOffset < matchLength) {
             throw new Error('LZ4 match run exceeds output size.');
         }
@@ -110,7 +114,7 @@ function decodeLz4Block(source, resultLength) {
 }
 function readLz4Length(source, nibble, nextOffset) {
     let length = nibble;
-    if (length !== 15) {
+    if (length !== LZ4_EXTENDED_LENGTH_NIBBLE) {
         return length;
     }
     for (;;) {
@@ -120,7 +124,7 @@ function readLz4Length(source, nibble, nextOffset) {
         }
         const value = source[offset];
         length += value;
-        if (value !== 255) {
+        if (value !== LZ4_EXTENDED_LENGTH_BYTE) {
             return length;
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zlink-systems/stream-wire",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",