@livedesk/hub 0.1.10 → 0.1.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/hub",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "LiveDesk local Hub API and browser frame bridge",
   "type": "module",
   "main": "src/server.js",

package/src/remote-hub.js

@@ -3881,6 +3881,9 @@ export function createRemoteHub(options = {}) {
             nativeEncodableFrameCount: Number.isFinite(Number(message.nativeEncodableFrameCount)) ? Number(message.nativeEncodableFrameCount) : 0,
             nativeSkippedFrameCount: Number.isFinite(Number(message.nativeSkippedFrameCount)) ? Number(message.nativeSkippedFrameCount) : 0,
             nativeEncodedFrameCount: Number.isFinite(Number(message.nativeEncodedFrameCount)) ? Number(message.nativeEncodedFrameCount) : 0,
+            nativeEncodeFramesInFlight: Number.isFinite(Number(message.nativeEncodeFramesInFlight)) ? Number(message.nativeEncodeFramesInFlight) : 0,
+            nativeBackpressureSkippedFrameCount: Number.isFinite(Number(message.nativeBackpressureSkippedFrameCount)) ? Number(message.nativeBackpressureSkippedFrameCount) : 0,
+            nativeIdleSkippedFrameCount: Number.isFinite(Number(message.nativeIdleSkippedFrameCount)) ? Number(message.nativeIdleSkippedFrameCount) : 0,
             nativeCaptureTelemetryAt: safeString(message.nativeCaptureTelemetryAt, 80),
             droppedByAgent: Number.isFinite(Number(message.droppedByAgent)) ? Number(message.droppedByAgent) : 0,
             hardwareEncoder: safeString(message.hardwareEncoder, 80),
@@ -4258,6 +4261,9 @@ export function createRemoteHub(options = {}) {
             nativeEncodableFrameCount: Number.isFinite(Number(message.nativeEncodableFrameCount)) ? Number(message.nativeEncodableFrameCount) : 0,
             nativeSkippedFrameCount: Number.isFinite(Number(message.nativeSkippedFrameCount)) ? Number(message.nativeSkippedFrameCount) : 0,
             nativeEncodedFrameCount: Number.isFinite(Number(message.nativeEncodedFrameCount)) ? Number(message.nativeEncodedFrameCount) : 0,
+            nativeEncodeFramesInFlight: Number.isFinite(Number(message.nativeEncodeFramesInFlight)) ? Number(message.nativeEncodeFramesInFlight) : 0,
+            nativeBackpressureSkippedFrameCount: Number.isFinite(Number(message.nativeBackpressureSkippedFrameCount)) ? Number(message.nativeBackpressureSkippedFrameCount) : 0,
+            nativeIdleSkippedFrameCount: Number.isFinite(Number(message.nativeIdleSkippedFrameCount)) ? Number(message.nativeIdleSkippedFrameCount) : 0,
             nativeCaptureTelemetryAt: safeString(message.nativeCaptureTelemetryAt, 80),
             droppedByAgent: Number.isFinite(Number(message.droppedByAgent)) ? Number(message.droppedByAgent) : 0,
             hubIngressDropped: Number.isFinite(Number(message.hubIngressDropped)) ? Number(message.hubIngressDropped) : 0,

package/src/server.js

@@ -63,10 +63,11 @@ runtimeManager.emit('runtime.started', { role: runtimeRole, pid: process.pid });
 const frameBackpressureBytes = readPositiveIntegerEnv('LIVEDESK_FRAME_WS_BACKPRESSURE_BYTES', 8 * 1024 * 1024);
 // ScreenCaptureKit and the native Agent handoff can release two bounded
 // eight-frame batches together. Keep the Wall lane large enough to retain the
-// complete dependent H.264 burst; Control keeps its separate two-frame
-// low-latency lane below.
+// complete dependent H.264 burst. Control is normally a single target, but its
+// macOS Agent handoff can release eight dependent H.264 frames together; keep
+// that complete bounded burst instead of stalling until the next recovery key.
 const frameClientQueuePackets = readPositiveIntegerEnv('LIVEDESK_FRAME_WS_QUEUE_PACKETS', 16);
-const controlFrameClientQueuePackets = readPositiveIntegerEnv('LIVEDESK_CONTROL_FRAME_WS_QUEUE_PACKETS', 2);
+const controlFrameClientQueuePackets = readPositiveIntegerEnv('LIVEDESK_CONTROL_FRAME_WS_QUEUE_PACKETS', 8);
 const frameStreamStopGraceMs = readPositiveIntegerEnv('LIVEDESK_FRAME_STREAM_STOP_GRACE_MS', 1500);
 const mode5FrameBackpressureBytes = readPositiveIntegerEnv('LIVEDESK_MODE5_WS_BACKPRESSURE_BYTES', 2 * 1024 * 1024);
 const mode5FrameQueuePackets = readPositiveIntegerEnv('LIVEDESK_MODE5_WS_QUEUE_PACKETS', 2);
@@ -2069,6 +2070,9 @@ function buildRemoteFrameBinaryPacket(frameEvent, diagnostics = {}) {
     nativeEncodableFrameCount: Number(frame.nativeEncodableFrameCount || 0) || 0,
     nativeSkippedFrameCount: Number(frame.nativeSkippedFrameCount || 0) || 0,
     nativeEncodedFrameCount: Number(frame.nativeEncodedFrameCount || 0) || 0,
+    nativeEncodeFramesInFlight: Number(frame.nativeEncodeFramesInFlight || 0) || 0,
+    nativeBackpressureSkippedFrameCount: Number(frame.nativeBackpressureSkippedFrameCount || 0) || 0,
+    nativeIdleSkippedFrameCount: Number(frame.nativeIdleSkippedFrameCount || 0) || 0,
     nativeCaptureTelemetryAt: frame.nativeCaptureTelemetryAt || '',
     droppedByAgent: Number(frame.droppedByAgent || 0) || 0,
     hubIngressDropped: Number(frame.hubIngressDropped || 0) || 0,

package/src/transport/udp-rendezvous.js

@@ -1,78 +1,402 @@
-import dgram from 'node:dgram';
-import { decodeRendezvousMessage, encodeRendezvousMessage, UDP_MAX_DATAGRAM_BYTES } from './udp-protocol.js';
-
-function safeText(value, max = 160) {
-    return String(value || '').replace(/[\r\n\t]/g, ' ').trim().slice(0, max);
-}
-
-function normalizePort(value, fallback) {
-    const port = Number(value);
-    return Number.isInteger(port) && port >= 0 && port <= 65535 ? port : fallback;
-}
-
-export function createUdpRendezvousServer({ host = '0.0.0.0', port = 5199, log = () => {} } = {}) {
-    const socket = dgram.createSocket('udp4');
-    const rooms = new Map();
-    let started = false;
-    let boundPort = normalizePort(port, 5199);
-
-    function send(message, address, targetPort) {
-        const payload = encodeRendezvousMessage(message);
-        socket.send(payload, targetPort, address);
-    }
-
-    function onMessage(payload, rinfo) {
-        if (!Buffer.isBuffer(payload) || payload.length > UDP_MAX_DATAGRAM_BYTES) return;
-        const message = decodeRendezvousMessage(payload);
-        if (message?.type !== 'rendezvous.register') return;
-        const roomId = safeText(message.roomId, 160);
-        const role = safeText(message.role, 16).toLowerCase();
-        const token = safeText(message.token, 256);
-        if (!roomId || !token || !['hub', 'client'].includes(role)) return;
-        let room = rooms.get(roomId);
-        if (!room || room.token !== token || Date.now() - room.updatedAt > 60_000) {
-            room = { token, peers: new Map(), updatedAt: Date.now() };
-            rooms.set(roomId, room);
-        }
-        room.updatedAt = Date.now();
-        room.peers.set(role, { address: rinfo.address, port: rinfo.port });
-        const peers = [...room.peers.entries()];
-        if (peers.length < 2) return;
-        for (const [peerRole, peer] of peers) {
-            const other = peers.find(([candidateRole]) => candidateRole !== peerRole)?.[1];
-            if (!other) continue;
-            send({ type: 'rendezvous.peer', roomId, role: peerRole === 'hub' ? 'client' : 'hub', host: other.address, port: other.port }, peer.address, peer.port);
-        }
-    }
-
-    socket.on('message', onMessage);
-    socket.on('error', error => log(`UDP rendezvous error: ${error?.message || error}`));
-
-    async function start() {
-        if (started) return { host, port: boundPort };
-        await new Promise((resolve, reject) => {
-            const onError = error => { socket.off('listening', onListening); reject(error); };
-            const onListening = () => { socket.off('error', onError); resolve(); };
-            socket.once('error', onError);
-            socket.once('listening', onListening);
-            socket.bind(boundPort, host);
-        });
-        started = true;
-        boundPort = socket.address().port;
-        log(`UDP rendezvous listening on udp://${host}:${boundPort}`);
-        return { host, port: boundPort };
-    }
-
-    async function close() {
-        rooms.clear();
-        if (!started) return;
-        await new Promise(resolve => socket.close(() => resolve()));
-        started = false;
-    }
-
-    return {
-        start,
-        close,
-        getStatus: () => ({ started, host, port: boundPort, rooms: rooms.size })
-    };
-}
+import dgram from 'node:dgram';
+import {
+    decodeRendezvousMessage,
+    encodeRendezvousMessage,
+    UDP_MAX_DATAGRAM_BYTES,
+    UDP_P2P_PROTOCOL
+} from './udp-protocol.js';
+
+const DEFAULT_LIMITS = Object.freeze({
+    roomTtlMs: 60_000,
+    sourceTtlMs: 120_000,
+    sweepIntervalMs: 10_000,
+    statusIntervalMs: 60_000,
+    maxRooms: 4_096,
+    maxSources: 8_192,
+    maxRoomsPerSource: 128,
+    perSourceRate: 20,
+    perSourceBurst: 40,
+    globalRate: 1_000,
+    globalBurst: 2_000
+});
+
+function safeText(value, max = 160) {
+    return String(value || '').replace(/[\r\n\t]/g, ' ').trim().slice(0, max);
+}
+
+function normalizePort(value, fallback) {
+    const port = Number(value);
+    return Number.isInteger(port) && port >= 0 && port <= 65535 ? port : fallback;
+}
+
+function normalizeInteger(value, fallback, min = 1, max = Number.MAX_SAFE_INTEGER) {
+    const number = Number(value);
+    return Number.isInteger(number) && number >= min && number <= max ? number : fallback;
+}
+
+function normalizeRate(value, fallback) {
+    const number = Number(value);
+    return Number.isFinite(number) && number > 0 ? number : fallback;
+}
+
+function createTokenBucket(capacity, now) {
+    return { tokens: capacity, updatedAt: now };
+}
+
+function consumeToken(bucket, rate, capacity, now) {
+    const elapsedMs = Math.max(0, now - bucket.updatedAt);
+    bucket.tokens = Math.min(capacity, bucket.tokens + (elapsedMs / 1_000) * rate);
+    bucket.updatedAt = Math.max(bucket.updatedAt, now);
+    if (bucket.tokens < 1) return false;
+    bucket.tokens -= 1;
+    return true;
+}
+
+export function createUdpRendezvousServer({
+    host = '0.0.0.0',
+    port = 5199,
+    log = () => {},
+    version = 'dev',
+    now = () => Date.now(),
+    roomTtlMs = DEFAULT_LIMITS.roomTtlMs,
+    sourceTtlMs = DEFAULT_LIMITS.sourceTtlMs,
+    sweepIntervalMs = DEFAULT_LIMITS.sweepIntervalMs,
+    statusIntervalMs = DEFAULT_LIMITS.statusIntervalMs,
+    maxRooms = DEFAULT_LIMITS.maxRooms,
+    maxSources = DEFAULT_LIMITS.maxSources,
+    maxRoomsPerSource = DEFAULT_LIMITS.maxRoomsPerSource,
+    perSourceRate = DEFAULT_LIMITS.perSourceRate,
+    perSourceBurst = DEFAULT_LIMITS.perSourceBurst,
+    globalRate = DEFAULT_LIMITS.globalRate,
+    globalBurst = DEFAULT_LIMITS.globalBurst
+} = {}) {
+    const socket = dgram.createSocket('udp4');
+    const rooms = new Map();
+    const unpairedRooms = new Map();
+    const sources = new Map();
+    const evictableSources = new Map();
+    const limits = Object.freeze({
+        roomTtlMs: normalizeInteger(roomTtlMs, DEFAULT_LIMITS.roomTtlMs),
+        sourceTtlMs: normalizeInteger(sourceTtlMs, DEFAULT_LIMITS.sourceTtlMs),
+        sweepIntervalMs: normalizeInteger(sweepIntervalMs, DEFAULT_LIMITS.sweepIntervalMs),
+        statusIntervalMs: normalizeInteger(statusIntervalMs, DEFAULT_LIMITS.statusIntervalMs, 0),
+        maxRooms: normalizeInteger(maxRooms, DEFAULT_LIMITS.maxRooms),
+        maxSources: normalizeInteger(maxSources, DEFAULT_LIMITS.maxSources),
+        maxRoomsPerSource: normalizeInteger(maxRoomsPerSource, DEFAULT_LIMITS.maxRoomsPerSource),
+        perSourceRate: normalizeRate(perSourceRate, DEFAULT_LIMITS.perSourceRate),
+        perSourceBurst: normalizeRate(perSourceBurst, DEFAULT_LIMITS.perSourceBurst),
+        globalRate: normalizeRate(globalRate, DEFAULT_LIMITS.globalRate),
+        globalBurst: normalizeRate(globalBurst, DEFAULT_LIMITS.globalBurst)
+    });
+    const counters = {
+        receivedDatagrams: 0,
+        receivedBytes: 0,
+        acceptedRegistrations: 0,
+        peerNotifications: 0,
+        sentBytes: 0,
+        sendErrors: 0,
+        invalidDatagrams: 0,
+        oversizeDatagrams: 0,
+        globalRateDrops: 0,
+        sourceRateDrops: 0,
+        sourceCapacityDrops: 0,
+        sourceRoomLimitDrops: 0,
+        roomCapacityDrops: 0,
+        tokenMismatchDrops: 0,
+        expiredRooms: 0,
+        evictedRooms: 0,
+        expiredSources: 0,
+        evictedSources: 0,
+        sweeps: 0,
+        socketErrors: 0
+    };
+    const globalBucket = createTokenBucket(limits.globalBurst, now());
+    const serviceVersion = safeText(version, 64) || 'dev';
+    let started = false;
+    let closing = false;
+    let startedAt = 0;
+    let boundPort = normalizePort(port, 5199);
+    let sweepTimer = null;
+    let statusTimer = null;
+    let lastError = '';
+
+    function sourceKey(rinfo) {
+        return safeText(rinfo?.address, 128);
+    }
+
+    function deleteRoom(roomId, reason = '') {
+        const room = rooms.get(roomId);
+        if (!room) return false;
+        rooms.delete(roomId);
+        unpairedRooms.delete(roomId);
+        const owner = sources.get(room.ownerSource);
+        if (owner) {
+            owner.activeRooms = Math.max(0, owner.activeRooms - 1);
+            if (owner.activeRooms === 0) {
+                evictableSources.delete(owner.key);
+                evictableSources.set(owner.key, owner);
+            }
+        }
+        if (reason === 'expired') counters.expiredRooms += 1;
+        if (reason === 'capacity') counters.evictedRooms += 1;
+        return true;
+    }
+
+    function sweep(at = now()) {
+        for (const [roomId, room] of rooms) {
+            if (at - room.updatedAt >= limits.roomTtlMs) deleteRoom(roomId, 'expired');
+        }
+        for (const [key, source] of sources) {
+            if (source.activeRooms === 0 && at - source.lastSeenAt >= limits.sourceTtlMs) {
+                sources.delete(key);
+                evictableSources.delete(key);
+                counters.expiredSources += 1;
+            }
+        }
+        counters.sweeps += 1;
+        return getStatus();
+    }
+
+    function getOrCreateSource(rinfo, at) {
+        const key = sourceKey(rinfo);
+        if (!key) return null;
+        let source = sources.get(key);
+        if (!source) {
+            if (sources.size >= limits.maxSources) {
+                const oldestEvictableSource = evictableSources.keys().next().value;
+                if (!oldestEvictableSource) {
+                    counters.sourceCapacityDrops += 1;
+                    return null;
+                }
+                evictableSources.delete(oldestEvictableSource);
+                sources.delete(oldestEvictableSource);
+                counters.evictedSources += 1;
+            }
+            source = {
+                key,
+                bucket: createTokenBucket(limits.perSourceBurst, at),
+                lastSeenAt: at,
+                activeRooms: 0
+            };
+            sources.set(key, source);
+            evictableSources.set(key, source);
+        }
+        source.lastSeenAt = at;
+        if (source.activeRooms === 0) {
+            evictableSources.delete(key);
+            evictableSources.set(key, source);
+        }
+        if (!consumeToken(source.bucket, limits.perSourceRate, limits.perSourceBurst, at)) {
+            counters.sourceRateDrops += 1;
+            return null;
+        }
+        return source;
+    }
+
+    function send(message, address, targetPort) {
+        let payload;
+        try {
+            payload = encodeRendezvousMessage(message);
+        } catch (error) {
+            counters.sendErrors += 1;
+            lastError = safeText(error?.message || error, 240);
+            return;
+        }
+        counters.peerNotifications += 1;
+        counters.sentBytes += payload.length;
+        socket.send(payload, targetPort, address, error => {
+            if (!error) return;
+            counters.sendErrors += 1;
+            lastError = safeText(error?.message || error, 240);
+        });
+    }
+
+    function createRoom(roomId, token, source, at) {
+        if (source.activeRooms >= limits.maxRoomsPerSource) {
+            counters.sourceRoomLimitDrops += 1;
+            return null;
+        }
+        if (rooms.size >= limits.maxRooms) {
+            const oldestUnpairedRoomId = unpairedRooms.keys().next().value;
+            if (oldestUnpairedRoomId) {
+                deleteRoom(oldestUnpairedRoomId, 'capacity');
+            } else {
+                counters.roomCapacityDrops += 1;
+                return null;
+            }
+        }
+        const room = {
+            token,
+            ownerSource: source.key,
+            peers: new Map(),
+            createdAt: at,
+            updatedAt: at
+        };
+        rooms.set(roomId, room);
+        unpairedRooms.set(roomId, room);
+        source.activeRooms += 1;
+        evictableSources.delete(source.key);
+        return room;
+    }
+
+    function onMessage(payload, rinfo) {
+        const at = now();
+        counters.receivedDatagrams += 1;
+        counters.receivedBytes += Buffer.isBuffer(payload) ? payload.length : 0;
+        if (!Buffer.isBuffer(payload)) {
+            counters.invalidDatagrams += 1;
+            return;
+        }
+        if (payload.length > UDP_MAX_DATAGRAM_BYTES) {
+            counters.oversizeDatagrams += 1;
+            return;
+        }
+        if (!consumeToken(globalBucket, limits.globalRate, limits.globalBurst, at)) {
+            counters.globalRateDrops += 1;
+            return;
+        }
+        const source = getOrCreateSource(rinfo, at);
+        if (!source) return;
+        const message = decodeRendezvousMessage(payload);
+        if (message?.type !== 'rendezvous.register') {
+            counters.invalidDatagrams += 1;
+            return;
+        }
+        const roomId = safeText(message.roomId, 160);
+        const role = safeText(message.role, 16).toLowerCase();
+        const token = safeText(message.token, 256);
+        if (!roomId || !token || !['hub', 'client'].includes(role)) {
+            counters.invalidDatagrams += 1;
+            return;
+        }
+        let room = rooms.get(roomId);
+        if (room && at - room.updatedAt >= limits.roomTtlMs) {
+            deleteRoom(roomId, 'expired');
+            room = null;
+        }
+        if (room && room.token !== token) {
+            counters.tokenMismatchDrops += 1;
+            return;
+        }
+        if (!room) {
+            room = createRoom(roomId, token, source, at);
+            if (!room) return;
+        }
+        room.updatedAt = at;
+        room.peers.set(role, { address: rinfo.address, port: rinfo.port });
+        counters.acceptedRegistrations += 1;
+        if (room.peers.size < 2) {
+            unpairedRooms.delete(roomId);
+            unpairedRooms.set(roomId, room);
+            return;
+        }
+        unpairedRooms.delete(roomId);
+        const hub = room.peers.get('hub');
+        const client = room.peers.get('client');
+        if (!hub || !client) return;
+        send({
+            type: 'rendezvous.peer',
+            roomId,
+            role: 'client',
+            host: client.address,
+            port: client.port
+        }, hub.address, hub.port);
+        send({
+            type: 'rendezvous.peer',
+            roomId,
+            role: 'hub',
+            host: hub.address,
+            port: hub.port
+        }, client.address, client.port);
+    }
+
+    socket.on('message', onMessage);
+    socket.on('error', error => {
+        counters.socketErrors += 1;
+        lastError = safeText(error?.message || error, 240);
+        log(`UDP rendezvous error: ${lastError}`);
+    });
+
+    function getStatus() {
+        const current = now();
+        return {
+            service: 'livedesk-udp-rendezvous',
+            version: serviceVersion,
+            protocol: UDP_P2P_PROTOCOL,
+            healthy: started && !closing,
+            started,
+            host,
+            port: boundPort,
+            uptimeMs: startedAt ? Math.max(0, current - startedAt) : 0,
+            rooms: rooms.size,
+            pairedRooms: rooms.size - unpairedRooms.size,
+            unpairedRooms: unpairedRooms.size,
+            sources: sources.size,
+            evictableSources: evictableSources.size,
+            limits: { ...limits },
+            counters: { ...counters },
+            lastError
+        };
+    }
+
+    function logStatus(reason) {
+        log(`UDP rendezvous status ${JSON.stringify({ reason, ...getStatus() })}`);
+    }
+
+    function startTimers() {
+        sweepTimer = setInterval(() => sweep(), limits.sweepIntervalMs);
+        sweepTimer.unref?.();
+        if (limits.statusIntervalMs > 0) {
+            statusTimer = setInterval(() => logStatus('periodic'), limits.statusIntervalMs);
+            statusTimer.unref?.();
+        }
+    }
+
+    function stopTimers() {
+        if (sweepTimer) clearInterval(sweepTimer);
+        if (statusTimer) clearInterval(statusTimer);
+        sweepTimer = null;
+        statusTimer = null;
+    }
+
+    async function start() {
+        if (started) return { host, port: boundPort };
+        await new Promise((resolve, reject) => {
+            const onError = error => { socket.off('listening', onListening); reject(error); };
+            const onListening = () => { socket.off('error', onError); resolve(); };
+            socket.once('error', onError);
+            socket.once('listening', onListening);
+            socket.bind(boundPort, host);
+        });
+        started = true;
+        closing = false;
+        startedAt = now();
+        boundPort = socket.address().port;
+        startTimers();
+        log(`UDP rendezvous listening on udp://${host}:${boundPort} version=${serviceVersion}`);
+        log(`UDP rendezvous limits ${JSON.stringify(limits)}`);
+        return { host, port: boundPort };
+    }
+
+    async function close() {
+        closing = true;
+        stopTimers();
+        rooms.clear();
+        unpairedRooms.clear();
+        sources.clear();
+        evictableSources.clear();
+        if (started) {
+            await new Promise(resolve => socket.close(() => resolve()));
+            started = false;
+        }
+        closing = false;
+    }
+
+    return {
+        start,
+        close,
+        getStatus,
+        sweepNow: () => sweep(),
+        logStatus: (reason = 'requested') => logStatus(safeText(reason, 48) || 'requested')
+    };
+}