@moondeck/station 0.0.0-stage → 1.0.0

package/lib/docker-exec.ts

@@ -0,0 +1,156 @@
+/**
+ * Async docker CLI runner.
+ *
+ * The host's hot paths — boot recovery (recoverRunningTasks) and the
+ * per-reconnect channel ensure (git identity + gh token injection) — used
+ * `spawnSync`, which blocks the single Node event loop for the entire docker
+ * call. With several tasks (and large containers), those blocking bursts starve
+ * the bridge heartbeat timer and the local UI server: the cloud stops getting
+ * pings, drops the host, the host reconnects, the cloud re-`ensure`s the
+ * channels → more blocking docker → the heartbeat dies again. A reconnect loop.
+ *
+ * Running docker through async `spawn` keeps the loop responsive while the
+ * command runs. Never rejects — it resolves the same `{status, stdout, stderr}`
+ * shape callers already branch on (mirrors spawnSync's result fields), with
+ * `status: null` on spawn error or timeout.
+ */
+
+import { spawn } from "node:child_process";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export interface DockerResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  /** True when tailOutputBytes discarded earlier diagnostic output. */
+  outputTruncated?: boolean;
+}
+
+export function dockerCli(
+  args: string[],
+  opts: {
+    input?: string;
+    timeoutMs?: number;
+    /** Optional aggregate stdout+stderr cap for cardinality-sensitive probes.
+     * Exceeding it kills the child and resolves with status:null. */
+    maxOutputBytes?: number;
+    /** Keep draining the child but retain only this many trailing bytes from
+     * each output stream. Use for legitimately verbose bounded operations
+     * whose complete compiler/install log must not accumulate in host RAM. */
+    tailOutputBytes?: number;
+    /** Selection probes can intentionally ignore this process's pinned host,
+     * and an exec that names a credential bare carries its value here
+     * (cliExecEnv in task-environment/docker.ts). */
+    env?: NodeJS.ProcessEnv;
+  } = {},
+): Promise<DockerResult> {
+  return new Promise<DockerResult>((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let stdoutTruncated = false;
+    let stderrTruncated = false;
+    let settled = false;
+    const child = spawn("docker", args, {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: opts.env,
+    });
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      // A SIGKILLed client normally closes at once, but an unreapable child
+      // (D-state, wedged pipe) must not hold this promise open forever: the
+      // caller's own deadline already expired, so settle as failed after a
+      // short grace even if `close` never fires.
+      const settle = setTimeout(() => {
+        stderr += `docker did not settle after its ${opts.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms deadline`;
+        finish(null);
+      }, 5_000);
+      settle.unref?.();
+    }, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    timer.unref?.();
+    const finish = (status: number | null) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({
+        status,
+        stdout,
+        stderr,
+        outputTruncated: stdoutTruncated || stderrTruncated || undefined,
+      });
+    };
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (c: string) => {
+      if (settled) return;
+      if (outputWouldExceedLimit(stdout, stderr, c, opts.maxOutputBytes)) {
+        stderr += "docker output exceeded configured limit";
+        child.kill("SIGKILL");
+        finish(null);
+        return;
+      }
+      const tailed = appendOutputTail(stdout, c, opts.tailOutputBytes);
+      stdout = tailed.output;
+      stdoutTruncated ||= tailed.truncated;
+    });
+    child.stderr?.on("data", (c: string) => {
+      if (settled) return;
+      if (outputWouldExceedLimit(stdout, stderr, c, opts.maxOutputBytes)) {
+        child.kill("SIGKILL");
+        finish(null);
+        return;
+      }
+      const tailed = appendOutputTail(stderr, c, opts.tailOutputBytes);
+      stderr = tailed.output;
+      stderrTruncated ||= tailed.truncated;
+    });
+    child.on("error", (err: Error) => {
+      stderr += err.message;
+      finish(null);
+    });
+    child.on("close", (code) => {
+      finish(code);
+    });
+    // EPIPE guard: if the child exits without draining stdin (or our own
+    // timeout SIGKILLs it mid-write), the failed write surfaces as an 'error'
+    // event on the stdin stream — unhandled, that's an uncaughtException that
+    // would take down the whole host service. Today's inputs are tiny (a gh
+    // token) and complete synchronously, but this keeps the helper safe for
+    // any future caller piping real data.
+    child.stdin?.on("error", () => {});
+    if (opts.input !== undefined) child.stdin?.write(opts.input);
+    child.stdin?.end();
+  });
+}
+
+function appendOutputTail(
+  current: string,
+  chunk: string,
+  limit: number | undefined,
+): { output: string; truncated: boolean } {
+  if (limit === undefined) return { output: current + chunk, truncated: false };
+  const bounded = Math.max(0, Math.floor(limit));
+  const combined = Buffer.from(current + chunk);
+  if (combined.byteLength <= bounded) {
+    return { output: combined.toString("utf8"), truncated: false };
+  }
+  return {
+    output: combined.subarray(combined.byteLength - bounded).toString("utf8"),
+    truncated: true,
+  };
+}
+
+function outputWouldExceedLimit(
+  stdout: string,
+  stderr: string,
+  chunk: string,
+  limit: number | undefined,
+): boolean {
+  return (
+    limit !== undefined &&
+    Buffer.byteLength(stdout) +
+      Buffer.byteLength(stderr) +
+      Buffer.byteLength(chunk) >
+      limit
+  );
+}