@exagone313/dsh-podman 0.2.0-rc.2

package/dist/subprocess.js

@@ -0,0 +1,369 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import { discardUnneededSpill, outputReader, spillTargetFor, splitEnv } from "./output-reader.js";
+import { globCwd, remoteArgv, unaryGuest } from "./guest-rpc.js";
+import { metadata } from "./workspace-binding.js";
+import { randomUUID } from "node:crypto";
+import { PassThrough } from "node:stream";
+export function createSubprocessProvider(resolver) {
+    // Live termination handles, so service disposal can stop every process this
+    // provider started (the harness's disposal contract).
+    const live = new Set();
+    return {
+        dispose: () => {
+            for (const terminate of [...live])
+                terminate();
+        },
+        // The harness's resolveExecutable carries no cwd, and this provider's
+        // execution world is per-workspace (each workspace is its own container),
+        // so there is no context in which an executable can be verified or looked
+        // up. Report every request as unresolvable instead of returning an
+        // unverified path.
+        resolveExecutable: async (command) => {
+            throw new Error(`cannot resolve executable ${JSON.stringify(command)}: no workspace context is available`);
+        },
+        spawn: (spec) => {
+            // A pre-aborted spawn is rejected synchronously with a stable Error,
+            // mirroring the local backend, rather than starting a process that would
+            // be terminated immediately.
+            if (spec.signal?.aborted) {
+                let reason = "aborted";
+                try {
+                    reason = String(spec.signal.reason ?? reason);
+                }
+                catch {
+                    // Arbitrary caller-owned reasons cannot escape the stable boundary.
+                }
+                throw new Error(`aborted before spawn: ${reason}`);
+            }
+            if (!Array.isArray(spec.argv) ||
+                spec.argv.length === 0 ||
+                typeof spec.argv[0] !== "string" ||
+                spec.argv[0] === "")
+                throw new Error("argv must contain a program");
+            const stdoutSpill = spillTargetFor(spec.stdio?.stdout, "stdout");
+            const stderrSpill = spillTargetFor(spec.stdio?.stderr, "stderr");
+            const stdoutReader = outputReader(spec.stdio?.stdout, stdoutSpill.spec);
+            const stderrReader = outputReader(spec.stdio?.stderr, stderrSpill.spec);
+            const state = {
+                pid: -1,
+                stdin: undefined,
+                stdout: spec.stdio?.stdout === "pipe" ? new PassThrough() : undefined,
+                stderr: spec.stdio?.stderr === "pipe" ? new PassThrough() : undefined,
+            };
+            let processBinding;
+            let terminated = false;
+            let exited = false;
+            let killTimer;
+            const signalProcess = (signal) => {
+                if (processBinding !== undefined && state.pid > 0) {
+                    void unaryGuest({ binding: processBinding }, "signal", {
+                        processId: String(state.pid),
+                        signal,
+                    }).catch(() => { });
+                }
+            };
+            // The harness's termination procedure: SIGTERM, then SIGKILL once the
+            // spec's grace period elapses without an exit.
+            const terminate = () => {
+                terminated = true;
+                signalProcess("SIGTERM");
+                if (killTimer === undefined) {
+                    const grace = typeof spec.graceMs === "number" && spec.graceMs > 0
+                        ? spec.graceMs
+                        : 5000;
+                    killTimer = setTimeout(() => {
+                        if (!exited)
+                            signalProcess("SIGKILL");
+                    }, grace);
+                    killTimer.unref?.();
+                }
+            };
+            // A ripgrep discovery listing runs from its search root, so a pattern
+            // containing "/" anchors to the path the harness passed; the workspace
+            // binding still resolves from the caller's cwd.
+            const runCwd = globCwd(spec.argv, spec.cwd) ?? spec.cwd;
+            const done = resolver.resolve(spec.cwd).then((binding) => new Promise((resolveDone, reject) => {
+                processBinding = binding;
+                const stream = binding.guest.exec(metadata(binding.token));
+                stream.on("data", (output) => {
+                    if (output.stdoutChunk) {
+                        const data = Buffer.from(output.stdoutChunk);
+                        stdoutReader?.append(data);
+                        state.stdout?.write(data);
+                        if (spec.stdio?.stdout === "inherit")
+                            process.stdout.write(data);
+                    }
+                    if (output.processId) {
+                        state.pid = Number(output.processId);
+                        if (terminated)
+                            terminate();
+                    }
+                    if (output.stderrChunk) {
+                        const data = Buffer.from(output.stderrChunk);
+                        stderrReader?.append(data);
+                        state.stderr?.write(data);
+                        if (spec.stdio?.stderr === "inherit")
+                            process.stderr.write(data);
+                    }
+                    if (output.exit) {
+                        exited = true;
+                        if (killTimer !== undefined)
+                            clearTimeout(killTimer);
+                        stdoutReader?.setSpillValid(Boolean(output.exit.stdoutSpillValid));
+                        stderrReader?.setSpillValid(Boolean(output.exit.stderrSpillValid));
+                        state.stdout?.end();
+                        state.stderr?.end();
+                        discardUnneededSpill(binding, stdoutReader);
+                        discardUnneededSpill(binding, stderrReader);
+                        resolveDone({
+                            exitCode: output.exit.exitCode,
+                            signal: output.exit.signaled ? output.exit.signal : null,
+                        });
+                    }
+                });
+                stream.on("error", reject);
+                const env = splitEnv(spec.env);
+                stream.write({
+                    start: {
+                        argv: remoteArgv(spec.argv),
+                        cwd: runCwd,
+                        env: env.env,
+                        unsetEnv: env.unsetEnv,
+                        // A caller that will not send stdin leaves the child on
+                        // /dev/null: a pipe would be a non-TTY stdin, and tools like
+                        // ripgrep then read stdin instead of the working directory.
+                        stdinPipe: spec.stdio?.stdin === "pipe",
+                        ...(stdoutSpill.target !== undefined
+                            ? { spillStdout: stdoutSpill.target }
+                            : {}),
+                        ...(stderrSpill.target !== undefined
+                            ? { spillStderr: stderrSpill.target }
+                            : {}),
+                    },
+                });
+                if (spec.stdio?.stdin !== "pipe")
+                    stream.end();
+                else {
+                    state.stdin = new PassThrough();
+                    state.stdin.on("data", (data) => stream.write({ stdinChunk: data }));
+                    state.stdin.on("end", () => stream.end());
+                }
+            }));
+            if (spec.signal !== undefined) {
+                if (spec.signal.aborted)
+                    terminate();
+                else
+                    spec.signal.addEventListener("abort", terminate, { once: true });
+            }
+            live.add(terminate);
+            void done.finally(() => live.delete(terminate)).catch(() => { });
+            return {
+                ...state,
+                collected: {
+                    ...(stdoutReader === undefined ? {} : { stdout: stdoutReader }),
+                    ...(stderrReader === undefined ? {} : { stderr: stderrReader }),
+                },
+                done,
+                terminate,
+                // Mirror the local backend's `waitWithAbort`: a pre-aborted or
+                // aborting signal returns false instead of waiting for the managed
+                // range, while a provider failure still propagates.
+                waitForExit: (signal) => {
+                    if (signal?.aborted) {
+                        void done.catch(() => { });
+                        return Promise.resolve(false);
+                    }
+                    if (signal === undefined)
+                        return done.then(() => true);
+                    return new Promise((resolve, reject) => {
+                        const onAbort = () => resolve(false);
+                        signal.addEventListener("abort", onAbort, { once: true });
+                        done.then(() => {
+                            signal.removeEventListener("abort", onAbort);
+                            resolve(true);
+                        }, (error) => {
+                            signal.removeEventListener("abort", onAbort);
+                            reject(error);
+                        });
+                    });
+                },
+            };
+        },
+        spawnTerminal: async (spec) => {
+            if (!Array.isArray(spec.argv) ||
+                spec.argv.length === 0 ||
+                typeof spec.argv[0] !== "string" ||
+                spec.argv[0] === "")
+                throw new Error("argv must contain a program");
+            spec.signal?.throwIfAborted();
+            const binding = await resolver.resolveForPath(spec.cwd, spec.cwd);
+            const call = binding.guest.terminal(metadata(binding.token));
+            const output = new PassThrough();
+            let exited = false;
+            let terminated = false;
+            let resolveExit;
+            let rejectExit;
+            const done = new Promise((resolveDone, rejectDone) => {
+                resolveExit = resolveDone;
+                rejectExit = rejectDone;
+            });
+            // A caller that never receives the handle (startup failure) must not
+            // leave `done` as an unhandled rejection.
+            done.catch(() => { });
+            let resolveStarted;
+            let rejectStarted;
+            const started = new Promise((resolvePid, rejectPid) => {
+                resolveStarted = resolvePid;
+                rejectStarted = rejectPid;
+            });
+            const pending = new Map();
+            const failPending = (error) => {
+                for (const waiter of pending.values())
+                    waiter.reject(error);
+                pending.clear();
+            };
+            call.on("data", (message) => {
+                if (message.started) {
+                    resolveStarted(Number(message.started.pid));
+                    return;
+                }
+                if (message.stdoutChunk) {
+                    output.write(Buffer.from(message.stdoutChunk));
+                    return;
+                }
+                if (message.exit) {
+                    exited = true;
+                    output.end();
+                    resolveExit({
+                        exitCode: message.exit.exitCode,
+                        signal: message.exit.signaled ? message.exit.signal : null,
+                    });
+                    return;
+                }
+                if (message.foreground) {
+                    const waiter = pending.get(message.foreground.requestId);
+                    if (waiter !== undefined) {
+                        pending.delete(message.foreground.requestId);
+                        waiter.resolve(message.foreground);
+                    }
+                    return;
+                }
+                if (message.signalled) {
+                    const waiter = pending.get(message.signalled.requestId);
+                    if (waiter !== undefined) {
+                        pending.delete(message.signalled.requestId);
+                        waiter.resolve(message.signalled);
+                    }
+                }
+            });
+            call.on("error", (error) => {
+                rejectStarted(error);
+                if (!exited) {
+                    exited = true;
+                    output.end();
+                    rejectExit(error);
+                }
+                failPending(error);
+            });
+            call.on("end", () => {
+                if (exited)
+                    return;
+                const error = new Error("terminal stream ended before the process exited");
+                rejectStarted(error);
+                exited = true;
+                output.end();
+                rejectExit(error);
+                failPending(error);
+            });
+            call.write({
+                start: {
+                    argv: remoteArgv(spec.argv),
+                    cwd: spec.cwd,
+                    env: spec.env ?? {},
+                    rows: spec.rows,
+                    cols: spec.cols,
+                },
+            });
+            const pid = await started;
+            const request = (message) => {
+                const requestId = randomUUID();
+                return new Promise((resolveWaiter, rejectWaiter) => {
+                    pending.set(requestId, { resolve: resolveWaiter, reject: rejectWaiter });
+                    try {
+                        call.write(message(requestId));
+                    }
+                    catch (error) {
+                        pending.delete(requestId);
+                        rejectWaiter(error);
+                    }
+                });
+            };
+            const handle = {
+                pid,
+                output,
+                done,
+                write: async (data) => {
+                    if (exited)
+                        throw new Error("terminal has exited");
+                    call.write({ stdinChunk: Buffer.from(data) });
+                },
+                inspectForeground: async () => {
+                    if (exited)
+                        return undefined;
+                    const response = await request((requestId) => ({
+                        inspectRequestId: requestId,
+                    }));
+                    return response.found
+                        ? {
+                            processGroupId: response.processGroupId,
+                            inputWaiting: response.inputWaiting,
+                        }
+                        : undefined;
+                },
+                signalForeground: async (signal) => {
+                    if (exited)
+                        throw new Error("terminal has exited");
+                    const response = await request((requestId) => ({
+                        signal: { signal, requestId },
+                    }));
+                    if (!response.found)
+                        throw new Error(`no foreground process group to signal ${signal}`);
+                    return response.processGroupId;
+                },
+                terminate: async () => {
+                    if (terminated)
+                        return;
+                    terminated = true;
+                    try {
+                        call.write({ close: true });
+                        call.end();
+                    }
+                    catch {
+                        // A finished call cannot be closed again; nothing to do.
+                    }
+                    try {
+                        await done;
+                    }
+                    catch {
+                        // Termination is idempotent and never rejects.
+                    }
+                    if (!output.writableEnded)
+                        output.end();
+                },
+            };
+            const onAbort = () => {
+                void handle.terminate();
+            };
+            if (spec.signal !== undefined) {
+                if (spec.signal.aborted)
+                    onAbort();
+                else
+                    spec.signal.addEventListener("abort", onAbort, { once: true });
+            }
+            return handle;
+        },
+    };
+}
+export { outputReader } from "./output-reader.js";

