@livedesk/hub 0.1.57 → 0.1.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/hub",
-  "version": "0.1.57",
+  "version": "0.1.58",
   "description": "VuvoDesk local Hub API and browser frame bridge",
   "type": "module",
   "main": "src/server.js",
@@ -11,12 +11,12 @@
   "scripts": {
     "dev": "node src/server.js",
     "start": "node src/server.js",
-    "check": "node --check src/server.js && node --check src/remote-hub.js && node --check src/remote-clipboard-contract.mjs && node --check src/console-direct.js",
+    "check": "node --check src/server.js && node --check src/remote-hub.js && node --check src/remote-clipboard-contract.mjs && node --check src/console-direct.js",
     "prepublishOnly": "node ../../scripts/livedesk-release-git-gate.mjs"
   },
   "dependencies": {
     "@ffmpeg-installer/ffmpeg": "^1.1.0",
-    "@livedesk/runtime-core": "0.1.8",
+    "@livedesk/runtime-core": "0.1.8",
     "@openai/codex-sdk": "0.145.0",
     "cors": "^2.8.5",
     "express": "^4.21.2",

package/src/console-direct.js

@@ -34,6 +34,8 @@ const ICE_CONNECT_TIMEOUT_MS = 10_000;
 const PEER_DISCONNECTED_TIMEOUT_MS = 5_000;
 const ACCESS_TOKEN_TIMEOUT_MS = 8_000;
 const SIGNAL_READY_TIMEOUT_MS = 10_000;
+const SIGNAL_HEARTBEAT_INTERVAL_MS = 15_000;
+const SIGNAL_HEARTBEAT_TIMEOUT_MS = 10_000;
 const CONTROL_ASSEMBLY_TIMEOUT_MS = 15_000;
 const MEDIA_ASSEMBLY_TIMEOUT_MS = 500;
 const LOGICAL_BIND_TIMEOUT_MS = 5_000;
@@ -302,6 +304,20 @@ export function createHubConsoleDirect(options = {}) {
     1,
     Number(options.signalReadyTimeoutMs) || SIGNAL_READY_TIMEOUT_MS
   );
+  const signalHeartbeatIntervalMs = Math.max(
+    1,
+    Number(options.signalHeartbeatIntervalMs) || SIGNAL_HEARTBEAT_INTERVAL_MS
+  );
+  const signalHeartbeatTimeoutMs = Math.max(
+    1,
+    Number(options.signalHeartbeatTimeoutMs) || SIGNAL_HEARTBEAT_TIMEOUT_MS
+  );
+  const scheduleSignalHeartbeatTimer = typeof options.scheduleSignalHeartbeatTimer === 'function'
+    ? options.scheduleSignalHeartbeatTimer
+    : setTimeout;
+  const cancelSignalHeartbeatTimer = typeof options.cancelSignalHeartbeatTimer === 'function'
+    ? options.cancelSignalHeartbeatTimer
+    : clearTimeout;
   const mediaAssemblyTimeoutMs = Math.max(
     1,
     Number(options.mediaAssemblyTimeoutMs) || MEDIA_ASSEMBLY_TIMEOUT_MS
@@ -317,6 +333,7 @@ export function createHubConsoleDirect(options = {}) {
   let retryTimer = null;
   let accessTokenAttempt = null;
   let signalReadyDeadline = null;
+  let signalHeartbeat = null;
   let retryAttempt = 0;
   let retryNotBeforeAt = 0;
   let nextRetryAt = '';
@@ -1174,6 +1191,7 @@ export function createHubConsoleDirect(options = {}) {
       retryAttempt = 0;
       retryNotBeforeAt = 0;
       nextRetryAt = '';
+      armSignalHeartbeat(ownerSignalGeneration, socket, connect);
       return;
     }
     const consoleId = String(payload.consoleId || '');
@@ -1284,6 +1302,114 @@ export function createHubConsoleDirect(options = {}) {
     signalReadyDeadline = deadline;
   };
 
+  const clearSignalHeartbeat = (ownerSignalGeneration, socket) => {
+    const heartbeat = signalHeartbeat;
+    if (!heartbeat
+      || (ownerSignalGeneration !== undefined && heartbeat.generation !== ownerSignalGeneration)
+      || (socket !== undefined && heartbeat.socket !== socket)) {
+      return false;
+    }
+    signalHeartbeat = null;
+    cancelSignalHeartbeatTimer(heartbeat.timer);
+    return true;
+  };
+
+  const failSignalHeartbeat = (heartbeat, connect, reason) => {
+    if (signalHeartbeat !== heartbeat
+      || stopped
+      || heartbeat.generation !== signalGeneration
+      || signalSocket !== heartbeat.socket) {
+      return;
+    }
+    clearSignalHeartbeat(heartbeat.generation, heartbeat.socket);
+    signalSocket = null;
+    lastHttpStatus = 0;
+    lastError = reason;
+    retireNegotiatingPeers(reason);
+    try { heartbeat.socket.terminate?.(); } catch {}
+    scheduleReconnect(connect);
+  };
+
+  const scheduleSignalHeartbeatPing = (heartbeat, connect) => {
+    if (signalHeartbeat !== heartbeat
+      || stopped
+      || heartbeat.generation !== signalGeneration
+      || signalSocket !== heartbeat.socket) {
+      return;
+    }
+    heartbeat.awaitingPong = false;
+    let pingTimer = null;
+    pingTimer = scheduleSignalHeartbeatTimer(() => {
+      if (signalHeartbeat !== heartbeat
+        || heartbeat.timer !== pingTimer
+        || stopped
+        || heartbeat.generation !== signalGeneration
+        || signalSocket !== heartbeat.socket) {
+        return;
+      }
+      heartbeat.awaitingPong = true;
+      let timeoutTimer = null;
+      timeoutTimer = scheduleSignalHeartbeatTimer(() => {
+        if (signalHeartbeat !== heartbeat
+          || heartbeat.timer !== timeoutTimer
+          || !heartbeat.awaitingPong
+          || stopped
+          || heartbeat.generation !== signalGeneration
+          || signalSocket !== heartbeat.socket) {
+          return;
+        }
+        failSignalHeartbeat(
+          heartbeat,
+          connect,
+          'console-direct-signal-heartbeat-timeout'
+        );
+      }, signalHeartbeatTimeoutMs);
+      heartbeat.timer = timeoutTimer;
+      heartbeat.timer.unref?.();
+      try {
+        if (heartbeat.socket.readyState !== WebSocket.OPEN
+          || typeof heartbeat.socket.ping !== 'function') {
+          throw new Error('console-direct-signal-heartbeat-unavailable');
+        }
+        heartbeat.socket.ping();
+      } catch {
+        failSignalHeartbeat(
+          heartbeat,
+          connect,
+          'console-direct-signal-heartbeat-failed'
+        );
+      }
+    }, signalHeartbeatIntervalMs);
+    heartbeat.timer = pingTimer;
+    heartbeat.timer.unref?.();
+  };
+
+  const armSignalHeartbeat = (ownerSignalGeneration, socket, connect) => {
+    clearSignalHeartbeat();
+    const heartbeat = {
+      generation: ownerSignalGeneration,
+      socket,
+      timer: null,
+      awaitingPong: false
+    };
+    signalHeartbeat = heartbeat;
+    scheduleSignalHeartbeatPing(heartbeat, connect);
+  };
+
+  const acceptSignalHeartbeatPong = (ownerSignalGeneration, socket, connect) => {
+    const heartbeat = signalHeartbeat;
+    if (!heartbeat
+      || heartbeat.generation !== ownerSignalGeneration
+      || heartbeat.socket !== socket
+      || !heartbeat.awaitingPong) {
+      return false;
+    }
+    cancelSignalHeartbeatTimer(heartbeat.timer);
+    heartbeat.timer = null;
+    scheduleSignalHeartbeatPing(heartbeat, connect);
+    return true;
+  };
+
   const scheduleReconnect = connect => {
     if (stopped || retryTimer || !(signalUrl instanceof URL)) return;
     const sequenceDelay = retryDelaysMs[Math.min(retryAttempt, retryDelaysMs.length - 1)];
@@ -1374,12 +1500,16 @@ export function createHubConsoleDirect(options = {}) {
         handleSignalMessage(raw, ownerSignalGeneration, socket);
       }
     });
+    socket.on('pong', () => {
+      acceptSignalHeartbeatPong(ownerSignalGeneration, socket, connect);
+    });
     socket.once('close', () => {
       const wasOwner = signalSocket === socket
         && ownerSignalGeneration === signalGeneration
         && !stopped;
       if (signalSocket === socket) signalSocket = null;
       clearSignalReadyDeadline(ownerSignalGeneration, socket);
+      clearSignalHeartbeat(ownerSignalGeneration, socket);
       if (!wasOwner) return;
       retireNegotiatingPeers('console-direct-signaling-closed');
       if (!retryTimer) state = 'disconnected';
@@ -1393,6 +1523,7 @@ export function createHubConsoleDirect(options = {}) {
       }
       signalSocket = null;
       clearSignalReadyDeadline(ownerSignalGeneration, socket);
+      clearSignalHeartbeat(ownerSignalGeneration, socket);
       retireNegotiatingPeers('console-direct-signaling-error');
       try { socket.terminate?.(); } catch {}
       scheduleReconnect(connect);
@@ -1413,6 +1544,7 @@ export function createHubConsoleDirect(options = {}) {
     signalGeneration += 1;
     cancelAccessTokenAttempt();
     clearSignalReadyDeadline();
+    clearSignalHeartbeat();
     if (retryTimer) clearTimeout(retryTimer);
     retryTimer = null;
     retryAttempt = 0;
@@ -1431,6 +1563,7 @@ export function createHubConsoleDirect(options = {}) {
     signalGeneration += 1;
     cancelAccessTokenAttempt();
     clearSignalReadyDeadline();
+    clearSignalHeartbeat();
     if (retryTimer) clearTimeout(retryTimer);
     retryTimer = null;
     nextRetryAt = '';
@@ -1472,6 +1605,7 @@ export function createHubConsoleDirect(options = {}) {
     const reconnectTimerActive = Boolean(retryTimer);
     const accessTokenDeadlineActive = Boolean(accessTokenAttempt);
     const signalReadyDeadlineActive = Boolean(signalReadyDeadline);
+    const signalHeartbeatTimerActive = Boolean(signalHeartbeat?.timer);
     return Object.freeze({
       enabled: signalUrl instanceof URL && Boolean(deviceId),
       state,
@@ -1491,6 +1625,8 @@ export function createHubConsoleDirect(options = {}) {
       reconnectTimerActive,
       accessTokenDeadlineActive,
       signalReadyDeadlineActive,
+      signalHeartbeatTimerActive,
+      signalHeartbeatAwaitingPong: signalHeartbeat?.awaitingPong === true,
       resourceTimers: iceConnectTimers
         + peerDisconnectTimers
         + assemblyDeadlineTimers
@@ -1498,7 +1634,8 @@ export function createHubConsoleDirect(options = {}) {
         + pendingLogicalControlRequests
         + Number(reconnectTimerActive)
         + Number(accessTokenDeadlineActive)
-        + Number(signalReadyDeadlineActive),
+        + Number(signalReadyDeadlineActive)
+        + Number(signalHeartbeatTimerActive),
       rejectedRelayCandidates,
       dataChannelBackpressureCloses,
       malformedWireCloses,
@@ -1530,6 +1667,8 @@ export const consoleDirectContract = Object.freeze({
   maxDefaultRetryDelayMs: DEFAULT_RETRY_DELAYS_MS.at(-1),
   accessTokenTimeoutMs: ACCESS_TOKEN_TIMEOUT_MS,
   signalReadyTimeoutMs: SIGNAL_READY_TIMEOUT_MS,
+  signalHeartbeatIntervalMs: SIGNAL_HEARTBEAT_INTERVAL_MS,
+  signalHeartbeatTimeoutMs: SIGNAL_HEARTBEAT_TIMEOUT_MS,
   logicalBindTimeoutMs: LOGICAL_BIND_TIMEOUT_MS,
   iceConnectTimeoutMs: ICE_CONNECT_TIMEOUT_MS,
   peerDisconnectedTimeoutMs: PEER_DISCONNECTED_TIMEOUT_MS,

package/src/console-direct.test.mjs

@@ -13,6 +13,8 @@ assert.equal(consoleDirectContract.maxDefaultRetryDelayMs, 20_000);
 assert.equal(consoleDirectContract.peerDisconnectedTimeoutMs, 5_000);
 assert.equal(consoleDirectContract.maxPendingMediaWireMessages, 8);
 assert.equal(consoleDirectContract.reliableAssemblyTimeoutMs, 15_000);
+assert.equal(consoleDirectContract.signalHeartbeatIntervalMs, 15_000);
+assert.equal(consoleDirectContract.signalHeartbeatTimeoutMs, 10_000);
 
 const HUB_EPOCH = '11111111-1111-4111-8111-111111111111';
 const HUB_EPOCH_TWO = '77777777-7777-4777-8777-777777777777';
@@ -38,6 +40,7 @@ class FakeSocket extends EventEmitter {
     this.sent = [];
     this.closeCode = 0;
     this.closeReason = '';
+    this.pingCount = 0;
     this.constructor.instances.push(this);
   }
 
@@ -55,6 +58,15 @@ class FakeSocket extends EventEmitter {
     this.emit('message', value, binary);
   }
 
+  ping() {
+    if (this.readyState !== FakeSocket.OPEN) throw new Error('fake-socket-not-open');
+    this.pingCount += 1;
+  }
+
+  pong() {
+    this.emit('pong');
+  }
+
   close(code = 1000, reason = '') {
     if (this.readyState === FakeSocket.CLOSED) return;
     this.closeCode = code;
@@ -222,6 +234,18 @@ async function connectedDirect(options = {}) {
       ? { peerDisconnectedTimeoutMs: options.peerDisconnectedTimeoutMs }
       : {}),
     ...(options.mediaAssemblyTimeoutMs ? { mediaAssemblyTimeoutMs: options.mediaAssemblyTimeoutMs } : {}),
+    ...(options.signalHeartbeatIntervalMs
+      ? { signalHeartbeatIntervalMs: options.signalHeartbeatIntervalMs }
+      : {}),
+    ...(options.signalHeartbeatTimeoutMs
+      ? { signalHeartbeatTimeoutMs: options.signalHeartbeatTimeoutMs }
+      : {}),
+    ...(options.scheduleSignalHeartbeatTimer
+      ? { scheduleSignalHeartbeatTimer: options.scheduleSignalHeartbeatTimer }
+      : {}),
+    ...(options.cancelSignalHeartbeatTimer
+      ? { cancelSignalHeartbeatTimer: options.cancelSignalHeartbeatTimer }
+      : {}),
     fetchImpl: options.fetchImpl || (async () => new Response('{}', {
       status: 200,
       headers: { 'Content-Type': 'application/json' }
@@ -319,6 +343,89 @@ test('a signaling reconnect preserves a healthy direct peer until the Hub epoch
   direct.close();
 });
 
+test('a silent half-open signaling socket is replaced while a healthy direct peer stays alive', async () => {
+  const { direct, signal } = await connectedDirect({
+    retryDelaysMs: [0],
+    signalHeartbeatIntervalMs: 5,
+    signalHeartbeatTimeoutMs: 20
+  });
+  const peer = offer(signal);
+  const control = new FakeDataChannel('livedesk-control-v1');
+  peer.emitDataChannel(control);
+  control.open();
+
+  assert.equal(direct.inspect().signalHeartbeatTimerActive, true);
+  await waitFor(() => signal.pingCount === 1);
+  assert.equal(direct.inspect().signalHeartbeatAwaitingPong, true);
+  await waitFor(() => FakeSignalSocket.instances.length === 2);
+
+  const replacementSignal = FakeSignalSocket.instances[1];
+  assert.equal(signal.readyState, FakeSignalSocket.CLOSED);
+  assert.equal(peer.closed, false);
+  assert.equal(direct.inspect().peerConnections, 1);
+  assert.equal(direct.inspect().lastError, 'console-direct-signal-heartbeat-timeout');
+  replacementSignal.open();
+  replacementSignal.receive(JSON.stringify({
+    type: 'signal-ready',
+    role: 'hub',
+    deviceId: 'hub-device',
+    hubEpoch: HUB_EPOCH
+  }), false);
+  assert.equal(peer.closed, false);
+  assert.equal(direct.inspect().signalHeartbeatTimerActive, true);
+
+  await waitFor(() => replacementSignal.pingCount === 1);
+  replacementSignal.pong();
+  assert.equal(direct.inspect().signalHeartbeatAwaitingPong, false);
+  assert.equal(direct.inspect().signalHeartbeatTimerActive, true);
+  direct.close();
+  assert.equal(direct.inspect().signalHeartbeatTimerActive, false);
+  assert.equal(direct.inspect().resourceTimers, 0);
+});
+
+test('a cancelled heartbeat timeout cannot retire a healthy signal after pong re-arms it', async () => {
+  let nextTimerId = 0;
+  const callbacks = new Map();
+  const cancelledTimers = new Set();
+  const { direct, signal } = await connectedDirect({
+    scheduleSignalHeartbeatTimer(callback) {
+      const timerId = ++nextTimerId;
+      callbacks.set(timerId, callback);
+      return timerId;
+    },
+    cancelSignalHeartbeatTimer(timerId) {
+      cancelledTimers.add(timerId);
+    }
+  });
+  const peer = offer(signal);
+  const control = new FakeDataChannel('livedesk-control-v1');
+  peer.emitDataChannel(control);
+  control.open();
+
+  assert.equal(nextTimerId, 1);
+  callbacks.get(1)();
+  assert.equal(signal.pingCount, 1);
+  assert.equal(direct.inspect().signalHeartbeatAwaitingPong, true);
+  assert.equal(nextTimerId, 2);
+
+  signal.pong();
+  assert.equal(cancelledTimers.has(2), true);
+  assert.equal(nextTimerId, 3);
+  assert.equal(direct.inspect().signalHeartbeatAwaitingPong, false);
+
+  callbacks.get(2)();
+  assert.equal(signal.readyState, FakeSignalSocket.OPEN);
+  assert.equal(FakeSignalSocket.instances.length, 1);
+  assert.equal(peer.closed, false);
+  assert.equal(direct.inspect().peerConnections, 1);
+  assert.equal(direct.inspect().signalHeartbeatTimerActive, true);
+  assert.equal(direct.inspect().signalHeartbeatAwaitingPong, false);
+
+  direct.close();
+  assert.equal(cancelledTimers.has(3), true);
+  assert.equal(direct.inspect().resourceTimers, 0);
+});
+
 test('a same-account token refresh reconnects signaling without dropping a healthy direct peer', async () => {
   const { direct, signal } = await connectedDirect();
   const peer = offer(signal);
@@ -812,8 +919,10 @@ test('a transient disconnected state recovers or retires the exact peer on one b
   assert.equal(peer.closed, true);
   assert.equal(direct.inspect().peerConnections, 0);
   assert.equal(direct.inspect().peerDisconnectTimers, 0);
-  assert.equal(direct.inspect().resourceTimers, 0);
+  assert.equal(direct.inspect().signalHeartbeatTimerActive, true);
+  assert.equal(direct.inspect().resourceTimers, 1);
   direct.close();
+  assert.equal(direct.inspect().resourceTimers, 0);
 });
 
 test('an oversized local frame closes only its logical media lane', async () => {
@@ -851,8 +960,11 @@ test('an unopened control channel cannot suppress the bounded ICE owner timeout'
   await new Promise(resolve => setTimeout(resolve, 15));
   assert.equal(peer.closed, true);
   assert.equal(direct.inspect().peerConnections, 0);
-  assert.equal(direct.inspect().resourceTimers, 0);
+  assert.equal(direct.inspect().iceConnectTimers, 0);
+  assert.equal(direct.inspect().signalHeartbeatTimerActive, true);
+  assert.equal(direct.inspect().resourceTimers, 1);
   direct.close();
+  assert.equal(direct.inspect().resourceTimers, 0);
 });
 
 test('an incomplete partial-reliable media message owns one deadline and close returns terminal zero', async () => {