@livedesk/hub 0.1.27 → 0.1.29

package/src/transport/udp-hub-transport.js

@@ -3,15 +3,19 @@ import { lookup } from 'node:dns/promises';
 import dgram from 'node:dgram';
 import {
     UDP_MAX_DATAGRAM_BYTES,
+    UDP_FRAME_CHUNK_PROTOCOL,
     UDP_P2P_PROTOCOL,
     UdpFrameReassembler,
     UdpReplayWindow,
-    decodeRendezvousMessage,
-    decodeUdpPacket,
+    decodeRendezvousMessage,
+    decodeUdpPacket,
     encodeRendezvousMessage,
     encodeUdpPacket,
-    createUdpSessionKey
-} from './udp-protocol.js';
+    createUdpSessionKey,
+    isUdpBinaryDatagram,
+    peekUdpSessionRouteKey,
+    udpSessionRouteKey
+} from './udp-protocol.js';
 
 function isEnabled(value, fallback = false) {
     if (value === undefined || value === null || value === '') return fallback;
@@ -69,9 +73,21 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
     const punchTimeoutMs = numberEnv(env.LIVEDESK_UDP_PUNCH_TIMEOUT_MS, 500, 10_000, 3000);
     const frameTimeoutMs = numberEnv(env.LIVEDESK_UDP_FRAME_TIMEOUT_MS, 20, 2000, 500);
     const maxPendingFrames = numberEnv(env.LIVEDESK_UDP_MAX_PENDING_FRAMES, 1, 16, 2);
-    const trace = isEnabled(env.LIVEDESK_UDP_TRACE, false);
-    const socket = dgram.createSocket('udp4');
-    const sessions = new Map();
+    const trace = isEnabled(env.LIVEDESK_UDP_TRACE, false);
+    const socket = dgram.createSocket('udp4');
+    const sessions = new Map();
+    const sessionsBySessionId = new Map();
+    const sessionsByRouteKey = new Map();
+    const resource = {
+        datagramsReceived: 0,
+        binaryDatagramsReceived: 0,
+        rendezvousJsonParseAttempts: 0,
+        binaryJsonParseAttempts: 0,
+        sessionLookupCount: 0,
+        linearSessionScanCount: 0,
+        authenticatedDatagrams: 0,
+        rejectedDatagrams: 0
+    };
     let frameHandler = () => {};
     let eventHandler = () => {};
     let started = false;
@@ -80,6 +96,8 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
     let rendezvousAddresses = new Set();
     let rendezvousRefreshTimer = null;
     let rendezvousRefreshPromise = null;
+    let frameExpiryTimer = null;
+    const peerProbeBurstDelaysMs = [0, 120, 360];
 
     function emit(type, event = {}) {
         eventHandler(type, event);
@@ -172,17 +190,31 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
         rendezvousRefreshTimer = null;
     }
 
+    function startFrameExpiryTimer() {
+        if (frameExpiryTimer) return;
+        frameExpiryTimer = setInterval(() => {
+            const now = Date.now();
+            for (const session of sessions.values()) {
+                session.reassembler.expire(now);
+            }
+        }, Math.max(20, Math.min(250, frameTimeoutMs)));
+        frameExpiryTimer.unref?.();
+    }
+
+    function stopFrameExpiryTimer() {
+        if (frameExpiryTimer) clearInterval(frameExpiryTimer);
+        frameExpiryTimer = null;
+    }
+
     function isTrustedRendezvousSource(rinfo) {
         return Number(rinfo?.port) === rendezvousPort
             && rendezvousAddresses.has(normalizedAddress(rinfo?.address));
     }
 
     function sessionForPacket(packet) {
-        if (!Buffer.isBuffer(packet) || packet.length < 7) return null;
-        const sessionLength = packet[6];
-        if (!sessionLength || packet.length < 27 + sessionLength) return null;
-        const sessionId = packet.subarray(27, 27 + sessionLength).toString('utf8');
-        return [...sessions.values()].find(item => item.sessionId === sessionId) || null;
+        resource.sessionLookupCount += 1;
+        const routeKey = peekUdpSessionRouteKey(packet);
+        return routeKey === null ? null : sessionsByRouteKey.get(routeKey) || null;
     }
 
     function bindAuthenticatedClientEndpoint(session, rinfo) {
@@ -199,8 +231,35 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
         return true;
     }
 
+    function clearPeerProbeTimers(session) {
+        if (!session?.peerProbeTimers) return;
+        for (const timer of session.peerProbeTimers) clearTimeout(timer);
+        session.peerProbeTimers.clear();
+    }
+
+    function schedulePeerProbeBurst(session, endpoint) {
+        clearPeerProbeTimers(session);
+        for (const delayMs of peerProbeBurstDelaysMs) {
+            const sendProbe = () => {
+                if (sessions.get(session.deviceId) !== session
+                    || !sameEndpoint(session.peerEndpoint, endpoint)) return;
+                sendPacket(session, 'probe', { punch: true }, Buffer.alloc(0), endpoint);
+            };
+            if (delayMs === 0) {
+                sendProbe();
+                continue;
+            }
+            const timer = setTimeout(() => {
+                session.peerProbeTimers.delete(timer);
+                sendProbe();
+            }, delayMs);
+            timer.unref?.();
+            session.peerProbeTimers.add(timer);
+        }
+    }
+
     function onRendezvousPeer(message, rinfo) {
-        const session = [...sessions.values()].find(item => item.sessionId === safeText(message.roomId, 160));
+        const session = sessionsBySessionId.get(safeText(message.roomId, 160));
         if (!session || message.protocol !== UDP_P2P_PROTOCOL || !isTrustedRendezvousSource(rinfo)) return;
         const address = safeText(message.host, 128);
         const port = Number(message.port);
@@ -217,22 +276,49 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
             };
             session.hubRendezvousObservedAt = Date.now();
         }
