withruntime 0.2.1 → 0.3.0

package/dist/sandbox.js

@@ -0,0 +1,628 @@
+import { CommandError, RuntimeError } from "./errors.js";
+import { Page } from "./page.js";
+import { sandboxFactories } from "./products/index.js";
+const CHUNK = 1_048_576;
+const PARALLEL = 4;
+const enc = (id) => encodeURIComponent(id);
+const toBase64 = (data) => (typeof data === "string" ? Buffer.from(data) : Buffer.from(data)).toString("base64");
+function commandBody(command, options) {
+    return {
+        ...(typeof command === "string" ? { command } : { argv: [...command] }),
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+        ...(options.env === undefined ? {} : { env: options.env }),
+        ...(options.stdin === undefined
+            ? {}
+            : typeof options.stdin === "string"
+                ? { stdin: options.stdin }
+                : { stdinBase64: toBase64(options.stdin) }),
+        ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+    };
+}
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
+export class Sandbox {
+    #info;
+    #t;
+    files;
+    processes;
+    constructor(transport, info) {
+        this.#t = transport;
+        this.#info = info;
+        this.files = new Files(transport, info.id);
+        this.processes = new Processes(transport, info.id);
+        for (const [name, make] of sandboxFactories())
+            Object.defineProperty(this, name, { value: make(transport, this), enumerable: false });
+    }
+    get id() {
+        return this.#info.id;
+    }
+    /** What the API last said about this sandbox. `refresh()` asks again. */
+    get info() {
+        return this.#info;
+    }
+    get state() {
+        return this.#info.state;
+    }
+    async refresh(options = {}) {
+        this.#info = await this.#t.json({
+            method: "GET",
+            path: `/v1/sandboxes/${enc(this.id)}`,
+            ...options,
+        });
+        return this;
+    }
+    /** Waits (server-side, no polling) until the sandbox reaches `state`. */
+    async waitFor(state, options = {}) {
+        this.#info = await this.#t.json({
+            method: "GET",
+            path: `/v1/sandboxes/${enc(this.id)}`,
+            query: { waitFor: state, timeoutSeconds: options.timeoutSeconds ?? 60 },
+            ...options,
+        });
+        return this;
+    }
+    /** Runs a command and returns its exit code and output. A string runs under
+     * `bash -c`; an array runs without a shell. With onStdout/onStderr the output
+     * streams as it happens. A timeout is a result (timedOut: true, the output so
+     * far), never an error; `check: true` throws CommandError on a non-zero exit. */
+    async exec(command, options = {}) {
+        const streaming = options.onStdout || options.onStderr || (options.timeoutMs ?? 0) > 60_000;
+        let result;
+        if (!streaming) {
+            result = await this.#t.json({
+                method: "POST",
+                path: `/v1/sandboxes/${enc(this.id)}:exec`,
+                body: commandBody(command, options),
+                ...pick(options),
+            });
+        }
+        else {
+            const out = { stdout: "", stderr: "" };
+            let exit;
+            let processId;
+            for await (const event of this.execStream(command, options)) {
+                if (event.type === "start")
+                    processId = event.processId;
+                else if (event.type === "stdout" || event.type === "stderr") {
+                    out[event.type] += event.data;
+                    (event.type === "stdout" ? options.onStdout : options.onStderr)?.(event.data);
+                }
+                else if (event.type === "exit")
+                    exit = event;
+            }
+            result = {
+                exitCode: exit?.exitCode ?? null,
+                ...out,
+                timedOut: exit?.timedOut ?? false,
+                ...(exit?.durationMs === undefined ? {} : { durationMs: exit.durationMs }),
+                ...(processId ? { processId } : {}),
+            };
+        }
+        if (options.check && (result.exitCode !== 0 || result.timedOut))
+            throw new CommandError(result);
+        return result;
+    }
+    /** The command's events as they happen: start, stdout, stderr, exit. Resumes
+     * by itself when the server ends a long stream, so it never drops output. */
+    async *execStream(command, options = {}) {
+        let processId;
+        let cursor = 0;
+        const events = this.#t.events({
+            method: "POST",
+            path: `/v1/sandboxes/${enc(this.id)}:exec`,
+            body: { ...commandBody(command, { timeoutMs: 86_400_000, ...options }), stream: true },
+            ...pick(options),
+            timeoutMs: options.timeoutMs === undefined ? 86_400_000 : options.timeoutMs + 60_000,
+        });
+        for await (const event of events) {
+            if (event.type === "start")
+                processId = event.processId;
+            if (event.type === "stdout" || event.type === "stderr")
+                cursor = event.offset + Buffer.byteLength(event.data);
+            if (event.type === "continue") {
+                cursor = event.cursor;
+                yield* this.processes.follow(event.processId, { cursor, signal: options.signal });
+                return;
+            }
+            if (event.type === "error")
+                throw new RuntimeError({
+                    message: event.error.message,
+                    code: event.error.code,
+                    status: 0,
+                    ...(event.error.requestId ? { requestId: event.error.requestId } : {}),
+                });
+            yield event;
+        }
+        void processId;
+    }
+    /** Starts a background process (a server, a watcher, a REPL) and returns at
+     * once. `stdin: "pipe"` keeps its input open for write(); `pty` gives it a
+     * terminal. */
+    async spawn(command, options = {}) {
+        const { stdin, pty, ...rest } = options;
+        const info = await this.#t.json({
+            method: "POST",
+            path: `/v1/sandboxes/${enc(this.id)}/processes`,
+            body: {
+                ...commandBody(command, rest),
+                ...(stdin === "pipe" ? { stdinMode: "pipe" } : stdin === undefined ? {} : { stdin }),
+                ...(pty ? { pty } : {}),
+            },
+            ...pick(rest),
+        });
+        return new Process(this.#t, this.id, info);
+    }
+    /** An interactive terminal over a WebSocket. Bytes you write are typed;
+     * onData receives what the terminal prints. */
+    async terminal(options = {}) {
+        const socket = await this.#t.websocket(`/v1/sandboxes/${enc(this.id)}/terminal`, {
+            cols: options.cols,
+            rows: options.rows,
+            command: options.command,
+            cwd: options.cwd,
+            processId: options.processId,
+        });
+        return Terminal.open(socket, options.onData);
+    }
+    async stop(options = {}) {
+        return this.#lifecycle("stop", options);
+    }
+    async pause(options = {}) {
+        return this.#lifecycle("pause", options);
+    }
+    /** Carries on a paused sandbox; `timeoutSeconds` is its new lease. */
+    async wake(options = {}) {
+        const { timeoutSeconds, ...rest } = options;
+        return this.#lifecycle("wake", rest, timeoutSeconds === undefined ? {} : { timeoutSeconds });
+    }
+    /** More time before the lease ends (at most an hour ahead of now). */
+    async extend(seconds, options = {}) {
+        return this.#lifecycle("extend", { ...options, wait: false }, { seconds });
+    }
+    /** Days a paused sandbox is kept before deletion (1 to 365). */
+    async setRetention(days, options = {}) {
+        return this.#lifecycle("retention", { ...options, wait: false }, { days });
+    }
+    /** Keeps this sandbox's whole machine (files, memory, running processes) as
+     * a snapshot to start new sandboxes from. A running sandbox is paused for
+     * the moment it takes, then woken; a paused one stays paused. */
+    async snapshot(options = {}) {
+        const { idempotencyKey, signal, timeoutMs, ...body } = options;
+        await this.refresh();
+        const running = this.state === "running";
+        if (running)
+            await this.pause();
+        try {
+            return await this.#t.json({
+                method: "POST",
+                path: `/v1/sandboxes/${enc(this.id)}:snapshot`,
+                body,
+                wait: 10,
+                ...pick({
+                    ...(idempotencyKey ? { idempotencyKey } : {}),
+                    ...(signal ? { signal } : {}),
+                    ...(timeoutMs ? { timeoutMs } : {}),
+                }),
+            });
+        }
+        finally {
+            if (running)
+                await this.wake();
+        }
+    }
+    async fork(options = {}) {
+        const { idempotencyKey, signal, timeoutMs, ...body } = options;
+        const reply = await this.#t.json({
+            method: "POST",
+            path: `/v1/sandboxes/${enc(this.id)}:fork`,
+            body,
+            wait: 60,
+            ...pick({
+                ...(idempotencyKey ? { idempotencyKey } : {}),
+                ...(signal ? { signal } : {}),
+                ...(timeoutMs ? { timeoutMs } : {}),
+            }),
+        });
+        const sandboxes = reply.sandboxes.map((info) => new Sandbox(this.#t, info));
+        return options.count === undefined ? sandboxes[0] : sandboxes;
+    }
+    /** Starts a stopped persistent sandbox again from its disk (memory is not kept). */
+    async restart(options = {}) {
+        return this.#lifecycle("restart", options);
+    }
+    async #lifecycle(verb, options, body = {}) {
+        this.#info = await this.#t.json({
+            method: "POST",
+            path: `/v1/sandboxes/${enc(this.id)}:${verb}`,
+            body,
+            wait: options.wait === false ? 0 : 60,
+            ...pick(options),
+        });
+        return this;
+    }
+    async [Symbol.asyncDispose]() {
+        if (this.#info.state === "stopped")
+            return;
+        await this.stop({ wait: false }).catch(() => undefined);
+    }
+    toJSON() {
+        return this.#info;
+    }
+}
+function pick(options) {
+    return {
+        ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.timeoutMs ? { timeoutMs: options.timeoutMs + 60_000 } : {}),
+    };
+}
+export class Processes {
+    t;
+    sandboxId;
+    constructor(t, sandboxId) {
+        this.t = t;
+        this.sandboxId = sandboxId;
+    }
+    async list() {
+        return (await this.t.json({
+            method: "GET",
+            path: `/v1/sandboxes/${enc(this.sandboxId)}/processes`,
+        })).data;
+    }
+    async get(processId) {
+        const info = await this.t.json({
+            method: "GET",
+            path: `/v1/sandboxes/${enc(this.sandboxId)}/processes/${enc(processId)}`,
+        });
+        return new Process(this.t, this.sandboxId, info);
+    }
+    /** Output events from `cursor` until the process exits, across stream slices. */
+    async *follow(processId, options = {}) {
+        let cursor = options.cursor ?? 0;
+        for (;;) {
+            let resumed = false;
+            for await (const event of this.t.events({
+                method: "GET",
+                path: `/v1/sandboxes/${enc(this.sandboxId)}/processes/${enc(processId)}/output`,
+                query: { cursor, follow: true },
+                timeoutMs: 180_000,
+                ...(options.signal ? { signal: options.signal } : {}),
+            })) {
+                if (event.type === "continue") {
+                    cursor = event.cursor;
+                    resumed = true;
+                    break;
+                }
+                if (event.type === "stdout" || event.type === "stderr")
+                    cursor = event.offset + Buffer.byteLength(event.data);
+                if (event.type === "error")
+                    throw new RuntimeError({
+                        message: event.error.message,
+                        code: event.error.code,
+                        status: 0,
+                    });
+                yield event;
+                if (event.type === "exit")
+                    return;
+            }
+            if (!resumed)
+                return;
+        }
+    }
+}
+/** A background process: its output, its input, its end. */
+export class Process {
+    t;
+    sandboxId;
+    info;
+    #inputOffset;
+    constructor(t, sandboxId, info) {
+        this.t = t;
+        this.sandboxId = sandboxId;
+        this.info = info;
+        this.#inputOffset = info.stdinOffset ?? 0;
+    }
+    get id() {
+        return this.info.id;
+    }
+    /** Every output event from the start (or `cursor`) until exit. */
+    output(options = {}) {
+        return new Processes(this.t, this.sandboxId).follow(this.id, options);
+    }
+    /** Waits for the process to end and returns its result. */
+    async wait(options = {}) {
+        const out = { stdout: "", stderr: "" };
+        let exit;
+        for await (const event of this.output(options)) {
+            if (event.type === "stdout" || event.type === "stderr")
+                out[event.type] += event.data;
+            if (event.type === "exit")
+                exit = event;
+        }
+        return {
+            exitCode: exit?.exitCode ?? null,
+            ...out,
+            timedOut: exit?.timedOut ?? false,
+            processId: this.id,
+        };
+    }
+    /** Sends input. Offsets are tracked for you, so a retried write is never typed twice. */
+    async write(data, options = {}) {
+        const bytes = typeof data === "string" ? Buffer.from(data) : Buffer.from(data);
+        let sent = 0;
+        do {
+            const reply = await this.t.json({
+                method: "POST",
+                path: `/v1/sandboxes/${enc(this.sandboxId)}/processes/${enc(this.id)}:write`,
+                body: {
+                    base64: bytes.subarray(sent).toString("base64"),
+                    offset: this.#inputOffset,
+                    ...(options.eof ? { eof: true } : {}),
+                },
+            });
+            sent += reply.offset - this.#inputOffset;
+            this.#inputOffset = reply.offset;
+        } while (sent < bytes.length);
+    }
+    async kill(signal = "SIGTERM") {
+        await this.t.json({
+            method: "POST",
+            path: `/v1/sandboxes/${enc(this.sandboxId)}/processes/${enc(this.id)}:signal`,
+            body: { signal },
+        });
+    }
+    async resize(cols, rows) {
+        await this.t.json({
+            method: "POST",
+            path: `/v1/sandboxes/${enc(this.sandboxId)}/processes/${enc(this.id)}:resize`,
+            body: { cols, rows },
+        });
+    }
+    async refresh() {
+        this.info = await this.t.json({
+            method: "GET",
+            path: `/v1/sandboxes/${enc(this.sandboxId)}/processes/${enc(this.id)}`,
+        });
+        return this.info;
+    }
+}
+export class Terminal {
+    socket;
+    exited;
+    #processId;
+    constructor(socket, exited) {
+        this.socket = socket;
+        this.exited = exited;
+    }
+    get processId() {
+        return this.#processId;
+    }
+    static open(socket, onData) {
+        socket.binaryType = "arraybuffer";
+        let settle;
+        const exited = new Promise((resolve) => (settle = resolve));
+        let exitCode = null;
+        return new Promise((resolve, reject) => {
+            let terminal;
+            socket.onmessage = (event) => {
+                if (typeof event.data === "string") {
+                    const message = JSON.parse(event.data);
+                    if (message.type === "ready") {
+                        terminal = new Terminal(socket, exited);
+                        terminal.#processId = message.processId;
+                        resolve(terminal);
+                    }
+                    else if (message.type === "exit")
+                        exitCode = message.exitCode ?? null;
+                    else if (message.type === "error" && !terminal)
+                        reject(new RuntimeError({
+                            message: message.error?.message ?? "Terminal failed.",
+                            code: message.error?.code ?? "terminal_failed",
+                            status: 0,
+                        }));
+                }
+                else
+                    onData?.(new Uint8Array(event.data));
+            };
+            socket.onclose = () => {
+                settle(exitCode);
+                if (!terminal)
+                    reject(new RuntimeError({
+                        message: "The terminal could not be opened (check the key and that the sandbox is running).",
+                        code: "terminal_refused",
+                        status: 0,
+                    }));
+            };
+            socket.onerror = () => undefined;
+        });
+    }
+    write(data) {
+        this.socket.send(typeof data === "string" ? new TextEncoder().encode(data) : data);
+    }
+    resize(cols, rows) {
+        this.socket.send(JSON.stringify({ type: "resize", cols, rows }));
+    }
+    close() {
+        this.socket.close(1000);
+    }
+}
+/** Files in the sandbox. Paths are absolute; any path the sandbox user may use. */
+export class Files {
+    t;
+    sandboxId;
+    constructor(t, sandboxId) {
+        this.t = t;
+        this.sandboxId = sandboxId;
+    }
+    #path = (suffix) => `/v1/sandboxes/${enc(this.sandboxId)}${suffix}`;
+    /** A file's bytes, any size. */
+    async read(path, options = {}) {
+        return this.t.bytes({
+            method: "GET",
+            path: this.#path("/files/content"),
+            query: { path },
+            accept: "application/octet-stream",
+            ...options,
+        });
+    }
+    async readText(path, options = {}) {
+        return new TextDecoder().decode(await this.read(path, options));
+    }
+    /** Writes a file of any size, atomically, making parent directories. Large
+     * ones go in parallel 1 MiB chunks checked against their SHA-256. */
+    async write(path, data, options = {}) {
+        const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+        if (bytes.length <= CHUNK) {
+            // bytes(), not send(): the answer is read, so its connection is free
+            // for the next call rather than held until garbage collection.
+            await this.t.bytes({
+                method: "PUT",
+                path: this.#path("/files/content"),
+                query: { path },
+                bytes,
+                ...options,
+            });
+            return { path, size: bytes.length };
+        }
+        const { createHash } = await import("node:crypto");
+        const sha256 = createHash("sha256").update(bytes).digest("hex");
+        const begin = await this.t.json({
+            method: "POST",
+            path: this.#path("/uploads"),
+            body: { path, size: bytes.length, sha256 },
+            ...options,
+        });
+        const offsets = [];
+        for (let offset = 0; offset < bytes.length; offset += begin.chunkBytes)
+            offsets.push(offset);
+        let next = 0;
+        const worker = async () => {
+            while (next < offsets.length) {
+                const offset = offsets[next++];
+                await this.t.bytes({
+                    method: "PUT",
+                    path: this.#path(`/uploads/${enc(begin.uploadId)}`),
+                    query: { offset },
+                    bytes: bytes.subarray(offset, offset + begin.chunkBytes),
+                });
+            }
+        };
+        try {
+            await Promise.all(Array.from({ length: Math.min(PARALLEL, offsets.length) }, worker));
+            await this.t.json({
+                method: "POST",
+                path: this.#path(`/uploads/${enc(begin.uploadId)}:commit`),
+                body: {},
+                ...options,
+            });
+        }
+        catch (error) {
+            await this.t
+                .json({
+                method: "POST",
+                path: this.#path(`/uploads/${enc(begin.uploadId)}:abort`),
+                body: {},
+            })
+                .catch(() => undefined);
+            throw error;
+        }
+        return { path, size: bytes.length };
+    }
+    /** Directory entries; `depth` goes deeper, `glob` filters (e.g. "**\/*.py"). */
+    async list(path = "/workspace", options = {}) {
+        return (await this.t.json({
+            method: "GET",
+            path: this.#path("/files/list"),
+            query: { path, ...options },
+        })).data;
+    }
+    async glob(pattern, root = "/workspace") {
+        return this.list(root, { glob: pattern });
+    }
+    async stat(path) {
+        return this.t.json({ method: "GET", path: this.#path("/files/stat"), query: { path } });
+    }
+    async exists(path) {
+        return (await this.stat(path)).exists;
+    }
+    async mkdir(path, options = {}) {
+        await this.t.json({
+            method: "POST",
+            path: this.#path("/files:mkdir"),
+            body: { path, ...options },
+        });
+    }
+    async remove(path, options = {}) {
+        return (await this.t.json({
+            method: "POST",
+            path: this.#path("/files:remove"),
+            body: { path, ...options },
+        })).removed;
+    }
+    async rename(from, to, options = {}) {
+        await this.t.json({
+            method: "POST",
+            path: this.#path("/files:rename"),
+            body: { from, to, ...options },
+        });
+    }
+    /** Copies a local file or directory into the sandbox. A directory travels as
+     * one gzipped tar and is unpacked in place. */
+    async upload(localPath, remotePath) {
+        const { stat, readFile } = await import("node:fs/promises");
+        const info = await stat(localPath);
+        if (info.isFile()) {
+            await this.write(remotePath, await readFile(localPath));
+            return;
+        }
+        const { packDirectory } = await import("./tar.js");
+        const archive = await packDirectory(localPath);
+        const staging = `/tmp/.runtime-upload-${crypto.randomUUID()}.tar.gz`;
+        await this.write(staging, archive);
+        const result = await new Sandbox(this.t, { id: this.sandboxId }).exec([
+            "sh",
+            "-c",
+            'mkdir -p "$1" && tar -xzf "$2" -C "$1"; code=$?; rm -f "$2"; exit $code',
+            "sh",
+            remotePath,
+            staging,
+        ]);
+        if (result.exitCode !== 0)
+            throw new CommandError(result);
+    }
+    /** Copies a file or directory out of the sandbox. */
+    async download(remotePath, localPath) {
+        const fs = await import("node:fs/promises");
+        const paths = await import("node:path");
+        const entry = await this.stat(remotePath);
+        if (!entry.exists)
+            throw new RuntimeError({
+                message: `${remotePath} does not exist.`,
+                code: "file_not_found",
+                status: 404,
+            });
+        if (entry.type !== "directory") {
+            await fs.mkdir(paths.dirname(localPath), { recursive: true });
+            await fs.writeFile(localPath, await this.read(remotePath));
+            return;
+        }
+        const staging = `/tmp/.runtime-download-${crypto.randomUUID()}.tar.gz`;
+        const sandbox = new Sandbox(this.t, { id: this.sandboxId });
+        const packed = await sandbox.exec(["tar", "-czf", staging, "-C", remotePath, "."]);
+        if (packed.exitCode !== 0)
+            throw new CommandError(packed);
+        try {
+            const { unpackArchive } = await import("./tar.js");
+            await unpackArchive(await this.read(staging), localPath);
+        }
+        finally {
+            await this.remove(staging).catch(() => undefined);
+        }
+    }
+}
+export function sandboxPage(t, body, query) {
+    return new Page(body.data.map((info) => new Sandbox(t, info)), body.nextCursor, async (cursor) => sandboxPage(t, await t.json({
+        method: "GET",
+        path: "/v1/sandboxes",
+        query: Object.assign({}, query, { cursor }),
+    }), query));
+}

package/dist/snapshots.d.ts

@@ -0,0 +1,50 @@
+import { Page } from "./page.js";
+import type { RequestOptions, Transport } from "./transport.js";
+/** A sandbox's whole machine (files, memory, running processes), kept on its
+ * host to start new sandboxes from. */
+export type Snapshot = {
+    id: string;
+    kind: "snapshot";
+    status: string;
+    state: "capturing" | "ready" | "failed" | "deleting" | "deleted";
+    name: string | null;
+    sourceSandboxId: string;
+    shape: {
+        vcpu: number;
+        memoryMiB: number;
+        diskMiB: number;
+        memoryGuarantee: string;
+    };
+    retentionDays: number;
+    /** What it stores, and what storage is metered for: the bytes it alone holds. */
+    storedBytes: number | null;
+    meteredBytes: number | null;
+    error: string | null;
+    createdAt: string;
+    readyAt: string | null;
+    expiresAt: string;
+    [key: string]: unknown;
+};
+export type SnapshotOptions = {
+    name?: string;
+    labels?: Record<string, string>;
+    retentionDays?: number;
+};
+/** `runtime.snapshots`. Take one with `sbx.snapshot()`, start from one with
+ * `runtime.sandboxes.create({ snapshot: id })`, or do both with `sbx.fork()`. */
+export declare class Snapshots {
+    private readonly t;
+    constructor(t: Transport);
+    create(input: {
+        sandboxId: string;
+    } & SnapshotOptions, options?: RequestOptions): Promise<Snapshot>;
+    get(id: string, options?: RequestOptions): Promise<Snapshot>;
+    list(filter?: {
+        sandboxId?: string;
+        name?: string;
+        state?: "capturing" | "ready" | "failed" | "deleting";
+        limit?: number;
+    }): Promise<Page<Snapshot>>;
+    delete(id: string, options?: RequestOptions): Promise<void>;
+    extend(id: string, retentionDays: number, options?: RequestOptions): Promise<Snapshot>;
+}