@livedesk/hub 0.1.41 → 0.1.43

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

@@ -1,297 +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
-  });
-}
+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
+  });
+}