@livedesk/hub 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/hub",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "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

@@ -2070,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-hub-transport.js

@@ -1,5 +1,6 @@
-import crypto from 'node:crypto';
-import dgram from 'node:dgram';
+import crypto from 'node:crypto';
+import { lookup } from 'node:dns/promises';
+import dgram from 'node:dgram';
 import {
     UDP_MAX_DATAGRAM_BYTES,
     UDP_P2P_PROTOCOL,
@@ -26,10 +27,15 @@ function numberEnv(value, min, max, fallback) {
     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);
-}
-
+function sameEndpoint(left, right) {
+    return !!left && !!right && String(left.address) === String(right.address) && Number(left.port) === Number(right.port);
+}
+
+function normalizedAddress(value) {
+    const address = safeText(value, 128).toLowerCase();
+    return address.startsWith('::ffff:') ? address.slice(7) : address;
+}
+
 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);
@@ -37,7 +43,8 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
     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 || 'www.gnsoftech.com', 128);
-    const rendezvousPort = numberEnv(env.LIVEDESK_UDP_RENDEZVOUS_PORT, 1, 65535, 5199);
+    const rendezvousPort = numberEnv(env.LIVEDESK_UDP_RENDEZVOUS_PORT, 1, 65535, 5199);
+    const rendezvousRefreshMs = numberEnv(env.LIVEDESK_UDP_RENDEZVOUS_REFRESH_MS, 1000, 50_000, 25_000);
     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);
@@ -46,9 +53,12 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
     const sessions = new Map();
     let frameHandler = () => {};
     let eventHandler = () => {};
-    let started = false;
-    let boundPort = requestedPort;
-    let sequence = crypto.randomInt(1, 0x7fffffff);
+    let started = false;
+    let boundPort = requestedPort;
+    let sequence = crypto.randomInt(1, 0x7fffffff);
+    let rendezvousAddresses = new Set();
+    let rendezvousRefreshTimer = null;
+    let rendezvousRefreshPromise = null;
 
     function emit(type, event = {}) {
         eventHandler(type, event);
@@ -60,8 +70,8 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
         return sequence;
     }
 
