@livedesk/hub 0.1.26 → 0.1.28

package/src/transport/udp-protocol.js

@@ -14,15 +14,19 @@ export const UDP_PACKET_TYPES = Object.freeze({
     pong: 5,
     frame: 6,
     close: 7
-});
-const UDP_PACKET_TYPE_NAMES = new Map(Object.entries(UDP_PACKET_TYPES).map(([name, value]) => [value, name]));
-const UDP_FIXED_HEADER_BYTES = 15;
-const UDP_NONCE_BYTES = 12;
-const UDP_TAG_BYTES = 16;
-const UDP_MAX_SESSION_ID_BYTES = 96;
+});
+const UDP_PACKET_TYPE_NAMES = new Map(Object.entries(UDP_PACKET_TYPES).map(([name, value]) => [value, name]));
+const UDP_FIXED_HEADER_BYTES = 15;
+const UDP_NONCE_BYTES = 12;
+const UDP_TAG_BYTES = 16;
+const UDP_MAX_SESSION_ID_BYTES = 96;
 const UDP_MAX_HEADER_BYTES = 4096;
 const UDP_MAX_PAYLOAD_BYTES = UDP_MAX_DATAGRAM_BYTES - UDP_FIXED_HEADER_BYTES - UDP_NONCE_BYTES - UDP_TAG_BYTES - 1;
 const UDP_FRAME_PAYLOAD_MAGIC = Buffer.from('LDF1', 'ascii');
