@livedesk/hub 0.1.70 → 0.1.71

package/package.json

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

package/src/console-direct-frame-admission.mjs

@@ -0,0 +1,80 @@
+export const CONSOLE_MEDIA_ADMISSION = Object.freeze({
+  laneBufferedBytes: 512 * 1024,
+  peerBufferedBytes: 1024 * 1024,
+  bufferedAgeMs: 120,
+  maxStreams: 64,
+  maxMetadataBytes: 64 * 1024
+});
+
+function h264Identity(packet) {
+  if (!Buffer.isBuffer(packet) || packet.length < 5) return null;
+  const size = packet.readUInt32BE(0);
+  if (size < 2 || size > CONSOLE_MEDIA_ADMISSION.maxMetadataBytes || 4 + size >= packet.length) return null;
+  let frame;
+  try { frame = JSON.parse(packet.toString('utf8', 4, 4 + size)); } catch { return null; }
+  if (frame?.frameMode !== 'mode3-h264-hw'
+    || !['wall', 'control'].includes(frame.streamPurpose)
+    || !Number.isSafeInteger(frame.captureGeneration) || frame.captureGeneration <= 0
+    || !Number.isSafeInteger(frame.monitorIndex) || frame.monitorIndex < 0
+    || !['deviceId', 'sessionId', 'streamId', 'commandId'].every(key => (
+      typeof frame[key] === 'string' && frame[key].length > 0 && frame[key].length <= 256
+    ))) return null;
+  return {
+    stream: JSON.stringify([frame.deviceId, frame.streamPurpose]),
+    owner: JSON.stringify([frame.sessionId, frame.streamId, frame.commandId, frame.captureGeneration, frame.monitorIndex]),
+    key: frame.isKeyFrame === true || frame.chunkType === 'key'
+  };
+}
+
+// This is send admission, not authentication or presentation authority. Those
+// exact binding gates still run at the Hub and browser. Retain no payload,
+// timer, task, or outbound queue; every decision precedes wire fragmentation.
+export function createConsoleFrameAdmission() {
+  const streams = new Map();
+  let bufferedSince = null;
+  let droppedFrames = 0;
+  let recoveredStreams = 0;
+  return {
+    admit(packet, { laneBufferedBytes, peerBufferedBytes, now }) {
+      const identity = h264Identity(packet);
+      if (!identity) return 'unmanaged';
+      let state = streams.get(identity.stream);
+      if (!state) {
+        if (streams.size >= CONSOLE_MEDIA_ADMISSION.maxStreams) return 'capacity';
+        state = { owner: identity.owner, awaitingKey: false };
+        streams.set(identity.stream, state);
+      } else if (state.owner !== identity.owner) {
+        state.owner = identity.owner;
+        state.awaitingKey = true;
+      }
+      if (laneBufferedBytes <= 0) bufferedSince = null;
+      else if (bufferedSince === null) bufferedSince = now;
+      const pressured = (laneBufferedBytes > 0 && (
+        laneBufferedBytes + packet.length > CONSOLE_MEDIA_ADMISSION.laneBufferedBytes
+        || now - bufferedSince >= CONSOLE_MEDIA_ADMISSION.bufferedAgeMs
+      )) || (peerBufferedBytes > 0
+        && peerBufferedBytes + packet.length > CONSOLE_MEDIA_ADMISSION.peerBufferedBytes);
+      if (pressured || (state.awaitingKey && !identity.key)) {
+        state.awaitingKey = true;
+        droppedFrames += 1;
+        return 'drop';
+      }
+      if (state.awaitingKey) recoveredStreams += 1;
+      state.awaitingKey = false;
+      return 'send';
+    },
+    inspect() {
+      return {
+        streamOwners: streams.size,
+        awaitingKeyStreams: [...streams.values()].filter(state => state.awaitingKey).length,
+        droppedFrames,
+        recoveredStreams,
+        retainedPayloadBytes: 0
+      };
+    },
+    clear() {
+      streams.clear();
+      bufferedSince = null;
+    }
+  };
+}