-    function sendPacket(session, type, header = {}, payload = Buffer.alloc(0), address = session.peerEndpoint || session.clientEndpoint) {
-        if (!address || !session) return false;
+    function sendPacket(session, type, header = {}, payload = Buffer.alloc(0), address = session.clientEndpoint || session.peerEndpoint) {
+        if (!address || !session) return false;
         let packet;
         try {
             packet = encodeUdpPacket({ type, sessionId: session.sessionId, key: session.key, sequence: nextSequence(), header, payload });
@@ -73,34 +83,105 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
         return true;
     }
 
-    function sendRendezvousRegister(session) {
-        if (!rendezvousHost) return;
-        const message = encodeRendezvousMessage({
-            type: 'rendezvous.register',
+    function sendRendezvousRegister(session) {
+        if (!rendezvousHost || rendezvousAddresses.size === 0 || !started) return false;
+        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 || Number(rinfo.port) !== rendezvousPort) return;
-        const address = safeText(message.host, 128);
+            role: 'hub',
+            token: session.rendezvousToken
+        });
+        let sent = false;
+        for (const address of rendezvousAddresses) {
+            try {
+                socket.send(message, rendezvousPort, address, error => {
+                    if (error) logWarn('udp', `UDP rendezvous registration failed: ${error?.message || error}`);
+                });
+                sent = true;
+            } catch (error) {
+                logWarn('udp', `UDP rendezvous registration failed: ${error?.message || error}`);
+            }
+        }
+        return sent;
+    }
+
+    async function resolveRendezvousAddresses() {
+        if (!rendezvousHost) return false;
+        try {
+            const records = await lookup(rendezvousHost, { all: true, family: 4, verbatim: true });
+            const resolved = new Set(records.map(record => normalizedAddress(record.address)).filter(Boolean));
+            if (resolved.size === 0) throw new Error('no-ipv4-address');
+            rendezvousAddresses = resolved;
+            return true;
+        } catch (error) {
+            logWarn('udp', `UDP rendezvous host resolution failed: ${error?.message || error}`);
+            return false;
+        }
+    }
+
+    function refreshRendezvousRegistrations(reason = 'periodic') {
+        if (!started || !rendezvousHost) return Promise.resolve(false);
+        if (rendezvousRefreshPromise) return rendezvousRefreshPromise;
+        rendezvousRefreshPromise = (async () => {
+            await resolveRendezvousAddresses();
+            if (!started) return false;
+            let refreshed = false;
+            for (const session of sessions.values()) {
+                refreshed = sendRendezvousRegister(session) || refreshed;
+            }
+            if (trace && refreshed) emit('UdpRendezvousRegistrationRefreshed', { reason });
+            return refreshed;
+        })().finally(() => {
+            rendezvousRefreshPromise = null;
+        });
+        return rendezvousRefreshPromise;
+    }
+
+    function startRendezvousRefreshTimer() {
+        if (!rendezvousHost || rendezvousRefreshTimer) return;
+        rendezvousRefreshTimer = setInterval(() => {
+            void refreshRendezvousRegistrations('periodic');
+        }, rendezvousRefreshMs);
+        rendezvousRefreshTimer.unref?.();
+    }
+
+    function stopRendezvousRefreshTimer() {
+        if (rendezvousRefreshTimer) clearInterval(rendezvousRefreshTimer);
+        rendezvousRefreshTimer = 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;
+    }
+
+    function bindAuthenticatedClientEndpoint(session, rinfo) {
+        const endpoint = { address: rinfo.address, port: rinfo.port };
+        if (sameEndpoint(session.clientEndpoint, endpoint)) return false;
+        session.clientEndpoint = endpoint;
+        session.lastPeerAt = Date.now();
+        sendRendezvousRegister(session);
+        void refreshRendezvousRegistrations('authenticated-endpoint-change');
+        emit('UdpAuthenticatedEndpointObserved', {
+            deviceId: session.deviceId,
+            endpoint: `${endpoint.address}:${endpoint.port}`
+        });
+        return true;
+    }
+
+    function onRendezvousPeer(message, rinfo) {
+        const session = [...sessions.values()].find(item => item.sessionId === 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);
         if (!address || !Number.isInteger(port) || port < 1 || port > 65535) return;
         session.peerEndpoint = { address, port };
@@ -112,24 +193,23 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
     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 });
+            onRendezvousPeer(rendezvous, rinfo);
+            return;
+        }
+        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;
+        bindAuthenticatedClientEndpoint(session, rinfo);
+        session.lastPacketAt = Date.now();
+        if (packet.type === 'probe') {
+            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' });
+        if (packet.type === 'ready') {
+            session.ready = true;
+            sendPacket(session, 'pong', { state: 'ready' });
             session.sendControl?.({
                 type: 'udp.session.ready',
                 protocol: UDP_P2P_PROTOCOL,
@@ -189,7 +269,9 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
             logWarn('udp', `UDP socket buffer tuning was unavailable: ${error?.message || error}`);
         }
         logEvent('udp', `UDP P2P socket listening on udp://${bindHost}:${boundPort}`);
-        return getStatus();
+        void refreshRendezvousRegistrations('startup');
+        startRendezvousRefreshTimer();
+        return getStatus();
     }
 
     function registerDevice({ deviceId, sessionId: tcpSessionId, sendControl, capabilities } = {}) {
@@ -260,11 +342,12 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
         };
     }
 
-    async function close() {
-        sessions.clear();
-        if (!started) return;
-        await new Promise(resolve => socket.close(() => resolve()));
-        started = false;
+    async function close() {
+        stopRendezvousRefreshTimer();
+        sessions.clear();
+        if (!started) return;
+        started = false;
+        await new Promise(resolve => socket.close(() => resolve()));
     }
 
     return {
@@ -286,8 +369,10 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
             bindHost,
             port: boundPort,
             advertiseHost,
-            rendezvousHost,
-            rendezvousPort,
+            rendezvousHost,
+            rendezvousPort,
+            rendezvousRefreshMs,
+            rendezvousResolvedAddressCount: rendezvousAddresses.size,
             maxDatagramBytes: UDP_MAX_DATAGRAM_BYTES,
             sessionCount: sessions.size,
             readySessionCount: [...sessions.values()].filter(session => session.ready).length

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')
+    };
+}