magus-cli 7.11.6 → 7.11.8

package/src/utils/spawn-bounded.ts

@@ -0,0 +1,202 @@
+/**
+ * spawn-bounded.ts — run an argv (never a shell) with a hard deadline that
+ * actually holds.
+ *
+ * Guarantee: the returned promise settles, exactly once, no later than
+ * `timeoutMs + KILL_SETTLE_MS`, whatever the child or its descendants do — even
+ * if the child never delivers "exit" at all (stuck in uninterruptible I/O). It
+ * never rejects: a spawn failure (ENOENT etc.) comes back as `spawnError`.
+ *
+ * The gotcha this exists for: a timeout kill reaches only the DIRECT child,
+ * while "close" waits for EVERY holder of the stdout/stderr pipes. `git pull`
+ * runs `git fetch`, which runs `ssh`; kill `git pull` and ssh still holds the
+ * inherited pipes, so a promise that settles on "close" waits for ssh to give up
+ * on its own (122 s observed, against a 30 s timeout). So:
+ *  - normal path: settle on "close", so all output is read;
+ *  - after a normal "exit" with no "close": settle after a short grace, or at
+ *    the deadline, whichever comes first — the deadline is never extended;
+ *  - deadline with the child still running: SIGKILL it, settle on its "exit",
+ *    and if that never comes, settle anyway KILL_SETTLE_MS later;
+ *  - `signal` aborted: SIGKILL the child and settle at once; an already-aborted
+ *    signal spawns nothing;
+ *  - on settle: destroy the pipe ends, so an orphan's copies cannot pin the
+ *    event loop.
+ *
+ * No `detached` / process-group kill: on POSIX that is setsid(), which drops the
+ * controlling terminal, and ssh then cannot reach /dev/tty for a key passphrase
+ * or a security-key PIN. The cost is that an orphaned descendant may outlive the
+ * call until it exits or hits SIGPIPE; it blocks nothing.
+ */
+
+import {
+	type ChildProcess,
+	type StdioOptions,
+	spawn,
+} from "node:child_process";
+
+/** How long to wait for "close" after a normal "exit" before settling anyway. */
+const CLOSE_GRACE_MS = 1_500;
+
+/** How long after our SIGKILL to wait for "exit" before settling without it. */
+const KILL_SETTLE_MS = 1_000;
+
+export interface BoundedOptions {
+	cwd?: string;
+	env?: NodeJS.ProcessEnv;
+	/** Defaults to ["pipe", "pipe", "pipe"]. */
+	stdio?: StdioOptions;
+	timeoutMs: number;
+	/** Abort: SIGKILL the child and settle at once. Already aborted: spawn nothing. */
+	signal?: AbortSignal;
+}
+
+export interface BoundedResult {
+	code: number | null;
+	signal: NodeJS.Signals | null;
+	stdout: string;
+	stderr: string;
+	/** True when our deadline fired while the child was still running, and we SIGKILLed it. */
+	timedOut: boolean;
+	/** True when `options.signal` aborted the call (the child, if any, was SIGKILLed). */
+	aborted: boolean;
+	/** Set when the process could not be spawned at all (ENOENT, EACCES, ...). */
+	spawnError?: Error;
+}
+
+function isRunning(child: ChildProcess): boolean {
+	return child.exitCode === null && child.signalCode === null;
+}
+
+export function runBounded(
+	cmd: string,
+	args: string[],
+	options: BoundedOptions,
+): Promise<BoundedResult> {
+	return new Promise((resolve) => {
+		const abortSignal = options.signal;
+		if (abortSignal?.aborted) {
+			resolve({
+				code: null,
+				signal: null,
+				stdout: "",
+				stderr: "",
+				timedOut: false,
+				aborted: true,
+			});
+			return;
+		}
+
+		let stdout = "";
+		let stderr = "";
+		let timedOut = false;
+		let aborted = false;
+		let settled = false;
+		/** Set by "exit"; the child is gone even if "close" never comes. */
+		let exited: { code: number | null; signal: NodeJS.Signals | null } | null =
+			null;
+		let graceTimer: ReturnType<typeof setTimeout> | undefined;
+		let killSettleTimer: ReturnType<typeof setTimeout> | undefined;
+
+		let child: ChildProcess;
+		try {
+			child = spawn(cmd, args, {
+				cwd: options.cwd,
+				env: options.env,
+				stdio: options.stdio ?? ["pipe", "pipe", "pipe"],
+			});
+		} catch (err) {
+			resolve({
+				code: null,
+				signal: null,
+				stdout: "",
+				stderr: "",
+				timedOut: false,
+				aborted: false,
+				spawnError: err instanceof Error ? err : new Error(String(err)),
+			});
+			return;
+		}
+
+		const settle = (
+			code: number | null,
+			signal: NodeJS.Signals | null,
+			spawnError?: Error,
+		) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(deadlineTimer);
+			clearTimeout(graceTimer);
+			clearTimeout(killSettleTimer);
+			abortSignal?.removeEventListener("abort", onAbort);
+			child.stdout?.destroy();
+			child.stderr?.destroy();
+			child.stdin?.destroy();
+			resolve({
+				code,
+				signal,
+				stdout,
+				stderr,
+				timedOut,
+				aborted,
+				spawnError,
+			});
+		};
+
+		/** SIGKILL the child, then settle on its "exit" — or without it, soon. */
+		const killAndBoundSettle = () => {
+			child.kill("SIGKILL");
+			killSettleTimer = setTimeout(
+				() => settle(null, "SIGKILL"),
+				KILL_SETTLE_MS,
+			);
+		};
+
+		// An explicit timer, not spawn's `timeout` option, so we know the kill was
+		// ours. It stays armed until settle: it is also what caps the close grace.
+		// `settle` above reads it, but no child event or abort can fire before this
+		// line runs, so the reference is always initialised by then.
+		const deadlineTimer = setTimeout(() => {
+			if (exited) {
+				// Exited on its own, still waiting for "close": the grace ends here.
+				settle(exited.code, exited.signal);
+				return;
+			}
+			if (!isRunning(child)) {
+				// Exited, but the "exit" event has not been delivered yet.
+				settle(child.exitCode, child.signalCode);
+				return;
+			}
+			timedOut = true;
+			killAndBoundSettle();
+		}, options.timeoutMs);
+
+		function onAbort() {
+			aborted = true;
+			if (exited) {
+				settle(exited.code, exited.signal);
+				return;
+			}
+			if (isRunning(child)) child.kill("SIGKILL");
+			settle(child.exitCode, child.signalCode ?? "SIGKILL");
+		}
+		abortSignal?.addEventListener("abort", onAbort, { once: true });
+
+		child.stdout?.on("data", (b: Buffer | string) => {
+			stdout += b.toString();
+		});
+		child.stderr?.on("data", (b: Buffer | string) => {
+			stderr += b.toString();
+		});
+
+		child.on("error", (err) => settle(null, null, err));
+		child.on("exit", (code, signal) => {
+			exited = { code, signal };
+			if (timedOut) {
+				settle(code, signal);
+				return;
+			}
+			graceTimer = setTimeout(() => settle(code, signal), CLOSE_GRACE_MS);
+		});
+		child.on("close", (code, signal) => settle(code, signal));
+	});
+}