@livedesk/hub 0.1.26 → 0.1.28

package/src/live-capture-transition-retry.mjs

@@ -0,0 +1,297 @@
+function finitePositive(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : fallback;
+}
+
+function clamp(value, minimum, maximum) {
+  return Math.max(minimum, Math.min(maximum, value));
+}
+
+/**
+ * Owns the Hub-to-browser retry that follows an exact native capture stop.
+ *
+ * Contract:
+ * - one owner per WebSocket/device intent generation;
+ * - the native stop promise is the event source (no polling loop);
+ * - retries and total elapsed time are both bounded;
+ * - supersede, close, success, and terminal failure synchronously release every timer.
+ */
+export function createLiveCaptureTransitionRetryCoordinator(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : Date.now;
+  const setTimer = typeof options.setTimer === 'function' ? options.setTimer : setTimeout;
+  const clearTimer = typeof options.clearTimer === 'function' ? options.clearTimer : clearTimeout;
+  const maxAttempts = Math.max(1, Math.floor(finitePositive(options.maxAttempts, 3)));
+  const minimumRetryAfterMs = Math.max(1, finitePositive(options.minimumRetryAfterMs, 25));
+  const maximumRetryAfterMs = Math.max(
+    minimumRetryAfterMs,
+    finitePositive(options.maximumRetryAfterMs, 250)
+  );
+  const minimumTotalMs = Math.max(1, finitePositive(options.minimumTotalMs, 2_000));
+  const maximumTotalMs = Math.max(minimumTotalMs, finitePositive(options.maximumTotalMs, 30_000));
+  const completionMarginMs = Math.max(0, Number(options.completionMarginMs ?? 2_000) || 0);
+  const clientStates = new WeakMap();
+  const activeOwners = new Set();
+
+  function stateFor(client) {
+    if (!client || (typeof client !== 'object' && typeof client !== 'function')) {
+      throw new TypeError('A capture transition retry requires an exact client owner.');
+    }
+    let state = clientStates.get(client);
+    if (!state) {
+      state = {
+        intentGenerations: new Map(),
+        owners: new Map()
+      };
+      clientStates.set(client, state);
+    }
+    return state;
+  }
+
+  function ownerIsCurrent(owner) {
+    if (!owner || owner.cancelled) {
+      return false;
+    }
+    const state = clientStates.get(owner.client);
+    return !!state
+      && state.owners.get(owner.deviceId) === owner
+      && state.intentGenerations.get(owner.deviceId) === owner.intentGeneration;
+  }
+
+  function releaseOwner(owner, reason = 'completed') {
+    if (!owner || owner.cancelled) {
+      return false;
+    }
+    owner.cancelled = true;
+    owner.cancelReason = reason;
+    owner.waitToken += 1;
+    if (owner.timer) {
+      clearTimer(owner.timer);
+      owner.timer = null;
+    }
+    const state = clientStates.get(owner.client);
+    if (state?.owners.get(owner.deviceId) === owner) {
+      state.owners.delete(owner.deviceId);
+    }
+    activeOwners.delete(owner);
+    return true;
+  }
+
+  function failOwner(owner, error, details = {}) {
+    if (!ownerIsCurrent(owner)) {
+      return false;
+    }
+    const onTerminal = owner.onTerminal;
+    const terminal = {
+      deviceId: owner.deviceId,
+      intentGeneration: owner.intentGeneration,
+      attemptCount: owner.attemptCount,
+      deadlineAtEpochMs: owner.deadlineAtEpochMs,
+      error,
+      ...details
+    };
+    releaseOwner(owner, error);
+    try {
+      onTerminal?.(terminal);
+    } catch {
+      // The retry owner is already terminal. UI notification failure cannot
+      // resurrect it or retain a timer.
+    }
+    return true;
+  }
+
+  function beginIntent(client, deviceId) {
+    const normalizedDeviceId = String(deviceId || '').trim();
+    if (!normalizedDeviceId) {
+      throw new TypeError('A capture transition retry requires a device id.');
+    }
+    const state = stateFor(client);
+    releaseOwner(state.owners.get(normalizedDeviceId), 'superseded');
+    const current = Number(state.intentGenerations.get(normalizedDeviceId) || 0);
+    const next = Number.isSafeInteger(current) && current > 0 ? current + 1 : 1;
+    state.intentGenerations.set(normalizedDeviceId, next);
+    return next;
+  }
+
+  function complete(client, deviceId, intentGeneration, reason = 'completed') {
+    const normalizedDeviceId = String(deviceId || '').trim();
+    const state = clientStates.get(client);
+    const owner = state?.owners.get(normalizedDeviceId);
+    if (!owner
+      || (Number.isSafeInteger(Number(intentGeneration))
+        && Number(intentGeneration) > 0
+        && owner.intentGeneration !== Number(intentGeneration))) {
+      return false;
+    }
+    return releaseOwner(owner, reason);
+  }
+
+  function cancelClient(client, reason = 'client-closed') {
+    const state = clientStates.get(client);
+    if (!state) {
+      return 0;
+    }
+    let cancelled = 0;
+    for (const owner of [...state.owners.values()]) {
+      if (releaseOwner(owner, reason)) {
+        cancelled += 1;
+      }
+    }
+    state.intentGenerations.clear();
+    clientStates.delete(client);
+    return cancelled;
+  }
+
+  function schedule(client, request = {}) {
+    const deviceId = String(request.deviceId || '').trim();
+    const intentGeneration = Number(request.intentGeneration || 0);
+    const result = request.result && typeof request.result === 'object'
+      ? request.result
+      : {};
+    const state = stateFor(client);
+    if (!deviceId
+      || !Number.isSafeInteger(intentGeneration)
+      || intentGeneration <= 0
+      || state.intentGenerations.get(deviceId) !== intentGeneration
+      || result.error !== 'CAPTURE_TRANSITION_IN_PROGRESS') {
+      return false;
+    }
+
+    let owner = state.owners.get(deviceId);
+    if (owner && owner.intentGeneration !== intentGeneration) {
+      releaseOwner(owner, 'superseded');
+      owner = null;
+    }
+    const transitionTimeoutMs = clamp(
+      finitePositive(result.transitionTimeoutMs, 11_000),
+      minimumRetryAfterMs,
+      maximumTotalMs
+    );
+    if (!owner) {
+      const totalWindowMs = clamp(
+        transitionTimeoutMs + completionMarginMs,
+        minimumTotalMs,
+        maximumTotalMs
+      );
+      owner = {
+        client,
+        deviceId,
+        intentGeneration,
+        attemptCount: 0,
+        deadlineAtEpochMs: now() + totalWindowMs,
+        timer: null,
+        phase: 'created',
+        cancelled: false,
+        cancelReason: '',
+        waitToken: 0,
+        retry: request.retry,
+        onTerminal: request.onTerminal,
+        transitionTimeoutMs
+      };
+      state.owners.set(deviceId, owner);
+      activeOwners.add(owner);
+    } else {
+      owner.retry = request.retry;
+      owner.onTerminal = request.onTerminal;
+      owner.transitionTimeoutMs = transitionTimeoutMs;
+      if (owner.timer) {
+        clearTimer(owner.timer);
+        owner.timer = null;
+      }
+    }
+
+    if (owner.attemptCount >= maxAttempts) {
+      failOwner(owner, 'CAPTURE_TRANSITION_ATTEMPT_LIMIT');
+      return false;
+    }
+
+    const retryAfterMs = clamp(
+      finitePositive(result.retryAfterMs, minimumRetryAfterMs),
+      minimumRetryAfterMs,
+      maximumRetryAfterMs
+    );
+    const waitToken = ++owner.waitToken;
+    owner.phase = 'waiting-stop';
+    const transitionPromise = result.transitionPromise
+      && typeof result.transitionPromise.then === 'function'
+      ? result.transitionPromise
+      : Promise.resolve({
+          captureStopConfirmed: false,
+          evidenceUnavailable: true
+        });
+
+    void Promise.resolve(transitionPromise).then(
+      settlement => {
+        if (!ownerIsCurrent(owner) || owner.waitToken !== waitToken) {
+          return;
+        }
+        const remainingMs = owner.deadlineAtEpochMs - now();
+        const captureStopConfirmed = settlement?.captureStopConfirmed === true;
+        const requiredRetryBudgetMs = captureStopConfirmed
+          ? retryAfterMs
+          : owner.transitionTimeoutMs + retryAfterMs;
+        if (remainingMs < requiredRetryBudgetMs) {
+          failOwner(owner, 'CAPTURE_TRANSITION_TIMEOUT', {
+            captureStopConfirmed,
+            remainingMs: Math.max(0, remainingMs)
+          });
+          return;
+        }
+        owner.phase = 'retry-delay';
+        owner.timer = setTimer(() => {
+          if (!ownerIsCurrent(owner) || owner.waitToken !== waitToken) {
+            return;
+          }
+          owner.timer = null;
+          owner.phase = 'retrying';
+          owner.attemptCount += 1;
+          const retryContext = {
+            deviceId: owner.deviceId,
+            intentGeneration: owner.intentGeneration,
+            attemptCount: owner.attemptCount,
+            deadlineAtEpochMs: owner.deadlineAtEpochMs,
+            captureStopConfirmed
+          };
+          void Promise.resolve()
+            .then(() => owner.retry?.(retryContext))
+            .then(() => {
+              if (ownerIsCurrent(owner) && owner.phase === 'retrying') {
+                failOwner(owner, 'CAPTURE_TRANSITION_RETRY_NOT_SETTLED');
+              }
+            })
+            .catch(error => {
+              failOwner(owner, 'CAPTURE_TRANSITION_RETRY_FAILED', {
+                detail: error instanceof Error ? error.message : String(error || '')
+              });
+            });
+        }, Math.min(retryAfterMs, remainingMs));
+        owner.timer?.unref?.();
+      },
+      error => {
+        failOwner(owner, 'CAPTURE_TRANSITION_WAIT_FAILED', {
+          detail: error instanceof Error ? error.message : String(error || '')
+        });
+      }
+    );
+    return true;
+  }
+
+  function snapshot() {
+    const owners = [...activeOwners].filter(ownerIsCurrent);
+    return {
+      activeOwnerCount: owners.length,
+      timerCount: owners.filter(owner => !!owner.timer).length,
+      waitingStopCount: owners.filter(owner => owner.phase === 'waiting-stop').length,
+      retryingCount: owners.filter(owner => owner.phase === 'retrying').length,
+      attemptCount: owners.reduce((total, owner) => total + owner.attemptCount, 0),
+      terminal: owners.length === 0
+    };
+  }
+
+  return Object.freeze({
+    beginIntent,
+    schedule,
+    complete,
+    cancelClient,
+    snapshot
+  });
+}