package/src/console-direct-frame-admission.test.mjs

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { CONSOLE_MEDIA_ADMISSION, createConsoleFrameAdmission } from './console-direct-frame-admission.mjs';
+import { buildImmutableRemoteFramePacket } from './frame-packet-contract.mjs';
+
+function packet({ key = false, device = 'a', generation = 1, monitor = 0, bytes = 1024 } = {}) {
+  return buildImmutableRemoteFramePacket({
+    deviceId: device, sessionId: 'session', streamId: 'stream', commandId: 'command',
+    captureGeneration: generation, monitorIndex: monitor, streamPurpose: 'wall',
+    frameMode: 'mode3-h264-hw', isKeyFrame: key
+  }, Buffer.alloc(bytes)).packet;
+}
+const empty = { laneBufferedBytes: 0, peerBufferedBytes: 0, now: 0 };
+
+test('a small persistent backlog is bounded by age without a timer or retained frame', () => {
+  const gate = createConsoleFrameAdmission();
+  assert.equal(gate.admit(packet({ key: true }), empty), 'send');
+  const pending = { laneBufferedBytes: 1024, peerBufferedBytes: 1024, now: 1 };
+  assert.equal(gate.admit(packet(), pending), 'send');
+  assert.equal(gate.admit(packet(), { ...pending, now: 1 + CONSOLE_MEDIA_ADMISSION.bufferedAgeMs }), 'drop');
+  assert.equal(gate.admit(packet(), { ...empty, now: 200 }), 'drop');
+  assert.equal(gate.admit(packet({ key: true }), { ...empty, now: 201 }), 'send');
+  assert.equal(gate.inspect().retainedPayloadBytes, 0);
+  assert.equal(gate.inspect().recoveredStreams, 1);
+  gate.clear();
+  assert.equal(gate.inspect().streamOwners, 0);
+  assert.equal(gate.inspect().awaitingKeyStreams, 0);
+});
+
+test('a pressured viewer cannot poison another viewer, device, or replacement binding', () => {
+  const phone = createConsoleFrameAdmission();
+  const desktop = createConsoleFrameAdmission();
+  const pressure = { ...empty, laneBufferedBytes: CONSOLE_MEDIA_ADMISSION.laneBufferedBytes, peerBufferedBytes: CONSOLE_MEDIA_ADMISSION.laneBufferedBytes };
+  assert.equal(phone.admit(packet(), pressure), 'drop');
+  assert.equal(desktop.admit(packet(), empty), 'send');
+  assert.equal(phone.admit(packet({ device: 'b', key: true }), empty), 'send');
+  assert.equal(phone.admit(packet(), empty), 'drop');
+  assert.equal(phone.admit(packet({ generation: 2, monitor: 1 }), empty), 'drop');
+  assert.equal(phone.admit(packet({ generation: 2, monitor: 1, key: true }), empty), 'send');
+  assert.equal(phone.inspect().awaitingKeyStreams, 0);
+});
+
+test('one complete key may exceed the soft watermark on an empty peer without admitting a second backlog', () => {
+  const gate = createConsoleFrameAdmission();
+  const key = packet({ key: true, bytes: 700 * 1024 });
+  assert.equal(gate.admit(key, empty), 'send');
+  assert.equal(gate.admit(key, { ...empty, laneBufferedBytes: key.length, peerBufferedBytes: key.length }), 'drop');
+  assert.equal(gate.admit(key, empty), 'send');
+  assert.equal(gate.admit(Buffer.from('legacy-binary'), empty), 'unmanaged');
+});
+
+test('a multiplexed lane has a fixed owner bound and releases it on close', () => {
+  const gate = createConsoleFrameAdmission();
+  for (let n = 0; n < CONSOLE_MEDIA_ADMISSION.maxStreams; n++) {
+    assert.equal(gate.admit(packet({ device: `device-${n}`, key: true }), empty), 'send');
+  }
+  assert.equal(gate.admit(packet({ device: 'overflow', key: true }), empty), 'capacity');
+  gate.clear();
+  assert.equal(gate.admit(packet({ device: 'replacement', key: true }), empty), 'send');
+});

package/src/console-direct.js