+const UDP_PACKET_MAGIC = Buffer.from('LDU1', 'ascii');
+const UDP_FRAME_CHUNK_MAGIC = Buffer.from('LDC1', 'ascii');
+export const UDP_FRAME_CHUNK_PROTOCOL = 'livedesk.udp.frame-chunk.v1';
+export const UDP_FRAME_CHUNK_HEADER_BYTES = 12;
 const UDP_MAX_FRAME_HEADER_BYTES = 64 * 1024;
 
 function asBuffer(value) {
@@ -45,6 +49,106 @@ function normalizeSessionId(value) {
     return sessionId;
 }
 
+export function isUdpBinaryDatagram(packet) {
+    return Buffer.isBuffer(packet)
+        && packet.length >= UDP_FIXED_HEADER_BYTES + UDP_NONCE_BYTES + UDP_TAG_BYTES
+        && packet[0] === UDP_PACKET_MAGIC[0]
+        && packet[1] === UDP_PACKET_MAGIC[1]
+        && packet[2] === UDP_PACKET_MAGIC[2]
+        && packet[3] === UDP_PACKET_MAGIC[3]
+        && packet[4] === UDP_P2P_VERSION;
+}
+
+export function peekUdpSessionId(packet) {
+    if (!isUdpBinaryDatagram(packet)) return '';
+    const sessionLength = packet[6];
+    const headerLength = packet.readUInt16BE(7);
+    const payloadLength = packet.readUInt16BE(9);
+    const associatedLength = UDP_FIXED_HEADER_BYTES + UDP_NONCE_BYTES + sessionLength + headerLength;
+    const expectedLength = associatedLength + payloadLength + UDP_TAG_BYTES;
+    if (sessionLength < 1 || sessionLength > UDP_MAX_SESSION_ID_BYTES
+        || headerLength > UDP_MAX_HEADER_BYTES || payloadLength > UDP_MAX_PAYLOAD_BYTES
+        || expectedLength !== packet.length) return '';
+    return packet.subarray(
+        UDP_FIXED_HEADER_BYTES + UDP_NONCE_BYTES,
+        UDP_FIXED_HEADER_BYTES + UDP_NONCE_BYTES + sessionLength
+    ).toString('utf8');
+}
+
+function routeKeyForBytes(bytes, offset = 0, length = bytes.length - offset) {
+    let hash = 0x811c9dc5;
+    const end = offset + length;
+    for (let index = offset; index < end; index += 1) {
+        hash = Math.imul(hash ^ bytes[index], 0x01000193) >>> 0;
+    }
+    return hash;
+}
+
+export function udpSessionRouteKey(sessionId) {
+    return routeKeyForBytes(Buffer.from(normalizeSessionId(sessionId), 'utf8'));
+}
+
+export function peekUdpSessionRouteKey(packet) {
+    if (!isUdpBinaryDatagram(packet)) return null;
+    const sessionLength = packet[6];
+    const headerLength = packet.readUInt16BE(7);
+    const payloadLength = packet.readUInt16BE(9);
+    const associatedLength = UDP_FIXED_HEADER_BYTES + UDP_NONCE_BYTES + sessionLength + headerLength;
+    if (sessionLength < 1 || sessionLength > UDP_MAX_SESSION_ID_BYTES
+        || headerLength > UDP_MAX_HEADER_BYTES || payloadLength > UDP_MAX_PAYLOAD_BYTES
+        || associatedLength + payloadLength + UDP_TAG_BYTES !== packet.length) return null;
+    return routeKeyForBytes(
+        packet,
+        UDP_FIXED_HEADER_BYTES + UDP_NONCE_BYTES,
+        sessionLength
+    );
+}
+
+function encodeFrameChunkHeader(header) {
+    const frameSerial = Number(header?.frameSerial);
+    const chunkIndex = Number(header?.chunkIndex);
+    const chunkCount = Number(header?.chunkCount);
+    if (!Number.isInteger(frameSerial) || frameSerial < 0 || frameSerial > 0xffff_ffff
+        || !Number.isInteger(chunkIndex) || chunkIndex < 0 || chunkIndex > 0xffff
+        || !Number.isInteger(chunkCount) || chunkCount < 1 || chunkCount > 4096
+        || chunkIndex >= chunkCount) {
+        throw new Error('invalid-udp-frame-chunk-header');
+    }
+    const bytes = Buffer.allocUnsafe(UDP_FRAME_CHUNK_HEADER_BYTES);
+    UDP_FRAME_CHUNK_MAGIC.copy(bytes, 0);
+    bytes.writeUInt32BE(frameSerial >>> 0, 4);
+    bytes.writeUInt16BE(chunkIndex, 8);
+    bytes.writeUInt16BE(chunkCount, 10);
+    return bytes;
+}
+
+function decodePacketHeader(type, bytes) {
+    if (type === 'frame'
+        && bytes.length === UDP_FRAME_CHUNK_HEADER_BYTES
+        && bytes[0] === UDP_FRAME_CHUNK_MAGIC[0]
+        && bytes[1] === UDP_FRAME_CHUNK_MAGIC[1]
+        && bytes[2] === UDP_FRAME_CHUNK_MAGIC[2]
+        && bytes[3] === UDP_FRAME_CHUNK_MAGIC[3]) {
+        const chunkIndex = bytes.readUInt16BE(8);
+        const chunkCount = bytes.readUInt16BE(10);
+        if (chunkCount < 1 || chunkCount > 4096 || chunkIndex >= chunkCount) return null;
+        const frameSerial = bytes.readUInt32BE(4);
+        return {
+            frameId: frameSerial,
+            frameSerial,
+            chunkIndex,
+            chunkCount,
+            binaryChunkHeader: true
+        };
+    }
+    try {
+        const value = JSON.parse(bytes.toString('utf8'));
+        return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+    } catch {
+        return null;
+    }
+}
+
 function decodeFrameHeader(header) {
     if (header?.frameHeader && typeof header.frameHeader === 'object') {
         return header.frameHeader;
@@ -84,6 +188,72 @@ function decodeFramedPayload(payload, legacyHeader = null) {
         return null;
     }
 }
+
+function copyChunkRange(chunks, sourceOffset, length, target, targetOffset = 0) {
+    let remaining = length;
+    let skip = sourceOffset;
+    let written = 0;
+    for (const chunk of chunks) {
+        if (!chunk || remaining <= 0) continue;
+        if (skip >= chunk.length) {
+            skip -= chunk.length;
+            continue;
+        }
+        const available = Math.min(remaining, chunk.length - skip);
+        chunk.copy(target, targetOffset + written, skip, skip + available);
+        written += available;
+        remaining -= available;
+        skip = 0;
+    }
+    return written === length;
+}
+
+function decodeFramedChunks(chunks, totalBytes, legacyHeader = null) {
+    if (chunks.length === 1) {
+        const complete = decodeFramedPayload(chunks[0], legacyHeader);
+        return complete
+            ? { ...complete, payloadCopyCount: 0, payloadCopyBytes: 0 }
+            : null;
+    }
+
+    const prefix = Buffer.allocUnsafe(Math.min(8, totalBytes));
+    if (!copyChunkRange(chunks, 0, prefix.length, prefix)) return null;
+    if (prefix.length < 8 || !prefix.subarray(0, 4).equals(UDP_FRAME_PAYLOAD_MAGIC)) {
+        const payload = Buffer.allocUnsafe(totalBytes);
+        if (!copyChunkRange(chunks, 0, totalBytes, payload)) return null;
+        return {
+            header: legacyHeader || {},
+            payload,
+            payloadCopyCount: 1,
+            payloadCopyBytes: totalBytes
+        };
+    }
+
+    const compressedHeaderLength = prefix.readUInt32BE(4);
+    const payloadOffset = 8 + compressedHeaderLength;
+    if (compressedHeaderLength < 1 || compressedHeaderLength > UDP_MAX_FRAME_HEADER_BYTES
+        || payloadOffset > totalBytes) return null;
+    try {
+        const compressedHeader = Buffer.allocUnsafe(compressedHeaderLength);
+        if (!copyChunkRange(chunks, 8, compressedHeaderLength, compressedHeader)) return null;
+        const json = inflateRawSync(compressedHeader, {
+            maxOutputLength: UDP_MAX_FRAME_HEADER_BYTES
+        }).toString('utf8');
+        const header = JSON.parse(json);
+        if (!header || typeof header !== 'object' || Array.isArray(header)) return null;
+        const payloadLength = totalBytes - payloadOffset;
+        const payload = Buffer.allocUnsafe(payloadLength);
+        if (!copyChunkRange(chunks, payloadOffset, payloadLength, payload)) return null;
+        return {
+            header,
+            payload,
+            payloadCopyCount: 1,
+            payloadCopyBytes: payloadLength
+        };
+    } catch {
+        return null;
+    }
+}
 
 function packetTypeCode(type) {
     const code = typeof type === 'number' ? type : UDP_PACKET_TYPES[String(type || '').toLowerCase()];
@@ -99,11 +269,16 @@ function normalizeSequence(value) {
     return sequence;
 }
 
-function encodeHeader(header) {
-    const bytes = Buffer.from(JSON.stringify(header && typeof header === 'object' ? header : {}), 'utf8');
-    if (bytes.length > UDP_MAX_HEADER_BYTES) throw new Error('udp-packet-header-too-large');
-    return bytes;
-}
+function encodeHeader(type, header) {
+    if ((typeof type === 'number' ? type : UDP_PACKET_TYPES[String(type || '').toLowerCase()])
+        === UDP_PACKET_TYPES.frame
+        && Number.isInteger(Number(header?.frameSerial))) {
+        return encodeFrameChunkHeader(header);
+    }
+    const bytes = Buffer.from(JSON.stringify(header && typeof header === 'object' ? header : {}), 'utf8');
+    if (bytes.length > UDP_MAX_HEADER_BYTES) throw new Error('udp-packet-header-too-large');
+    return bytes;
+}
 
 export function deriveUdpSessionKey(keyMaterial) {
     return normalizeKey(keyMaterial);
@@ -116,12 +291,12 @@ export function createUdpSessionKey() {
 export function encodeUdpPacket({ type, sessionId, key, sequence = 0, header = {}, payload = Buffer.alloc(0) }) {
     const normalizedSessionId = normalizeSessionId(sessionId);
     const sessionBytes = Buffer.from(normalizedSessionId, 'utf8');
-    const headerBytes = encodeHeader(header);
-    const payloadBytes = asBuffer(payload);
-    if (payloadBytes.length > UDP_MAX_PAYLOAD_BYTES) throw new Error('udp-packet-payload-too-large');
-
-    const preamble = Buffer.allocUnsafe(UDP_FIXED_HEADER_BYTES);
-    UDP_P2P_PROTOCOL.startsWith('livedesk') && Buffer.from('LDU1', 'ascii').copy(preamble, 0);
+    const headerBytes = encodeHeader(type, header);
+    const payloadBytes = asBuffer(payload);
+    if (payloadBytes.length > UDP_MAX_PAYLOAD_BYTES) throw new Error('udp-packet-payload-too-large');
+
+    const preamble = Buffer.allocUnsafe(UDP_FIXED_HEADER_BYTES);
+    UDP_PACKET_MAGIC.copy(preamble, 0);
     preamble[4] = UDP_P2P_VERSION;
     preamble[5] = packetTypeCode(type);
     preamble[6] = sessionBytes.length;
@@ -139,11 +314,10 @@ export function encodeUdpPacket({ type, sessionId, key, sequence = 0, header = {
     return packet;
 }
 
-export function decodeUdpPacket(packet, key) {
-    const bytes = asBuffer(packet);
-    if (bytes.length < UDP_FIXED_HEADER_BYTES + UDP_NONCE_BYTES + UDP_TAG_BYTES) return null;
-    if (!bytes.subarray(0, 4).equals(Buffer.from('LDU1', 'ascii')) || bytes[4] !== UDP_P2P_VERSION) return null;
-    const type = UDP_PACKET_TYPE_NAMES.get(bytes[5]);
+export function decodeUdpPacket(packet, key, expectedSession = null) {
+    const bytes = asBuffer(packet);
+    if (!isUdpBinaryDatagram(bytes)) return null;
+    const type = UDP_PACKET_TYPE_NAMES.get(bytes[5]);
     const sessionLength = bytes[6];
     const headerLength = bytes.readUInt16BE(7);
     const payloadLength = bytes.readUInt16BE(9);
@@ -154,28 +328,36 @@ export function decodeUdpPacket(packet, key) {
         || headerLength > UDP_MAX_HEADER_BYTES || payloadLength > UDP_MAX_PAYLOAD_BYTES
         || expectedLength !== bytes.length) return null;
 
-    const associatedData = bytes.subarray(0, associatedLength);
-    const sessionStart = UDP_FIXED_HEADER_BYTES + UDP_NONCE_BYTES;
-    const sessionId = bytes.subarray(sessionStart, sessionStart + sessionLength).toString('utf8');
-    const headerStart = sessionStart + sessionLength;
-    let header;
-    try {
-        header = JSON.parse(bytes.subarray(headerStart, headerStart + headerLength).toString('utf8'));
-    } catch {
-        return null;
-    }
-    const nonce = bytes.subarray(UDP_FIXED_HEADER_BYTES, UDP_FIXED_HEADER_BYTES + UDP_NONCE_BYTES);
-    const ciphertextStart = associatedLength;
-    const ciphertext = bytes.subarray(ciphertextStart, ciphertextStart + payloadLength);
-    const tag = bytes.subarray(ciphertextStart + payloadLength);
-    try {
-        const decipher = crypto.createDecipheriv('aes-256-gcm', normalizeKey(key), nonce);
-        decipher.setAAD(associatedData);
-        decipher.setAuthTag(tag);
-        const payload = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
-        return { type, sessionId, sequence, header, payload };
-    } catch {
-        return null;
+    const associatedData = bytes.subarray(0, associatedLength);
+    const sessionStart = UDP_FIXED_HEADER_BYTES + UDP_NONCE_BYTES;
+    const sessionSlice = bytes.subarray(sessionStart, sessionStart + sessionLength);
+    const expectedSessionBytes = Buffer.isBuffer(expectedSession?.bytes)
+        ? expectedSession.bytes
+        : null;
+    if (expectedSessionBytes && !sessionSlice.equals(expectedSessionBytes)) return null;
+    const sessionId = expectedSessionBytes
+        ? String(expectedSession?.id || '')
+        : sessionSlice.toString('utf8');
+    const headerStart = sessionStart + sessionLength;
+    const nonce = bytes.subarray(UDP_FIXED_HEADER_BYTES, UDP_FIXED_HEADER_BYTES + UDP_NONCE_BYTES);
+    const ciphertextStart = associatedLength;
+    const ciphertext = bytes.subarray(ciphertextStart, ciphertextStart + payloadLength);
+    const tag = bytes.subarray(ciphertextStart + payloadLength);
+    try {
+        const decipher = crypto.createDecipheriv('aes-256-gcm', normalizeKey(key), nonce);
+        decipher.setAAD(associatedData);
+        decipher.setAuthTag(tag);
+        let payload = decipher.update(ciphertext);
+        const final = decipher.final();
+        if (final.length > 0) payload = Buffer.concat([payload, final], payload.length + final.length);
+        const header = decodePacketHeader(
+            type,
+            bytes.subarray(headerStart, headerStart + headerLength)
+        );
+        if (!header) return null;
+        return { type, sessionId, sequence, header, payload };
+    } catch {
+        return null;
     }
 }
 
@@ -221,54 +403,80 @@ export class UdpFrameReassembler {
         this.timeoutMs = Math.max(20, Math.min(2000, Math.floor(Number(timeoutMs) || 500)));
         this.maxFrameBytes = Math.max(64 * 1024, Math.min(16 * 1024 * 1024, Math.floor(Number(maxFrameBytes) || 8 * 1024 * 1024)));
         this.pending = new Map();
+        this.pendingBytes = 0;
+        this.pendingChunkBuffers = 0;
+        this.pendingBytesHighWatermark = 0;
+        this.pendingChunkBuffersHighWatermark = 0;
         this.droppedFrames = 0;
         this.expiredFrames = 0;
         this.evictedFrames = 0;
-    }
-
-    ingest(packet, now = Date.now()) {
-        if (!packet || packet.type !== 'frame') return null;
-        this.expire(now);
-        const header = packet.header && typeof packet.header === 'object' ? packet.header : {};
-        const frameId = String(header.frameId || '').slice(0, 160);
-        const chunkIndex = Number(header.chunkIndex);
-        const chunkCount = Number(header.chunkCount);
-        if (!frameId || !Number.isInteger(chunkIndex) || !Number.isInteger(chunkCount)
-            || chunkIndex < 0 || chunkCount < 1 || chunkCount > 4096 || chunkIndex >= chunkCount) return null;
-        let state = this.pending.get(frameId);
-        if (!state) {
+        this.completedFrames = 0;
+        this.completedPayloadCopyCount = 0;
+        this.completedPayloadCopyBytes = 0;
+        this.fullWireDuplicateCopyCount = 0;
+        this.binaryChunkHeaderCount = 0;
+        this.legacyChunkHeaderCount = 0;
+    }
+
+    ingest(packet, now = Date.now()) {
+        if (!packet || packet.type !== 'frame') return null;
+        this.expire(now);
+        const header = packet.header && typeof packet.header === 'object' ? packet.header : {};
+        const frameId = Number.isInteger(header.frameSerial)
+            ? header.frameSerial
+            : String(header.frameId || '').slice(0, 160);
+        const chunkIndex = Number(header.chunkIndex);
+        const chunkCount = Number(header.chunkCount);
+        if ((frameId === '' || frameId === null) || !Number.isInteger(chunkIndex) || !Number.isInteger(chunkCount)
+            || chunkIndex < 0 || chunkCount < 1 || chunkCount > 4096 || chunkIndex >= chunkCount) return null;
+        let state = this.pending.get(frameId);
+        if (!state) {
             while (this.pending.size >= this.maxPending) {
                 const oldest = this.pending.keys().next().value;
                 if (oldest === undefined) break;
-                if (this.pending.delete(oldest)) {
+                const evicted = this.#detach(oldest);
+                if (evicted) {
                     this.droppedFrames += 1;
                     this.evictedFrames += 1;
                 }
             }
             state = { createdAt: now, chunkCount, chunks: new Array(chunkCount), received: 0, totalBytes: 0, frameHeader: null };
             this.pending.set(frameId, state);
-        }
-        if (state.chunkCount !== chunkCount || state.chunks[chunkIndex]) return null;
-        const payload = asBuffer(packet.payload);
-        state.chunks[chunkIndex] = payload;
-        state.received += 1;
-        state.totalBytes += payload.length;
+        }
+        if (state.chunkCount !== chunkCount || state.chunks[chunkIndex]) return null;
+        const payload = asBuffer(packet.payload);
+        state.chunks[chunkIndex] = payload;
+        state.received += 1;
+        state.totalBytes += payload.length;
+        this.pendingBytes += payload.length;
+        this.pendingChunkBuffers += 1;
+        this.pendingBytesHighWatermark = Math.max(this.pendingBytesHighWatermark, this.pendingBytes);
+        this.pendingChunkBuffersHighWatermark = Math.max(
+            this.pendingChunkBuffersHighWatermark,
+            this.pendingChunkBuffers
+        );
+        if (header.binaryChunkHeader === true) this.binaryChunkHeaderCount += 1;
+        else this.legacyChunkHeaderCount += 1;
         const decodedFrameHeader = decodeFrameHeader(header);
         if (decodedFrameHeader) state.frameHeader = decodedFrameHeader;
         if (state.totalBytes > this.maxFrameBytes) {
-            if (this.pending.delete(frameId)) this.droppedFrames += 1;
+            if (this.#detach(frameId)) this.droppedFrames += 1;
             return null;
         }
         if (state.received !== state.chunkCount) return null;
-        this.pending.delete(frameId);
-        const complete = decodeFramedPayload(
-            Buffer.concat(state.chunks, state.totalBytes),
+        this.#detach(frameId);
+        const complete = decodeFramedChunks(
+            state.chunks,
+            state.totalBytes,
             state.frameHeader || header.frameHeader || {}
         );
         if (!complete) {
             this.droppedFrames += 1;
             return null;
         }
+        this.completedFrames += 1;
+        this.completedPayloadCopyCount += complete.payloadCopyCount;
+        this.completedPayloadCopyBytes += complete.payloadCopyBytes;
         return {
             frameId,
             header: complete.header,
@@ -278,21 +486,45 @@ export class UdpFrameReassembler {
 
     expire(now = Date.now()) {
         for (const [frameId, state] of this.pending) {
-            if (now - state.createdAt > this.timeoutMs && this.pending.delete(frameId)) {
+            if (now - state.createdAt > this.timeoutMs && this.#detach(frameId)) {
                 this.droppedFrames += 1;
                 this.expiredFrames += 1;
             }
         }
     }
 
+    clear() {
+        this.pending.clear();
+        this.pendingBytes = 0;
+        this.pendingChunkBuffers = 0;
+    }
+
     getStats() {
         return {
             pendingFrames: this.pending.size,
+            pendingBytes: this.pendingBytes,
+            pendingChunkBuffers: this.pendingChunkBuffers,
+            pendingBytesHighWatermark: this.pendingBytesHighWatermark,
+            pendingChunkBuffersHighWatermark: this.pendingChunkBuffersHighWatermark,
             droppedFrames: this.droppedFrames,
             expiredFrames: this.expiredFrames,
-            evictedFrames: this.evictedFrames
+            evictedFrames: this.evictedFrames,
+            completedFrames: this.completedFrames,
+            completedPayloadCopyCount: this.completedPayloadCopyCount,
+            completedPayloadCopyBytes: this.completedPayloadCopyBytes,
+            fullWireDuplicateCopyCount: this.fullWireDuplicateCopyCount,
+            binaryChunkHeaderCount: this.binaryChunkHeaderCount,
+            legacyChunkHeaderCount: this.legacyChunkHeaderCount
         };
     }
+
+    #detach(frameId) {
+        const state = this.pending.get(frameId);
+        if (!state || !this.pending.delete(frameId)) return null;
+        this.pendingBytes = Math.max(0, this.pendingBytes - state.totalBytes);
+        this.pendingChunkBuffers = Math.max(0, this.pendingChunkBuffers - state.received);
+        return state;
+    }
 }
 
 export function encodeRendezvousMessage(message) {