-        session.peerEndpoint = { address, port };
+        session.peerEndpoint = { address, port };
         session.lastPeerAt = Date.now();
-        sendPacket(session, 'probe', { punch: true }, Buffer.alloc(0), session.peerEndpoint);
+        schedulePeerProbeBurst(session, session.peerEndpoint);
         emit('UdpPeerEndpointObserved', { deviceId: session.deviceId, endpoint: `${address}:${port}` });
     }
 
-    socket.on('message', (payload, rinfo) => {
-        const rendezvous = decodeRendezvousMessage(payload);
-        if (rendezvous?.type === 'rendezvous.peer') {
-            onRendezvousPeer(rendezvous, rinfo);
+    socket.on('message', (payload, rinfo) => {
+        resource.datagramsReceived += 1;
+        if (!isUdpBinaryDatagram(payload)) {
+            // Rendezvous messages are the only JSON datagrams. Binary packets
+            // never pay a speculative JSON parse/exception before routing.
+            if (payload?.[0] !== 0x7b) {
+                resource.rejectedDatagrams += 1;
+                return;
+            }
+            resource.rendezvousJsonParseAttempts += 1;
+            const rendezvous = decodeRendezvousMessage(payload);
+            if (rendezvous?.type === 'rendezvous.peer') {
+                onRendezvousPeer(rendezvous, rinfo);
+            } else {
+                resource.rejectedDatagrams += 1;
+            }
             return;
         }
+        resource.binaryDatagramsReceived += 1;
         const session = sessionForPacket(payload);
-        if (!session) return;
-        const packet = decodeUdpPacket(payload, session.key);
-        if (!packet || packet.sessionId !== session.sessionId || !session.replay.accept(packet.sequence)) return;
+        if (!session) {
+            resource.rejectedDatagrams += 1;
+            return;
+        }
+        session.resource.binaryDatagramsReceived += 1;
+        session.resource.decryptAttempts += 1;
+        const packet = decodeUdpPacket(payload, session.key, {
+            id: session.sessionId,
+            bytes: session.sessionIdBytes
+        });
+        if (!packet || packet.sessionId !== session.sessionId || !session.replay.accept(packet.sequence)) {
+            session.resource.rejectedDatagrams += 1;
+            resource.rejectedDatagrams += 1;
+            return;
+        }
+        resource.authenticatedDatagrams += 1;
+        session.resource.authenticatedDatagrams += 1;
         bindAuthenticatedClientEndpoint(session, rinfo);
         session.lastPacketAt = Date.now();
         if (packet.type === 'probe') {
@@ -240,7 +326,8 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
             emit('UdpProbeReceived', { deviceId: session.deviceId });
             return;
         }
-        if (packet.type === 'ready') {
+        if (packet.type === 'ready') {
+            clearPeerProbeTimers(session);
             session.ready = true;
             sendPacket(session, 'pong', { state: 'ready' });
             session.sendControl?.({
@@ -288,6 +375,7 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
                 protocol: 'livedesk.frame-transport-proof.v1',
                 streamId: safeText(complete.header?.streamId, 128),
                 commandId: safeText(complete.header?.commandId, 128),
+                streamPurpose: safeText(complete.header?.streamPurpose, 24),
                 captureGeneration: Number(complete.header?.captureGeneration || 0) || 0,
                 monitorIndex: Number(complete.header?.monitorIndex ?? -1),
                 error: proofAccepted ? '' : safeText(handled?.error || 'frame-proof-rejected', 160)
@@ -300,6 +388,7 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
                 frameSeq: Number(complete.header?.frameSeq || 0) || 0,
                 streamId: safeText(complete.header?.streamId, 128),
                 commandId: safeText(complete.header?.commandId, 128),
+                streamPurpose: safeText(complete.header?.streamPurpose, 24),
                 captureGeneration: Number(complete.header?.captureGeneration || 0) || 0,
                 monitorIndex: Number(complete.header?.monitorIndex ?? -1)
             });
@@ -327,19 +416,36 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
         logEvent('udp', `UDP P2P socket listening on udp://${bindHost}:${boundPort}`);
         void refreshRendezvousRegistrations('startup');
         startRendezvousRefreshTimer();
+        startFrameExpiryTimer();
         return getStatus();
     }
 
-    function registerDevice({ deviceId, sessionId: tcpSessionId, sendControl, capabilities } = {}) {
-        if (!enabled || capabilities?.udpP2p !== true || !started) return null;
-        const id = safeText(deviceId, 160);
-        if (!id) return null;
-        sessions.get(id)?.sendControl?.({ type: 'udp.session.close', reason: 'replaced' });
-        const key = createUdpSessionKey();
-        const session = {
+    function registerDevice({ deviceId, sessionId: tcpSessionId, sendControl, capabilities } = {}) {
+        if (!enabled || capabilities?.udpP2p !== true || !started) return null;
+        const id = safeText(deviceId, 160);
+        if (!id) return null;
+        const previous = sessions.get(id);
+        previous?.sendControl?.({ type: 'udp.session.close', reason: 'replaced' });
+        if (previous) {
+            clearPeerProbeTimers(previous);
+            sessions.delete(id);
+            sessionsBySessionId.delete(previous.sessionId);
+            sessionsByRouteKey.delete(previous.routeKey);
+            previous.reassembler.clear();
+        }
+        const key = createUdpSessionKey();
+        let udpSessionId;
+        let routeKey;
+        do {
+            udpSessionId = crypto.randomUUID();
+            routeKey = udpSessionRouteKey(udpSessionId);
+        } while (sessionsByRouteKey.has(routeKey));
+        const session = {
             deviceId: id,
             tcpSessionId: safeText(tcpSessionId, 160),
-            sessionId: crypto.randomUUID(),
+            sessionId: udpSessionId,
+            sessionIdBytes: Buffer.from(udpSessionId, 'utf8'),
+            routeKey,
             key,
             keyBase64: key.toString('base64'),
             rendezvousToken: crypto.randomBytes(16).toString('hex'),
@@ -349,14 +455,23 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
             hubRendezvousEndpoint: null,
             hubRendezvousObservedAt: 0,
             replay: new UdpReplayWindow(),
-            reassembler: new UdpFrameReassembler({ maxPending: maxPendingFrames, timeoutMs: frameTimeoutMs }),
+            reassembler: new UdpFrameReassembler({ maxPending: maxPendingFrames, timeoutMs: frameTimeoutMs }),
+            resource: {
+                binaryDatagramsReceived: 0,
+                decryptAttempts: 0,
+                authenticatedDatagrams: 0,
+                rejectedDatagrams: 0
+            },
             ready: false,
+            peerProbeTimers: new Set(),
             createdAt: Date.now(),
             lastPacketAt: 0,
             framesReceived: 0
-        };
-        sessions.set(id, session);
-        sendControl?.({
+        };
+        sessions.set(id, session);
+        sessionsBySessionId.set(session.sessionId, session);
+        sessionsByRouteKey.set(session.routeKey, session);
+        sendControl?.({
             type: 'udp.session.offer',
             protocol: UDP_P2P_PROTOCOL,
             sessionId: session.sessionId,
@@ -365,8 +480,9 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
             port: boundPort,
             expiresInMs: punchTimeoutMs + 15_000,
             punchTimeoutMs,
-            maxDatagramBytes: UDP_MAX_DATAGRAM_BYTES,
-            frameTimeoutMs,
+            maxDatagramBytes: UDP_MAX_DATAGRAM_BYTES,
+            frameChunkHeader: UDP_FRAME_CHUNK_PROTOCOL,
+            frameTimeoutMs,
             maxPendingFrames,
             rendezvous: rendezvousHost
                 ? { host: rendezvousHost, port: rendezvousPort, roomId: session.sessionId, token: session.rendezvousToken }
@@ -377,12 +493,16 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
         return { sessionId: session.sessionId, ready: false };
     }
 
-    function unregisterDevice(deviceId, tcpSessionId = '') {
+    function unregisterDevice(deviceId, tcpSessionId = '') {
         const id = safeText(deviceId, 160);
         const session = sessions.get(id);
-        if (!session || (tcpSessionId && session.tcpSessionId !== tcpSessionId)) return;
+        if (!session || (tcpSessionId && session.tcpSessionId !== tcpSessionId)) return;
+        clearPeerProbeTimers(session);
         sessions.delete(id);
-        emit('UdpSessionClosed', { deviceId: id, reason: 'tcp-session-closed' });
+        sessionsBySessionId.delete(session.sessionId);
+        sessionsByRouteKey.delete(session.routeKey);
+        session.reassembler.clear();
+        emit('UdpSessionClosed', { deviceId: id, reason: 'tcp-session-closed' });
     }
 
     function getDeviceStatus(deviceId) {
@@ -396,6 +516,12 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
             sessionId: session.sessionId,
             lastPacketAt: session.lastPacketAt ? new Date(session.lastPacketAt).toISOString() : '',
             framesReceived: session.framesReceived,
+            resource: {
+                ...session.resource,
+                binaryJsonParseAttempts: 0,
+                sessionLookup: 'map-o1',
+                linearSessionScanCount: 0
+            },
             ...session.reassembler.getStats()
         };
     }
@@ -467,7 +593,14 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
 
     async function close() {
         stopRendezvousRefreshTimer();
+        stopFrameExpiryTimer();
+        for (const session of sessions.values()) {
+            clearPeerProbeTimers(session);
+            session.reassembler.clear();
+        }
         sessions.clear();
+        sessionsBySessionId.clear();
+        sessionsByRouteKey.clear();
         if (!started) return;
         started = false;
         await new Promise(resolve => socket.close(() => resolve()));
@@ -486,8 +619,45 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
         setEventHandler: handler => { eventHandler = typeof handler === 'function' ? handler : () => {}; }
     };
 
-    function getStatus() {
-        return {
+    function getStatus() {
+        let readySessionCount = 0;
+        const reassembly = {
+            pendingFrames: 0,
+            pendingBytes: 0,
+            pendingChunkBuffers: 0,
+            pendingBytesHighWatermark: 0,
+            pendingChunkBuffersHighWatermark: 0,
+            droppedFrames: 0,
+            completedFrames: 0,
+            completedPayloadCopyCount: 0,
+            completedPayloadCopyBytes: 0,
+            fullWireDuplicateCopyCount: 0,
+            binaryChunkHeaderCount: 0,
+            legacyChunkHeaderCount: 0
+        };
+        for (const session of sessions.values()) {
+            if (session.ready) readySessionCount += 1;
+            const stats = session.reassembler.getStats();
+            reassembly.pendingFrames += stats.pendingFrames;
+            reassembly.pendingBytes += stats.pendingBytes;
+            reassembly.pendingChunkBuffers += stats.pendingChunkBuffers;
+            reassembly.pendingBytesHighWatermark = Math.max(
+                reassembly.pendingBytesHighWatermark,
+                stats.pendingBytesHighWatermark
+            );
+            reassembly.pendingChunkBuffersHighWatermark = Math.max(
+                reassembly.pendingChunkBuffersHighWatermark,
+                stats.pendingChunkBuffersHighWatermark
+            );
+            reassembly.droppedFrames += stats.droppedFrames;
+            reassembly.completedFrames += stats.completedFrames;
+            reassembly.completedPayloadCopyCount += stats.completedPayloadCopyCount;
+            reassembly.completedPayloadCopyBytes += stats.completedPayloadCopyBytes;
+            reassembly.fullWireDuplicateCopyCount += stats.fullWireDuplicateCopyCount;
+            reassembly.binaryChunkHeaderCount += stats.binaryChunkHeaderCount;
+            reassembly.legacyChunkHeaderCount += stats.legacyChunkHeaderCount;
+        }
+        return {
             enabled,
             preferred: preferP2p,
             started,
@@ -498,9 +668,15 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
             rendezvousPort,
             rendezvousRefreshMs,
             rendezvousResolvedAddressCount: rendezvousAddresses.size,
-            maxDatagramBytes: UDP_MAX_DATAGRAM_BYTES,
-            sessionCount: sessions.size,
-            readySessionCount: [...sessions.values()].filter(session => session.ready).length
-        };
+            maxDatagramBytes: UDP_MAX_DATAGRAM_BYTES,
+            sessionCount: sessions.size,
+            readySessionCount,
+            resource: {
+                ...resource,
+                indexedSessionCount: sessionsBySessionId.size,
+                indexedRouteCount: sessionsByRouteKey.size,
+                ...reassembly
+            }
+        };
     }
 }