@@ -9,6 +9,7 @@ import {
   encodeDirectConsoleWireMessage
 } from '../../runtime-core/src/console-direct-wire.js';
 import { workspaceRoleCanControl, workspaceRoleCanRequest } from './auth/workspace-access.js';
+import { createConsoleFrameAdmission } from './console-direct-frame-admission.mjs';
 
 const DEFAULT_SIGNAL_URL = 'https://livedesk-wake.lovecrdm.workers.dev';
 const DEFAULT_STUN_URLS = Object.freeze(['stun:stun.cloudflare.com:3478']);
@@ -87,6 +88,34 @@ function byteLength(value) {
   return Buffer.byteLength(String(value || ''), 'utf8');
 }
 
+function optionalPeerMetric(peer, method) {
+  try {
+    const value = peer[method]?.();
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+  } catch { return null; }
+}
+
+function candidateAddressScope(value) {
+  if (typeof value !== 'string' || !value || value === '?') return 'unknown';
+  if (/^(127\.|::1$)/i.test(value)) return 'loopback';
+  if (/^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|169\.254\.|f[cd][0-9a-f]{2}:|fe80:)/i.test(value)) return 'private';
+  return 'public';
+}
+
+function inspectPeerPath(peer) {
+  try {
+    const pair = peer.getSelectedCandidatePair?.();
+    if (!pair?.local || !pair?.remote) return null;
+    return {
+      localType: String(pair.local.type || 'unknown').slice(0, 24),
+      remoteType: String(pair.remote.type || 'unknown').slice(0, 24),
+      localScope: candidateAddressScope(pair.local.address),
+      remoteScope: candidateAddressScope(pair.remote.address),
+      transport: String(pair.remote.transportType || 'unknown').slice(0, 24)
+    };
+  } catch { return null; }
+}
+
 function parseJson(value) {
   try {
     return JSON.parse(String(value || ''));
@@ -527,6 +556,7 @@ export function createHubConsoleDirect(options = {}) {
     disposePendingLogicalControl(owner, channelState.channelId);
     disposeAssemblerTimer(channelState);
     channelState.assembler.dispose();
+    channelState.frameAdmission?.clear();
     closeLocalSocket(
       owner,
       channelState,
@@ -667,6 +697,18 @@ export function createHubConsoleDirect(options = {}) {
 
   function sendWire(owner, channelState, kind, value, maxMessageBytes, options = {}) {
     if (!isOwnerActive(owner) || channelState.closed || !channelIsOpen(channelState.channel)) return false;
+    if (kind === 'binary' && channelState.frameAdmission && value.byteLength <= maxMessageBytes) {
+      const admission = channelState.frameAdmission.admit(value, {
+        laneBufferedBytes: channelBufferedAmount(channelState),
+        peerBufferedBytes: ownerBufferedAmount(owner),
+        now: performance.now()
+      });
+      if (admission === 'drop') return true;
+      if (admission === 'capacity') {
+        closeLogicalChannel(owner, channelState, { code: 1009, reason: 'console-direct-frame-owner-capacity' });
+        return false;
+      }
+    }
     let chunks;
     try {
       const messageId = channelState.nextSendMessageId >>> 0;
@@ -973,7 +1015,7 @@ export function createHubConsoleDirect(options = {}) {
     socket.on('message', (data, isBinary) => {
       if (!isOwnerActive(owner) || owner.channels.get(channelId) !== channelState || channelState.localSocket !== socket) return;
       const kind = isBinary ? 'binary' : 'text';
-      const value = isBinary ? new Uint8Array(Buffer.from(data)) : String(data);
+      const value = isBinary ? (Buffer.isBuffer(data) ? data : Buffer.from(data)) : String(data);
       if (!sendWire(owner, channelState, kind, value, channelState.maxMessageBytes)) {
         closeLogicalChannel(owner, channelState, {
           code: 1013,
@@ -1182,6 +1224,7 @@ export function createHubConsoleDirect(options = {}) {
         nextSendMessageId: 1,
         openRequested: false,
         localSocket: null,
+        frameAdmission: identity.purpose === 'frame' ? createConsoleFrameAdmission() : null,
         closed: false
       };
       owner.channels.set(identity.channelId, channelState);
@@ -1938,6 +1981,7 @@ export function createHubConsoleDirect(options = {}) {
   };
 
   const inspect = () => {
+    const peerDiagnostics = [];
     let logicalWebSocketChannels = 0;
     let localWebSocketChannels = 0;
     let pendingHttpRequests = 0;
@@ -1964,6 +2008,30 @@ export function createHubConsoleDirect(options = {}) {
       }
       retainedAssemblyBytes += Number(owner.wireBudget.inspect().retainedBytes || 0);
       bufferedSendBytes += ownerBufferedAmount(owner);
+      peerDiagnostics.push({
+        consoleId: owner.consoleId,
+        connectionId: owner.connectionId,
+        generation: owner.generation,
+        peerState: owner.peerState,
+        iceState: owner.iceState,
+        rttMs: optionalPeerMetric(owner.peer, 'rtt'),
+        bytesSent: optionalPeerMetric(owner.peer, 'bytesSent'),
+        bytesReceived: optionalPeerMetric(owner.peer, 'bytesReceived'),
+        selectedPath: inspectPeerPath(owner.peer),
+        bufferedSendBytes: (() => {
+          const values = [owner.control, ...owner.channels.values()]
+            .filter(lane => lane && !lane.closed)
+            .map(lane => optionalPeerMetric(lane.channel, 'bufferedAmount'));
+          return values.some(value => value === null) ? null : values.reduce((sum, value) => sum + value, 0);
+        })(),
+        pendingHttpRequests: owner.pendingHttp.size,
+        lanes: [...owner.channels.values()].map(lane => ({
+          channelId: lane.channelId,
+          purpose: lane.purpose,
+          bufferedBytes: optionalPeerMetric(lane.channel, 'bufferedAmount'),
+          frameAdmission: lane.frameAdmission?.inspect() ?? null
+        }))
+      });
     }
     const reconnectTimerActive = Boolean(retryTimer);
     const accessTokenDeadlineActive = Boolean(accessTokenAttempt);
@@ -1982,6 +2050,7 @@ export function createHubConsoleDirect(options = {}) {
       pendingLogicalControlRequests,
       retainedAssemblyBytes,
       bufferedSendBytes,
+      peerDiagnostics,
       iceConnectTimers,
       peerDisconnectTimers,
       assemblyDeadlineTimers,

package/src/console-direct.test.mjs

@@ -9,6 +9,7 @@ import {
 } from '../../runtime-core/src/console-direct-wire.js';
 import { consoleDirectContract, createHubConsoleDirect } from './console-direct.js';
 import { workspaceRoleCanRequest } from './auth/workspace-access.js';
+import { buildImmutableRemoteFramePacket } from './frame-packet-contract.mjs';
 
 assert.equal(consoleDirectContract.maxDefaultRetryDelayMs, 20_000);
 assert.equal(consoleDirectContract.peerDisconnectedTimeoutMs, 5_000);
@@ -1336,6 +1337,64 @@ test('media pressure retires only its stale logical lane while preserving the co
   direct.close();
 });
 
+test('a pressured H.264 viewer drops whole dependent frames and resumes on a key without reconnecting', async () => {
+  const { direct, signal } = await connectedDirect();
+  const peer = offer(signal);
+  const control = new FakeDataChannel('livedesk-control-v1');
+  peer.emitDataChannel(control);
+  control.open();
+  const lane = new FakeDataChannel(`livedesk-ws-v1:${CHANNEL_ID}:frame`);
+  peer.emitDataChannel(lane);
+  lane.open();
+  sendWire(control, {
+    type: 'ws-open', connectionId: CONNECTION_ONE, hubEpoch: HUB_EPOCH,
+    channelId: CHANNEL_ID, purpose: 'frame', path: '/api/remote/frames/ws'
+  });
+  const local = FakeLocalSocket.instances[0];
+  local.open();
+  const frame = (sequence, key, generation = 1) => buildImmutableRemoteFramePacket({
+    deviceId: 'device-a', sessionId: 'session-a', streamId: 'wall-a', commandId: 'command-a',
+    captureGeneration: generation, monitorIndex: 0, streamPurpose: 'wall',
+    frameMode: 'mode3-h264-hw', chunkType: key ? 'key' : 'delta',
+    isKeyFrame: key, streamFrameSeq: sequence
+  }, Buffer.alloc(32 * 1024)).packet;
+  local.receive(frame(1, true));
+  const initialChunks = lane.sent.length;
+  lane.buffered = consoleDirectContract.controlHeadroomBufferedBytes;
+  local.receive(frame(2, false));
+  assert.equal(lane.closed, false, 'congestion must not create another logical handshake or key-frame burst');
+  assert.equal(lane.sent.length, initialChunks, 'no fragment of a dropped frame enters SCTP');
+  lane.buffered = 0;
+  local.receive(frame(3, false));
+  assert.equal(lane.sent.length, initialChunks, 'a dependent delta cannot follow a discarded delta');
+  local.receive(frame(4, true));
+  assert.ok(lane.sent.length > initialChunks);
+  const recoveredChunks = lane.sent.length;
+  local.receive(frame(5, false));
+  assert.ok(lane.sent.length > recoveredChunks);
+  assert.equal(control.closed, false);
+  assert.equal(peer.closed, false);
+  assert.equal(direct.inspect().dataChannelBackpressureCloses, 0);
+  const diagnostics = direct.inspect().peerDiagnostics[0];
+  assert.equal(diagnostics.rttMs, null, 'missing native RTT is unknown');
+  assert.equal(diagnostics.bytesSent, null, 'missing native byte counters are unknown');
+  assert.equal(diagnostics.lanes[0].frameAdmission.droppedFrames, 2);
+  assert.equal(diagnostics.lanes[0].frameAdmission.recoveredStreams, 1);
+  peer.rtt = () => 12;
+  peer.bytesSent = () => 1234;
+  peer.selectedPair = {
+    local: { type: 'host', address: '192.168.0.4', candidate: 'must-not-leak' },
+    remote: { type: 'host', address: '192.168.0.8', transportType: 'Udp' }
+  };
+  const measured = direct.inspect().peerDiagnostics[0];
+  assert.equal(measured.rttMs, 12);
+  assert.equal(measured.bytesSent, 1234);
+  assert.equal(measured.selectedPath.remoteScope, 'private');
+  assert.doesNotMatch(JSON.stringify(measured), /192\.168\.|must-not-leak/);
+  direct.close();
+  assert.deepEqual(direct.inspect().peerDiagnostics, []);
+});
+
 test('a reliable control response drops stale media backlog without retiring the peer', async () => {
   const { direct, signal } = await connectedDirect({
     fetchImpl: async () => new Response('{"online":true}', {

package/src/control-presentation-borrow-contract.test.mjs

@@ -479,7 +479,7 @@ function parseBorrowLifecycleFramePacket(data) {
   }
 }
 
-test('the browser Wall borrower follows exact Control key frames without owning native capture', {
+test('Hub and phone Wall borrowers follow Control without stopping or retaining each other', {
   timeout: 20_000
 }, async () => {
   const {
@@ -563,7 +563,7 @@ test('the browser Wall borrower follows exact Control key frames without owning
     ).toString('base64')
   });
 
-  const connectBorrower = async label => {
+  const connectBorrower = async (label, options = {}) => {
     const socket = new WebSocket(
       `ws://127.0.0.1:${httpPort}/api/remote/frames/ws?devices=${encodeURIComponent(deviceId)}`,
       { headers: { Origin: baseUrl }, perMessageDeflate: false }
@@ -603,7 +603,8 @@ test('the browser Wall borrower follows exact Control key frames without owning
       maxWidth: 960,
       maxHeight: 540,
       quality: 55,
-      monitorIndex: 0
+      monitorIndex: 0,
+      ...options
     }));
     return { socket, observed, subscribeJsonIndex };
   };
@@ -799,6 +800,20 @@ test('the browser Wall borrower follows exact Control key frames without owning
     assert.equal(firstFrame.streamPurpose, 'control');
     assert.equal(firstFrame.monitorIndex, 0);
 
+    const hubBorrower = await connectBorrower('desktop Hub', {
+      fps: 30, maxWidth: 1920, maxHeight: 1080
+    });
+    await waitForBorrowStart(hubBorrower.observed, initialControl.commandId,
+      hubBorrower.subscribeJsonIndex, 'desktop Hub borrows the same Control owner');
+    sendControlFrame(initialControl, 4, true);
+    await waitForExactReady(hubBorrower.observed, initialControl, 0, 'desktop Hub key readiness');
+    const otherMonitor = await connectBorrower('other monitor', { monitorIndex: 1 });
+    await waitForBorrowLifecycle(() => otherMonitor.observed.json.some(message =>
+      JSON.stringify(message).includes('CONTROL_CAPTURE_OWNS_DEVICE')),
+    'different monitor reports ownership conflict');
+    assert.equal(otherMonitor.observed.frames.length, 0, 'never substitute a different monitor');
+    otherMonitor.socket.close();
+
     const firstStopCommandIndex = agentMessages.length;
     const stopInitialPromise = postJson(
       `/api/remote/devices/${encodeURIComponent(deviceId)}/live/stop`,
@@ -855,6 +870,8 @@ test('the browser Wall borrower follows exact Control key frames without owning
     const replacementFrameIndex = firstBorrower.observed.frames.length;
     sendOpen(replacementControl);
     sendControlFrame(replacementControl, 1, true);
+    await waitForBorrowStart(hubBorrower.observed, replacementControl.commandId,
+      0, 'desktop Hub follows the replacement generation');
     const replacementBorrowStart = await waitForBorrowStart(
       firstBorrower.observed,
       replacementControl.commandId,
@@ -878,6 +895,8 @@ test('the browser Wall borrower follows exact Control key frames without owning
     await new Promise(resolveWait => setTimeout(resolveWait, 60));
     assert.equal(firstBorrower.observed.frames.length, replacementFrameIndex);
     sendControlFrame(replacementControl, 3, true);
+    await waitForExactReady(hubBorrower.observed, replacementControl, 0,
+      'desktop Hub replacement key readiness');
     await waitForExactReady(
       firstBorrower.observed,
       replacementControl,
@@ -915,6 +934,10 @@ test('the browser Wall borrower follows exact Control key frames without owning
       stopCountBeforeBorrowerClose,
       'Closing a read-only borrower must never stop the native Control owner.'
     );
+    sendControlFrame(replacementControl, 4, true);
+    await waitForBorrowLifecycle(() => hubBorrower.observed.frames.some(frame =>
+      frame.commandId === replacementControl.commandId && frame.frameSeq === 4),
+    'desktop Hub keeps receiving after phone borrower closes');
 
     const fallbackBorrower = await connectBorrower('fallback borrower');
     await waitForBorrowStart(
@@ -924,7 +947,7 @@ test('the browser Wall borrower follows exact Control key frames without owning
       'fallback borrower Control binding'
     );
     const fallbackReadyIndex = fallbackBorrower.observed.json.length;
-    sendControlFrame(replacementControl, 4, true);
+    sendControlFrame(replacementControl, 5, true);
     await waitForExactReady(
       fallbackBorrower.observed,
       replacementControl,
@@ -984,6 +1007,11 @@ test('the browser Wall borrower follows exact Control key frames without owning
       'ordinary Wall browser binding after confirmed Control stop'
     );
     assert.equal(fallbackWallStart.started[0].presentationPurpose, '');
+    await waitForBorrowLifecycle(() => hubBorrower.observed.json.some(message =>
+      message.type === 'RemoteFrameLiveAutoStart'
+      && message.started?.some(item => item.commandId === fallbackWallCommand.message.commandId
+        && item.streamPurpose === 'wall' && item.readOnlyControlBorrow !== true)),
+    'desktop Hub and phone both restore the ordinary Wall owner');
   } catch (error) {
     error.message += hubOutput.length > 0
       ? `\nIsolated Hub output:\n${hubOutput.join('\n')}`