@hyperdrive.bot/fleet-server 0.3.157 → 0.3.158

package/dist/server/utils/spawn-broker-child.mjs

@@ -0,0 +1,156 @@
+// Spawn broker helper process. The daemon forks this small Node process once and
+// asks it to run non-interactive subprocesses (git, gh, which, ...) over IPC, so
+// the daemon itself never forks its multi-GB image: on WSL2 every direct spawn()
+// from the daemon blocked its event loop for about 100ms.
+//
+// Protocol (JSON over the IPC channel):
+//   parent -> child  { type: "spawn", id, command, args, cwd, env, shell }
+//                    { type: "kill", id, signal }
+//   child -> parent  { type: "spawned", id, pid }
+//                    { type: "data", id, fd: 1 | 2, data: base64 }
+//                    { type: "error", id, error: { message, code, errno, syscall, path } }
+//                    { type: "close", id, exitCode, signal }
+//
+// Timeouts, output caps and exit-code policy stay in the parent, which kills the
+// child through the "kill" message exactly like it would kill a direct ChildProcess.
+import { spawn } from "node:child_process";
+
+const children = new Map();
+
+function send(message) {
+  // Returns false when the channel is backed up (or gone; the disconnect handler
+  // cleans up in that case).
+  return sendRaw(message);
+}
+
+function serializeError(error) {
+  return {
+    message: error?.message ?? String(error),
+    code: error?.code,
+    errno: error?.errno,
+    syscall: error?.syscall,
+    path: error?.path,
+  };
+}
+
+const CHUNK_BYTES = 64 * 1024;
+
+// Forward a stream in bounded chunks, stop forwarding once the caller's cap is
+// reached (the caller decides whether to kill), and pause the source while the
+// IPC channel is backed up so output never piles up in memory on either side.
+function forward(stream, id, fd, maxBytes) {
+  const cap = Number.isFinite(maxBytes) && maxBytes >= 0 ? maxBytes : Infinity;
+  let forwarded = 0;
+  stream.on("data", (chunk) => {
+    if (forwarded >= cap) return;
+    const slice = chunk.length > cap - forwarded ? chunk.subarray(0, cap - forwarded) : chunk;
+    forwarded += slice.length;
+    for (let offset = 0; offset < slice.length; offset += CHUNK_BYTES) {
+      const part = slice.subarray(offset, offset + CHUNK_BYTES);
+      const ok = send({ type: "data", id, fd, data: part.toString("base64") });
+      if (!ok) {
+        stream.pause();
+        waitForDrain(() => stream.resume());
+      }
+    }
+  });
+}
+
+const drainWaiters = [];
+function waitForDrain(callback) {
+  drainWaiters.push(callback);
+  if (drainWaiters.length > 1) return;
+  // An empty message's send callback fires once everything queued before it
+  // has been written to the channel.
+  sendRaw({ type: "noop" }, () => {
+    const waiters = drainWaiters.splice(0);
+    for (const waiter of waiters) waiter();
+  });
+}
+
+function sendRaw(message, callback) {
+  if (!process.connected) return false;
+  try {
+    return process.send(message, undefined, undefined, callback);
+  } catch {
+    return false;
+  }
+}
+
+function handleSpawn(message) {
+  const { id } = message;
+  let child;
+  try {
+    child = spawn(message.command, message.args, {
+      cwd: message.cwd,
+      env: message.env,
+      shell: message.shell ?? false,
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+    });
+  } catch (error) {
+    send({ type: "error", id, error: serializeError(error) });
+    return;
+  }
+  children.set(id, child);
+  if (child.pid !== undefined) {
+    send({ type: "spawned", id, pid: child.pid });
+  }
+  forward(child.stdout, id, 1, message.maxStdoutBytes);
+  forward(child.stderr, id, 2, message.maxStderrBytes);
+  child.on("error", (error) => {
+    children.delete(id);
+    send({ type: "error", id, error: serializeError(error) });
+  });
+  child.on("close", (exitCode, signal) => {
+    children.delete(id);
+    send({ type: "close", id, exitCode, signal });
+  });
+}
+
+function killAll() {
+  for (const child of children.values()) {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+      // already gone
+    }
+  }
+  children.clear();
+}
+
+process.on("message", (message) => {
+  if (!message || typeof message !== "object") return;
+  if (message.type === "spawn") {
+    handleSpawn(message);
+    return;
+  }
+  if (message.type === "kill") {
+    const child = children.get(message.id);
+    if (child) {
+      try {
+        child.kill(message.signal ?? "SIGTERM");
+      } catch {
+        // already gone
+      }
+    }
+    return;
+  }
+  if (message.type === "crash-for-test" && process.env.PASEO_SPAWN_BROKER_TEST_HOOKS === "1") {
+    process.exit(1);
+  }
+});
+
+// The daemon owns us: when its IPC channel closes (clean shutdown or crash) we take
+// our children down and exit, so nothing is orphaned.
+process.on("disconnect", () => {
+  killAll();
+  process.exit(0);
+});
+
+for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+  process.on(signal, () => {
+    killAll();
+    process.exit(0);
+  });
+}