package/dist/subprocess.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/subprocess.test.js

@@ -0,0 +1,234 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import test from "node:test";
+import assert from "node:assert/strict";
+import { FakeTerminalCall, fakeTerminalResolver, spawnGuest, spawnSpec } from "./test-support.js";
+import { createSubprocessProvider, globCwd, outputReader, remoteArgv } from "./index.js";
+test("globCwd runs a discovery listing from its absolute search root", () => {
+    assert.equal(globCwd(["rg", "--files", "--glob=sub/b.txt", "--", "/tmp/globtest"], "/projects/team"), "/tmp/globtest");
+    assert.equal(globCwd(["rg", "--files", "--glob=a", "--", "sub"], "/projects/team"), undefined, "a relative root keeps the caller's cwd");
+    assert.equal(globCwd(["rg", "--files", "--glob=a"], "/projects/team"), undefined, "no search root keeps the caller's cwd");
+    assert.equal(globCwd(["rg", "-n", "x", "--", "/tmp/x"], "/projects/team"), undefined, "only a discovery listing is re-anchored");
+    assert.equal(globCwd(["bash", "-c", "rg"], "/projects/team"), undefined);
+    assert.equal(globCwd(["rg", "--files", "--", "/a", "/b"], "/projects/team"), undefined, "several search roots keep the caller's cwd");
+});
+test("subprocess provider runs a glob listing from its search root", async () => {
+    const fake = spawnGuest();
+    const provider = createSubprocessProvider(fake.resolver);
+    const handle = provider.spawn(spawnSpec({
+        argv: ["rg", "--files", "--glob=sub/b.txt", "--", "/tmp/globtest"],
+    }));
+    await handle.done;
+    const start = fake.starts[0].start;
+    assert.equal(start.cwd, "/tmp/globtest");
+    assert.deepEqual(start.argv, [
+        "/usr/bin/rg",
+        "--files",
+        "--glob=sub/b.txt",
+        "--",
+        "/tmp/globtest",
+    ]);
+});
+test("remoteArgv remaps ripgrep onto the guest path", () => {
+    assert.deepEqual(remoteArgv(["rg", "-n", "foo"]), [
+        "/usr/bin/rg",
+        "-n",
+        "foo",
+    ]);
+    assert.deepEqual(remoteArgv(["/usr/bin/rg", "-l", "x"]), [
+        "/usr/bin/rg",
+        "-l",
+        "x",
+    ]);
+});
+test("remoteArgv unwraps landlock-run wrappers", () => {
+    assert.deepEqual(remoteArgv(["landlock-run", "--", "/usr/bin/rg", "-l"]), [
+        "/usr/bin/rg",
+        "-l",
+    ]);
+    assert.deepEqual(remoteArgv(["landlock-run", "--", "rg", "-l", "src"]), ["/usr/bin/rg", "-l", "src"]);
+});
+test("remoteArgv leaves ordinary commands untouched", () => {
+    assert.deepEqual(remoteArgv(["bash", "-c", "echo hi"]), [
+        "bash",
+        "-c",
+        "echo hi",
+    ]);
+    assert.deepEqual(remoteArgv(["landlock-run", "cmd", "arg"]), [
+        "landlock-run",
+        "cmd",
+        "arg",
+    ]);
+    assert.deepEqual(remoteArgv([]), []);
+});
+test("outputReader is undefined without a bounded mode", () => {
+    assert.equal(outputReader(undefined), undefined);
+    assert.equal(outputReader(null), undefined);
+    assert.equal(outputReader("pipe"), undefined);
+    assert.equal(outputReader({ maxBytes: -1 }), undefined);
+    assert.equal(outputReader({ maxBytes: Number.NaN }), undefined);
+});
+test("outputReader reads appended output", () => {
+    const reader = outputReader({ maxBytes: 16 });
+    reader.append(Buffer.from("hello "));
+    reader.append(Buffer.from("world"));
+    const first = reader.readFrom(0);
+    assert.equal(first.text, "hello world");
+    assert.equal(first.nextOffset, 11);
+    assert.equal(first.lossy, false);
+});
+test("outputReader advertises a valid spill only for a lossy read", () => {
+    const spill = { path: "/tmp/dsh-podman/x.stdout", maxBytes: 64 };
+    const reader = outputReader({ maxBytes: 4 }, spill);
+    reader.append(Buffer.from("abcdefgh"));
+    assert.equal(reader.spillNeeded, true);
+    const lossy = reader.readFrom(0);
+    assert.equal(lossy.lossy, true);
+    assert.equal(lossy.spillPath, spill.path);
+    reader.setSpillValid(false);
+    assert.equal(reader.readFrom(0).spillPath, undefined);
+    const small = outputReader({ maxBytes: 64 }, spill);
+    small.append(Buffer.from("hi"));
+    assert.equal(small.spillNeeded, false);
+    assert.equal(small.readFrom(0).spillPath, undefined);
+});
+test("outputReader drops bytes beyond the retention window", () => {
+    const reader = outputReader({ maxBytes: 5 });
+    reader.append(Buffer.from("hello"));
+    reader.append(Buffer.from("world"));
+    const read = reader.readFrom(0);
+    assert.equal(read.text, "world");
+    assert.equal(read.nextOffset, 10);
+    assert.equal(read.lossy, true);
+});
+test("outputReader honors in-window offsets", () => {
+    const reader = outputReader({ maxBytes: 5 });
+    reader.append(Buffer.from("abcdefghij"));
+    const atStart = reader.readFrom(5);
+    assert.equal(atStart.text, "fghij");
+    assert.equal(atStart.lossy, false);
+    const pastEnd = reader.readFrom(10);
+    assert.equal(pastEnd.text, "");
+    assert.equal(pastEnd.lossy, false);
+});
+test("resolveExecutable rejects every request without a workspace context", async () => {
+    const provider = createSubprocessProvider({});
+    await assert.rejects(() => provider.resolveExecutable(""));
+    await assert.rejects(() => provider.resolveExecutable("bin/tool"));
+    await assert.rejects(() => provider.resolveExecutable("ls"));
+    await assert.rejects(() => provider.resolveExecutable("/usr/bin/ls"));
+});
+test("spawnTerminal drives the guest terminal stream", async () => {
+    const fake = new FakeTerminalCall();
+    const provider = createSubprocessProvider(fakeTerminalResolver(fake));
+    const handle = await provider.spawnTerminal({
+        argv: ["bash"],
+        cwd: "/projects/team",
+        rows: 24,
+        cols: 80,
+        graceMs: 1000,
+    });
+    assert.equal(handle.pid, 42);
+    const chunks = [];
+    handle.output.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+    const outputEnded = new Promise((resolve) => handle.output.on("end", resolve));
+    fake.emitStdout(Buffer.from("hello"));
+    await handle.write("ls\n");
+    assert.deepEqual(fake.stdinChunks.map((chunk) => chunk.toString("utf8")), ["ls\n"]);
+    assert.deepEqual(await handle.inspectForeground(), {
+        processGroupId: 7,
+        inputWaiting: true,
+    });
+    assert.equal(await handle.signalForeground("SIGINT"), 7);
+    fake.emitExit(0, false);
+    assert.deepEqual(await handle.done, { exitCode: 0, signal: null });
+    await outputEnded;
+    assert.equal(Buffer.concat(chunks).toString("utf8"), "hello");
+    await handle.terminate();
+});
+test("spawnTerminal rejects an empty argv", async () => {
+    const provider = createSubprocessProvider(fakeTerminalResolver(new FakeTerminalCall()));
+    await assert.rejects(() => provider.spawnTerminal({ argv: [], cwd: "/projects/team", rows: 24, cols: 80 }), /argv must contain a program/);
+});
+test("subprocess provider terminates live processes on dispose", async () => {
+    const { signals, resolver } = spawnGuest({ emitExit: false });
+    const provider = createSubprocessProvider(resolver);
+    provider.spawn(spawnSpec());
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    provider.dispose();
+    assert.ok(signals.some((signal) => signal.signal === "SIGTERM"));
+});
+test("subprocess provider terminates on the spec abort signal", async () => {
+    const { signals, resolver } = spawnGuest({ emitExit: false });
+    const provider = createSubprocessProvider(resolver);
+    const controller = new AbortController();
+    provider.spawn(spawnSpec({ signal: controller.signal }));
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    controller.abort();
+    assert.ok(signals.some((signal) => signal.signal === "SIGTERM"));
+});
+test("subprocess provider rejects a pre-aborted spawn synchronously", () => {
+    const { resolver } = spawnGuest();
+    const provider = createSubprocessProvider(resolver);
+    const controller = new AbortController();
+    controller.abort(new Error("stop"));
+    assert.throws(() => provider.spawn(spawnSpec({ signal: controller.signal })), /aborted before spawn: Error: stop/);
+});
+test("subprocess provider waitForExit honors an abort signal", async () => {
+    const live = spawnGuest({ emitExit: false });
+    const liveProvider = createSubprocessProvider(live.resolver);
+    const handle = liveProvider.spawn(spawnSpec());
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    const controller = new AbortController();
+    const pending = handle.waitForExit(controller.signal);
+    controller.abort();
+    assert.equal(await pending, false);
+    liveProvider.dispose();
+    const exited = spawnGuest();
+    const exitedProvider = createSubprocessProvider(exited.resolver);
+    const exitedHandle = exitedProvider.spawn(spawnSpec());
+    assert.equal(await exitedHandle.waitForExit(), true);
+});
+test("subprocess provider forwards env tombstones and spills", async () => {
+    const fake = spawnGuest({ exit: { stdoutSpillValid: true } });
+    const provider = createSubprocessProvider(fake.resolver);
+    const handle = provider.spawn(spawnSpec({
+        env: { KEEP: "1", DROP: undefined },
+        stdio: {
+            stdin: "ignore",
+            stdout: { maxBytes: 4, spill: { maxBytes: 64 } },
+            stderr: { maxBytes: 4 },
+        },
+    }));
+    await handle.done;
+    const start = fake.starts[0].start;
+    assert.deepEqual(start.env, { KEEP: "1" });
+    assert.deepEqual(start.unsetEnv, ["DROP"]);
+    assert.equal(start.spillStdout.maxBytes, 64);
+    assert.match(start.spillStdout.path, /^\/tmp\/dsh-podman\/.+\.stdout$/);
+    assert.equal(start.spillStderr, undefined);
+    // No output was emitted, so the in-memory tail covered everything and the
+    // unneeded spill is discarded.
+    assert.equal(fake.deletes.length, 1);
+    assert.equal(fake.deletes[0].path, start.spillStdout.path);
+});
+test("subprocess provider keeps a spill that holds dropped output", async () => {
+    const fake = spawnGuest({
+        exit: { stdoutSpillValid: true },
+        stdout: "0123456789",
+    });
+    const provider = createSubprocessProvider(fake.resolver);
+    const handle = provider.spawn(spawnSpec({
+        stdio: {
+            stdin: "ignore",
+            stdout: { maxBytes: 4, spill: { maxBytes: 64 } },
+            stderr: { maxBytes: 4 },
+        },
+    }));
+    await handle.done;
+    assert.equal(fake.deletes.length, 0);
+    const read = handle.collected.stdout.readFrom(0);
+    assert.equal(read.lossy, true);
+    assert.equal(read.spillPath, fake.starts[0].start.spillStdout.path);
+});