@livedesk/hub 0.1.7 → 0.1.8

package/src/server.js

@@ -61,7 +61,7 @@ const runtimeManager = createHubRuntime({
 });
 runtimeManager.emit('runtime.started', { role: runtimeRole, pid: process.pid });
 const frameBackpressureBytes = readPositiveIntegerEnv('LIVEDESK_FRAME_WS_BACKPRESSURE_BYTES', 8 * 1024 * 1024);
-const frameClientQueuePackets = readPositiveIntegerEnv('LIVEDESK_FRAME_WS_QUEUE_PACKETS', 4);
+const frameClientQueuePackets = readPositiveIntegerEnv('LIVEDESK_FRAME_WS_QUEUE_PACKETS', 8);
 const controlFrameClientQueuePackets = readPositiveIntegerEnv('LIVEDESK_CONTROL_FRAME_WS_QUEUE_PACKETS', 2);
 const frameStreamStopGraceMs = readPositiveIntegerEnv('LIVEDESK_FRAME_STREAM_STOP_GRACE_MS', 1500);
 const mode5FrameBackpressureBytes = readPositiveIntegerEnv('LIVEDESK_MODE5_WS_BACKPRESSURE_BYTES', 2 * 1024 * 1024);
@@ -170,19 +170,27 @@ function readPositiveIntegerEnv(name, fallback) {
 function handleRemoteHubEvent(type, event) {
   liveDeskUpdateManager?.handleRemoteEvent(type, event);
   hubTransferJobs?.handleRemoteEvent(type, event);
-  if (type === 'RemoteInputApplied') {
-    for (const ws of inputClients) {
-      sendJson(ws, {
-        type: 'RemoteInputApplied',
-        ...event
+  if (type === 'RemoteInputApplied') {
+    const targetConnectionId = String(event?.hubConnectionId || '').trim();
+    for (const ws of inputClients) {
+      if (targetConnectionId && ws.liveDeskInputClientId !== targetConnectionId) {
+        continue;
+      }
+      sendJson(ws, {
+        type: 'RemoteInputApplied',
+        ...event
       });
     }
     return;
-  }
+  }
   if (type === 'RemoteInputError') {
-    for (const ws of inputClients) {
-      sendJson(ws, {
-        type: 'RemoteInputError',
+    const targetConnectionId = String(event?.hubConnectionId || '').trim();
+    for (const ws of inputClients) {
+      if (targetConnectionId && ws.liveDeskInputClientId !== targetConnectionId) {
+        continue;
+      }
+      sendJson(ws, {
+        type: 'RemoteInputError',
         ...event
       });
     }
@@ -1813,11 +1821,21 @@ function enqueueFramePacketForClient(ws, packet, meta) {
       ws.liveDeskFrameBackpressureDrops = Number(ws.liveDeskFrameBackpressureDrops || 0) + 1;
     }
   }
-  while (lane.queue.length >= frameClientQueueLimit(ws)) {
-    dropQueuedFrameForLane(lane);
-    ws.liveDeskFrameBackpressureDrops = Number(ws.liveDeskFrameBackpressureDrops || 0) + 1;
-  }
-  lane.queue.push({
+  while (lane.queue.length >= frameClientQueueLimit(ws)) {
+    dropQueuedFrameForLane(lane);
+    ws.liveDeskFrameBackpressureDrops = Number(ws.liveDeskFrameBackpressureDrops || 0) + 1;
+  }
+  // Queue eviction can put this H.264 device into key-frame recovery after
+  // the pre-overflow check above. Never enqueue the current dependent delta
+  // while the decoder is waiting for a fresh recovery key frame.
+  if (meta.isH264 && meta.isKeyFrame) {
+    lane.awaitingKeyFrames.delete(meta.deviceId);
+  } else if (meta.isH264 && lane.awaitingKeyFrames.has(meta.deviceId)) {
+    lane.dropped += 1;
+    ws.liveDeskFrameBackpressureDrops = Number(ws.liveDeskFrameBackpressureDrops || 0) + 1;
+    return false;
+  }
+  lane.queue.push({
     packet,
     deviceId: meta.deviceId,
     frameSeq: meta.frameSeq,
@@ -2035,18 +2053,41 @@ function buildRemoteFrameBinaryPacket(frameEvent, diagnostics = {}) {
     agentPaceMs: Number(frame.agentPaceMs || 0) || 0,
     agentQueueBeforePaceMs: Number(frame.agentQueueBeforePaceMs || 0) || 0,
     agentFrameAgeMs: Number(frame.agentFrameAgeMs || 0) || 0,
-    droppedByAgent: Number(frame.droppedByAgent || 0) || 0,
-    hubIngressDropped: Number(frame.hubIngressDropped || 0) || 0,
-    hubClientDropped: Number(diagnostics.hubClientDropped || 0) || 0,
-    hardwareEncoder: frame.hardwareEncoder || '',
+    droppedByAgent: Number(frame.droppedByAgent || 0) || 0,
+    hubIngressDropped: Number(frame.hubIngressDropped || 0) || 0,
+    hubClientDropped: Number(diagnostics.hubClientDropped || 0) || 0,
+    hubClientQueueDepth: Number(diagnostics.hubClientQueueDepth || 0) || 0,
+    hubClientQueueLimit: Number(diagnostics.hubClientQueueLimit || 0) || 0,
+    hubClientBufferedBytes: Number(diagnostics.hubClientBufferedBytes || 0) || 0,
+    udpIncompleteFrames: Number(frame.udpIncompleteFrames || 0) || 0,
+    transport: frame.transport || '',
+    videoTransport: frame.videoTransport || (frame.transport === 'udp-p2p'
+      ? 'p2p-udp'
+      : frame.transport === 'ws-binary'
+        ? 'direct-ws'
+        : 'direct-tcp'),
+    frameTransportActive: frame.frameTransportActive || '',
+    frameTransportProtocol: frame.frameTransportProtocol || '',
+    frameTransportState: frame.frameTransportState || '',
+    frameTransportP2pReady: frame.frameTransportP2pReady === true,
+    frameTransportReason: frame.frameTransportReason || '',
+    frameTransportChangedAt: frame.frameTransportChangedAt || '',
+    frameTransportSwitchCount: Number(frame.frameTransportSwitchCount || 0) || 0,
+    frameTransportTcpFailureCount: Number(frame.frameTransportTcpFailureCount || 0) || 0,
+    hardwareEncoder: frame.hardwareEncoder || '',
     platformProfile: frame.platformProfile || '',
     monitorIndex: Number.isFinite(Number(frame.monitorIndex)) ? Number(frame.monitorIndex) : 0,
     monitorCount: Number.isFinite(Number(frame.monitorCount)) ? Number(frame.monitorCount) : 1,
     fps: Number(frame.fps || 0) || 0,
     requestedFps: Number(frame.requestedFps || 0) || 0,
     effectiveFps: Number(frame.effectiveFps || 0) || 0,
-    captureAverageMs: Number(frame.captureAverageMs || 0) || 0,
-    captureP95Ms: Number(frame.captureP95Ms || 0) || 0,
+    captureTimingAvailable: frame.captureTimingAvailable === true,
+    captureAverageMs: frame.captureTimingAvailable === true && Number.isFinite(Number(frame.captureAverageMs))
+      ? Number(frame.captureAverageMs)
+      : null,
+    captureP95Ms: frame.captureTimingAvailable === true && Number.isFinite(Number(frame.captureP95Ms))
+      ? Number(frame.captureP95Ms)
+      : null,
     slowFrameCount: Number(frame.slowFrameCount || 0) || 0,
     captureHelperRestarts: Number(frame.captureHelperRestarts || 0) || 0,
     capturedAt: frame.capturedAt || '',
@@ -2055,8 +2096,12 @@ function buildRemoteFrameBinaryPacket(frameEvent, diagnostics = {}) {
     hubPacketEpochMs,
     byteLength: Number(frameEvent.byteLength || payload.length) || payload.length,
     contentHash: frame.contentHash || '',
-    captureMs: Number(frame.captureMs || 0) || 0,
-    captureStageMs: Number(frame.captureStageMs || 0) || 0,
+    captureMs: frame.captureTimingAvailable === true && Number.isFinite(Number(frame.captureMs))
+      ? Number(frame.captureMs)
+      : null,
+    captureStageMs: frame.captureTimingAvailable === true && Number.isFinite(Number(frame.captureStageMs))
+      ? Number(frame.captureStageMs)
+      : null,
     convertMs: Number(frame.convertMs || 0) || 0,
     compressMs: Number(frame.compressMs || 0) || 0,
     captureSourceSerial: Number(frame.captureSourceSerial || 0) || 0,
@@ -2140,7 +2185,6 @@ function broadcastRemoteBinaryFrame(frameEvent) {
   const isMode5 = String(frame.frameMode || frame.mode || '').toLowerCase() === 'mode5-lzo-delta';
   const isKeyFrame = frame.isKeyFrame === true || String(frame.chunkType || '').toLowerCase() === 'key';
   const frameSeq = Number(frame.frameSeq || 0) || 0;
-  let sharedPacket = null;
   for (const client of targetClients) {
     if (client.readyState !== client.OPEN) {
       continue;
@@ -2157,7 +2201,8 @@ function broadcastRemoteBinaryFrame(frameEvent) {
       || Number(frame.monitorIndex || 0) !== expectedBinding.monitorIndex) {
       continue;
     }
-    if (!expectedBinding.readySent) {
+    const requiresReadyKeyFrame = String(expectedBinding.streamPurpose || '').toLowerCase() === 'control' && isH264;
+    if (!expectedBinding.readySent && (!requiresReadyKeyFrame || isKeyFrame)) {
       expectedBinding.readySent = sendJson(client, {
         type: 'RemoteFrameStreamReady',
         deviceId,
@@ -2179,13 +2224,18 @@ function broadcastRemoteBinaryFrame(frameEvent) {
       client.liveDeskFrameBackpressureDrops = Number(client.liveDeskFrameBackpressureDrops || 0) + 1;
       continue;
     }
-    sharedPacket ||= buildRemoteFrameBinaryPacket(frameEvent);
-    if (!sharedPacket) {
+    const packet = buildRemoteFrameBinaryPacket(frameEvent, {
+      hubClientDropped: lane.dropped,
+      hubClientQueueDepth: lane.queue.length,
+      hubClientQueueLimit: frameClientQueueLimit(client),
+      hubClientBufferedBytes: Number(client.bufferedAmount || 0) || 0
+    });
+    if (!packet) {
       continue;
     }
-    enqueueFramePacketForClient(client, sharedPacket, { deviceId, frameSeq, isH264, isMode5, isKeyFrame });
-  }
-}
+    enqueueFramePacketForClient(client, packet, { deviceId, frameSeq, isH264, isMode5, isKeyFrame });
+  }
+}
 
 function broadcastRemoteBinaryAudio(audioEvent) {
   const deviceId = String(audioEvent?.deviceId || audioEvent?.frame?.deviceId || '').trim();
@@ -4016,12 +4066,26 @@ app.post('/api/remote/devices/:deviceId/live/start', requireHubFeatureAccess, (r
   res.json(remoteHub.startLiveStream(req.params.deviceId, req.body || {}));
 });
 
-app.post('/api/remote/devices/:deviceId/live/stop', (req, res) => {
-  noStore(res);
-  res.json(remoteHub.stopLiveStream(req.params.deviceId, req.body || {}));
-});
-
-app.post('/api/remote/devices/:deviceId/audio/start', requireHubFeatureAccess, (req, res) => {
+app.post('/api/remote/devices/:deviceId/live/stop', (req, res) => {
+  noStore(res);
+  res.json(remoteHub.stopLiveStream(req.params.deviceId, req.body || {}));
+});
+
+app.post('/api/remote/devices/:deviceId/live/pause', requireHubFeatureAccess, async (req, res, next) => {
+  noStore(res);
+  try {
+    res.json(await remoteHub.pauseLiveCapture(req.params.deviceId, req.body || {}));
+  } catch (error) {
+    next(error);
+  }
+});
+
+app.post('/api/remote/devices/:deviceId/live/resume', requireHubFeatureAccess, (req, res) => {
+  noStore(res);
+  res.json(remoteHub.resumeLiveCapture(req.params.deviceId, req.body || {}));
+});
+
+app.post('/api/remote/devices/:deviceId/audio/start', requireHubFeatureAccess, (req, res) => {
   noStore(res);
   res.json(remoteHub.startAudioStream(req.params.deviceId, req.body || {}));
 });
@@ -4185,9 +4249,10 @@ audioWss.on('connection', (ws, req) => {
   });
 });
 
-inputWss.on('connection', ws => {
-  inputClients.add(ws);
-  ws.liveDeskInputClientId = `riws-${++inputClientSeq}`;
+inputWss.on('connection', ws => {
+  inputClients.add(ws);
+  ws.liveDeskInputClientId = `riws-${++inputClientSeq}`;
+  ws.liveDeskInputDeviceIds = new Set();
   try {
     ws._socket?.setNoDelay?.(true);
   } catch {
@@ -4202,10 +4267,18 @@ inputWss.on('connection', ws => {
       return;
     }
     const deviceId = String(payload?.deviceId || '').trim();
-    const inputEventId = String(payload?.requestId || '').trim() || crypto.randomUUID();
+    const inputEventId = String(
+      payload?.input?.inputEventId
+      || payload?.inputEventId
+      || payload?.requestId
+      || ''
+    ).trim() || crypto.randomUUID();
     const input = payload?.input && typeof payload.input === 'object'
       ? { ...payload.input, inputEventId, hubConnectionId: ws.liveDeskInputClientId, hubReceivedAtEpochMs: Date.now() }
       : { ...payload, inputEventId, hubConnectionId: ws.liveDeskInputClientId, hubReceivedAtEpochMs: Date.now() };
+    if (deviceId) {
+      ws.liveDeskInputDeviceIds.add(deviceId);
+    }
     const result = remoteHub.sendInputControl(deviceId, input);
     const inputType = String(input?.type || '').toLowerCase();
     const fireAndForget = payload?.fireAndForget === true
@@ -4214,16 +4287,26 @@ inputWss.on('connection', ws => {
     if (fireAndForget && result?.ok) {
       return;
     }
-    sendJson(ws, {
-      type: result?.ok ? 'RemoteInputQueued' : 'RemoteInputError',
-      requestId: payload?.requestId || '',
-      deviceId,
-      result,
+    sendJson(ws, {
+      type: result?.ok ? 'RemoteInputQueued' : 'RemoteInputError',
+      requestId: payload?.requestId || '',
+      deviceId,
+      inputSeq: Number(input?.inputSeq || 0) || 0,
+      inputEventId: String(input?.inputEventId || ''),
+      hubConnectionId: ws.liveDeskInputClientId,
+      result,
       timestamp: new Date().toISOString()
     });
   });
-  ws.on('close', () => inputClients.delete(ws));
-  ws.on('error', () => inputClients.delete(ws));
+  const releaseBrowserInputOwner = reason => {
+    inputClients.delete(ws);
+    for (const deviceId of ws.liveDeskInputDeviceIds || []) {
+      remoteHub.releaseInputOwner(deviceId, ws.liveDeskInputClientId, reason);
+    }
+    ws.liveDeskInputDeviceIds?.clear?.();
+  };
+  ws.on('close', () => releaseBrowserInputOwner('browser-input-websocket-closed'));
+  ws.on('error', () => releaseBrowserInputOwner('browser-input-websocket-error'));
   sendJson(ws, {
     type: 'RemoteInputSocketReady',
     protocol: 'livedesk.remote.input.json.v1',

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

@@ -30,16 +30,16 @@ function sameEndpoint(left, right) {
     return !!left && !!right && String(left.address) === String(right.address) && Number(left.port) === Number(right.port);
 }
 
-export function createHubUdpTransport({ env = process.env, logEvent = () => {}, logWarn = () => {} } = {}) {
-    const enabled = isEnabled(env.LIVEDESK_UDP_ENABLED, false);
-    const preferP2p = isEnabled(env.LIVEDESK_UDP_PREFER_P2P, true);
+export function createHubUdpTransport({ env = process.env, logEvent = () => {}, logWarn = () => {} } = {}) {
+    const enabled = isEnabled(env.LIVEDESK_UDP_ENABLED, true);
+    const preferP2p = isEnabled(env.LIVEDESK_UDP_PREFER_P2P, false);
     const bindHost = safeText(env.LIVEDESK_UDP_BIND_HOST || '0.0.0.0', 128) || '0.0.0.0';
     const requestedPort = numberEnv(env.LIVEDESK_UDP_PORT, 0, 65535, 0);
     const advertiseHost = safeText(env.LIVEDESK_UDP_ADVERTISE_HOST || env.LIVEDESK_REMOTE_PUBLIC_HOST || '', 128);
-    const rendezvousHost = safeText(env.LIVEDESK_UDP_RENDEZVOUS_HOST || '', 128);
+    const rendezvousHost = safeText(env.LIVEDESK_UDP_RENDEZVOUS_HOST || 'www.gnsoftech.com', 128);
     const rendezvousPort = numberEnv(env.LIVEDESK_UDP_RENDEZVOUS_PORT, 1, 65535, 5199);
     const punchTimeoutMs = numberEnv(env.LIVEDESK_UDP_PUNCH_TIMEOUT_MS, 500, 10_000, 3000);
-    const frameTimeoutMs = numberEnv(env.LIVEDESK_UDP_FRAME_TIMEOUT_MS, 20, 2000, 80);
+    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');
@@ -146,15 +146,23 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
             return;
         }
         if (packet.type !== 'frame') return;
-        const complete = session.reassembler.ingest(packet);
-        if (!complete) return;
-        session.framesReceived += 1;
-        frameHandler({
-            deviceId: session.deviceId,
-            sessionId: session.sessionId,
-            header: complete.header,
-            payload: complete.payload,
-            transport: 'udp-p2p'
+        const complete = session.reassembler.ingest(packet);
+        if (!complete) return;
+        session.framesReceived += 1;
+        const reassembly = session.reassembler.getStats();
+        frameHandler({
+            deviceId: session.deviceId,
+            sessionId: session.sessionId,
+            header: {
+                ...complete.header,
+                hubIngressDropped: Math.max(
+                    Number(complete.header?.hubIngressDropped || 0) || 0,
+                    reassembly.droppedFrames
+                ),
+                udpIncompleteFrames: reassembly.droppedFrames
+            },
+            payload: complete.payload,
+            transport: 'udp-p2p'
         });
         sendPacket(session, 'pong', {
             state: 'frame-ack',
@@ -171,10 +179,16 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
             socket.once('error', onError);
             socket.once('listening', onListening);
             socket.bind(requestedPort, bindHost);
-        });
-        started = true;
-        boundPort = socket.address().port;
-        logEvent('udp', `UDP P2P socket listening on udp://${bindHost}:${boundPort}`);
+        });
+        started = true;
+        boundPort = socket.address().port;
+        try {
+            socket.setRecvBufferSize(8 * 1024 * 1024);
+            socket.setSendBufferSize(1024 * 1024);
+        } catch (error) {
+            logWarn('udp', `UDP socket buffer tuning was unavailable: ${error?.message || error}`);
+        }
+        logEvent('udp', `UDP P2P socket listening on udp://${bindHost}:${boundPort}`);
         return getStatus();
     }
 
@@ -240,9 +254,10 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
             state: session.ready ? 'udp-ready' : 'udp-session-created',
             ready: session.ready,
             sessionId: session.sessionId,
-            lastPacketAt: session.lastPacketAt ? new Date(session.lastPacketAt).toISOString() : '',
-            framesReceived: session.framesReceived
-        };
+            lastPacketAt: session.lastPacketAt ? new Date(session.lastPacketAt).toISOString() : '',
+            framesReceived: session.framesReceived,
+            ...session.reassembler.getStats()
+        };
     }
 
     async function close() {

package/src/transport/udp-protocol.js

@@ -1,4 +1,5 @@
-import crypto from 'node:crypto';
+import crypto from 'node:crypto';
+import { inflateRawSync } from 'node:zlib';
 
 export const UDP_P2P_PROTOCOL = 'livedesk.udp.p2p.v1';
 export const UDP_P2P_VERSION = 1;
@@ -17,8 +18,10 @@ 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_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_MAX_FRAME_HEADER_BYTES = 64 * 1024;
 
 function asBuffer(value) {
     if (Buffer.isBuffer(value)) return value;
@@ -32,13 +35,53 @@ function normalizeKey(key) {
     return value.length === 32 ? value : crypto.createHash('sha256').update(value).digest();
 }
 
-function normalizeSessionId(value) {
+function normalizeSessionId(value) {
     const sessionId = String(value || '').trim();
     if (!sessionId || Buffer.byteLength(sessionId, 'utf8') > UDP_MAX_SESSION_ID_BYTES) {
         throw new Error('invalid-udp-session-id');
     }
     return sessionId;
-}
+}
+
+function decodeFrameHeader(header) {
+    if (header?.frameHeader && typeof header.frameHeader === 'object') {
+        return header.frameHeader;
+    }
+    const encoded = String(header?.frameHeaderDeflate || '');
+    if (!encoded || encoded.length > 8192 || !/^[A-Za-z0-9+/]+={0,2}$/.test(encoded)) {
+        return null;
+    }
+    try {
+        const json = inflateRawSync(Buffer.from(encoded, 'base64'), { maxOutputLength: 64 * 1024 }).toString('utf8');
+        const value = JSON.parse(json);
+        return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+    } catch {
+        return null;
+    }
+}
+
+function decodeFramedPayload(payload, legacyHeader = null) {
+    const bytes = asBuffer(payload);
+    if (bytes.length < 8 || !bytes.subarray(0, 4).equals(UDP_FRAME_PAYLOAD_MAGIC)) {
+        return { header: legacyHeader || {}, payload: bytes };
+    }
+    const compressedHeaderLength = bytes.readUInt32BE(4);
+    if (compressedHeaderLength < 1 || compressedHeaderLength > UDP_MAX_FRAME_HEADER_BYTES
+        || 8 + compressedHeaderLength > bytes.length) return null;
+    try {
+        const json = inflateRawSync(bytes.subarray(8, 8 + compressedHeaderLength), {
+            maxOutputLength: UDP_MAX_FRAME_HEADER_BYTES
+        }).toString('utf8');
+        const header = JSON.parse(json);
+        if (!header || typeof header !== 'object' || Array.isArray(header)) return null;
+        return {
+            header,
+            payload: bytes.subarray(8 + compressedHeaderLength)
+        };
+    } catch {
+        return null;
+    }
+}
 
 function packetTypeCode(type) {
     const code = typeof type === 'number' ? type : UDP_PACKET_TYPES[String(type || '').toLowerCase()];
@@ -147,12 +190,15 @@ export class UdpReplayWindow {
     }
 }
 
-export class UdpFrameReassembler {
-    constructor({ maxPending = 2, timeoutMs = 80, maxFrameBytes = 8 * 1024 * 1024 } = {}) {
-        this.maxPending = Math.max(1, Math.min(16, Math.floor(Number(maxPending) || 2)));
-        this.timeoutMs = Math.max(20, Math.min(2000, Math.floor(Number(timeoutMs) || 80)));
-        this.maxFrameBytes = Math.max(64 * 1024, Math.min(16 * 1024 * 1024, Math.floor(Number(maxFrameBytes) || 8 * 1024 * 1024)));
-        this.pending = new Map();
+export class UdpFrameReassembler {
+    constructor({ maxPending = 2, timeoutMs = 500, maxFrameBytes = 8 * 1024 * 1024 } = {}) {
+        this.maxPending = Math.max(1, Math.min(16, Math.floor(Number(maxPending) || 2)));
+        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.droppedFrames = 0;
+        this.expiredFrames = 0;
+        this.evictedFrames = 0;
     }
 
     ingest(packet, now = Date.now()) {
@@ -166,11 +212,14 @@ export class UdpFrameReassembler {
             || 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;
-                this.pending.delete(oldest);
-            }
+            while (this.pending.size >= this.maxPending) {
+                const oldest = this.pending.keys().next().value;
+                if (oldest === undefined) break;
+                if (this.pending.delete(oldest)) {
+                    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);
         }
@@ -179,26 +228,47 @@ export class UdpFrameReassembler {
         state.chunks[chunkIndex] = payload;
         state.received += 1;
         state.totalBytes += payload.length;
-        if (header.frameHeader && typeof header.frameHeader === 'object') state.frameHeader = header.frameHeader;
-        if (state.totalBytes > this.maxFrameBytes) {
-            this.pending.delete(frameId);
-            return null;
-        }
-        if (state.received !== state.chunkCount) return null;
-        this.pending.delete(frameId);
-        return {
-            frameId,
-            header: state.frameHeader || header.frameHeader || {},
-            payload: Buffer.concat(state.chunks, state.totalBytes)
-        };
-    }
+        const decodedFrameHeader = decodeFrameHeader(header);
+        if (decodedFrameHeader) state.frameHeader = decodedFrameHeader;
+        if (state.totalBytes > this.maxFrameBytes) {
+            if (this.pending.delete(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),
+            state.frameHeader || header.frameHeader || {}
+        );
+        if (!complete) {
+            this.droppedFrames += 1;
+            return null;
+        }
+        return {
+            frameId,
+            header: complete.header,
+            payload: complete.payload
+        };
+    }
 
-    expire(now = Date.now()) {
-        for (const [frameId, state] of this.pending) {
-            if (now - state.createdAt > this.timeoutMs) this.pending.delete(frameId);
-        }
-    }
-}
+    expire(now = Date.now()) {
+        for (const [frameId, state] of this.pending) {
+            if (now - state.createdAt > this.timeoutMs && this.pending.delete(frameId)) {
+                this.droppedFrames += 1;
+                this.expiredFrames += 1;
+            }
+        }
+    }
+
+    getStats() {
+        return {
+            pendingFrames: this.pending.size,
+            droppedFrames: this.droppedFrames,
+            expiredFrames: this.expiredFrames,
+            evictedFrames: this.evictedFrames
+        };
+    }
+}
 
 export function encodeRendezvousMessage(message) {
     const payload = Buffer.from(JSON.stringify(message && typeof message === 'object' ? message : {}), 'utf8');