livedesk 0.1.458 → 0.1.460

package/diagnostics/livedesk-transport-physical.mjs

@@ -0,0 +1,508 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  REQUIRED_PHASES,
+  buildTransportPhysicalReport,
+  genericTransportPhysicalError,
+  isTransportPhysicalPhaseEvidence
+} from './livedesk-transport-physical-core.mjs';
+
+const DEFAULT_HUB_URL = 'http://127.0.0.1:5179';
+const DEFAULT_PHASE_TIMEOUT_MS = 15_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 5_000;
+const HUB_COMMAND_TIMEOUT_MS = 8_000;
+const CONTROL_REQUEST_TIMEOUT_MS = 10_000;
+const START_REQUEST_TIMEOUT_MS = 15_000;
+const CLEANUP_CONFIRM_TIMEOUT_MS = 20_000;
+const CLEANUP_RETRY_DELAY_MS = 250;
+const DEFAULT_TTL_MS = 150_000;
+const MIN_TTL_MARGIN_MS = 20_000;
+
+export function normalizeTransportPhysicalTiming(options = {}) {
+  const ttlMs = Math.max(15_000, Math.min(180_000, Number(options.ttlMs) || DEFAULT_TTL_MS));
+  const phaseTimeoutMs = Math.max(
+    3_000,
+    Math.min(15_000, Number(options.phaseTimeoutMs) || DEFAULT_PHASE_TIMEOUT_MS));
+  const requestTimeoutMs = Math.max(
+    500,
+    Math.min(10_000, Number(options.requestTimeoutMs) || DEFAULT_REQUEST_TIMEOUT_MS));
+  const acquireCommandBudgetMs = HUB_COMMAND_TIMEOUT_MS;
+  const transitionCommandBudgetMs = (REQUIRED_PHASES.length - 1) * HUB_COMMAND_TIMEOUT_MS;
+  const releaseCommandBudgetMs = HUB_COMMAND_TIMEOUT_MS;
+  const commandBudgetMs = acquireCommandBudgetMs
+    + transitionCommandBudgetMs
+    + releaseCommandBudgetMs;
+  const frameEvidenceBudgetMs = REQUIRED_PHASES.length * phaseTimeoutMs;
+  const requiredTtlMs = frameEvidenceBudgetMs + commandBudgetMs + MIN_TTL_MARGIN_MS;
+  if (requiredTtlMs > ttlMs) {
+    throw new Error(
+      `transport-physical timing budget invalid: ${REQUIRED_PHASES.length} frame evidence budgets, `
+      + `acquire/transition/release command budgets, and ${MIN_TTL_MARGIN_MS}ms margin `
+      + `require at least ${requiredTtlMs}ms TTL.`);
+  }
+  return {
+    ttlMs,
+    phaseTimeoutMs,
+    requestTimeoutMs,
+    requiredTtlMs,
+    ttlMarginMs: MIN_TTL_MARGIN_MS,
+    frameEvidenceBudgetMs,
+    commandBudgetMs,
+    acquireCommandBudgetMs,
+    transitionCommandBudgetMs,
+    releaseCommandBudgetMs
+  };
+}
+
+export function parseTransportPhysicalArgs(argv) {
+  const args = {
+    hubUrl: DEFAULT_HUB_URL,
+    deviceId: '',
+    reportPath: '',
+    ttlMs: DEFAULT_TTL_MS,
+    phaseTimeoutMs: DEFAULT_PHASE_TIMEOUT_MS,
+    requestTimeoutMs: DEFAULT_REQUEST_TIMEOUT_MS
+  };
+  const values = [...argv];
+  if (values[0] === 'diagnose' && values[1] === 'transport-physical') values.splice(0, 2);
+  for (let index = 0; index < values.length; index += 1) {
+    const flag = values[index];
+    const next = values[index + 1];
+    if (flag === '--hub' && next) {
+      args.hubUrl = next;
+      index += 1;
+    } else if (flag === '--device' && next) {
+      args.deviceId = next;
+      index += 1;
+    } else if (flag === '--report' && next) {
+      args.reportPath = path.resolve(next);
+      index += 1;
+    } else if (flag === '--ttl' && next) {
+      args.ttlMs = Number(next);
+      index += 1;
+    } else if (flag === '--phase-timeout' && next) {
+      args.phaseTimeoutMs = Number(next);
+      index += 1;
+    } else if (flag === '--request-timeout' && next) {
+      args.requestTimeoutMs = Number(next);
+      index += 1;
+    } else if (flag === '--help' || flag === '-h') {
+      args.help = true;
+    } else {
+      throw new Error(`Unknown transport-physical option: ${flag}`);
+    }
+  }
+  return {
+    ...args,
+    ...normalizeTransportPhysicalTiming(args)
+  };
+}
+
+export function assertLoopbackHubUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error('transport-physical requires a valid localhost HTTP Hub URL');
+  }
+  if (parsed.protocol !== 'http:'
+    || parsed.username
+    || parsed.password
+    || !['127.0.0.1', 'localhost', '[::1]', '::1'].includes(parsed.hostname)) {
+    throw new Error('transport-physical requires a localhost HTTP Hub URL');
+  }
+  return parsed.origin;
+}
+
+export function combineAbortSignals(signals = []) {
+  const controller = new AbortController();
+  const listeners = [];
+  let disposed = false;
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    for (const [signal, listener] of listeners.splice(0)) {
+      signal.removeEventListener?.('abort', listener);
+    }
+  };
+  const abortFrom = () => {
+    if (!controller.signal.aborted) {
+      controller.abort(new Error('transport diagnostic aborted'));
+    }
+    dispose();
+  };
+  for (const signal of signals.filter(Boolean)) {
+    if (signal.aborted) {
+      abortFrom();
+      break;
+    }
+    const listener = () => abortFrom();
+    signal.addEventListener?.('abort', listener, { once: true });
+    listeners.push([signal, listener]);
+  }
+  return { signal: controller.signal, dispose };
+}
+
+export function abortableDelay(delayMs, signal) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let timer;
+    const finish = (callback, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener?.('abort', onAbort);
+      callback(value);
+    };
+    const onAbort = () => finish(
+      reject,
+      signal?.reason instanceof Error
+        ? signal.reason
+        : new Error('transport diagnostic aborted'));
+    if (signal?.aborted) {
+      onAbort();
+      return;
+    }
+    signal?.addEventListener?.('abort', onAbort, { once: true });
+    timer = setTimeout(() => finish(resolve), Math.max(0, Number(delayMs) || 0));
+  });
+}
+
+export async function requestJson(
+  url,
+  {
+    method = 'GET',
+    token = '',
+    body,
+    signal,
+    requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS
+  } = {}
+) {
+  const timeoutController = new AbortController();
+  const timeout = setTimeout(
+    () => timeoutController.abort(new Error('Hub request timed out.')),
+    Math.max(1, Number(requestTimeoutMs) || DEFAULT_REQUEST_TIMEOUT_MS));
+  const combined = combineAbortSignals([signal, timeoutController.signal]);
+  try {
+    const response = await fetch(url, {
+      method,
+      signal: combined.signal,
+      headers: {
+        accept: 'application/json',
+        ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+        ...(token ? { 'x-livedesk-diagnostic-token': token } : {})
+      },
+      body: body === undefined ? undefined : JSON.stringify(body)
+    });
+    const payload = await response.json().catch(() => ({}));
+    if (!response.ok || payload?.ok === false) {
+      throw new Error(genericTransportPhysicalError(
+        payload?.error,
+        `Hub request failed with status ${response.status}.`));
+    }
+    return payload;
+  } catch (error) {
+    if (timeoutController.signal.aborted && !signal?.aborted) {
+      throw new Error('Hub request timed out.');
+    }
+    if (signal?.aborted || combined.signal.aborted) {
+      throw new Error('transport diagnostic aborted');
+    }
+    throw new Error(genericTransportPhysicalError(error, 'Hub request failed.'));
+  } finally {
+    clearTimeout(timeout);
+    combined.dispose();
+  }
+}
+
+export function hasConfirmedTransportPhysicalRelease(snapshot) {
+  return snapshot?.state === 'completed'
+    && Array.isArray(snapshot?.cleanup)
+    && snapshot.cleanup.some(entry => entry?.state === 'agent-released');
+}
+
+export async function cleanupTransportPhysicalLease({
+  hubUrl,
+  leaseId,
+  token,
+  reason = 'runner-failed',
+  initialSnapshot = null,
+  cleanupTimeoutMs = CLEANUP_CONFIRM_TIMEOUT_MS,
+  requestTimeoutMs = CONTROL_REQUEST_TIMEOUT_MS,
+  retryDelayMs = CLEANUP_RETRY_DELAY_MS
+}) {
+  const deadline = Date.now() + Math.max(1, Number(cleanupTimeoutMs) || CLEANUP_CONFIRM_TIMEOUT_MS);
+  let latest = initialSnapshot;
+  let lastError = null;
+  let attempts = 0;
+  while (Date.now() < deadline) {
+    attempts += 1;
+    const remainingMs = Math.max(1, deadline - Date.now());
+    try {
+      latest = await requestJson(
+        `${hubUrl}/api/remote/diagnostics/transport/${encodeURIComponent(leaseId)}`,
+        {
+          method: 'DELETE',
+          token,
+          body: { reason },
+          requestTimeoutMs: Math.min(
+            Math.max(1, Number(requestTimeoutMs) || CONTROL_REQUEST_TIMEOUT_MS),
+            remainingMs)
+        });
+      lastError = null;
+      if (hasConfirmedTransportPhysicalRelease(latest)) {
+        return { confirmed: true, snapshot: latest, attempts, error: '' };
+      }
+    } catch (error) {
+      lastError = error;
+    }
+    const retryRemainingMs = deadline - Date.now();
+    if (retryRemainingMs <= 0) break;
+    await abortableDelay(Math.min(
+      Math.max(1, Number(retryDelayMs) || CLEANUP_RETRY_DELAY_MS),
+      retryRemainingMs));
+  }
+  return {
+    confirmed: false,
+    snapshot: latest,
+    attempts,
+    error: genericTransportPhysicalError(
+      latest ? latest.error : lastError,
+      'Hub did not confirm Agent diagnostic release.')
+  };
+}
+
+async function chooseDevice(hubUrl, requestedDeviceId, signal, requestTimeoutMs) {
+  if (requestedDeviceId) return requestedDeviceId;
+  const response = await requestJson(`${hubUrl}/api/remote/devices`, {
+    signal,
+    requestTimeoutMs
+  });
+  const candidates = Array.isArray(response?.devices) ? response.devices : [];
+  const candidate = candidates.find(device =>
+    device?.connected === true
+    && device?.latestLiveFrame?.currentGenerationVerified === true
+    && String(device?.latestLiveFrame?.mimeType || '').toLowerCase() === 'video/h264'
+    && String(device?.latestLiveFrame?.frameTransportActive || '').toLowerCase() === 'direct');
+  if (!candidate?.deviceId) {
+    throw new Error('No connected Client has a current Direct H.264 Wall/Control stream.');
+  }
+  return candidate.deviceId;
+}
+
+async function waitForPhase(
+  hubUrl,
+  leaseId,
+  token,
+  phase,
+  deadline,
+  signal,
+  requestTimeoutMs
+) {
+  let latest = null;
+  while (Date.now() < deadline) {
+    signal?.throwIfAborted?.();
+    const remainingMs = Math.max(1, deadline - Date.now());
+    latest = await requestJson(
+      `${hubUrl}/api/remote/diagnostics/transport/${encodeURIComponent(leaseId)}`,
+      {
+        token,
+        signal,
+        requestTimeoutMs: Math.min(requestTimeoutMs, remainingMs)
+      });
+    if (latest.frames?.some(frame => isTransportPhysicalPhaseEvidence(frame, phase))) {
+      return latest;
+    }
+    if (latest.state !== 'active') {
+      throw new Error(genericTransportPhysicalError(
+        latest.error,
+        `transport diagnostic stopped during ${phase}`));
+    }
+    await abortableDelay(Math.min(200, Math.max(1, deadline - Date.now())), signal);
+  }
+  throw new Error(`Timed out waiting for a received ${phase} H.264 SPS+PPS+IDR.`);
+}
+
+async function writeStableJson(reportPath, report) {
+  await fs.mkdir(path.dirname(reportPath), { recursive: true });
+  const temporaryPath = `${reportPath}.${process.pid}.tmp`;
+  await fs.writeFile(temporaryPath, `${JSON.stringify(report, null, 2)}\n`, {
+    encoding: 'utf8',
+    mode: 0o600
+  });
+  await fs.rename(temporaryPath, reportPath);
+}
+
+function defaultReportPath() {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return path.join(os.homedir(), '.livedesk', 'diagnostics', `transport-physical-${stamp}.json`);
+}
+
+export async function runTransportPhysicalDiagnostic(options = {}) {
+  const hubUrl = assertLoopbackHubUrl(options.hubUrl || DEFAULT_HUB_URL);
+  const timing = normalizeTransportPhysicalTiming(options);
+  const lifecycleController = new AbortController();
+  const combined = combineAbortSignals([lifecycleController.signal, options.signal]);
+  const signal = combined.signal;
+  const reportPath = options.reportPath || defaultReportPath();
+  let deviceId = '';
+  let leaseId = '';
+  let token = '';
+  let latest = null;
+  let completed = false;
+  let runError = null;
+
+  const stopForSignal = () => {
+    if (!lifecycleController.signal.aborted) {
+      lifecycleController.abort(new Error('transport diagnostic interrupted'));
+    }
+  };
+  process.once('SIGINT', stopForSignal);
+  process.once('SIGTERM', stopForSignal);
+  try {
+    deviceId = await chooseDevice(
+      hubUrl,
+      options.deviceId || '',
+      signal,
+      timing.requestTimeoutMs);
+    const started = await requestJson(`${hubUrl}/api/remote/diagnostics/transport/start`, {
+      method: 'POST',
+      body: { deviceId, ttlMs: timing.ttlMs },
+      signal,
+      requestTimeoutMs: Math.max(timing.requestTimeoutMs, START_REQUEST_TIMEOUT_MS)
+    });
+    leaseId = started.leaseId;
+    token = started.token;
+    if (!leaseId || !token) throw new Error('Hub did not issue a diagnostic lease.');
+    const actualLeaseMs = Date.parse(started.expiresAt || '') - Date.parse(started.startedAt || '');
+    if (!Number.isFinite(actualLeaseMs) || actualLeaseMs < timing.requiredTtlMs) {
+      throw new Error('Hub diagnostic lease is shorter than the four-phase timing contract.');
+    }
+
+    let frameEvidenceDeadline = Date.now() + timing.phaseTimeoutMs;
+    latest = await waitForPhase(
+      hubUrl,
+      leaseId,
+      token,
+      REQUIRED_PHASES[0],
+      frameEvidenceDeadline,
+      signal,
+      timing.requestTimeoutMs);
+    for (const phase of REQUIRED_PHASES.slice(1)) {
+      await requestJson(
+        `${hubUrl}/api/remote/diagnostics/transport/${encodeURIComponent(leaseId)}/phase`,
+        {
+          method: 'POST',
+          token,
+          body: { phase },
+          signal,
+          requestTimeoutMs: Math.max(timing.requestTimeoutMs, CONTROL_REQUEST_TIMEOUT_MS)
+        });
+      frameEvidenceDeadline = Date.now() + timing.phaseTimeoutMs;
+      latest = await waitForPhase(
+        hubUrl,
+        leaseId,
+        token,
+        phase,
+        frameEvidenceDeadline,
+        signal,
+        timing.requestTimeoutMs);
+    }
+  } catch (error) {
+    runError = error;
+  } finally {
+    if (leaseId && token) {
+      const cleanup = await cleanupTransportPhysicalLease({
+        hubUrl,
+        leaseId,
+        token,
+        reason: runError
+          ? (signal.aborted ? 'runner-aborted' : 'runner-failed')
+          : 'runner-complete',
+        initialSnapshot: latest,
+        requestTimeoutMs: Math.max(timing.requestTimeoutMs, CONTROL_REQUEST_TIMEOUT_MS)
+      });
+      latest = cleanup.snapshot || latest;
+      completed = cleanup.confirmed;
+      if (!completed && !runError) {
+        runError = new Error(cleanup.error || 'Hub did not confirm diagnostic lease cleanup.');
+      }
+    }
+    process.removeListener('SIGINT', stopForSignal);
+    process.removeListener('SIGTERM', stopForSignal);
+    combined.dispose();
+  }
+
+  if (runError) {
+    latest = {
+      ...(latest || {}),
+      ok: false,
+      state: latest?.state === 'completed' ? latest.state : 'failed',
+      error: genericTransportPhysicalError(runError)
+    };
+  }
+  const report = buildTransportPhysicalReport(latest || {}, { hubUrl, deviceId });
+  await writeStableJson(reportPath, report);
+  if (runError) {
+    const failure = new Error(
+      `${genericTransportPhysicalError(runError)} (redacted report: ${reportPath})`);
+    failure.cause = runError;
+    throw failure;
+  }
+  return { report, reportPath };
+}
+
+function printHelp() {
+  console.log([
+    'Usage: livedesk diagnose transport-physical [options]',
+    '',
+    '  --device <id>          Connected Client device ID (auto-selects a Direct H.264 stream)',
+    '  --hub <localhost-url>  Hub UI origin (default http://127.0.0.1:5179)',
+    '  --ttl <ms>             Fail-closed diagnostic lease TTL (default 150000)',
+    '  --phase-timeout <ms>   Per-path SPS+PPS+IDR timeout (3000-15000)',
+    '  --request-timeout <ms> Poll timeout (500-10000; control/start use safe minimums)',
+    '  --report <path>        Redacted JSON report path',
+    '',
+    `Contract: ${REQUIRED_PHASES.length} frame budgets + acquire + `
+      + `${REQUIRED_PHASES.length - 1} transitions + release command budgets `
+      + `+ ${MIN_TTL_MARGIN_MS}ms margin <= TTL.`
+  ].join('\n'));
+}
+
+export async function runTransportPhysicalDiagnosticCli(argv = []) {
+  const args = parseTransportPhysicalArgs(argv);
+  if (args.help) {
+    printHelp();
+    return { status: 'help' };
+  }
+  const { report, reportPath } = await runTransportPhysicalDiagnostic(args);
+  console.log(`[LiveDesk] transport-physical ${report.result.status}: ${report.result.summary}`);
+  console.log(`[LiveDesk] redacted report: ${reportPath}`);
+  if (report.result.status !== 'passed') process.exitCode = 2;
+  return { status: report.result.status, report, reportPath };
+}
+
+const isMain = process.argv[1]
+  && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+if (isMain) {
+  runTransportPhysicalDiagnosticCli(process.argv.slice(2))
+    .catch(error => {
+      console.error(
+        `[LiveDesk] transport-physical failed: ${genericTransportPhysicalError(error)}`);
+      process.exitCode = 1;
+    });
+}
+
+export {
+  DEFAULT_PHASE_TIMEOUT_MS,
+  DEFAULT_REQUEST_TIMEOUT_MS,
+  DEFAULT_TTL_MS,
+  CLEANUP_CONFIRM_TIMEOUT_MS,
+  CONTROL_REQUEST_TIMEOUT_MS,
+  HUB_COMMAND_TIMEOUT_MS,
+  MIN_TTL_MARGIN_MS
+};

package/hub/package.json

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