promigence 0.1.0-beta.12

package/dist/sdk/handles.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `CommandHandle` — the handle `commands.run(cmd, { background: true })` returns.
+ *
+ * Output is read the way the API serves it: by byte range, polled. There is no second streaming
+ * transport for background execs, and a poll at 100–500 ms is below the resolution anyone reads a
+ * dev server's log at. `wait()` parks on the API's `wait_ms` long-poll between reads, so a
+ * process that ends is noticed within one round trip, not one poll interval.
+ *
+ * Stated once: `pid` is the API's `exec_id` (a string), not a process number —
+ * it is what `commands.kill(pid)` and `commands.connect(pid)` take.
+ */
+import { type CommandResult } from "./core.js";
+import { inspect, type InspectOptions } from "node:util";
+import type { BackgroundExecRecord, PromigenceClient } from "./client.js";
+export interface CommandHandleOpts {
+    onStdout?: (data: string) => void;
+    onStderr?: (data: string) => void;
+    /** Poll interval while only callbacks are attached (default 250 ms). */
+    pollMs?: number;
+    /**
+     * The bound the command was started with, in ms: `wait()` then throws `CommandTimeoutError`
+     * for a command killed there rather than a bare `CommandExitError(137)`.
+     */
+    timeoutMs?: number;
+}
+export declare class CommandHandle {
+    #private;
+    /** The `exec_id`. */
+    readonly pid: string;
+    readonly sandboxId: string;
+    /** Everything read so far, decoded as UTF-8. */
+    stdout: string;
+    stderr: string;
+    private readonly opts;
+    private readonly offset;
+    private readonly decoder;
+    private record;
+    private pumping;
+    private stopped;
+    private draining;
+    constructor(client: PromigenceClient, record: BackgroundExecRecord, opts?: CommandHandleOpts);
+    /** The last status the API reported. */
+    get state(): BackgroundExecRecord["state"];
+    get exitCode(): number | undefined;
+    get error(): string | undefined;
+    /** Started with `stdin: true`, so `sendStdin` / `closeStdin` reach the process. */
+    get stdinOpen(): boolean;
+    /**
+     * Write to the process's standard input. Text is sent as UTF-8; bytes are sent as they are.
+     *
+     * Only for a command started with `{ stdin: true }` — a child's stdin cannot be opened after
+     * it has been spawned, and this throws (`no_stdin`) rather than dropping the bytes.
+     */
+    sendStdin(data: string | Uint8Array): Promise<number>;
+    /**
+     * Close stdin (EOF). A process reading to end-of-input — `sort`, `cat`, a REPL — does nothing
+     * until this arrives, so it is the other half of `sendStdin` and not an optional tidy-up.
+     */
+    closeStdin(): Promise<void>;
+    /** Read every byte that is buffered now, on both streams. Serialised: one drain at a time. */
+    private drain;
+    private pump;
+    /**
+     * Wait for the process to end and return its result. A non-zero exit throws
+     * `CommandExitError` (it carries `stdout`/`stderr`/`exitCode`); a command killed at the
+     * `timeoutMs` it was started with throws `CommandTimeoutError`, a `CommandExitError` that says so.
+     */
+    wait(): Promise<CommandResult>;
+    /** SIGKILL. `true` if the process was running and the signal was delivered. */
+    kill(): Promise<boolean>;
+    /** Stop polling for output. The process keeps running; `commands.connect(pid)` re-attaches. */
+    disconnect(): Promise<void>;
+    /** What `JSON.stringify` shows: ids and status. The client (and its key) is never part of it. */
+    toJSON(): {
+        pid: string;
+        sandboxId: string;
+        state: BackgroundExecRecord["state"];
+        exitCode: number | undefined;
+    };
+    /** What `console.log` / `util.inspect` show: the same as `toJSON`. */
+    [inspect.custom](_depth: number, opts: InspectOptions): string;
+}

package/dist/sdk/handles.js

