zevairouter 1.0.173 → 1.0.174

package/cli/src/cli/routerProcessLifecycle.js

@@ -0,0 +1,685 @@
+"use strict";
+
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const DEFAULT_TERM_TIMEOUT_MS = 4_000;
+const DEFAULT_KILL_TIMEOUT_MS = 1_000;
+const DEFAULT_POLL_INTERVAL_MS = 100;
+const MAX_WAIT_TIMEOUT_MS = 60_000;
+
+class RouterProcessLifecycleError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "RouterProcessLifecycleError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function lifecycleError(code, message, details) {
+  return new RouterProcessLifecycleError(code, message, details);
+}
+
+function isValidPid(value) {
+  return Number.isInteger(value) && value > 1;
+}
+
+function normalizeListenerPids(value) {
+  if (!Array.isArray(value)) {
+    throw lifecycleError(
+      "LISTENER_ENUMERATION_FAILED",
+      "Listener enumeration did not return an array.",
+    );
+  }
+
+  const pids = [];
+  const seen = new Set();
+  for (const pid of value) {
+    if (!isValidPid(pid)) {
+      throw lifecycleError(
+        "LISTENER_ENUMERATION_FAILED",
+        `Listener enumeration returned an invalid PID: ${String(pid)}.`,
+      );
+    }
+    if (!seen.has(pid)) {
+      seen.add(pid);
+      pids.push(pid);
+    }
+  }
+  return pids.sort((left, right) => left - right);
+}
+
+function normalizePort(value) {
+  if (!Number.isInteger(value) || value < 1 || value > 65_535) {
+    throw lifecycleError("INVALID_INPUT", `Invalid listener port: ${String(value)}.`);
+  }
+  return value;
+}
+
+function normalizeWait(value, name, { allowZero = true } = {}) {
+  const minimum = allowZero ? 0 : 1;
+  if (!Number.isInteger(value) || value < minimum || value > MAX_WAIT_TIMEOUT_MS) {
+    throw lifecycleError(
+      "INVALID_INPUT",
+      `${name} must be an integer from ${minimum} to ${MAX_WAIT_TIMEOUT_MS}.`,
+    );
+  }
+  return value;
+}
+
+function canonicalAbsolutePosixPath(value) {
+  if (
+    typeof value !== "string"
+    || value.length === 0
+    || /[\0\r\n]/.test(value)
+    || !path.posix.isAbsolute(value)
+    || (value.length > 1 && value.endsWith("/"))
+    || path.posix.normalize(value) !== value
+  ) {
+    return null;
+  }
+  return value;
+}
+
+function isAllowedMacOsRouterCwd(cwd, globalRoot) {
+  const root = canonicalAbsolutePosixPath(globalRoot);
+  const candidate = canonicalAbsolutePosixPath(cwd);
+  if (!root || root === "/" || !candidate) return false;
+
+  if (candidate === path.posix.join(root, "zevairouter", "cli", "app")) {
+    return true;
+  }
+
+  const relative = path.posix.relative(root, candidate);
+  const parts = relative.split("/");
+  return parts.length === 3
+    && /^\.zevairouter-[A-Za-z0-9_-]+$/.test(parts[0])
+    && parts[1] === "cli"
+    && parts[2] === "app";
+}
+
+function isExactNextServerCommand(command) {
+  return typeof command === "string"
+    && /^next-server(?: \(v[^()\s]+\))?$/.test(command);
+}
+
+function parseMacOsLsofCwdMetadata(output, expectedPid) {
+  if (typeof output !== "string" || !isValidPid(expectedPid)) return null;
+
+  let pid = null;
+  let command = null;
+  let descriptor = null;
+  let cwd = null;
+  for (const line of output.split(/\r?\n/)) {
+    if (!line) continue;
+    const field = line[0];
+    const value = line.slice(1);
+    if (field === "p") {
+      if (pid != null || !/^\d+$/.test(value)) return null;
+      pid = Number(value);
+    } else if (field === "c") {
+      if (pid == null || command != null) return null;
+      command = value;
+    } else if (field === "f") {
+      if (command == null || descriptor != null) return null;
+      descriptor = value;
+    } else if (field === "n") {
+      if (descriptor !== "cwd" || cwd != null) return null;
+      cwd = value;
+    } else {
+      return null;
+    }
+  }
+
+  if (pid !== expectedPid || command !== "node" || descriptor !== "cwd" || !cwd) {
+    return null;
+  }
+  return { pid, command, cwd };
+}
+
+function parseLinuxProcStatStartToken(output, expectedPid) {
+  if (typeof output !== "string" || !isValidPid(expectedPid) || /[\r\n]/.test(output.trim())) {
+    return null;
+  }
+  const value = output.trim();
+  const openParen = value.indexOf(" (");
+  const closeParen = value.lastIndexOf(") ");
+  if (openParen < 1 || closeParen <= openParen + 2) return null;
+  if (Number(value.slice(0, openParen)) !== expectedPid) return null;
+  const fieldsAfterCommand = value.slice(closeParen + 2).split(/\s+/);
+  const startTime = fieldsAfterCommand[19];
+  if (fieldsAfterCommand.length < 20 || !/^\d+$/.test(startTime)) return null;
+  return `${expectedPid}:${startTime}`;
+}
+
+function outputFromNoMatch(error) {
+  if (error?.status !== 1) return null;
+  if (typeof error.stdout === "string") return error.stdout;
+  if (Buffer.isBuffer(error.stdout)) return error.stdout.toString("utf8");
+  return "";
+}
+
+function parseListenerPidOutput(output) {
+  const pids = [];
+  for (const line of String(output || "").split(/\r?\n/)) {
+    if (!line) continue;
+    const match = line.match(/^(\d+)$/);
+    if (!match) {
+      throw lifecycleError(
+        "LISTENER_ENUMERATION_FAILED",
+        "lsof returned malformed listener metadata.",
+      );
+    }
+    pids.push(Number(match[1]));
+  }
+  return normalizeListenerPids(pids);
+}
+
+function parsePsProcessDetails(output, expectedPid) {
+  const lines = String(output || "").split(/\r?\n/).filter((line) => line.trim());
+  if (lines.length !== 1) return null;
+  const match = lines[0].match(/^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.+?)\s*$/);
+  if (!match || Number(match[1]) !== expectedPid || !match[4]) return null;
+  return {
+    pid: Number(match[1]),
+    ppid: Number(match[2]),
+    state: match[3],
+    command: match[4],
+  };
+}
+
+function parsePsStartToken(output, expectedPid) {
+  const lines = String(output || "").split(/\r?\n/).filter((line) => line.trim());
+  if (lines.length !== 1) return null;
+  const match = lines[0].match(/^\s*(\d+)\s+(.+?)\s*$/);
+  if (!match || Number(match[1]) !== expectedPid || !match[2]) return null;
+  return match[2];
+}
+
+function defaultSyncSleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function createMacOsProcessLifecycleDependencies(options = {}) {
+  const run = options.execFileSync || execFileSync;
+  const lsofPath = options.lsofPath || "/usr/sbin/lsof";
+  const psPath = options.psPath || "/bin/ps";
+  const processKill = options.processKill || process.kill.bind(process);
+  const sleep = options.sleep || defaultSyncSleep;
+  const timeoutMs = options.commandTimeoutMs ?? 5_000;
+  if (typeof run !== "function" || typeof processKill !== "function" || typeof sleep !== "function") {
+    throw lifecycleError("INVALID_INPUT", "Invalid macOS lifecycle dependency override.");
+  }
+  if (typeof lsofPath !== "string" || !lsofPath || typeof psPath !== "string" || !psPath) {
+    throw lifecycleError("INVALID_INPUT", "macOS lifecycle executable paths are required.");
+  }
+  normalizeWait(timeoutMs, "commandTimeoutMs", { allowZero: false });
+
+  const runOptions = {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: timeoutMs,
+    windowsHide: true,
+  };
+
+  return {
+    listListenerPids(port) {
+      normalizePort(port);
+      let output;
+      try {
+        output = run(lsofPath, [
+          "-nP",
+          `-tiTCP:${port}`,
+          "-sTCP:LISTEN",
+        ], runOptions);
+      } catch (error) {
+        output = outputFromNoMatch(error);
+        if (output == null) throw error;
+      }
+      return parseListenerPidOutput(output);
+    },
+
+    readProcessIdentity(pid) {
+      if (!isValidPid(pid)) return null;
+      let detailsOutput;
+      let startOutput;
+      try {
+        detailsOutput = run(psPath, [
+          "-p",
+          String(pid),
+          "-o",
+          "pid=,ppid=,state=,command=",
+        ], runOptions);
+      } catch (error) {
+        detailsOutput = outputFromNoMatch(error);
+        if (detailsOutput == null) throw error;
+      }
+      const details = parsePsProcessDetails(detailsOutput, pid);
+      if (!details) return null;
+      try {
+        startOutput = run(psPath, [
+          "-p",
+          String(pid),
+          "-o",
+          "pid=,lstart=",
+        ], runOptions);
+      } catch (error) {
+        startOutput = outputFromNoMatch(error);
+        if (startOutput == null) throw error;
+      }
+      const startToken = parsePsStartToken(startOutput, pid);
+      return startToken == null ? null : { ...details, startToken };
+    },
+
+    readLsofMetadata(pid) {
+      if (!isValidPid(pid)) return "";
+      try {
+        return run(lsofPath, [
+          "-n",
+          "-P",
+          "-a",
+          "-p",
+          String(pid),
+          "-d",
+          "cwd",
+          "-F",
+          "pcn",
+        ], runOptions);
+      } catch (error) {
+        const output = outputFromNoMatch(error);
+        if (output == null) throw error;
+        return output;
+      }
+    },
+
+    sendSignal(pid, signal) {
+      processKill(pid, signal);
+    },
+
+    sleep,
+  };
+}
+
+function validStartToken(value) {
+  return (typeof value === "number" && Number.isFinite(value))
+    || (typeof value === "string" && value.length > 0 && !/[\0\r\n]/.test(value));
+}
+
+function requireDependencies(dependencies, names) {
+  if (!dependencies || typeof dependencies !== "object") {
+    throw lifecycleError("INVALID_INPUT", "Lifecycle dependencies are required.");
+  }
+  for (const name of names) {
+    if (typeof dependencies[name] !== "function") {
+      throw lifecycleError("INVALID_INPUT", `Lifecycle dependency ${name} is required.`);
+    }
+  }
+}
+
+function readOwnedMacOsOrphanIdentity(pid, globalRoot, dependencies) {
+  let processInfo;
+  let lsofOutput;
+  try {
+    processInfo = dependencies.readProcessIdentity(pid);
+    lsofOutput = dependencies.readLsofMetadata(pid);
+  } catch (error) {
+    throw lifecycleError(
+      "OWNERSHIP_UNPROVEN",
+      `Could not inspect listener PID ${pid}: ${error.message}`,
+      { pid, cause: error },
+    );
+  }
+
+  if (
+    !processInfo
+    || processInfo.pid !== pid
+    || processInfo.ppid !== 1
+    || typeof processInfo.state !== "string"
+    || processInfo.state.length === 0
+    || processInfo.state.startsWith("Z")
+    || !isExactNextServerCommand(processInfo.command)
+    || !validStartToken(processInfo.startToken)
+  ) {
+    throw lifecycleError(
+      "OWNERSHIP_UNPROVEN",
+      `Listener PID ${pid} is not an exact orphaned ZevaiRouter next-server process.`,
+      { pid },
+    );
+  }
+
+  const metadata = parseMacOsLsofCwdMetadata(lsofOutput, pid);
+  if (!metadata || !isAllowedMacOsRouterCwd(metadata.cwd, globalRoot)) {
+    throw lifecycleError(
+      "OWNERSHIP_UNPROVEN",
+      `Listener PID ${pid} does not have an exact ZevaiRouter runtime working directory.`,
+      { pid },
+    );
+  }
+
+  return Object.freeze({
+    pid,
+    ppid: processInfo.ppid,
+    command: processInfo.command,
+    startToken: processInfo.startToken,
+    lsofCommand: metadata.command,
+    cwd: metadata.cwd,
+  });
+}
+
+function resolveOwnedMacOsOrphanListeners(options = {}) {
+  const { globalRoot, dependencies } = options;
+  requireDependencies(dependencies, ["readProcessIdentity", "readLsofMetadata"]);
+  if (!canonicalAbsolutePosixPath(globalRoot) || globalRoot === "/") {
+    throw lifecycleError("INVALID_INPUT", "globalRoot must be a canonical absolute path.");
+  }
+
+  const listenerPids = normalizeListenerPids(options.listenerPids || []);
+  return listenerPids.map((pid) => (
+    readOwnedMacOsOrphanIdentity(pid, globalRoot, dependencies)
+  ));
+}
+
+function sameIdentity(left, right) {
+  return Boolean(left && right)
+    && left.pid === right.pid
+    && left.ppid === right.ppid
+    && left.command === right.command
+    && Object.is(left.startToken, right.startToken)
+    && left.lsofCommand === right.lsofCommand
+    && left.cwd === right.cwd;
+}
+
+function enumerateListenerPids(port, dependencies) {
+  try {
+    return normalizeListenerPids(dependencies.listListenerPids(port));
+  } catch (error) {
+    if (error instanceof RouterProcessLifecycleError) throw error;
+    throw lifecycleError(
+      "LISTENER_ENUMERATION_FAILED",
+      `Could not enumerate listeners on port ${port}: ${error.message}`,
+      { port, cause: error },
+    );
+  }
+}
+
+function assertKnownListenerSubset(currentPids, capturedByPid, port) {
+  const unknownPids = currentPids.filter((pid) => !capturedByPid.has(pid));
+  if (unknownPids.length > 0) {
+    throw lifecycleError(
+      "LISTENER_SET_CHANGED",
+      `Port ${port} gained an unverified listener; no further process was signaled.`,
+      { port, unknownPids },
+    );
+  }
+}
+
+function revalidateCapturedListeners(pids, capturedByPid, globalRoot, dependencies) {
+  const refreshed = pids.map((pid) => (
+    readOwnedMacOsOrphanIdentity(pid, globalRoot, dependencies)
+  ));
+  for (const identity of refreshed) {
+    if (!sameIdentity(capturedByPid.get(identity.pid), identity)) {
+      throw lifecycleError(
+        "PROCESS_IDENTITY_CHANGED",
+        `Listener PID ${identity.pid} changed identity before signaling.`,
+        { pid: identity.pid },
+      );
+    }
+  }
+}
+
+function remainingCapturedProcessPids(pids, capturedByPid, dependencies) {
+  const remaining = [];
+  for (const pid of pids) {
+    let processInfo;
+    try {
+      processInfo = dependencies.readProcessIdentity(pid);
+    } catch (error) {
+      throw lifecycleError(
+        "OWNERSHIP_UNPROVEN",
+        `Could not inspect captured PID ${pid}: ${error.message}`,
+        { pid, cause: error },
+      );
+    }
+    if (!processInfo || String(processInfo.state || "").startsWith("Z")) continue;
+    const captured = capturedByPid.get(pid);
+    if (
+      !captured
+      || processInfo.pid !== captured.pid
+      || processInfo.ppid !== captured.ppid
+      || processInfo.command !== captured.command
+      || !Object.is(processInfo.startToken, captured.startToken)
+    ) {
+      throw lifecycleError(
+        "PROCESS_IDENTITY_CHANGED",
+        `Captured PID ${pid} changed identity while waiting for shutdown.`,
+        { pid },
+      );
+    }
+    remaining.push(pid);
+  }
+  return remaining;
+}
+
+function signalListeners(
+  pids,
+  signal,
+  port,
+  capturedByPid,
+  globalRoot,
+  dependencies,
+  { requireListener = true } = {},
+) {
+  const signaled = [];
+  for (const pid of pids) {
+    // A previous listener signal or a slow lsof call can create a PID-reuse
+    // window. Recheck membership, then identity, immediately before each kill.
+    const current = enumerateListenerPids(port, dependencies);
+    assertKnownListenerSubset(current, capturedByPid, port);
+    if (requireListener && !current.includes(pid)) continue;
+    revalidateCapturedListeners([pid], capturedByPid, globalRoot, dependencies);
+    try {
+      dependencies.sendSignal(pid, signal);
+      signaled.push(pid);
+    } catch (error) {
+      const current = enumerateListenerPids(port, dependencies);
+      assertKnownListenerSubset(current, capturedByPid, port);
+      if (current.includes(pid)) {
+        throw lifecycleError(
+          "SIGNAL_FAILED",
+          `Failed to send ${signal} to owned listener PID ${pid}: ${error.message}`,
+          { pid, signal, cause: error },
+        );
+      }
+    }
+  }
+  return signaled;
+}
+
+function waitForRelease({
+  port,
+  processPids,
+  timeoutMs,
+  pollIntervalMs,
+  capturedByPid,
+  dependencies,
+}) {
+  let remainingMs = timeoutMs;
+  while (true) {
+    const listenerPids = enumerateListenerPids(port, dependencies);
+    assertKnownListenerSubset(listenerPids, capturedByPid, port);
+    const liveProcessPids = remainingCapturedProcessPids(
+      processPids,
+      capturedByPid,
+      dependencies,
+    );
+    if ((listenerPids.length === 0 && liveProcessPids.length === 0) || remainingMs === 0) {
+      return { listenerPids, processPids: liveProcessPids };
+    }
+    const delay = Math.min(pollIntervalMs, remainingMs);
+    dependencies.sleep(delay);
+    remainingMs -= delay;
+  }
+}
+
+function lifecycleResult(initialPids, termPids = [], killPids = []) {
+  return {
+    stopped: termPids.length > 0 || killPids.length > 0,
+    listenerPids: initialPids,
+    termSignaledPids: termPids,
+    killSignaledPids: killPids,
+    forced: killPids.length > 0,
+  };
+}
+
+function stopOwnedMacOsOrphanListeners(options = {}) {
+  const platform = options.platform ?? process.platform;
+  if (platform !== "darwin") {
+    throw lifecycleError(
+      "UNSUPPORTED_PLATFORM",
+      "Orphan next-server recovery is restricted to macOS.",
+    );
+  }
+
+  const port = normalizePort(options.port);
+  const globalRoot = options.globalRoot;
+  const termTimeoutMs = normalizeWait(
+    options.termTimeoutMs ?? DEFAULT_TERM_TIMEOUT_MS,
+    "termTimeoutMs",
+  );
+  const killTimeoutMs = normalizeWait(
+    options.killTimeoutMs ?? DEFAULT_KILL_TIMEOUT_MS,
+    "killTimeoutMs",
+  );
+  const pollIntervalMs = normalizeWait(
+    options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+    "pollIntervalMs",
+    { allowZero: false },
+  );
+  const { dependencies } = options;
+  requireDependencies(dependencies, [
+    "listListenerPids",
+    "readProcessIdentity",
+    "readLsofMetadata",
+    "sendSignal",
+    "sleep",
+  ]);
+
+  const initialPids = enumerateListenerPids(port, dependencies);
+  if (initialPids.length === 0) return lifecycleResult([]);
+
+  // Resolve every listener before signaling any of them. A mixed listener set
+  // therefore fails atomically without touching even the verified processes.
+  const captured = resolveOwnedMacOsOrphanListeners({
+    listenerPids: initialPids,
+    globalRoot,
+    dependencies,
+  });
+  const capturedByPid = new Map(captured.map((identity) => [identity.pid, identity]));
+
+  revalidateCapturedListeners(initialPids, capturedByPid, globalRoot, dependencies);
+  const beforeTerm = enumerateListenerPids(port, dependencies);
+  assertKnownListenerSubset(beforeTerm, capturedByPid, port);
+  const beforeTermProcesses = remainingCapturedProcessPids(
+    initialPids,
+    capturedByPid,
+    dependencies,
+  );
+  if (beforeTerm.length === 0 && beforeTermProcesses.length === 0) {
+    return lifecycleResult(initialPids);
+  }
+
+  const termSignaledPids = signalListeners(
+    beforeTermProcesses,
+    "SIGTERM",
+    port,
+    capturedByPid,
+    globalRoot,
+    dependencies,
+    { requireListener: false },
+  );
+  let remaining = waitForRelease({
+    port,
+    processPids: initialPids,
+    timeoutMs: termTimeoutMs,
+    pollIntervalMs,
+    capturedByPid,
+    dependencies,
+  });
+  if (remaining.listenerPids.length === 0 && remaining.processPids.length === 0) {
+    const confirmed = enumerateListenerPids(port, dependencies);
+    if (confirmed.length !== 0) assertKnownListenerSubset(confirmed, capturedByPid, port);
+    if (confirmed.length !== 0) {
+      throw lifecycleError(
+        "PORT_STILL_OCCUPIED",
+        `Port ${port} was reclaimed before release could be confirmed.`,
+        { port, listenerPids: confirmed },
+      );
+    }
+    return lifecycleResult(initialPids, termSignaledPids);
+  }
+
+  revalidateCapturedListeners(remaining.processPids, capturedByPid, globalRoot, dependencies);
+  const beforeKill = enumerateListenerPids(port, dependencies);
+  assertKnownListenerSubset(beforeKill, capturedByPid, port);
+  const beforeKillProcesses = remainingCapturedProcessPids(
+    remaining.processPids,
+    capturedByPid,
+    dependencies,
+  );
+  if (beforeKill.length === 0 && beforeKillProcesses.length === 0) {
+    return lifecycleResult(initialPids, termSignaledPids);
+  }
+
+  const killSignaledPids = signalListeners(
+    beforeKillProcesses,
+    "SIGKILL",
+    port,
+    capturedByPid,
+    globalRoot,
+    dependencies,
+    { requireListener: false },
+  );
+  remaining = waitForRelease({
+    port,
+    processPids: beforeKillProcesses,
+    timeoutMs: killTimeoutMs,
+    pollIntervalMs,
+    capturedByPid,
+    dependencies,
+  });
+  if (remaining.listenerPids.length !== 0 || remaining.processPids.length !== 0) {
+    throw lifecycleError(
+      "PORT_STILL_OCCUPIED",
+      `Owned next-server processes did not fully release port ${port}.`,
+      {
+        port,
+        listenerPids: remaining.listenerPids,
+        processPids: remaining.processPids,
+      },
+    );
+  }
+
+  const confirmed = enumerateListenerPids(port, dependencies);
+  if (confirmed.length !== 0) {
+    assertKnownListenerSubset(confirmed, capturedByPid, port);
+    throw lifecycleError(
+      "PORT_STILL_OCCUPIED",
+      `Port ${port} was reclaimed before release could be confirmed.`,
+      { port, listenerPids: confirmed },
+    );
+  }
+  return lifecycleResult(initialPids, termSignaledPids, killSignaledPids);
+}
+
+module.exports = {
+  RouterProcessLifecycleError,
+  createMacOsProcessLifecycleDependencies,
+  isAllowedMacOsRouterCwd,
+  isExactNextServerCommand,
+  parseLinuxProcStatStartToken,
+  parseMacOsLsofCwdMetadata,
+  resolveOwnedMacOsOrphanListeners,
+  stopOwnedMacOsOrphanListeners,
+};