package/src/mode4-atlas-pool.js

@@ -51,6 +51,7 @@ export class Mode4AtlasPool {
       : callbacks => new Mode4AtlasSession(callbacks);
     this.onStatus = typeof options.onStatus === 'function' ? options.onStatus : () => {};
     this.entries = new Map();
+    this.closingByKey = new Map();
   }
 
   acquire(config, callbacks = {}) {
@@ -65,6 +66,7 @@ export class Mode4AtlasPool {
         streamId: `mode4-atlas-shared-${randomUUID()}`
       };
       entry.session = this.createSession({
+        startAfter: this.closingByKey.get(key) || null,
         onFrame: output => {
           for (const listener of entry.clients.values()) listener.onFrame?.(output);
         },
@@ -100,7 +102,14 @@ export class Mode4AtlasPool {
         entry.clients.delete(clientId);
         if (entry.clients.size === 0) {
           this.entries.delete(key);
-          entry.session.close();
+          const closePromise = Promise.resolve(entry.session.close());
+          this.closingByKey.set(key, closePromise);
+          const retireCloseOwner = () => {
+            if (this.closingByKey.get(key) === closePromise) {
+              this.closingByKey.delete(key);
+            }
+          };
+          void closePromise.then(retireCloseOwner, retireCloseOwner);
         }
       }
     };
@@ -116,8 +125,13 @@ export class Mode4AtlasPool {
     return this.entries.size;
   }
 
-  close() {
-    for (const entry of this.entries.values()) entry.session.close();
+  async close() {
+    const closePromises = [...this.closingByKey.values()];
+    for (const entry of this.entries.values()) {
+      closePromises.push(Promise.resolve(entry.session.close()));
+    }
     this.entries.clear();
+    this.closingByKey.clear();
+    await Promise.allSettled(closePromises);
   }
 }

package/src/mode4-atlas-worker.js

@@ -36,6 +36,10 @@ let encoderOutputSeen = false;
 let encoderGeneration = 0;
 let encoderRestartTimer = null;
 let encoderStartupTimer = null;
+let encoderStopPromise = null;
+let configureRevision = 0;
+let configureChain = Promise.resolve();
+let shutdownPromise = null;
 let inputWaitTimer = null;
 let outputBuffer = Buffer.alloc(0);
 let frameSeq = 0;
@@ -48,6 +52,9 @@ let inputRevision = 0;
 let lastEncodedInputRevision = -1;
 let lastAtlasWriteAtEpochMs = 0;
 const ENCODER_STARTUP_OUTPUT_TIMEOUT_MS = 8_000;
+const ENCODER_STDIN_DRAIN_MS = 250;
+const ENCODER_TERM_EXIT_MS = 500;
+const ENCODER_KILL_EXIT_MS = 750;
 const ATLAS_KEEPALIVE_MS = 1_000;
 
 function clamp(value, min, max, fallback) {
@@ -128,7 +135,7 @@ function buildEncoderCandidates() {
 }
 
 function startEncoder() {
-  if (closed || encoder || encoderCandidates.length === 0) return;
+  if (closed || encoder || encoderStopPromise || encoderCandidates.length === 0) return;
   if (encoderCandidateIndex >= encoderCandidates.length) {
     send({ type: 'status', state: 'error', error: 'No Mode 4 H.264 encoder is available.' });
     return;
@@ -144,9 +151,23 @@ function startEncoder() {
     '-bsf:v', 'h264_metadata=aud=insert', '-f', 'h264', 'pipe:1'
   ];
   const child = spawn(candidate.path, args, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
-  encoder = { child, candidate, inputSeen: false };
+  const encoderEntry = {
+    child,
+    candidate,
+    inputSeen: false,
+    stopping: false,
+    intentionalStop: false
+  };
+  encoder = encoderEntry;
   encoderOutputSeen = false;
   outputBuffer = Buffer.alloc(0);
+  send({
+    type: 'encoder-owner',
+    state: 'active',
+    pid: Number(child.pid || 0),
+    encoderGeneration,
+    encoder: candidate.name
+  });
   child.stdout.on('data', appendEncodedBytes);
   child.stdin.on('error', error => {
     if (encoder?.child === child && !isClosedPipeError(error)) {
@@ -163,8 +184,20 @@ function startEncoder() {
     encoderStartupTimer = null;
     const wasCurrent = encoder?.child === child;
     if (wasCurrent) encoder = null;
-    flushEncodedUnit();
-    if (closed) return;
+    send({
+      type: 'encoder-owner',
+      state: 'exited',
+      pid: Number(child.pid || 0),
+      encoderGeneration,
+      encoder: candidate.name,
+      code
+    });
+    if (!closed && !encoderEntry.intentionalStop) {
+      flushEncodedUnit();
+    } else {
+      outputBuffer = Buffer.alloc(0);
+    }
+    if (closed || encoderEntry.intentionalStop) return;
     send({ type: 'status', state: 'encoder-restart', encoder: candidate.name, code, emitted: encoderOutputSeen });
     clearTimeout(encoderRestartTimer);
     encoderRestartTimer = setTimeout(startEncoder, encoderOutputSeen ? 800 : 120);
@@ -189,16 +222,71 @@ function armEncoderStartupTimer(child, candidate) {
   }, ENCODER_STARTUP_OUTPUT_TIMEOUT_MS);
 }
 
-function stopEncoder() {
+function waitForChildExit(child, timeoutMs) {
+  if (!child || child.exitCode !== null || child.signalCode !== null) {
+    return Promise.resolve(true);
+  }
+  return new Promise(resolve => {
+    let settled = false;
+    let timer = null;
+    const finish = exited => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      child.off('exit', handleExit);
+      child.off('close', handleExit);
+      resolve(exited);
+    };
+    const handleExit = () => finish(true);
+    child.once('exit', handleExit);
+    child.once('close', handleExit);
+    timer = setTimeout(() => finish(
+      child.exitCode !== null || child.signalCode !== null
+    ), Math.max(1, Number(timeoutMs || 0)));
+    timer.unref?.();
+  });
+}
+
+async function stopEncoder(reason = 'stop') {
   clearTimeout(encoderRestartTimer);
   encoderRestartTimer = null;
   clearTimeout(encoderStartupTimer);
   encoderStartupTimer = null;
-  const child = encoder?.child;
-  encoder = null;
-  if (!child) return;
-  try { child.stdin.end(); } catch {}
-  setTimeout(() => { try { child.kill(); } catch {} }, 250).unref?.();
+  if (encoderStopPromise) return encoderStopPromise;
+  const encoderEntry = encoder;
+  const child = encoderEntry?.child;
+  if (!child) return true;
+  encoderEntry.stopping = true;
+  encoderEntry.intentionalStop = true;
+
+  const stopPromise = (async () => {
+    try { child.stdin.end(); } catch {}
+    let exited = await waitForChildExit(child, ENCODER_STDIN_DRAIN_MS);
+    if (!exited) {
+      try { child.kill('SIGTERM'); } catch {}
+      exited = await waitForChildExit(child, ENCODER_TERM_EXIT_MS);
+    }
+    if (!exited) {
+      try { child.kill('SIGKILL'); } catch {}
+      exited = await waitForChildExit(child, ENCODER_KILL_EXIT_MS);
+    }
+    if (!exited) {
+      send({
+        type: 'status',
+        state: 'encoder-stop-failed',
+        error: `Mode 4 encoder pid ${Number(child.pid || 0)} did not exit during ${reason}.`,
+        pid: Number(child.pid || 0),
+        encoderGeneration
+      });
+      return false;
+    }
+    if (encoder?.child === child) encoder = null;
+    return true;
+  })().finally(() => {
+    if (encoderStopPromise === stopPromise) encoderStopPromise = null;
+  });
+  encoderStopPromise = stopPromise;
+  return stopPromise;
 }
 
 function findStartCodes(buffer) {
@@ -374,7 +462,8 @@ function ingestFrame(message) {
 
 function writeAtlasFrame() {
   if (latestTiles.size === 0) return;
-  if (!encoder) {
+  if (!encoder || encoder.stopping) {
+    if (encoder?.stopping) return;
     startEncoder();
     return;
   }
@@ -438,7 +527,8 @@ function startComposeClock() {
   tickTimer = setTimeout(tick, intervalMs);
 }
 
-function configure(value) {
+async function configure(value, revision) {
+  if (closed) return;
   const next = normalizeConfig(value);
   const encoderChanged = next.width !== config.width || next.height !== config.height || next.fps !== config.fps;
   config = next;
@@ -457,7 +547,8 @@ function configure(value) {
   }, 3000) : null;
   rebuildLayout();
   if (encoderChanged || !encoder) {
-    stopEncoder();
+    const stopped = await stopEncoder('reconfigure');
+    if (!stopped || closed || revision !== configureRevision) return;
     encoderCandidates = buildEncoderCandidates();
     encoderCandidateIndex = 0;
     if (latestTiles.size > 0) startEncoder();
@@ -465,22 +556,44 @@ function configure(value) {
   startComposeClock();
 }
 
+function queueConfigure(value) {
+  const revision = ++configureRevision;
+  configureChain = configureChain
+    .then(() => configure(value, revision))
+    .catch(error => {
+      if (!closed) {
+        send({
+          type: 'status',
+          state: 'configure-error',
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    });
+  return configureChain;
+}
+
 process.on('message', message => {
-  if (message?.type === 'configure') configure(message);
+  if (message?.type === 'configure') void queueConfigure(message);
   else if (message?.type === 'frame') ingestFrame(message);
-  else if (message?.type === 'close') shutdown();
+  else if (message?.type === 'close') void shutdown();
 });
 
 function shutdown() {
-  if (closed) return;
+  if (shutdownPromise) return shutdownPromise;
   closed = true;
   clearTimeout(tickTimer);
   clearTimeout(inputWaitTimer);
-  stopEncoder();
-  setTimeout(() => process.exit(0), 50).unref?.();
+  clearTimeout(encoderRestartTimer);
+  clearTimeout(encoderStartupTimer);
+  shutdownPromise = (async () => {
+    await configureChain.catch(() => {});
+    const encoderExited = await stopEncoder('worker-shutdown');
+    process.exit(encoderExited ? 0 : 1);
+  })();
+  return shutdownPromise;
 }
 
-process.on('disconnect', shutdown);
-process.on('SIGTERM', shutdown);
-process.on('SIGINT', shutdown);
+process.on('disconnect', () => { void shutdown(); });
+process.on('SIGTERM', () => { void shutdown(); });
+process.on('SIGINT', () => { void shutdown(); });
 send({ type: 'status', state: 'ready' });