@livedesk/hub 0.1.26 → 0.1.28

package/src/frame-packet-contract.mjs

@@ -0,0 +1,427 @@
+export function createRemoteFramePacketMetrics() {
+  return {
+    packetBuilds: 0,
+    packetAllocations: 0,
+    metadataSerializations: 0,
+    metadataUtf8Writes: 0,
+    payloadCopyOperations: 0,
+    payloadCopyBytes: 0,
+    packetBytes: 0,
+    fanoutFrames: 0,
+    fanoutEligibleSubscribers: 0,
+    fanoutEnqueuedSubscribers: 0,
+    fanoutMaxEligibleSubscribers: 0,
+    sparseTelemetryFrames: 0,
+    sparseTelemetrySuppressedFrames: 0,
+    sparseTelemetryFields: 0
+  };
+}
+
+export const REMOTE_FRAME_SPARSE_NATIVE_TELEMETRY_FIELDS = Object.freeze([
+  'nativeCaptureTelemetryAvailable',
+  'nativeCaptureTelemetryVersion',
+  'nativeEncoderHardwareAccelerationKnown',
+  'nativeEncoderHardwareAccelerated',
+  'nativeEncoderHardwareQueryStatus',
+  'nativeCaptureDisplayId',
+  'nativeCaptureFps',
+  'nativeCompressionFps',
+  'nativeEncodedFps',
+  'nativeCaptureSampleCount',
+  'nativeEncodableFrameCount',
+  'nativeSkippedFrameCount',
+  'nativeCompressionOutputCount',
+  'nativeEncodedFrameCount',
+  'nativeEncodeFramesInFlight',
+  'nativeEncodePendingFrameCount',
+  'nativeEncodeTimestampOwnerCount',
+  'nativeEncodeTimestampOwnerHighWatermark',
+  'nativeBackpressureCoalescedFrameCount',
+  'nativeBackpressureSkippedFrameCount',
+  'nativeEncodePendingReplacedFrameCount',
+  'nativeIdleSkippedFrameCount',
+  'nativeVideoToolboxActiveSessionCount',
+  'nativeVideoToolboxSessionHighWatermark',
+  'nativeOutputQueueDepth',
+  'nativeOutputQueueBytes',
+  'nativeOutputQueueOldestAgeMs',
+  'nativeOutputQueueHighWatermark',
+  'nativeOutputQueueDroppedCount',
+  'nativeOutputQueueAwaitingKeyFrame',
+  'nativeCopyTelemetryAvailable',
+  'nativeAnnexBAccessUnitAllocationCount',
+  'nativeAnnexBPayloadCopyCount',
+  'nativeAnnexBPayloadCopiedBytes',
+  'nativeAndPipeResidenceAgeMs',
+  'pipePayloadAllocationCount',
+  'pipePayloadCopyCount',
+  'pipePayloadCopiedBytes',
+  'handoffDroppedFrameCount',
+  'handoffRecoveryKeyFrameRequestCount',
+  'handoffOldestFrameAgeMs',
+  'nativeCaptureResourceTelemetryAvailable',
+  'nativeCaptureTelemetryAt'
+]);
+
+const EMPTY_SPARSE_TELEMETRY = Object.freeze({});
+const REMOTE_FRAME_NATIVE_RESOURCE_TELEMETRY_FIELDS = new Set([
+  'nativeEncodeFramesInFlight',
+  'nativeEncodePendingFrameCount',
+  'nativeEncodeTimestampOwnerCount',
+  'nativeEncodeTimestampOwnerHighWatermark',
+  'nativeBackpressureCoalescedFrameCount',
+  'nativeBackpressureSkippedFrameCount',
+  'nativeEncodePendingReplacedFrameCount',
+  'nativeIdleSkippedFrameCount',
+  'nativeVideoToolboxActiveSessionCount',
+  'nativeVideoToolboxSessionHighWatermark',
+  'nativeOutputQueueDepth',
+  'nativeOutputQueueBytes',
+  'nativeOutputQueueOldestAgeMs',
+  'nativeOutputQueueHighWatermark',
+  'nativeOutputQueueDroppedCount',
+  'nativeOutputQueueAwaitingKeyFrame',
+  'nativeCopyTelemetryAvailable',
+  'nativeAnnexBAccessUnitAllocationCount',
+  'nativeAnnexBPayloadCopyCount',
+  'nativeAnnexBPayloadCopiedBytes',
+  'nativeAndPipeResidenceAgeMs',
+  'pipePayloadAllocationCount',
+  'pipePayloadCopyCount',
+  'pipePayloadCopiedBytes',
+  'handoffDroppedFrameCount',
+  'handoffRecoveryKeyFrameRequestCount',
+  'handoffOldestFrameAgeMs'
+]);
+
+function optionalFiniteNumber(value) {
+  if (value === null || value === undefined || value === '') {
+    return undefined;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function createSparseTelemetryLane() {
+  return {
+    sessionId: '',
+    streamId: '',
+    commandId: '',
+    captureGeneration: 0,
+    monitorIndex: -1,
+    telemetryAt: '',
+    telemetryVersion: undefined,
+    captureSampleCount: undefined,
+    encodedFrameCount: undefined,
+    telemetryAvailable: undefined,
+    resourceTelemetryAvailable: undefined,
+    hardwareKnown: undefined,
+    lastEmittedAtMs: 0
+  };
+}
+
+/**
+ * Contract:
+ * - At most two fixed lane records are retained per device (Wall + Control).
+ * - The device map has an explicit upper bound and only scans on cold-path
+ *   admission after that bound has been reached.
+ * - A capture-generation handoff cannot inherit telemetry from its predecessor.
+ */
+export function createRemoteFrameSparseTelemetryTracker(options = {}) {
+  return {
+    cadenceMs: Math.max(250, Number(options.cadenceMs) || 1_000),
+    maxDevices: Math.max(1, Number(options.maxDevices) || 1_024),
+    devices: new Map()
+  };
+}
+
+export function retainRemoteFrameSparseTelemetryDevices(tracker, activeDeviceIds) {
+  if (!tracker?.devices) {
+    return 0;
+  }
+  const active = activeDeviceIds instanceof Set
+    ? activeDeviceIds
+    : new Set(activeDeviceIds || []);
+  let removed = 0;
+  for (const deviceId of tracker.devices.keys()) {
+    if (!active.has(deviceId)) {
+      tracker.devices.delete(deviceId);
+      removed += 1;
+    }
+  }
+  return removed;
+}
+
+function sparseTelemetryDeviceState(tracker, deviceId, nowMs) {
+  let state = tracker.devices.get(deviceId);
+  if (state) {
+    state.lastSeenAtMs = nowMs;
+    return state;
+  }
+  if (tracker.devices.size >= tracker.maxDevices) {
+    let oldestDeviceId = '';
+    let oldestSeenAtMs = Number.POSITIVE_INFINITY;
+    for (const [candidateDeviceId, candidate] of tracker.devices) {
+      if (candidate.lastSeenAtMs < oldestSeenAtMs) {
+        oldestDeviceId = candidateDeviceId;
+        oldestSeenAtMs = candidate.lastSeenAtMs;
+      }
+    }
+    if (oldestDeviceId) {
+      tracker.devices.delete(oldestDeviceId);
+    }
+  }
+  state = {
+    lastSeenAtMs: nowMs,
+    wall: createSparseTelemetryLane(),
+    control: createSparseTelemetryLane()
+  };
+  tracker.devices.set(deviceId, state);
+  return state;
+}
+
+function sparseTelemetryOwnerChanged(lane, frame) {
+  return lane.sessionId !== String(frame.sessionId || '')
+    || lane.streamId !== String(frame.streamId || '')
+    || lane.commandId !== String(frame.commandId || '')
+    || lane.captureGeneration !== (Number(frame.captureGeneration || 0) || 0)
+    || lane.monitorIndex !== (Number.isFinite(Number(frame.monitorIndex)) ? Number(frame.monitorIndex) : 0);
+}
+
+function updateSparseTelemetryOwner(lane, frame) {
+  lane.sessionId = String(frame.sessionId || '');
+  lane.streamId = String(frame.streamId || '');
+  lane.commandId = String(frame.commandId || '');
+  lane.captureGeneration = Number(frame.captureGeneration || 0) || 0;
+  lane.monitorIndex = Number.isFinite(Number(frame.monitorIndex)) ? Number(frame.monitorIndex) : 0;
+}
+
+function appendSparseTelemetryValue(target, frame, field) {
+  if (!Object.prototype.hasOwnProperty.call(frame, field)) {
+    return;
+  }
+  const value = frame[field];
+  if (value === undefined || value === null || value === '') {
+    return;
+  }
+  if (field === 'nativeEncoderHardwareAccelerated'
+      || field === 'nativeOutputQueueAwaitingKeyFrame'
+      || field === 'nativeCopyTelemetryAvailable'
+      || field === 'nativeCaptureTelemetryAvailable'
+      || field === 'nativeEncoderHardwareAccelerationKnown'
+      || field === 'nativeCaptureResourceTelemetryAvailable') {
+    if (typeof value === 'boolean') {
+      target[field] = value;
+    }
+    return;
+  }
+  if (field === 'nativeEncoderHardwareQueryStatus' || field === 'nativeCaptureTelemetryAt') {
+    target[field] = String(value);
+    return;
+  }
+  const parsed = optionalFiniteNumber(value);
+  if (parsed !== undefined) {
+    target[field] = parsed;
+  }
+}
+
+/**
+ * Returns only native capture diagnostics that need to cross the browser
+ * packet boundary now. Per-frame timing/currentness remains in the base packet.
+ * Repeated one-Hz native samples are not expanded into 24/30 identical JSON
+ * objects per second.
+ */
+export function selectSparseRemoteFrameTelemetry(
+  frame,
+  tracker,
+  nowMs = Date.now(),
+  metrics = null,
+  deviceIdOverride = ''
+) {
+  if (!frame || !tracker?.devices) {
+    return EMPTY_SPARSE_TELEMETRY;
+  }
+  const deviceId = String(deviceIdOverride || frame.deviceId || '').trim();
+  if (!deviceId) {
+    return EMPTY_SPARSE_TELEMETRY;
+  }
+  const purpose = String(frame.streamPurpose || '').toLowerCase() === 'control'
+    ? 'control'
+    : 'wall';
+  const state = sparseTelemetryDeviceState(tracker, deviceId, nowMs);
+  const lane = state[purpose];
+  const ownerChanged = sparseTelemetryOwnerChanged(lane, frame);
+  if (ownerChanged) {
+    updateSparseTelemetryOwner(lane, frame);
+  }
+
+  const telemetryAt = String(frame.nativeCaptureTelemetryAt || '');
+  const telemetryVersion = optionalFiniteNumber(frame.nativeCaptureTelemetryVersion);
+  const captureSampleCount = optionalFiniteNumber(frame.nativeCaptureSampleCount);
+  const encodedFrameCount = optionalFiniteNumber(frame.nativeEncodedFrameCount);
+  const telemetryAvailable = typeof frame.nativeCaptureTelemetryAvailable === 'boolean'
+    ? frame.nativeCaptureTelemetryAvailable
+    : undefined;
+  const resourceTelemetryAvailable = typeof frame.nativeCaptureResourceTelemetryAvailable === 'boolean'
+    ? frame.nativeCaptureResourceTelemetryAvailable
+    : undefined;
+  const hardwareKnown = typeof frame.nativeEncoderHardwareAccelerationKnown === 'boolean'
+    ? frame.nativeEncoderHardwareAccelerationKnown
+    : undefined;
+  const sampleChanged = lane.telemetryAt !== telemetryAt
+    || lane.telemetryVersion !== telemetryVersion
+    || lane.captureSampleCount !== captureSampleCount
+    || lane.encodedFrameCount !== encodedFrameCount
+    || lane.telemetryAvailable !== telemetryAvailable
+    || lane.resourceTelemetryAvailable !== resourceTelemetryAvailable
+    || lane.hardwareKnown !== hardwareKnown;
+  const cadenceElapsed = nowMs - lane.lastEmittedAtMs >= tracker.cadenceMs;
+
+  lane.telemetryAt = telemetryAt;
+  lane.telemetryVersion = telemetryVersion;
+  lane.captureSampleCount = captureSampleCount;
+  lane.encodedFrameCount = encodedFrameCount;
+  lane.telemetryAvailable = telemetryAvailable;
+  lane.resourceTelemetryAvailable = resourceTelemetryAvailable;
+  lane.hardwareKnown = hardwareKnown;
+
+  if (!ownerChanged && !sampleChanged && !cadenceElapsed) {
+    incrementMetric(metrics, 'sparseTelemetrySuppressedFrames');
+    return EMPTY_SPARSE_TELEMETRY;
+  }
+
+  lane.lastEmittedAtMs = nowMs;
+  const selected = {};
+  for (const field of REMOTE_FRAME_SPARSE_NATIVE_TELEMETRY_FIELDS) {
+    if (field !== 'nativeCaptureTelemetryAvailable' && telemetryAvailable !== true) {
+      continue;
+    }
+    if (REMOTE_FRAME_NATIVE_RESOURCE_TELEMETRY_FIELDS.has(field)
+        && resourceTelemetryAvailable !== true) {
+      continue;
+    }
+    appendSparseTelemetryValue(selected, frame, field);
+  }
+  incrementMetric(metrics, 'sparseTelemetryFrames');
+  incrementMetric(metrics, 'sparseTelemetryFields', Object.keys(selected).length);
+  return selected;
+}
+
+function incrementMetric(metrics, property, amount = 1) {
+  if (!metrics || !Object.prototype.hasOwnProperty.call(metrics, property)) {
+    return;
+  }
+  metrics[property] = Math.max(0, Number(metrics[property] || 0) + amount);
+}
+
+/**
+ * Contract:
+ * - One call owns exactly one browser wire packet.
+ * - Metadata is serialized and UTF-8 encoded once directly into that packet.
+ * - The compressed payload is copied once into the exact packet owner.
+ * - Callers must treat the returned frozen descriptor and its Buffer as
+ *   immutable and may share the same descriptor across every subscriber lane.
+ */
+export function buildImmutableRemoteFramePacket(metadata, payload, metrics = null) {
+  if (!Buffer.isBuffer(payload) || payload.length === 0) {
+    return null;
+  }
+
+  const metadataJson = JSON.stringify(metadata);
+  const metadataByteLength = Buffer.byteLength(metadataJson, 'utf8');
+  const packetByteLength = 4 + metadataByteLength + payload.length;
+  const packet = Buffer.allocUnsafeSlow(packetByteLength);
+  packet.writeUInt32BE(metadataByteLength, 0);
+  const metadataBytesWritten = packet.write(
+    metadataJson,
+    4,
+    metadataByteLength,
+    'utf8'
+  );
+  if (metadataBytesWritten !== metadataByteLength) {
+    throw new Error('remote-frame-metadata-write-incomplete');
+  }
+  const payloadBytesWritten = payload.copy(packet, 4 + metadataByteLength);
+  if (payloadBytesWritten !== payload.length) {
+    throw new Error('remote-frame-payload-copy-incomplete');
+  }
+
+  incrementMetric(metrics, 'packetBuilds');
+  incrementMetric(metrics, 'packetAllocations');
+  incrementMetric(metrics, 'metadataSerializations');
+  incrementMetric(metrics, 'metadataUtf8Writes');
+  incrementMetric(metrics, 'payloadCopyOperations');
+  incrementMetric(metrics, 'payloadCopyBytes', payload.length);
+  incrementMetric(metrics, 'packetBytes', packetByteLength);
+
+  return Object.freeze({
+    packet,
+    byteLength: packetByteLength,
+    metadataByteLength,
+    payloadByteLength: payload.length
+  });
+}
+
+/**
+ * Fan out one immutable packet owner without rebuilding subscriber-specific
+ * metadata or payload storage. Per-subscriber queue admission remains the
+ * enqueue callback's responsibility.
+ */
+export function fanoutImmutableRemoteFramePacket(
+  packetOwner,
+  eligibleSubscribers,
+  enqueue,
+  metrics = null
+) {
+  if (!packetOwner?.packet || typeof enqueue !== 'function') {
+    return {
+      eligibleSubscribers: 0,
+      enqueuedSubscribers: 0
+    };
+  }
+
+  const subscribers = Array.isArray(eligibleSubscribers)
+    ? eligibleSubscribers
+    : [...(eligibleSubscribers || [])];
+  let enqueuedSubscribers = 0;
+  for (const subscriber of subscribers) {
+    if (enqueue(subscriber, packetOwner) === true) {
+      enqueuedSubscribers += 1;
+    }
+  }
+
+  incrementMetric(metrics, 'fanoutFrames');
+  incrementMetric(metrics, 'fanoutEligibleSubscribers', subscribers.length);
+  incrementMetric(metrics, 'fanoutEnqueuedSubscribers', enqueuedSubscribers);
+  if (metrics) {
+    metrics.fanoutMaxEligibleSubscribers = Math.max(
+      Math.max(0, Number(metrics.fanoutMaxEligibleSubscribers || 0)),
+      subscribers.length
+    );
+  }
+
+  return {
+    eligibleSubscribers: subscribers.length,
+    enqueuedSubscribers
+  };
+}
+
+export function snapshotRemoteFramePacketMetrics(metrics) {
+  const source = metrics || {};
+  return {
+    packetBuilds: Math.max(0, Number(source.packetBuilds || 0)),
+    packetAllocations: Math.max(0, Number(source.packetAllocations || 0)),
+    metadataSerializations: Math.max(0, Number(source.metadataSerializations || 0)),
+    metadataUtf8Writes: Math.max(0, Number(source.metadataUtf8Writes || 0)),
+    payloadCopyOperations: Math.max(0, Number(source.payloadCopyOperations || 0)),
+    payloadCopyBytes: Math.max(0, Number(source.payloadCopyBytes || 0)),
+    packetBytes: Math.max(0, Number(source.packetBytes || 0)),
+    fanoutFrames: Math.max(0, Number(source.fanoutFrames || 0)),
+    fanoutEligibleSubscribers: Math.max(0, Number(source.fanoutEligibleSubscribers || 0)),
+    fanoutEnqueuedSubscribers: Math.max(0, Number(source.fanoutEnqueuedSubscribers || 0)),
+    fanoutMaxEligibleSubscribers: Math.max(0, Number(source.fanoutMaxEligibleSubscribers || 0)),
+    sparseTelemetryFrames: Math.max(0, Number(source.sparseTelemetryFrames || 0)),
+    sparseTelemetrySuppressedFrames: Math.max(0, Number(source.sparseTelemetrySuppressedFrames || 0)),
+    sparseTelemetryFields: Math.max(0, Number(source.sparseTelemetryFields || 0))
+  };
+}