withruntime 0.8.4 → 0.9.0

package/dist/sandbox.js

@@ -1,3 +1,4 @@
+import { KEEP_ALIVE_MARGIN_SECONDS, STREAMED_EXEC_TIMEOUT_MS, WAIT_FOR_TIMEOUT_SECONDS, } from "./api-defaults.js";
 import { CommandError, ConnectionError, NotFoundError, RuntimeError } from "./errors.js";
 import { Page } from "./page.js";
 import { sandboxWatches, watchDirectory, } from "./products/watch.js";
@@ -12,6 +13,15 @@ const CHUNK = 1_048_576;
  * connections at once. */
 const PARALLEL = 8;
 const enc = (id) => encodeURIComponent(id);
+/** DELETE /v1/sandboxes/{id}, for `sandbox.delete()` and
+ * `runtime.sandboxes.delete(id)`. */
+export function deleteSandbox(t, id, options = {}) {
+    return t.json({
+        method: "DELETE",
+        path: `/v1/sandboxes/${enc(id)}`,
+        ...options,
+    });
+}
 /* Web APIs only, so the sandbox's commands, processes and files work in a
    browser with a session token (Sandbox.fromSession): no Buffer, no
    node:crypto. */
@@ -85,6 +95,13 @@ export class Sandbox {
         });
         return new Sandbox(transport, { id: session.sandboxId });
     }
+    /** The API's latest answer. `start`, the report of an image's start
+     * command, is the create's alone: the API keeps no record of it, so a
+     * later read of this sandbox keeps it here. */
+    #keep(info) {
+        const start = this.#info?.start;
+        this.#info = info.start === undefined && start !== undefined ? { ...info, start } : info;
+    }
     /** What the API last said about this sandbox. `refresh()` asks again. */
     get info() {
         return this.#info;
@@ -93,21 +110,24 @@ export class Sandbox {
         return this.#info.state;
     }
     async refresh(options = {}) {
-        this.#info = await this.#t.json({
+        this.#keep(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({
+        this.#keep(await this.#t.json({
             method: "GET",
             path: `/v1/sandboxes/${enc(this.id)}`,
-            query: { waitFor: state, timeoutSeconds: options.timeoutSeconds ?? 60 },
+            query: {
+                waitFor: state,
+                timeoutSeconds: options.timeoutSeconds ?? WAIT_FOR_TIMEOUT_SECONDS,
+            },
             ...options,
-        });
+        }));
         return this;
     }
     /** Runs a command and returns its exit code and output. A string runs under
@@ -136,7 +156,7 @@ export class Sandbox {
                         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);
+                        await (event.type === "stdout" ? options.onStdout : options.onStderr)?.(event.data);
                     }
                     else if (event.type === "truncated")
                         dropped = true;
@@ -206,9 +226,12 @@ export class Sandbox {
         const events = this.#t.events({
             method: "POST",
             path: `/v1/sandboxes/${enc(this.id)}:exec`,
-            body: { ...commandBody(command, { timeoutMs: 86_400_000, ...options }), stream: true },
+            body: {
+                ...commandBody(command, { timeoutMs: STREAMED_EXEC_TIMEOUT_MS, ...options }),
+                stream: true,
+            },
             ...pick(options),
-            timeoutMs: options.timeoutMs === undefined ? 86_400_000 : options.timeoutMs + 60_000,
+            timeoutMs: options.timeoutMs === undefined ? STREAMED_EXEC_TIMEOUT_MS : options.timeoutMs + 60_000,
         });
         try {
             for await (const event of events) {
@@ -245,7 +268,7 @@ export class Sandbox {
      * once. `stdin: "pipe"` keeps its input open for write(); `pty` gives it a
      * terminal. */
     async spawn(command, options = {}) {
-        const { stdin, pty, ...rest } = options;
+        const { stdin, pty, outputEncoding, ...rest } = options;
         const info = await this.#t.json({
             method: "POST",
             path: `/v1/sandboxes/${enc(this.id)}/processes`,
@@ -253,6 +276,7 @@ export class Sandbox {
                 ...commandBody(command, rest),
                 ...(stdin === "pipe" ? { stdinMode: "pipe" } : stdin === undefined ? {} : { stdin }),
                 ...(pty ? { pty } : {}),
+                ...(outputEncoding ? { outputEncoding } : {}),
             },
             ...pick(rest),
         });
