livedesk 0.1.283 → 0.1.285

package/hub/src/remote-hub.js

@@ -960,8 +960,9 @@ function serializeDevice(device, options = {}) {
                 byteLength: device.latestAudioFrame.byteLength
             }
             : null,
-        latestAudioStatus: device.latestAudioStatus ? { ...device.latestAudioStatus } : null,
-        latestTask: device.latestTask ? { ...device.latestTask } : null,
+        latestAudioStatus: device.latestAudioStatus ? { ...device.latestAudioStatus } : null,
+        udp: device.udp ? { ...device.udp } : { enabled: false, state: 'tcp-only', ready: false },
+        latestTask: device.latestTask ? { ...device.latestTask } : null,
         synthetic: device.synthetic === true,
         recentTasks: Array.isArray(device.recentTasks)
             ? device.recentTasks.map(task => ({ ...task }))
@@ -1395,6 +1396,9 @@ export function createRemoteHub(options = {}) {
     const getWelcomeDevicePolicy = typeof options.getWelcomeDevicePolicy === 'function'
         ? options.getWelcomeDevicePolicy
         : getEffectiveDevicePolicy;
+    const udpTransport = options.udpTransport && typeof options.udpTransport === 'object'
+        ? options.udpTransport
+        : null;
 
     function getDevicePolicy(device) {
         try {
@@ -1746,7 +1750,7 @@ export function createRemoteHub(options = {}) {
         };
     }
 
-    function getStatus({ includeSecrets = false } = {}) {
+    function getStatus({ includeSecrets = false } = {}) {
         const connectedDevices = [...devices.values()].filter(device => device.connected).length;
         const activeHostTarget = serializeHostTarget();
         const routeInfo = getAgentEndpointRouteInfo();
@@ -1791,10 +1795,18 @@ export function createRemoteHub(options = {}) {
             hostTargetExpiresAt: activeHostTarget.expiresAt,
             publicIPv4Address: publicIPv4Cache.address,
             publicIPv4UpdatedAt: publicIPv4Cache.updatedAt ? new Date(publicIPv4Cache.updatedAt).toISOString() : '',
-            publicIPv4Error: publicIPv4Cache.error,
-            externalExposure: isWildcardHost(host) || !isLoopbackHost(host),
-            lastError
-        };
+            publicIPv4Error: publicIPv4Cache.error,
+            udp: udpTransport?.getStatus?.() || {
+                enabled: false,
+                preferred: false,
+                started: false,
+                port: 0,
+                sessionCount: 0,
+                readySessionCount: 0
+            },
+            externalExposure: isWildcardHost(host) || !isLoopbackHost(host),
+            lastError
+        };
     }
 
     function rotatePairingPin() {
@@ -2650,9 +2662,15 @@ export function createRemoteHub(options = {}) {
             },
             activeLiveStream: null,
             activeAudioStream: null,
-            latestAudioFrame: null,
-            latestAudioStatus: null,
-            latestTask: null,
+            latestAudioFrame: null,
+            latestAudioStatus: null,
+            udp: {
+                enabled: capabilities.udpP2p === true,
+                state: 'tcp-only',
+                ready: false,
+                sessionId: ''
+            },
+            latestTask: null,
             recentTasks: [],
             pendingTaskCommands: new Map(),
             pendingTaskTimers: new Map(),
@@ -2662,7 +2680,7 @@ export function createRemoteHub(options = {}) {
 
         devices.set(deviceId, device);
         sockets.set(socket, deviceId);
-        writeJsonLine(socket, {
+        writeJsonLine(socket, {
             type: 'welcome',
             protocol: REMOTE_AGENT_PROTOCOL,
             protocolVersion: REMOTE_PROTOCOL_VERSION,
@@ -2672,8 +2690,22 @@ export function createRemoteHub(options = {}) {
             frameProtocol: buildRemoteFrameProtocolDescriptor(),
             frameModes: getSupportedRemoteFrameModeProfiles(),
             effectivePolicy: getWelcomeDevicePolicy({ deviceId, capabilities }),
-            serverTime: now
-        });
+            serverTime: now
+        });
+
+        const udpSession = udpTransport?.registerDevice?.({
+            deviceId,
+            sessionId,
+            sendControl: payload => writeJsonLine(socket, payload),
+            capabilities
+        });
+        if (udpSession?.sessionId) {
+            device.udp = {
+                ...device.udp,
+                state: 'udp-session-created',
+                sessionId: udpSession.sessionId
+            };
+        }
 
         logEvent('remote', `device connected ${device.deviceName} (${deviceId})`, 'success');
         emitRemoteEvent('RemoteDeviceConnected', device);
@@ -2812,8 +2844,9 @@ export function createRemoteHub(options = {}) {
             return;
         }
 
-        device.connected = false;
-        device.socket = null;
+        device.connected = false;
+        device.socket = null;
+        udpTransport?.unregisterDevice?.(deviceId, device.sessionId);
         closeInputSocket(device, reason);
         closeFrameSocket(device, reason);
         device.disconnectedAt = new Date().toISOString();
@@ -3687,7 +3720,7 @@ export function createRemoteHub(options = {}) {
         return true;
     }
 
-    function handleAgentBinaryFrame(socket, state, header, framePayload) {
+    function handleAgentBinaryFrame(socket, state, header, framePayload) {
         if (!state.authenticated || !state.device) {
             writeJsonLine(socket, { type: 'error', error: 'hello-required' });
             socket.destroy();
@@ -3734,11 +3767,37 @@ export function createRemoteHub(options = {}) {
             return;
         }
 
-        emitRemoteEvent('RemoteAgentMessageIgnored', device, {
-            messageType: safeString(header.type, 80),
-            frameKind
-        });
-    }
+        emitRemoteEvent('RemoteAgentMessageIgnored', device, {
+            messageType: safeString(header.type, 80),
+            frameKind
+        });
+    }
+
+    function handleUdpFrame({ deviceId, sessionId, header, payload } = {}) {
+        const device = devices.get(safeString(deviceId, 160));
+        if (!device || !device.connected) {
+            return false;
+        }
+        if (device.udp?.sessionId && device.udp.sessionId !== safeString(sessionId, 160)) {
+            return false;
+        }
+        const frameMode = safeString(header?.frameMode || header?.mode, 40).toLowerCase();
+        if (frameMode !== 'mode3-h264-hw') {
+            emitRemoteEvent('RemoteFrameDropped', device, { reason: 'udp-frame-mode-not-supported', transport: 'udp-p2p', frameMode });
+            return false;
+        }
+        device.udp = {
+            ...device.udp,
+            state: 'udp-active',
+            ready: true,
+            lastFrameAt: new Date().toISOString(),
+            framesReceived: Number(device.udp?.framesReceived || 0) + 1
+        };
+        return applyLiveFrame(device, {
+            ...header,
+            transport: 'udp-p2p'
+        }, payload, 'udp-p2p');
+    }
 
     function dropQueuedAgentBinaryFrame(state) {
         if (!Array.isArray(state.binaryQueue) || state.binaryQueue.length === 0) {
@@ -4399,13 +4458,14 @@ export function createRemoteHub(options = {}) {
         });
     }
 
-    async function start() {
+    async function start() {
         if (!enabled || started) {
             return getStatus({ includeSecrets: false });
         }
 
-        try {
-            await listenOnPort(requestedPort);
+        try {
+            await udpTransport?.start?.();
+            await listenOnPort(requestedPort);
         } catch (error) {
             if (error?.code === 'EADDRINUSE') {
                 const conflict = new Error(
@@ -4422,7 +4482,7 @@ export function createRemoteHub(options = {}) {
         return getStatus({ includeSecrets: false });
     }
 
-    async function close() {
+    async function close() {
         for (const device of devices.values()) {
             failAllPendingTasks(device, 'hub-shutdown');
             if (device.socket && !device.socket.destroyed) {
@@ -4437,8 +4497,9 @@ export function createRemoteHub(options = {}) {
             }
         }
 
-        sockets.clear();
-        if (!server) {
+        sockets.clear();
+        await udpTransport?.close?.();
+        if (!server) {
             started = false;
             return;
         }
@@ -5488,7 +5549,7 @@ export function createRemoteHub(options = {}) {
         });
     }
 
-    function getFramePayload(deviceId, frameKind, options = {}) {
+    function getFramePayload(deviceId, frameKind, options = {}) {
         const device = devices.get(String(deviceId || ''));
         if (!device) {
             return null;
@@ -5505,10 +5566,25 @@ export function createRemoteHub(options = {}) {
             payload: frame.payload,
             mimeType: safeString(frame.mimeType || frame.format || 'application/octet-stream', 120) || 'application/octet-stream',
             byteLength: frame.payload.length
-        };
-    }
-
-    return {
+        };
+    }
+
+    udpTransport?.setFrameHandler?.(handleUdpFrame);
+    udpTransport?.setEventHandler?.((type, event = {}) => {
+        const device = devices.get(safeString(event.deviceId, 160));
+        if (device?.udp) {
+            if (type === 'UdpSessionReady') {
+                device.udp = { ...device.udp, state: 'udp-ready', ready: true };
+            } else if (type === 'UdpSessionClosed') {
+                device.udp = { ...device.udp, state: 'tcp-fallback', ready: false };
+            }
+        }
+        if (device) {
+            emitRemoteEvent(`Remote${type}`, device, { ...event });
+        }
+    });
+
+    return {
         start,
         close,
         getStatus,
@@ -5534,8 +5610,9 @@ export function createRemoteHub(options = {}) {
         stopAudioStream,
         getDeviceLiveFrame,
         getDeviceThumbnail,
-        getFramePayload,
-        seedSyntheticFleet,
+        getFramePayload,
+        handleUdpFrame,
+        seedSyntheticFleet,
         clearSyntheticFleet,
         getPairToken: () => pairToken,
         getPairingPin: () => pairingPin

package/hub/src/server.js

@@ -27,6 +27,7 @@ import { effectiveDevicePolicy } from './settings/settings-schema.js';
 import { buildEffectiveDevicePolicy } from './settings/effective-device-policy.js';
 import { CaptureStore } from './captures/capture-store.js';
 import { createLiveDeskUpdateManager } from './live-desk-update.js';
+import { createHubUdpTransport } from './transport/udp-hub-transport.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const webDistCandidates = [
@@ -250,14 +251,21 @@ void liveDeskSettingsStore.getRecord().catch(error => {
   console.warn(`[LiveDesk Hub] settings load failed: ${error instanceof Error ? error.message : String(error)}`);
 });
 
+const udpTransport = createHubUdpTransport({
+  env: process.env,
+  logEvent: (_scope, message) => console.log(`[LiveDesk Hub] ${message}`),
+  logWarn: (_scope, message) => console.warn(`[LiveDesk Hub] ${message}`)
+});
+
 const remoteHub = createRemoteHub({
   managerPackage: '@livedesk/hub',
   managerVersion: packageInfo.version,
-  env: {
+  env: {
     ...process.env,
     MINDEXEC_MANAGER_PACKAGE: '@livedesk/hub',
     MINDEXEC_MANAGER_VERSION: packageInfo.version
-  },
+  },
+  udpTransport,
   logEvent: (_scope, message) => console.log(`[LiveDesk Hub] ${message}`),
   logWarn: (_scope, message) => console.warn(`[LiveDesk Hub] ${message}`),
   emitEvent: handleRemoteHubEvent,

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

@@ -0,0 +1,281 @@
+import crypto from 'node:crypto';
+import dgram from 'node:dgram';
+import {
+    UDP_MAX_DATAGRAM_BYTES,
+    UDP_P2P_PROTOCOL,
+    UdpFrameReassembler,
+    UdpReplayWindow,
+    decodeRendezvousMessage,
+    decodeUdpPacket,
+    encodeRendezvousMessage,
+    encodeUdpPacket,
+    createUdpSessionKey
+} from './udp-protocol.js';
+
+function isEnabled(value, fallback = false) {
+    if (value === undefined || value === null || value === '') return fallback;
+    return /^(1|true|yes|on)$/i.test(String(value).trim());
+}
+
+function safeText(value, max = 160) {
+    return String(value || '').replace(/[\r\n\t]/g, ' ').trim().slice(0, max);
+}
+
+function numberEnv(value, min, max, fallback) {
+    const number = Number(value);
+    return Number.isFinite(number) ? Math.max(min, Math.min(max, Math.floor(number))) : fallback;
+}
+
+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);
+    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 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 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();
+    let frameHandler = () => {};
+    let eventHandler = () => {};
+    let started = false;
+    let boundPort = requestedPort;
+    let sequence = crypto.randomInt(1, 0x7fffffff);
+
+    function emit(type, event = {}) {
+        eventHandler(type, event);
+        if (trace) logEvent('udp', `${type} ${JSON.stringify({ deviceId: event.deviceId || '', state: event.state || '', reason: event.reason || '' })}`);
+    }
+
+    function nextSequence() {
+        sequence = (sequence + 1) >>> 0;
+        return sequence;
+    }
+
+    function sendPacket(session, type, header = {}, payload = Buffer.alloc(0), address = session.peerEndpoint || session.clientEndpoint) {
+        if (!address || !session) return false;
+        let packet;
+        try {
+            packet = encodeUdpPacket({ type, sessionId: session.sessionId, key: session.key, sequence: nextSequence(), header, payload });
+        } catch (error) {
+            logWarn('udp', `UDP packet rejected device=${session.deviceId}: ${error?.message || error}`);
+            return false;
+        }
+        socket.send(packet, address.port, address.address);
+        return true;
+    }
+
+    function sendRendezvousRegister(session) {
+        if (!rendezvousHost) return;
+        const message = encodeRendezvousMessage({
+            type: 'rendezvous.register',
+            protocol: UDP_P2P_PROTOCOL,
+            roomId: session.sessionId,
+            role: 'hub',
+            token: session.rendezvousToken
+        });
+        socket.send(message, rendezvousPort, rendezvousHost);
+    }
+
+    function sessionForPacket(packet, rinfo) {
+        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');
+        const session = [...sessions.values()].find(item => item.sessionId === sessionId);
+        if (!session) return null;
+        if (!session.clientEndpoint) session.clientEndpoint = { address: rinfo.address, port: rinfo.port };
+        if (!sameEndpoint(session.clientEndpoint, rinfo)) return null;
+        return session;
+    }
+
+    function onRendezvousPeer(message, rinfo) {
+        const session = [...sessions.values()].find(item => item.sessionId === safeText(message.roomId, 160));
+        if (!session || !rendezvousHost || rinfo.address !== rendezvousHost) return;
+        const address = safeText(message.host, 128);
+        const port = Number(message.port);
+        if (!address || !Number.isInteger(port) || port < 1 || port > 65535) return;
+        session.peerEndpoint = { address, port };
+        session.lastPeerAt = Date.now();
+        sendPacket(session, 'probe', { punch: true }, Buffer.alloc(0), 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);
+            return;
+        }
+        const session = sessionForPacket(payload, rinfo);
+        if (!session) return;
+        const packet = decodeUdpPacket(payload, session.key);
+        if (!packet || packet.sessionId !== session.sessionId || !session.replay.accept(packet.sequence)) return;
+        session.lastPacketAt = Date.now();
+        if (packet.type === 'probe') {
+            session.clientEndpoint = { address: rinfo.address, port: rinfo.port };
+            sendPacket(session, 'probe-ack', { observedHost: rinfo.address, observedPort: rinfo.port });
+            emit('UdpProbeReceived', { deviceId: session.deviceId });
+            return;
+        }
+        if (packet.type === 'ready') {
+            session.ready = true;
+            session.clientEndpoint = { address: rinfo.address, port: rinfo.port };
+            sendPacket(session, 'pong', { state: 'ready' });
+            session.sendControl?.({
+                type: 'udp.session.ready',
+                protocol: UDP_P2P_PROTOCOL,
+                sessionId: session.sessionId,
+                transport: 'udp-p2p',
+                ready: true,
+                endpoint: { host: advertiseHost, port: boundPort }
+            });
+            emit('UdpSessionReady', { deviceId: session.deviceId, state: 'udp-ready' });
+            return;
+        }
+        if (packet.type === 'ping') {
+            sendPacket(session, 'pong', { now: Date.now() });
+            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'
+        });
+        sendPacket(session, 'pong', {
+            state: 'frame-ack',
+            frameSeq: Number(complete.header?.frameSeq || 0) || 0
+        });
+    });
+    socket.on('error', error => logWarn('udp', `UDP socket error: ${error?.message || error}`));
+
+    async function start() {
+        if (!enabled || started) return getStatus();
+        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(requestedPort, bindHost);
+        });
+        started = true;
+        boundPort = socket.address().port;
+        logEvent('udp', `UDP P2P socket listening on udp://${bindHost}:${boundPort}`);
+        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 = {
+            deviceId: id,
+            tcpSessionId: safeText(tcpSessionId, 160),
+            sessionId: crypto.randomUUID(),
+            key,
+            keyBase64: key.toString('base64'),
+            rendezvousToken: crypto.randomBytes(16).toString('hex'),
+            sendControl,
+            clientEndpoint: null,
+            peerEndpoint: null,
+            replay: new UdpReplayWindow(),
+            reassembler: new UdpFrameReassembler({ maxPending: maxPendingFrames, timeoutMs: frameTimeoutMs }),
+            ready: false,
+            createdAt: Date.now(),
+            lastPacketAt: 0,
+            framesReceived: 0
+        };
+        sessions.set(id, session);
+        sendControl?.({
+            type: 'udp.session.offer',
+            protocol: UDP_P2P_PROTOCOL,
+            sessionId: session.sessionId,
+            key: session.keyBase64,
+            host: advertiseHost,
+            port: boundPort,
+            expiresInMs: punchTimeoutMs + 15_000,
+            punchTimeoutMs,
+            maxDatagramBytes: UDP_MAX_DATAGRAM_BYTES,
+            frameTimeoutMs,
+            maxPendingFrames,
+            rendezvous: rendezvousHost
+                ? { host: rendezvousHost, port: rendezvousPort, roomId: session.sessionId, token: session.rendezvousToken }
+                : null
+        });
+        sendRendezvousRegister(session);
+        emit('UdpSessionCreated', { deviceId: id, state: 'udp-session-created' });
+        return { sessionId: session.sessionId, ready: false };
+    }
+
+    function unregisterDevice(deviceId, tcpSessionId = '') {
+        const id = safeText(deviceId, 160);
+        const session = sessions.get(id);
+        if (!session || (tcpSessionId && session.tcpSessionId !== tcpSessionId)) return;
+        sessions.delete(id);
+        emit('UdpSessionClosed', { deviceId: id, reason: 'tcp-session-closed' });
+    }
+
+    function getDeviceStatus(deviceId) {
+        const session = sessions.get(safeText(deviceId, 160));
+        if (!session) return { enabled, state: enabled ? 'disabled' : 'tcp-only', ready: false };
+        return {
+            enabled,
+            preferred: preferP2p,
+            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
+        };
+    }
+
+    async function close() {
+        sessions.clear();
+        if (!started) return;
+        await new Promise(resolve => socket.close(() => resolve()));
+        started = false;
+    }
+
+    return {
+        start,
+        close,
+        registerDevice,
+        unregisterDevice,
+        getDeviceStatus,
+        getStatus,
+        setFrameHandler: handler => { frameHandler = typeof handler === 'function' ? handler : () => {}; },
+        setEventHandler: handler => { eventHandler = typeof handler === 'function' ? handler : () => {}; }
+    };
+
+    function getStatus() {
+        return {
+            enabled,
+            preferred: preferP2p,
+            started,
+            bindHost,
+            port: boundPort,
+            advertiseHost,
+            rendezvousHost,
+            rendezvousPort,
+            maxDatagramBytes: UDP_MAX_DATAGRAM_BYTES,
+            sessionCount: sessions.size,
+            readySessionCount: [...sessions.values()].filter(session => session.ready).length
+        };
+    }
+}