@livedesk/hub 0.1.74 → 0.1.76

package/package.json

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

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

@@ -3,7 +3,8 @@ export const CONSOLE_MEDIA_ADMISSION = Object.freeze({
   peerBufferedBytes: 1024 * 1024,
   bufferedAgeMs: 120,
   maxStreams: 64,
-  maxMetadataBytes: 64 * 1024
+  maxMetadataBytes: 64 * 1024,
+  maxSendBatches: 16
 });
 
 function h264Identity(packet) {
@@ -31,13 +32,44 @@ function h264Identity(packet) {
 // timer, task, or outbound queue; every decision precedes wire fragmentation.
 export function createConsoleFrameAdmission() {
   const streams = new Map();
-  let bufferedSince = null;
+  const sendBatches = [];
+  let accountedBytes = 0;
   let droppedFrames = 0;
   let recoveredStreams = 0;
+  const flow = { inputFrames: 0, inputKeyFrames: 0, admittedFrames: 0,
+    laneByteDrops: 0, peerByteDrops: 0, ageDrops: 0, dependentDrops: 0 };
+  let lastInputAt = null, lastKeyAt = null, lastAdmittedAt = null;
+  function sent(bytes, now) {
+    if (!(bytes > 0)) return;
+    accountedBytes += bytes;
+    if (sendBatches.length >= CONSOLE_MEDIA_ADMISSION.maxSendBatches) {
+      // Coalesce at the newer end using the older timestamp: bounds remain
+      // conservative, never younger than the bytes whose age we protect.
+      const last = sendBatches.at(-1);
+      last.bytes += bytes;
+    } else sendBatches.push({ bytes, at: now });
+  }
+  function oldestBufferedAt(bufferedBytes, now) {
+    if (bufferedBytes > accountedBytes) sent(bufferedBytes - accountedBytes, now);
+    let drained = Math.max(0, accountedBytes - bufferedBytes);
+    while (drained > 0 && sendBatches.length > 0) {
+      const oldest = sendBatches[0];
+      const consumed = Math.min(drained, oldest.bytes);
+      oldest.bytes -= consumed;
+      drained -= consumed;
+      accountedBytes -= consumed;
+      if (oldest.bytes === 0) sendBatches.shift();
+    }
+    return sendBatches[0]?.at ?? now;
+  }
   return {
+    sent,
     admit(packet, { laneBufferedBytes, peerBufferedBytes, now }) {
       const identity = h264Identity(packet);
       if (!identity) return 'unmanaged';
+      flow.inputFrames += 1;
+      lastInputAt = now;
+      if (identity.key) { flow.inputKeyFrames += 1; lastKeyAt = now; }
       let state = streams.get(identity.stream);
       if (!state) {
         if (streams.size >= CONSOLE_MEDIA_ADMISSION.maxStreams) return 'capacity';
@@ -47,34 +79,50 @@ export function createConsoleFrameAdmission() {
         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)) {
+      const oldestAt = oldestBufferedAt(Math.max(0, laneBufferedBytes), now);
+      const laneBytePressure = laneBufferedBytes > 0
+        && laneBufferedBytes + packet.length > CONSOLE_MEDIA_ADMISSION.laneBufferedBytes;
+      const peerBytePressure = peerBufferedBytes > 0
+        && peerBufferedBytes + packet.length > CONSOLE_MEDIA_ADMISSION.peerBufferedBytes;
+      const agePressure = laneBufferedBytes > 0
+        && now - oldestAt >= CONSOLE_MEDIA_ADMISSION.bufferedAgeMs;
+      if (laneBytePressure || peerBytePressure || agePressure || (state.awaitingKey && !identity.key)) {
+        // Exclusive reasons distinguish the original pressure from subsequent
+        // dependent deltas. Keep only scalar evidence, never frames or timers.
+        if (laneBytePressure) flow.laneByteDrops += 1;
+        else if (peerBytePressure) flow.peerByteDrops += 1;
+        else if (agePressure) flow.ageDrops += 1;
+        else flow.dependentDrops += 1;
         state.awaitingKey = true;
         droppedFrames += 1;
         return 'drop';
       }
       if (state.awaitingKey) recoveredStreams += 1;
       state.awaitingKey = false;
+      flow.admittedFrames += 1;
+      lastAdmittedAt = now;
       return 'send';
     },
-    inspect() {
+    inspect(now = performance.now()) {
+      const age = at => at === null ? null : Math.max(0, now - at);
       return {
+        ...flow,
+        lastInputAgeMs: age(lastInputAt),
+        lastKeyAgeMs: age(lastKeyAt),
+        lastAdmittedAgeMs: age(lastAdmittedAt),
         streamOwners: streams.size,
         awaitingKeyStreams: [...streams.values()].filter(state => state.awaitingKey).length,
         droppedFrames,
         recoveredStreams,
+        sendBatches: sendBatches.length,
         retainedPayloadBytes: 0
       };
     },
     clear() {
       streams.clear();
-      bufferedSince = null;
+      sendBatches.length = 0;
+      accountedBytes = 0;
+      lastInputAt = lastKeyAt = lastAdmittedAt = null;
     }
   };
 }

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

@@ -58,3 +58,60 @@ test('a multiplexed lane has a fixed owner bound and releases it on close', () =
   gate.clear();
   assert.equal(gate.admit(packet({ device: 'replacement', key: true }), empty), 'send');
 });
+
+test('a continuously draining nonempty lane does not confuse current bytes with a stale backlog', () => {
+  const gate = createConsoleFrameAdmission();
+  for (let n = 0; n < 300; n++) {
+    const now = n * 33;
+    // Half of each accepted batch remains at the next sample, even though
+    // every older batch has drained. A never-zero timestamp would drop at 120ms.
+    assert.equal(gate.admit(packet({ key: n === 0 }), {
+      laneBufferedBytes: n === 0 ? 0 : 1000, peerBufferedBytes: 1000, now
+    }), 'send');
+    gate.sent(2000, now);
+  }
+  assert.equal(gate.inspect().droppedFrames, 0);
+  assert.ok(gate.inspect().sendBatches <= 2);
+  gate.clear();
+  assert.equal(gate.inspect().sendBatches, 0);
+});
+
+test('fresh sends cannot rejuvenate actually blocked bytes and batch metadata remains bounded', () => {
+  const gate = createConsoleFrameAdmission();
+  assert.equal(gate.admit(packet({ key: true }), empty), 'send');
+  gate.sent(2000, 0);
+  let pending = 2000;
+  for (let n = 1; n < 120; n++) {
+    assert.equal(gate.admit(packet(), { laneBufferedBytes: pending, peerBufferedBytes: pending, now: n }), 'send');
+    gate.sent(100, n); pending += 100;
+  }
+  assert.equal(gate.inspect().sendBatches, CONSOLE_MEDIA_ADMISSION.maxSendBatches);
+  assert.equal(gate.admit(packet(), { laneBufferedBytes: pending, peerBufferedBytes: pending, now: 120 }), 'drop');
+  assert.equal(gate.admit(packet(), { ...empty, now: 121 }), 'drop');
+  assert.equal(gate.admit(packet({ key: true }), { ...empty, now: 122 }), 'send');
+  assert.equal(gate.inspect().sendBatches, 0);
+});
+
+test('read-driven flow evidence distinguishes source starvation, pressure and waiting for a key', () => {
+  const gate = createConsoleFrameAdmission();
+  assert.equal(gate.inspect(0).lastInputAgeMs, null);
+  gate.admit(packet({ key: true }), empty);
+  gate.sent(2000, 0);
+  const queued = { laneBufferedBytes: 2000, peerBufferedBytes: 2000, now: 120 };
+  assert.equal(gate.admit(packet(), queued), 'drop');
+  assert.equal(gate.admit(packet(), { ...empty, now: 150 }), 'drop');
+  const stalled = gate.inspect(200);
+  assert.equal(stalled.inputFrames, 3);
+  assert.equal(stalled.inputKeyFrames, 1);
+  assert.equal(stalled.admittedFrames, 1);
+  assert.equal(stalled.ageDrops, 1);
+  assert.equal(stalled.dependentDrops, 1);
+  assert.equal(stalled.lastInputAgeMs, 50);
+  assert.equal(stalled.lastKeyAgeMs, 200);
+  assert.equal(stalled.lastAdmittedAgeMs, 200);
+  assert.equal(gate.admit(packet({ key: true }), { ...empty, now: 220 }), 'send');
+  assert.equal(gate.inspect(221).lastAdmittedAgeMs, 1);
+  gate.clear();
+  assert.equal(gate.inspect(222).lastInputAgeMs, null);
+  assert.equal(gate.inspect(222).streamOwners, 0);
+});

package/src/console-direct-ice-evidence.mjs

@@ -0,0 +1,87 @@
+import { isIP } from 'node:net';
+
+// Connection setup only: no SDP, addresses, credentials, packets, timers, or
+// references to native peers are retained. Counts describe announcements, not
+// unique paths (SDP and trickled candidates can announce the same path).
+export const CONSOLE_ICE_HISTORY_LIMIT = 8;
+// Explicit advanced configuration only. This does not open a firewall/router
+// port or enable a relay; unset configuration retains native ephemeral ports.
+export function normalizeConsoleIcePortRange(value) {
+  if (value === undefined || value === null || value === '') return {};
+  const match = String(value).trim().match(/^(\d{4,5})-(\d{4,5})$/);
+  const begin = Number(match?.[1]);
+  const end = Number(match?.[2]);
+  if (!match || begin < 1024 || end > 65535 || end < begin || end - begin >= 64) {
+    throw new Error('console-direct-ice-port-range-invalid');
+  }
+  return { portRangeBegin: begin, portRangeEnd: end };
+}
+const MAX_COUNT = 65_535;
+const count = value => Math.min(MAX_COUNT, value + 1);
+const states = new Set(['new', 'gathering', 'complete', 'completed', 'checking',
+  'connecting', 'connected', 'disconnected', 'failed', 'closed']);
+const reasons = new Set([
+  'console-direct-ice-timeout', 'console-direct-ice-failed', 'console-direct-ice-closed',
+  'console-direct-peer-failed', 'console-direct-peer-closed', 'console-direct-peer-replaced',
+  'console-direct-description-failed', 'console-direct-candidate-failed',
+  'console-direct-candidate-invalid', 'console-direct-relay-candidate-rejected',
+  'console-direct-relay-pair-rejected', 'console-direct-remote-closed',
+  'console-direct-peer-disconnected-timeout', 'console-direct-stopped'
+]);
+
+export const safeIceState = value => states.has(value) ? value : 'unknown';
+
+function candidateCounts() {
+  return { announcements: 0, host: 0, srflx: 0, prflx: 0, relay: 0,
+    ipv4: 0, ipv6: 0, mdns: 0, udp: 0, tcp: 0, unknown: 0 };
+}
+
+export function createConsoleIceEvidence() {
+  return { localDescriptionSent: false, remoteDescriptionApplied: false,
+    localCandidateSendFailures: 0,
+    gatheringState: 'unknown', local: candidateCounts(), remote: candidateCounts() };
+}
+
+export function recordConsoleIceCandidate(counts, value) {
+  if (typeof value !== 'string' || !value.trim()) return;
+  counts.announcements = count(counts.announcements);
+  if (value.length > 4096) { counts.unknown = count(counts.unknown); return; }
+  const parts = value.trim().replace(/^a=/, '').split(/\s+/);
+  const transport = parts[2]?.toLowerCase();
+  const type = parts[7]?.toLowerCase();
+  if (!/^candidate:/i.test(parts[0]) || parts[6]?.toLowerCase() !== 'typ'
+      || !['host', 'srflx', 'prflx', 'relay'].includes(type)) {
+    counts.unknown = count(counts.unknown);
+    return;
+  }
+  counts[type] = count(counts[type]);
+  if (transport === 'udp' || transport === 'tcp') counts[transport] = count(counts[transport]);
+  const family = isIP(parts[4] || '');
+  if (family) counts[`ipv${family}`] = count(counts[`ipv${family}`]);
+  else if (/^[a-z0-9-]+\.local$/i.test(parts[4] || '')) counts.mdns = count(counts.mdns);
+  else counts.unknown = count(counts.unknown);
+}
+
+export function recordConsoleIceDescription(counts, sdp) {
+  if (typeof sdp !== 'string' || sdp.length > 64 * 1024) return;
+  for (const line of sdp.split(/\r?\n/)) {
+    if (/^a=candidate:/i.test(line)) recordConsoleIceCandidate(counts, line);
+  }
+}
+
+export function snapshotConsoleIceEvidence(evidence) {
+  return { ...evidence, local: { ...evidence.local }, remote: { ...evidence.remote } };
+}
+
+export function retainConsoleIceRetirement(history, owner, reason, now = Date.now()) {
+  const snapshot = {
+    consoleId: owner.consoleId, connectionId: owner.connectionId, generation: owner.generation,
+    endedAt: new Date(now).toISOString(), durationMs: Math.max(0, now - owner.createdAt),
+    reason: reasons.has(reason) ? reason : 'other-peer-retirement',
+    peerState: safeIceState(owner.peerState), iceState: safeIceState(owner.iceState),
+    controlOpened: owner.controlOpened === true,
+    ...snapshotConsoleIceEvidence(owner.iceEvidence)
+  };
+  history.push(snapshot);
+  if (history.length > CONSOLE_ICE_HISTORY_LIMIT) history.shift();
+}

package/src/console-direct-ice-evidence.test.mjs

@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  createConsoleIceEvidence, normalizeConsoleIcePortRange, recordConsoleIceCandidate, recordConsoleIceDescription,
+  retainConsoleIceRetirement, snapshotConsoleIceEvidence
+} from './console-direct-ice-evidence.mjs';
+
+test('explicit ICE port ranges remain bounded and never alter the default', () => {
+  assert.deepEqual(normalizeConsoleIcePortRange(), {});
+  assert.deepEqual(normalizeConsoleIcePortRange(''), {});
+  assert.deepEqual(normalizeConsoleIcePortRange('54443-54443'), { portRangeBegin: 54443, portRangeEnd: 54443 });
+  assert.deepEqual(normalizeConsoleIcePortRange('54443-54450'), { portRangeBegin: 54443, portRangeEnd: 54450 });
+  for (const invalid of ['1-2', '1023-1024', '65535-65536', '55555-54443', '54443-54507', '54443', 'abc', '54443-54450x']) {
+    assert.throws(() => normalizeConsoleIcePortRange(invalid), /port-range-invalid/);
+  }
+});
+
+test('ICE evidence counts candidate families without retaining endpoints or SDP secrets', () => {
+  const evidence = createConsoleIceEvidence();
+  recordConsoleIceDescription(evidence.local, [
+    'a=ice-pwd:DO-NOT-RETAIN',
+    'a=candidate:1 1 UDP 123 192.168.0.4 59900 typ host',
+    'a=candidate:2 1 udp 123 203.0.113.123 59901 typ srflx raddr 192.168.0.4 rport 59900',
+    'a=candidate:3 1 tcp 123 2001:db8::abcd 59902 typ host tcptype passive',
+    'a=candidate:4 1 udp 123 device-secret.local 59903 typ host'
+  ].join('\r\n'));
+  recordConsoleIceCandidate(evidence.remote, 'invalid SDP DO-NOT-RETAIN');
+  assert.equal(evidence.local.announcements, 4);
+  assert.equal(evidence.local.host, 3);
+  assert.equal(evidence.local.srflx, 1);
+  assert.equal(evidence.local.ipv4, 2);
+  assert.equal(evidence.local.ipv6, 1);
+  assert.equal(evidence.local.mdns, 1);
+  assert.equal(evidence.local.udp, 3);
+  assert.equal(evidence.local.tcp, 1);
+  assert.equal(evidence.remote.unknown, 1);
+  assert.doesNotMatch(JSON.stringify(evidence), /DO-NOT-RETAIN|192\.168|203\.0|db8|device-secret|5990/);
+  const snapshot = snapshotConsoleIceEvidence(evidence);
+  snapshot.local.host = 99;
+  assert.equal(evidence.local.host, 3);
+});
+
+test('retirement history is bounded, detached, and uses fixed reason/state labels', () => {
+  const history = [];
+  const owner = { consoleId: 'console', connectionId: 'connection', createdAt: 100,
+    peerState: 'connecting', iceState: 'checking', iceEvidence: createConsoleIceEvidence() };
+  for (let generation = 1; generation <= 30; generation++) {
+    retainConsoleIceRetirement(history, { ...owner, generation }, 'console-direct-ice-timeout', 200);
+  }
+  assert.equal(history.length, 8);
+  assert.equal(history[0].generation, 23);
+  assert.equal(history.at(-1).durationMs, 100);
+  owner.iceEvidence.remote.host = 99;
+  assert.equal(history.at(-1).remote.host, 0);
+  retainConsoleIceRetirement(history, { ...owner, peerState: 'secret-state' }, 'secret-reason', 200);
+  assert.equal(history.at(-1).peerState, 'unknown');
+  assert.equal(history.at(-1).reason, 'other-peer-retirement');
+  assert.doesNotMatch(JSON.stringify(history), /secret-/);
+});