@@ -304,6 +328,14 @@ export class Sandbox {
     async pause(options = {}) {
         return this.#lifecycle("pause", options);
     }
+    /** Deletes it for good: stops it if it runs or is paused, deletes its disk
+     * and paused memory, revokes its previews and ports, and removes it from
+     * lists. Its snapshots, usage and audit entries stay. Deleting it again
+     * answers the same. */
+    async delete(options = {}) {
+        this.#keepAlive?.();
+        return deleteSandbox(this.#t, this.id, options);
+    }
     /** Carries on a paused sandbox; `timeoutSeconds` is its new lease. */
     async wake(options = {}) {
         const { timeoutSeconds, ...rest } = options;
@@ -331,6 +363,26 @@ export class Sandbox {
     async update(settings, options = {}) {
         return this.#lifecycle("update", { ...options, wait: false }, { ...settings });
     }
+    /** Moves it to another image (id, name, name:tag or name@version), keeping
+     * its id, /workspace (its home: dotfiles, pip --user and npm -g installs),
+     * volumes, environment, name and previews. Its processes restart, and
+     * everything else on its old disk (sudo installs, apt packages, /etc) is
+     * lost, which `keep: "workspace"` says you know; snapshot it first to keep
+     * everything. A running sandbox is paused first. A switch that fails is
+     * undone (`switch_undone`), the sandbox on its old image with nothing lost.
+     * Charged as a wake. */
+    async switchImage(image, options) {
+        const { keep, ...rest } = options;
+        this.#keep(await this.#t.json({
+            method: "POST",
+            path: `/v1/sandboxes/${enc(this.id)}:switch-image`,
+            body: { image, keep },
+            // A pause, two boots and the copy between them.
+            wait: 120,
+            ...pick(rest),
+        }));
+        return this;
+    }
     /** Keeps a running sandbox's lease ahead of now, in the background, until
      * stop() or the returned function ends it: every `everySeconds` (60) it
      * extends the lease so that `marginSeconds` (600) remain, never more than
@@ -341,7 +393,7 @@ export class Sandbox {
     keepAlive(options = {}) {
         this.#keepAlive?.();
         const every = Math.max(10, options.everySeconds ?? 60) * 1000;
-        const margin = Math.min(3600, Math.max(60, options.marginSeconds ?? 600));
+        const margin = Math.min(3600, Math.max(60, options.marginSeconds ?? KEEP_ALIVE_MARGIN_SECONDS));
         let ended = false;
         let timer;
         const end = () => {
@@ -386,29 +438,76 @@ export class Sandbox {
      * the moment it takes, then woken; a paused one stays paused. */
     async snapshot(options = {}) {
         const { idempotencyKey, signal, timeoutMs, ...body } = options;
-        await this.refresh();
+        if (body.mode !== undefined && body.mode !== "memory" && body.mode !== "disk")
+            throw new TypeError("Snapshot mode must be memory or disk.");
+        signal?.throwIfAborted();
+        const until = performance.now() + Math.min(timeoutMs && timeoutMs > 0 ? timeoutMs : 60_000, 60_000);
+        const request = () => {
+            signal?.throwIfAborted();
+            const left = Math.ceil(until - performance.now());
+            if (left <= 0)
+                throw new RuntimeError({
+                    code: "snapshot_timeout",
+                    status: 0,
+                    message: "Snapshot capture ran past its deadline.",
+                });
+            return { ...(signal ? { signal } : {}), timeoutMs: left };
+        };
+        await this.refresh(request());
         // Straight after a fork or a wake the sandbox is still `resuming`, and
         // after a pause still `pausing`: wait for where it is going, or a
         // snapshot of it is refused as not paused (user lane, 23 September 2026).
         if (this.state === "resuming" || this.state === "starting")
-            await this.waitFor("running");
+            await this.waitFor("running", request());
         else if (this.state === "pausing")
-            await this.waitFor("paused");
+            await this.waitFor("paused", request());
         const running = this.state === "running";
-        if (running)
-            await this.pause();
+        // Check before entering cleanup: an abort during refresh must not pause or wake.
+        const pauseOptions = running ? request() : undefined;
         try {
-            return await this.#t.json({
+            if (running)
+                await this.pause(pauseOptions);
+            let snapshot = await this.#t.json({
                 method: "POST",
                 path: `/v1/sandboxes/${enc(this.id)}:snapshot`,
                 body,
                 wait: 10,
-                ...pick({
-                    ...(idempotencyKey ? { idempotencyKey } : {}),
-                    ...(signal ? { signal } : {}),
-                    ...(timeoutMs ? { timeoutMs } : {}),
-                }),
+                ...(idempotencyKey ? { idempotencyKey } : {}),
+                ...request(),
             });
+            // Prefer: wait is bounded on the server. A capture still in progress
+            // must keep its source paused, or the worker refuses it after we wake.
+            while (snapshot.state === "capturing") {
+                signal?.throwIfAborted();
+                if (performance.now() >= until)
+                    throw new RuntimeError({
+                        code: "snapshot_timeout",
+                        status: 0,
+                        message: "Snapshot capture did not finish within one minute.",
+                        details: { snapshotId: snapshot.id },
+                    });
+                await new Promise((resolve) => setTimeout(resolve, 200));
+                snapshot = await this.#t.json({
+                    method: "GET",
+                    path: `/v1/snapshots/${enc(snapshot.id)}`,
+                    ...request(),
+                });
+            }
+            if (snapshot.state !== "ready")
+                throw new RuntimeError({
+                    code: "snapshot_failed",
+                    status: 409,
+                    message: snapshot.error ?? `Snapshot capture ended in state ${snapshot.state}.`,
+                    details: { snapshotId: snapshot.id },
+                });
+            if (body.mode === "disk" && snapshot.mode !== "disk")
+                throw new RuntimeError({
+                    code: "snapshot_mode_mismatch",
+                    status: 409,
+                    message: "The server did not confirm a disk-only snapshot.",
+                    details: { snapshotId: snapshot.id },
+                });
+            return snapshot;
         }
         finally {
             if (running)
@@ -436,13 +535,13 @@ export class Sandbox {
         return this.#lifecycle("restart", options);
     }
     async #lifecycle(verb, options, body = {}) {
-        this.#info = await this.#t.json({
+        this.#keep(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]() {
@@ -481,11 +580,27 @@ class OutputCursor {
                     droppedBytes: event.offset - this.cursor,
                     resumeAt: event.offset,
                 };
-            this.cursor = Math.max(this.cursor, event.offset + utf8(event.data).byteLength);
+            this.cursor = Math.max(this.cursor, event.offset +
+                (event.base64 === undefined
+                    ? utf8(event.data).byteLength
+                    : processBytes(event.base64).length));
         }
         yield event;
     }
 }