package/dist/server/utils/spawn-broker.d.ts

@@ -0,0 +1,120 @@
+import { EventEmitter } from "node:events";
+/**
+ * Minimal surface of a ChildProcess that non-interactive callers use: stdout and
+ * stderr "data" events, "error" / "close" events, and kill(). Both a real
+ * ChildProcess and a BrokeredChildProcess satisfy it.
+ */
+export interface NonInteractiveChildProcess {
+    readonly stdout: EventEmitter | null;
+    readonly stderr: EventEmitter | null;
+    readonly pid?: number;
+    kill(signal?: NodeJS.Signals | number): boolean;
+    on(event: "error", listener: (error: Error) => void): this;
+    on(event: "close" | "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+    once(event: string, listener: (...args: unknown[]) => void): this;
+}
+export interface BrokerSpawnRequest {
+    command: string;
+    args: string[];
+    cwd?: string;
+    env: NodeJS.ProcessEnv;
+    shell?: boolean | string;
+    /** The helper forwards at most this many stdout bytes (callers pass cap + 1 so they still see the overflow). */
+    maxStdoutBytes?: number;
+    /** The helper forwards at most this many stderr bytes. */
+    maxStderrBytes?: number;
+}
+export interface BrokerSpawnPolicy {
+    /**
+     * Whether a request whose start was never acknowledged may be re-run on a direct
+     * spawn when the helper dies. Only safe for read-only commands: the helper may
+     * already have started (and SIGKILLed) the process before its ack was lost.
+     */
+    retryOnDirect: boolean;
+}
+type DirectSpawn = () => NonInteractiveChildProcess;
+type BrokerMessage = {
+    type: "spawned";
+    id: number;
+    pid: number;
+} | {
+    type: "data";
+    id: number;
+    fd: 1 | 2;
+    data: string;
+} | {
+    type: "error";
+    id: number;
+    error: {
+        message: string;
+        code?: string;
+        errno?: number;
+        syscall?: string;
+        path?: string;
+    };
+} | {
+    type: "close";
+    id: number;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+};
+export declare function isSpawnBrokerEnabled(): boolean;
+/**
+ * A process run by the broker. Emits the same events, in the same order, as a
+ * direct ChildProcess with stdio ["ignore", "pipe", "pipe"]. If the broker fails
+ * before the process is confirmed started, it transparently falls back to a
+ * direct spawn so the caller never sees the difference.
+ */
+export declare class BrokeredChildProcess extends EventEmitter implements NonInteractiveChildProcess {
+    readonly stdout: EventEmitter<[never]>;
+    readonly stderr: EventEmitter<[never]>;
+    pid: number | undefined;
+    killed: boolean;
+    brokered: boolean;
+    private started;
+    private closed;
+    private fallbackChild;
+    private pendingKill;
+    readonly id: number;
+    private readonly broker;
+    private readonly directSpawn;
+    private readonly retryOnDirect;
+    constructor(id: number, broker: SpawnBroker, directSpawn: DirectSpawn, policy: BrokerSpawnPolicy);
+    kill(signal?: NodeJS.Signals | number): boolean;
+    /** @internal */
+    handleMessage(message: BrokerMessage): void;
+    /** @internal Broker died or could not be reached. */
+    handleBrokerLost(): void;
+    /** @internal */
+    startFallback(): void;
+}
+export declare class SpawnBroker {
+    private child;
+    private readonly pending;
+    private nextId;
+    private consecutiveFailures;
+    private disabledUntil;
+    private exitHookInstalled;
+    private readonly childPath;
+    constructor(childPath?: string);
+    get pendingCount(): number;
+    get brokerPid(): number | undefined;
+    spawn(request: BrokerSpawnRequest, directSpawn: DirectSpawn, policy?: BrokerSpawnPolicy): NonInteractiveChildProcess;
+    /** @internal */
+    sendKill(id: number, signal: NodeJS.Signals | number): void;
+    /** @internal */
+    release(id: number): void;
+    /** Stop the helper. Pending requests fall back or report SIGKILL. */
+    dispose(): void;
+    /** Test hook: make the helper exit abruptly. */
+    crashForTest(): void;
+    private ensureChild;
+    private handleChildLost;
+    private recordFailure;
+    private updateRef;
+    private installExitHook;
+}
+export declare function getSharedSpawnBroker(): SpawnBroker;
+export declare function resetSharedSpawnBrokerForTest(): void;
+export {};
+//# sourceMappingURL=spawn-broker.d.ts.map

package/dist/server/utils/spawn-broker.js

@@ -0,0 +1,299 @@
+import { fork } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+const FAILURE_COOLDOWN_MS = 60000;
+const MAX_CONSECUTIVE_FAILURES = 3;
+export function isSpawnBrokerEnabled() {
+    if (process.platform === "win32")
+        return false;
+    const flag = process.env.PASEO_SPAWN_BROKER;
+    return flag !== "0" && flag !== "false";
+}
+function resolveBrokerChildPath() {
+    // The helper is a plain .mjs file that sits next to this module both in src/ (tests,
+    // tsx dev) and in dist/server/utils/ (build:lib copies it), so the published package
+    // ships it at node_modules/@hyperdrive.bot/fleet-server/dist/server/utils/.
+    return fileURLToPath(new URL("./spawn-broker-child.mjs", import.meta.url));
+}
+/**
+ * A process run by the broker. Emits the same events, in the same order, as a
+ * direct ChildProcess with stdio ["ignore", "pipe", "pipe"]. If the broker fails
+ * before the process is confirmed started, it transparently falls back to a
+ * direct spawn so the caller never sees the difference.
+ */
+export class BrokeredChildProcess extends EventEmitter {
+    constructor(id, broker, directSpawn, policy) {
+        super();
+        this.stdout = new EventEmitter();
+        this.stderr = new EventEmitter();
+        this.killed = false;
+        this.brokered = true;
+        this.started = false;
+        this.closed = false;
+        this.fallbackChild = null;
+        this.pendingKill = null;
+        this.id = id;
+        this.broker = broker;
+        this.directSpawn = directSpawn;
+        this.retryOnDirect = policy.retryOnDirect;
+    }
+    kill(signal = "SIGTERM") {
+        if (this.closed)
+            return false;
+        this.killed = true;
+        if (this.fallbackChild) {
+            return this.fallbackChild.kill(signal);
+        }
+        this.pendingKill = signal;
+        this.broker.sendKill(this.id, signal);
+        return true;
+    }
+    /** @internal */
+    handleMessage(message) {
+        if (this.closed || this.fallbackChild)
+            return;
+        switch (message.type) {
+            case "spawned":
+                this.started = true;
+                this.pid = message.pid;
+                this.emit("spawn");
+                return;
+            case "data": {
+                const target = message.fd === 1 ? this.stdout : this.stderr;
+                target.emit("data", Buffer.from(message.data, "base64"));
+                return;
+            }
+            case "error": {
+                const error = Object.assign(new Error(message.error.message), {
+                    code: message.error.code,
+                    errno: message.error.errno,
+                    syscall: message.error.syscall,
+                    path: message.error.path,
+                });
+                this.emit("error", error);
+                return;
+            }
+            case "close":
+                this.closed = true;
+                this.broker.release(this.id);
+                this.emit("exit", message.exitCode, message.signal);
+                this.emit("close", message.exitCode, message.signal);
+                return;
+        }
+    }
+    /** @internal Broker died or could not be reached. */
+    handleBrokerLost() {
+        if (this.closed || this.fallbackChild)
+            return;
+        if (this.started) {
+            // The process really ran (the broker kills its children when it dies), so
+            // re-running it could repeat a side effect. Report it as killed instead.
+            this.closed = true;
+            this.emit("exit", null, "SIGKILL");
+            this.emit("close", null, "SIGKILL");
+            return;
+        }
+        if (this.retryOnDirect) {
+            this.startFallback();
+            return;
+        }
+        // The request may already have run (and been killed) inside the helper, so a
+        // mutating command must not run a second time: surface the loss instead.
+        this.closed = true;
+        const error = Object.assign(new Error("Spawn broker exited before confirming the process started"), { code: "ERR_SPAWN_BROKER_LOST" });
+        queueMicrotask(() => this.emit("error", error));
+    }
+    /** @internal */
+    startFallback() {
+        this.brokered = false;
+        let child;
+        try {
+            child = this.directSpawn();
+        }
+        catch (error) {
+            this.closed = true;
+            queueMicrotask(() => this.emit("error", error));
+            return;
+        }
+        this.fallbackChild = child;
+        this.pid = child.pid;
+        child.stdout?.on("data", (chunk) => this.stdout.emit("data", chunk));
+        child.stderr?.on("data", (chunk) => this.stderr.emit("data", chunk));
+        child.on("error", (error) => this.emit("error", error));
+        child.on("exit", (code, signal) => this.emit("exit", code, signal));
+        child.on("close", (code, signal) => {
+            this.closed = true;
+            this.emit("close", code, signal);
+        });
+        if (this.pendingKill !== null) {
+            child.kill(this.pendingKill);
+        }
+    }
+}
+export class SpawnBroker {
+    constructor(childPath = resolveBrokerChildPath()) {
+        this.child = null;
+        this.pending = new Map();
+        this.nextId = 1;
+        this.consecutiveFailures = 0;
+        this.disabledUntil = 0;
+        this.exitHookInstalled = false;
+        this.childPath = childPath;
+    }
+    get pendingCount() {
+        return this.pending.size;
+    }
+    get brokerPid() {
+        return this.child?.pid;
+    }
+    spawn(request, directSpawn, policy = { retryOnDirect: false }) {
+        const proc = new BrokeredChildProcess(this.nextId++, this, directSpawn, policy);
+        const child = this.ensureChild();
+        if (!child) {
+            // The request never left this process, so a direct spawn cannot double-run it.
+            proc.startFallback();
+            return proc;
+        }
+        this.pending.set(proc.id, proc);
+        this.updateRef();
+        try {
+            child.send({ type: "spawn", id: proc.id, ...request }, (error) => {
+                if (error)
+                    this.handleChildLost(child);
+            });
+        }
+        catch {
+            this.handleChildLost(child);
+        }
+        return proc;
+    }
+    /** @internal */
+    sendKill(id, signal) {
+        const child = this.child;
+        if (!child || !child.connected)
+            return;
+        try {
+            child.send({ type: "kill", id, signal });
+        }
+        catch {
+            // handled by the disconnect path
+        }
+    }
+    /** @internal */
+    release(id) {
+        this.pending.delete(id);
+        this.updateRef();
+    }
+    /** Stop the helper. Pending requests fall back or report SIGKILL. */
+    dispose() {
+        const child = this.child;
+        if (child) {
+            this.handleChildLost(child);
+            child.kill("SIGTERM");
+        }
+    }
+    /** Test hook: make the helper exit abruptly. */
+    crashForTest() {
+        this.child?.send({ type: "crash-for-test" });
+    }
+    ensureChild() {
+        if (this.child)
+            return this.child;
+        if (Date.now() < this.disabledUntil)
+            return null;
+        if (!existsSync(this.childPath)) {
+            this.recordFailure();
+            return null;
+        }
+        let child;
+        try {
+            child = fork(this.childPath, [], {
+                execArgv: [],
+                stdio: ["ignore", "ignore", "inherit", "ipc"],
+                serialization: "json",
+                // Electron desktop: the daemon runs as the Electron binary with
+                // ELECTRON_RUN_AS_NODE=1, and Electron's fork re-injects that variable, so a
+                // PATH-only env still boots the helper as plain Node.
+                env: {
+                    PATH: process.env.PATH ?? "",
+                    ...(process.env.PASEO_SPAWN_BROKER_TEST_HOOKS === "1"
+                        ? { PASEO_SPAWN_BROKER_TEST_HOOKS: "1" }
+                        : {}),
+                },
+            });
+        }
+        catch {
+            this.recordFailure();
+            return null;
+        }
+        this.child = child;
+        child.on("message", (message) => {
+            this.consecutiveFailures = 0;
+            this.pending.get(message.id)?.handleMessage(message);
+        });
+        child.on("error", () => this.handleChildLost(child));
+        child.on("exit", () => this.handleChildLost(child));
+        child.on("disconnect", () => this.handleChildLost(child));
+        this.installExitHook();
+        this.updateRef();
+        return child;
+    }
+    handleChildLost(child) {
+        if (this.child !== child)
+            return;
+        this.child = null;
+        this.recordFailure();
+        const lost = [...this.pending.values()];
+        this.pending.clear();
+        for (const proc of lost) {
+            proc.handleBrokerLost();
+        }
+    }
+    recordFailure() {
+        this.consecutiveFailures += 1;
+        if (this.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+            this.disabledUntil = Date.now() + FAILURE_COOLDOWN_MS;
+            this.consecutiveFailures = 0;
+        }
+    }
+    updateRef() {
+        const child = this.child;
+        if (!child)
+            return;
+        // Never keep the daemon alive just for the helper; hold a ref only while a
+        // request is in flight so awaiting callers are not cut off.
+        const channel = child.channel;
+        if (this.pending.size > 0) {
+            child.ref();
+            channel?.ref?.();
+        }
+        else {
+            child.unref();
+            channel?.unref?.();
+        }
+    }
+    installExitHook() {
+        if (this.exitHookInstalled)
+            return;
+        this.exitHookInstalled = true;
+        process.once("exit", () => {
+            try {
+                this.child?.kill("SIGKILL");
+            }
+            catch {
+                // already gone
+            }
+        });
+    }
+}
+let sharedBroker = null;
+export function getSharedSpawnBroker() {
+    sharedBroker ?? (sharedBroker = new SpawnBroker());
+    return sharedBroker;
+}
+export function resetSharedSpawnBrokerForTest() {
+    sharedBroker?.dispose();
+    sharedBroker = null;
+}
+//# sourceMappingURL=spawn-broker.js.map

package/dist/server/utils/spawn.d.ts

@@ -1,5 +1,6 @@
 import { type ChildProcess, type SpawnOptions } from "node:child_process";
 import { type ProcessEnvRecord } from "../server/paseo-env.js";
+import { type NonInteractiveChildProcess } from "./spawn-broker.js";
 interface ExternalEnvOptions {
     baseEnv?: ProcessEnvRecord;
     envMode?: "external" | "internal";
@@ -20,6 +21,26 @@ interface ExecCommandResult {
     stderr: string;
 }
 export declare function spawnProcess(command: string, args: string[], options?: SpawnProcessOptions): ChildProcess;
+export interface NonInteractiveSpawnOptions extends ExternalEnvOptions {
+    cwd?: string;
+    shell?: boolean | string;
+    /** Output the broker forwards at most; set to your own cap + 1. */
+    maxStdoutBytes?: number;
+    maxStderrBytes?: number;
+    /**
+     * Re-run on a direct spawn if the broker dies before acknowledging the start.
+     * Only for read-only commands; defaults to false.
+     */
+    retryOnDirect?: boolean;
+}
+/**
+ * Spawn a short-lived command whose stdin is ignored and whose stdout/stderr are
+ * piped. Runs through the spawn broker helper process when available (so the
+ * daemon does not fork its own large image), and falls back to spawnProcess.
+ * Use spawnProcess instead when you need stdin, detached, a pty or a real
+ * ChildProcess handle.
+ */
+export declare function spawnNonInteractive(command: string, args: string[], options?: NonInteractiveSpawnOptions): NonInteractiveChildProcess;
 export declare function execCommand(command: string, args: string[], options?: ExecCommandOptions): Promise<ExecCommandResult>;
 export declare function platformShell(): {
     command: string;