livedesk 0.1.455 → 0.1.456

package/diagnostics/livedesk-mac-physical-isolation.mjs

@@ -0,0 +1,311 @@
+import { randomBytes } from 'node:crypto';
+import { mkdir, open, readFile, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+export function createMacDiagnosticAbortState() {
+  let requestedSignal = '';
+  let abortError;
+  const listeners = new Set();
+  return Object.freeze({
+    request(signalName) {
+      if (requestedSignal) return false;
+      requestedSignal = String(signalName || 'abort').trim().toUpperCase() || 'ABORT';
+      abortError = new Error(`Mac physical diagnostic interrupted by ${requestedSignal}.`);
+      abortError.code = 'LIVEDESK_MAC_DIAGNOSTIC_ABORTED';
+      abortError.signal = requestedSignal;
+      for (const listener of [...listeners]) {
+        try {
+          listener(abortError);
+        } catch {
+          // Abort notification must remain idempotent even if a listener fails.
+        }
+      }
+      listeners.clear();
+      return true;
+    },
+    get requested() {
+      return Boolean(requestedSignal);
+    },
+    get signal() {
+      return requestedSignal;
+    },
+    get error() {
+      return abortError;
+    },
+    throwIfRequested() {
+      if (abortError) throw abortError;
+    },
+    subscribe(listener) {
+      if (typeof listener !== 'function') {
+        throw new TypeError('Mac diagnostic abort listener must be a function.');
+      }
+      if (abortError) {
+        listener(abortError);
+        return () => {};
+      }
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  });
+}
+
+export function createIdempotentAsyncCleanup(cleanup) {
+  if (typeof cleanup !== 'function') {
+    throw new TypeError('Mac diagnostic cleanup must be a function.');
+  }
+  let cleanupPromise;
+  return () => {
+    if (!cleanupPromise) {
+      cleanupPromise = Promise.resolve().then(cleanup);
+    }
+    return cleanupPromise;
+  };
+}
+
+export function buildMacDiagnosticTeardownPlan({
+  agentStopped = false,
+  hubStopped = false,
+  decodersStopped = false,
+  helperFinalCount = -1
+} = {}) {
+  const reasons = [];
+  if (agentStopped !== true) reasons.push('owned RemoteFast did not confirm exit');
+  if (hubStopped !== true) reasons.push('owned Hub did not confirm exit');
+  if (decodersStopped !== true) reasons.push('owned decoder did not confirm exit');
+  if (Number(helperFinalCount) !== 0) {
+    reasons.push(`capture helper drain ended at ${Number(helperFinalCount)}`);
+  }
+  return Object.freeze({
+    canRemoveState: reasons.length === 0,
+    reasons: Object.freeze(reasons)
+  });
+}
+
+export async function runMacDiagnosticStateTeardown({
+  plan,
+  removeWorkspace,
+  releaseLease
+} = {}) {
+  if (plan?.canRemoveState !== true) {
+    return {
+      removed: false,
+      reasons: Array.isArray(plan?.reasons) ? [...plan.reasons] : ['unsafe teardown plan']
+    };
+  }
+  if (typeof removeWorkspace === 'function') {
+    await removeWorkspace();
+  }
+  if (typeof releaseLease === 'function') {
+    await releaseLease();
+  }
+  return { removed: true, reasons: [] };
+}
+
+export async function settleAllOrThrowFirst(promises) {
+  const results = await Promise.allSettled(Array.from(promises || []));
+  const firstFailure = results.find(result => result.status === 'rejected');
+  if (firstFailure) throw firstFailure.reason;
+  return results.map(result => result.value);
+}
+
+export function runMacDiagnosticAbortableAttempt(
+  getValue,
+  {
+    abortState,
+    timeoutMs = 2_000,
+    label = 'diagnostic attempt'
+  } = {}
+) {
+  if (typeof getValue !== 'function') {
+    return Promise.reject(new TypeError('Mac diagnostic attempt must be a function.'));
+  }
+  const controller = new AbortController();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let unsubscribeAbort = () => {};
+    const finish = (callback, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      unsubscribeAbort();
+      callback(value);
+    };
+    const timeout = setTimeout(() => {
+      const error = new Error(`${label} exceeded ${Math.max(1, timeoutMs)}ms.`);
+      error.code = 'LIVEDESK_MAC_DIAGNOSTIC_ATTEMPT_TIMEOUT';
+      controller.abort(error);
+      finish(reject, error);
+    }, Math.max(1, timeoutMs));
+    timeout.unref?.();
+    if (abortState?.subscribe) {
+      unsubscribeAbort = abortState.subscribe(error => {
+        controller.abort(error);
+        finish(reject, error);
+      });
+    }
+    Promise.resolve()
+      .then(() => {
+        if (settled) return undefined;
+        return getValue(controller.signal);
+      })
+      .then(
+        value => finish(resolve, value),
+        error => finish(reject, error)
+      );
+  });
+}
+
+export function waitForOwnedProcessExit(child, timeoutMs = 10_000) {
+  if (!child || child.exitCode !== null || child.signalCode !== null) {
+    return Promise.resolve(true);
+  }
+  return Promise.race([
+    new Promise(resolve => child.once('exit', () => resolve(true))),
+    delay(timeoutMs).then(() => false)
+  ]);
+}
+
+export async function stopOwnedProcess(child, label, timeoutMs = 10_000) {
+  if (
+    !child
+    || Number(child.pid || 0) <= 1
+    || child.exitCode !== null
+    || child.signalCode !== null
+  ) {
+    return true;
+  }
+  child.kill('SIGTERM');
+  if (await waitForOwnedProcessExit(child, timeoutMs)) return true;
+  child.kill('SIGKILL');
+  if (await waitForOwnedProcessExit(child, 2_000)) return true;
+  throw new Error(`${label} pid ${Number(child.pid || 0)} did not exit after owned-process cleanup.`);
+}
+
+export function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+export async function inspectMacDiagnosticLease({
+  directory = path.join(homedir(), '.livedesk', 'diagnostics'),
+  pidAlive = isProcessAlive
+} = {}) {
+  const lockPath = path.join(path.resolve(directory), 'mac-physical-gate.lock');
+  let owner;
+  try {
+    owner = JSON.parse(await readFile(lockPath, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return Object.freeze({ status: 'missing', path: lockPath, pid: 0 });
+    }
+    return Object.freeze({
+      status: 'unreadable',
+      path: lockPath,
+      pid: 0,
+      error: error instanceof Error ? error.message : String(error)
+    });
+  }
+  const ownerPid = Number(owner?.pid || 0);
+  const ownerToken = String(owner?.token || '').trim();
+  if (!Number.isInteger(ownerPid) || ownerPid <= 1 || ownerToken.length < 16) {
+    return Object.freeze({
+      status: 'unreadable',
+      path: lockPath,
+      pid: ownerPid,
+      error: 'invalid diagnostic lease owner'
+    });
+  }
+  let active;
+  try {
+    active = pidAlive(ownerPid) === true;
+  } catch (error) {
+    return Object.freeze({
+      status: 'unreadable',
+      path: lockPath,
+      pid: ownerPid,
+      error: error instanceof Error ? error.message : String(error)
+    });
+  }
+  return Object.freeze({
+    status: active ? 'active' : 'stale',
+    path: lockPath,
+    pid: ownerPid
+  });
+}
+
+export async function acquireMacDiagnosticLease({
+  directory = path.join(homedir(), '.livedesk', 'diagnostics'),
+  ownerPid = process.pid,
+  token = randomBytes(16).toString('hex'),
+  pidAlive = isProcessAlive
+} = {}) {
+  if (!Number.isInteger(ownerPid) || ownerPid <= 1) {
+    throw new Error(`Invalid Mac diagnostic lease owner pid: ${ownerPid}`);
+  }
+  const lockPath = path.join(path.resolve(directory), 'mac-physical-gate.lock');
+  await mkdir(path.dirname(lockPath), { recursive: true });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    let handle;
+    let created = false;
+    try {
+      handle = await open(lockPath, 'wx', 0o600);
+      created = true;
+      await handle.writeFile(`${JSON.stringify({
+        schemaVersion: 1,
+        pid: ownerPid,
+        token,
+        startedAt: new Date().toISOString()
+      })}\n`, 'utf8');
+      await handle.close();
+      return {
+        path: lockPath,
+        token,
+        ownerPid,
+        async release() {
+          let current;
+          try {
+            current = JSON.parse(await readFile(lockPath, 'utf8'));
+          } catch {
+            return false;
+          }
+          if (String(current?.token || '') !== token || Number(current?.pid || 0) !== ownerPid) {
+            return false;
+          }
+          await rm(lockPath, { force: true });
+          return true;
+        }
+      };
+    } catch (error) {
+      try { await handle?.close(); } catch {}
+      if (error?.code !== 'EEXIST') {
+        if (created) await rm(lockPath, { force: true }).catch(() => undefined);
+        throw error;
+      }
+      let owner;
+      try {
+        owner = JSON.parse(await readFile(lockPath, 'utf8'));
+      } catch {
+        throw new Error(
+          `Mac physical diagnostic lease ownership is unreadable at ${lockPath}; `
+          + 'no process was stopped and the diagnostic did not start.'
+        );
+      }
+      const existingPid = Number(owner?.pid || 0);
+      if (pidAlive(existingPid)) {
+        throw new Error(
+          `Mac physical diagnostic is already running (pid ${existingPid}); `
+          + 'no second capture helper was started.'
+        );
+      }
+      await rm(lockPath, { force: true });
+    }
+  }
+  throw new Error('Unable to acquire the Mac physical diagnostic lease.');
+}