+function processBytes(encoded) {
+    try {
+        return atob(encoded);
+    }
+    catch (cause) {
+        throw new RuntimeError({
+            code: "invalid_process_output",
+            status: 502,
+            message: "The process returned invalid base64 output.",
+            cause,
+        });
+    }
+}
 /** A stream cut off by the network rather than refused by Runtime: worth
  * reconnecting to from the cursor. */
 function cutOff(error) {
@@ -637,6 +752,7 @@ export class Process {
     sandboxId;
     info;
     #inputOffset;
+    #inputWrites = Promise.resolve();
     constructor(t, sandboxId, info) {
         this.t = t;
         this.sandboxId = sandboxId;
@@ -650,6 +766,34 @@ export class Process {
     output(options = {}) {
         return new Processes(this.t, this.sandboxId).follow(this.id, options);
     }
+    /** Lossless output for a process spawned with outputEncoding: "base64".
+     * Refuses text-only output rather than inventing bytes that were discarded. */
+    async *outputBytes(options = {}) {
+        if (this.info.outputEncoding !== "base64")
+            throw new RuntimeError({
+                code: "binary_output_unavailable",
+                status: 409,
+                message: "Spawn the process with outputEncoding: base64 to read lossless bytes.",
+            });
+        for await (const event of this.output(options)) {
+            if (event.type === "stdout" || event.type === "stderr") {
+                if (event.base64 === undefined)
+                    throw new RuntimeError({
+                        code: "binary_output_unavailable",
+                        status: 502,
+                        message: "The process returned text without its original bytes.",
+                    });
+                const raw = processBytes(event.base64);
+                yield {
+                    type: event.type,
+                    offset: event.offset,
+                    data: Uint8Array.from(raw, (c) => c.charCodeAt(0)),
+                };
+            }
+            else
+                yield event;
+        }
+    }
     /** Waits for the process to end and returns its result. */
     async wait(options = {}) {
         const out = { stdout: "", stderr: "" };
@@ -672,22 +816,37 @@ export class Process {
         };
     }
     /** Sends input. Offsets are tracked for you, so a retried write is never typed twice. */
-    async write(data, options = {}) {
-        const bytes = utf8(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: base64(bytes.subarray(sent)),
-                    offset: this.#inputOffset,
-                    ...(options.eof ? { eof: true } : {}),
-                },
-            });
-            sent += reply.offset - this.#inputOffset;
-            this.#inputOffset = reply.offset;
-        } while (sent < bytes.length);
+    write(data, options = {}) {
+        // Copy before queuing: callers may reuse their buffer while a previous
+        // write waits for the guest to drain its pipe.
+        const bytes = new Uint8Array(utf8(data));
+        const eof = options.eof === true;
+        const write = this.#inputWrites.then(async () => {
+            let sent = 0;
+            do {
+                const chunk = bytes.subarray(sent, sent + 1_048_576);
+                const reply = await this.t.json({
+                    method: "POST",
+                    path: `/v1/sandboxes/${enc(this.sandboxId)}/processes/${enc(this.id)}:write`,
+                    body: {
+                        base64: base64(chunk),
+                        offset: this.#inputOffset,
+                        ...(eof && sent + chunk.length === bytes.length ? { eof: true } : {}),
+                    },
+                });
+                const accepted = reply.offset - this.#inputOffset;
+                if (!Number.isSafeInteger(reply.offset) || accepted < 0 || accepted > chunk.length)
+                    throw new ConnectionError({
+                        message: "The process returned an invalid input offset.",
+                        code: "connection_error",
+                        status: 0,
+                    });
+                sent += accepted;
+                this.#inputOffset = reply.offset;
+            } while (sent < bytes.length);
+        });
+        this.#inputWrites = write.catch(() => undefined);
+        return write;
     }
     async kill(signal = "SIGTERM") {
         await this.t.json({
@@ -943,44 +1102,64 @@ export class Files {
     }
     /** Directory entries; `depth` goes deeper, `glob` filters (e.g. "**\/*.py"). */
     async list(path = "/workspace", options = {}) {
+        const { signal, timeoutMs, idempotencyKey, ...query } = options;
         return (await this.t.json({
             method: "GET",
             path: this.#path("/files/list"),
-            query: { path, ...options },
+            query: { path, ...query },
+            signal,
+            timeoutMs,
+            idempotencyKey,
         })).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 stat(path, options = {}) {
+        return this.t.json({
+            method: "GET",
+            path: this.#path("/files/stat"),
+            query: { path },
+            ...options,
+        });
     }
-    async exists(path) {
-        return (await this.stat(path)).exists;
+    async exists(path, options = {}) {
+        return (await this.stat(path, options)).exists;
     }
     async mkdir(path, options = {}) {
+        const { parents, ...request } = options;
         await this.t.json({
             method: "POST",
             path: this.#path("/files:mkdir"),
-            body: { path, ...options },
+            body: { path, parents },
+            ...request,
         });
     }
     async remove(path, options = {}) {
+        const { recursive, ...request } = options;
         return (await this.t.json({
             method: "POST",
             path: this.#path("/files:remove"),
-            body: { path, ...options },
+            body: { path, recursive },
+            ...request,
         })).removed;
     }
     async rename(from, to, options = {}) {
+        const { overwrite, ...request } = options;
         await this.t.json({
             method: "POST",
             path: this.#path("/files:rename"),
-            body: { from, to, ...options },
+            body: {
+                from,
+                to,
+                ...(overwrite === undefined ? {} : { overwrite }),
+            },
+            ...request,
         });
     }
     /** Copies a local file or directory into the sandbox. A directory travels as
-     * one gzipped tar and is unpacked in place. */
+     * one gzipped tar to the API's folder routes, and the sandbox's own `tar`
+     * unpacks it as it arrives, making the folder. */
     async upload(localPath, remotePath) {
         const { stat, readFile } = await import("node:fs/promises");
         const info = await stat(localPath);
@@ -1000,20 +1179,39 @@ export class Files {
         }
         const { packDirectory } = await import("./tar.js");
         const archive = await packDirectory(localPath);
-        // Large writes go only to /workspace (the server refuses others), so the
-        // archive is staged there and removed after unpacking.
-        const staging = `/workspace/.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 -xpzf "$2" -C "$1"; code=$?; rm -f "$2"; exit $code',
-            "sh",
-            remotePath,
-            staging,
-        ]);
-        if (result.exitCode !== 0)
-            throw new CommandError(result);
+        if (archive.length <= CHUNK) {
+            await this.t.bytes({
+                method: "PUT",
+                path: this.#path("/files/archive"),
+                query: { path: remotePath },
+                bytes: archive,
+            });
+            return;
+        }
+        // Larger: parts in order, each unpacked as it arrives; a part resent
+        // after a lost answer is not written twice.
+        const begin = await this.t.json({
+            method: "POST",
+            path: this.#path("/files/archive/uploads"),
+            body: { path: remotePath, gzip: true },
+        });
+        const upload = (suffix = "") => this.#path(`/files/archive/uploads/${enc(begin.uploadId)}${suffix}`);
+        try {
+            for (let offset = 0; offset < archive.length; offset += begin.chunkBytes)
+                await this.t.bytes({
+                    method: "PUT",
+                    path: upload(),
+                    query: { offset },
+                    bytes: archive.subarray(offset, offset + begin.chunkBytes),
+                });
+            await this.t.json({ method: "POST", path: upload(":commit"), body: {} });
+        }
+        catch (error) {
+            await this.t
+                .json({ method: "POST", path: upload(":abort"), body: {} })
+                .catch(() => undefined);
+            throw error;
+        }
     }
     /** Streams a file to disk through a partial file beside the target, renamed
      * into place only once every byte has arrived: a failed copy never leaves
@@ -1048,7 +1246,8 @@ export class Files {
         }
     }
     /** Copies a file or directory out of the sandbox. A file streams to disk,
-     * any size, checked against its length. */
+     * any size, checked against its length; a directory comes as one tar from
+     * the API's folder route. */
     async download(remotePath, localPath) {
         const fs = await import("node:fs/promises");
         const paths = await import("node:path");
@@ -1064,18 +1263,16 @@ export class Files {
             await this.#streamTo(remotePath, localPath);
             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);
-        }
+        // The sandbox's own `tar` packs it as it streams, and it is unpacked as
+        // it arrives; one cut short is refused and nothing is put in place.
+        const archive = await this.t.fileStream({
+            method: "GET",
+            path: this.#path("/files/archive"),
+            query: { path: remotePath, gzip: true },
+            accept: "application/gzip",
+        });
+        const { unpackStream } = await import("./tar.js");
+        await unpackStream(archive, localPath);
     }
 }
 export function sandboxPage(t, body, query) {

package/dist/snapshots.d.ts

@@ -6,6 +6,8 @@ import type { RequestOptions, Transport } from "./transport.js";
 export type Snapshot = {
     id: string;
     kind: "snapshot";
+    /** Absent on older servers means memory. */
+    mode?: "memory" | "disk";
     status: string;
     state: "capturing" | "ready" | "failed" | "deleting" | "deleted";
     name: string | null;
@@ -36,6 +38,8 @@ export type Snapshot = {
     [key: string]: unknown;
 };
 export type SnapshotOptions = {
+    /** Save files for a fresh boot, or the whole machine (default). */
+    mode?: "memory" | "disk";
     name?: string;
     labels?: Record<string, string>;
     retentionDays?: number;
@@ -54,7 +58,13 @@ export declare class Snapshots {
         name?: string;
         state?: "capturing" | "ready" | "failed" | "deleting";
         limit?: number;
-    }): Promise<Page<Snapshot>>;
+    }, options?: RequestOptions): Promise<Page<Snapshot>>;
+    /** Replace supplied labels or name; omitted fields are preserved. Null clears the name. */
+    update(id: string, input: {
+        name?: string | null;
+        labels?: Record<string, string>;
+        ifLabels?: Record<string, string>;
+    }, options?: RequestOptions): Promise<Snapshot>;
     delete(id: string, options?: RequestOptions): Promise<void>;
     extend(id: string, retentionDays: number, options?: RequestOptions): Promise<Snapshot>;
 }

package/dist/snapshots.js

@@ -19,7 +19,7 @@ export class Snapshots {
     get(id, options = {}) {
         return this.t.json({ method: "GET", path: `/v1/snapshots/${enc(id)}`, ...options });
     }
-    async list(filter = {}) {
+    async list(filter = {}, options = {}) {
         const query = {
             sandboxId: filter.sandboxId,
             name: filter.name,
@@ -31,11 +31,21 @@ export class Snapshots {
                 method: "GET",
                 path: "/v1/snapshots",
                 query: { ...query, cursor },
+                ...options,
             });
             return new Page(body.data, body.nextCursor, (next) => fetchPage(next));
         };
         return fetchPage();
     }
+    /** Replace supplied labels or name; omitted fields are preserved. Null clears the name. */
+    update(id, input, options = {}) {
+        return this.t.json({
+            method: "POST",
+            path: `/v1/snapshots/${enc(id)}:update`,
+            body: input,
+            ...options,
+        });
+    }
     async delete(id, options = {}) {
         await this.t.json({
             method: "POST",