@@ -0,0 +1,135 @@
+import { CommandExitError, EnvFailedError } from "./core.js";
+import { inspect } from "node:util";
+import { CommandTimeoutError, exitTimedOut } from "./command-errors.js";
+const HANDLE_WAIT_MS = 30_000;
+const HANDLE_POLL_MS = 250;
+export class CommandHandle {
+    pid;
+    sandboxId;
+    stdout = "";
+    stderr = "";
+    #client;
+    opts;
+    offset = { stdout: 0, stderr: 0 };
+    decoder = { stdout: new TextDecoder(), stderr: new TextDecoder() };
+    record;
+    pumping = false;
+    stopped = false;
+    draining;
+    constructor(client, record, opts = {}) {
+        this.#client = client;
+        this.record = record;
+        this.pid = record.exec_id;
+        this.sandboxId = record.sandbox_id;
+        this.opts = opts;
+        if (opts.onStdout || opts.onStderr)
+            void this.pump();
+    }
+    get state() { return this.record.state; }
+    get exitCode() {
+        const e = this.record.exit;
+        if (!e)
+            return undefined;
+        return e.exit_code ?? (e.signal ? 128 + e.signal : -1);
+    }
+    get error() { return this.record.error?.msg; }
+    get stdinOpen() { return Boolean(this.record.stdin_open); }
+    async sendStdin(data) {
+        const r = await this.#client.sandboxes.execs.stdin(this.sandboxId, this.pid, { data });
+        return r.written;
+    }
+    async closeStdin() {
+        await this.#client.sandboxes.execs.stdin(this.sandboxId, this.pid, { eof: true });
+    }
+    drain() {
+        const run = async () => {
+            for (const s of ["stdout", "stderr"]) {
+                for (;;) {
+                    const r = await this.#client.sandboxes.execs.read(this.sandboxId, this.pid, s, { offset: this.offset[s] });
+                    this.record = r.record;
+                    if (r.data.length === 0)
+                        break;
+                    this.offset[s] += r.data.length;
+                    const text = this.decoder[s].decode(r.data, { stream: true });
+                    this[s] += text;
+                    if (text)
+                        (s === "stdout" ? this.opts.onStdout : this.opts.onStderr)?.(text);
+                    if (r.eof)
+                        break;
+                }
+            }
+        };
+        const next = (this.draining ?? Promise.resolve()).then(run, run);
+        this.draining = next.catch(() => { });
+        return next;
+    }
+    async pump() {
+        if (this.pumping)
+            return;
+        this.pumping = true;
+        try {
+            while (!this.stopped) {
+                await this.drain();
+                if (this.record.state !== "running") {
+                    await this.drain();
+                    break;
+                }
+                await new Promise((r) => { setTimeout(r, this.opts.pollMs ?? 250); });
+            }
+        }
+        catch {
+        }
+        finally {
+            this.pumping = false;
+        }
+    }
+    async wait() {
+        for (;;) {
+            await this.drain();
+            if (this.record.state !== "running")
+                break;
+            this.record = await this.#client.sandboxes.execs.get(this.sandboxId, this.pid, { waitMs: HANDLE_WAIT_MS });
+            if (this.record.state === "running" && !((this.record.waited_ms ?? 0) >= HANDLE_WAIT_MS)) {
+                await new Promise((r) => { setTimeout(r, HANDLE_POLL_MS); });
+            }
+        }
+        await this.drain();
+        for (const s of ["stdout", "stderr"]) {
+            const tail = this.decoder[s].decode();
+            if (tail) {
+                this[s] += tail;
+                (s === "stdout" ? this.opts.onStdout : this.opts.onStderr)?.(tail);
+            }
+        }
+        if (this.record.state === "failed") {
+            const e = this.record.error;
+            throw new EnvFailedError(e?.code ?? "sandbox_unresponsive", `background exec ${this.pid} failed: ${e?.msg ?? "no exit record"}`, "Not your command's failure. Check the sandbox is still ready (`promigence run report <run_id>`) and start it again.");
+        }
+        const result = {
+            exitCode: this.exitCode ?? -1,
+            stdout: this.stdout,
+            stderr: this.stderr,
+            truncated: Boolean(this.record.truncated),
+            execId: this.pid,
+        };
+        if (result.exitCode !== 0) {
+            if (exitTimedOut(this.record.exit, this.opts.timeoutMs))
+                throw new CommandTimeoutError(result, this.opts.timeoutMs);
+            throw new CommandExitError(result);
+        }
+        return result;
+    }
+    async kill() {
+        const r = await this.#client.sandboxes.execs.signal(this.sandboxId, this.pid, "SIGKILL");
+        return r.delivered;
+    }
+    async disconnect() {
+        this.stopped = true;
+    }
+    toJSON() {
+        return { pid: this.pid, sandboxId: this.sandboxId, state: this.state, exitCode: this.exitCode };
+    }
+    [inspect.custom](_depth, opts) {
+        return `CommandHandle ${inspect(this.toJSON(), opts)}`;
+    }
+}

package/dist/sdk/hint.js

@@ -0,0 +1,7 @@
+const PLAIN = /^[A-Za-z0-9_./:@,][A-Za-z0-9_./:@,=-]*$/;
+export function hintArg(value) {
+    const s = String(value);
+    if (PLAIN.test(s))
+        return s;
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}