withruntime 0.2.2 → 0.3.1

package/dist/sandbox.d.ts

@@ -0,0 +1,192 @@
+import { Page } from "./page.js";
+import type { RequestOptions, Transport } from "./transport.js";
+import type { CommandResult, ExecOptions, FileEntry, OutputEvent, ProcessInfo, SandboxInfo } from "./types.js";
+import { type SandboxExtensions } from "./products/index.js";
+import type { Snapshot, SnapshotOptions } from "./snapshots.js";
+/** A running (or stopped) sandbox. Every method is one API call or a short
+ * sequence of them; `await using sbx = await Sandbox.create()` stops it for
+ * you at the end of the block. */
+export interface Sandbox extends SandboxExtensions {
+}
+export declare class Sandbox implements AsyncDisposable {
+    #private;
+    readonly files: Files;
+    readonly processes: Processes;
+    constructor(transport: Transport, info: SandboxInfo);
+    get id(): string;
+    /** What the API last said about this sandbox. `refresh()` asks again. */
+    get info(): SandboxInfo;
+    get state(): SandboxInfo["state"];
+    refresh(options?: RequestOptions): Promise<this>;
+    /** Waits (server-side, no polling) until the sandbox reaches `state`. */
+    waitFor(state: "running" | "paused" | "stopped", options?: {
+        timeoutSeconds?: number;
+    } & RequestOptions): Promise<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. */
+    exec(command: string | readonly string[], options?: ExecOptions): Promise<CommandResult>;
+    /** 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. */
+    execStream(command: string | readonly string[], options?: ExecOptions): AsyncGenerator<OutputEvent>;
+    /** 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. */
+    spawn(command: string | readonly string[], options?: Omit<ExecOptions, "onStdout" | "onStderr" | "check" | "stdin"> & {
+        /** "pipe" keeps input open for write(); any other text is given once, then closed. */
+        stdin?: string;
+        pty?: {
+            cols?: number;
+            rows?: number;
+        };
+    }): Promise<Process>;
+    /** An interactive terminal over a WebSocket. Bytes you write are typed;
+     * onData receives what the terminal prints. */
+    terminal(options?: {
+        cols?: number;
+        rows?: number;
+        command?: string;
+        cwd?: string;
+        /** Attach to a process started with a pty instead of a new shell. */
+        processId?: string;
+        onData?: (data: Uint8Array) => void;
+    }): Promise<Terminal>;
+    stop(options?: RequestOptions & {
+        wait?: boolean;
+    }): Promise<this>;
+    pause(options?: RequestOptions & {
+        wait?: boolean;
+    }): Promise<this>;
+    /** Carries on a paused sandbox; `timeoutSeconds` is its new lease. */
+    wake(options?: RequestOptions & {
+        wait?: boolean;
+        timeoutSeconds?: number;
+    }): Promise<this>;
+    /** More time before the lease ends (at most an hour ahead of now). */
+    extend(seconds: number, options?: RequestOptions): Promise<this>;
+    /** Days a paused sandbox is kept before deletion (1 to 365). */
+    setRetention(days: number, options?: RequestOptions): Promise<this>;
+    /** 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. */
+    snapshot(options?: SnapshotOptions & RequestOptions): Promise<Snapshot>;
+    /** Copies of this sandbox as it is now (files, memory, running processes),
+     * each its own sandbox, answered once they run. A running sandbox is paused
+     * for the moment its snapshot takes, then woken. One without `count`; an
+     * array with it. */
+    fork(options?: {
+        name?: string;
+        labels?: Record<string, string>;
+        keepSnapshot?: boolean;
+    } & RequestOptions): Promise<Sandbox>;
+    fork(options: {
+        count: number;
+        name?: string;
+        labels?: Record<string, string>;
+        keepSnapshot?: boolean;
+    } & RequestOptions): Promise<Sandbox[]>;
+    /** Starts a stopped persistent sandbox again from its disk (memory is not kept). */
+    restart(options?: RequestOptions & {
+        wait?: boolean;
+    }): Promise<this>;
+    [Symbol.asyncDispose](): Promise<void>;
+    toJSON(): SandboxInfo;
+}
+export declare class Processes {
+    private readonly t;
+    private readonly sandboxId;
+    constructor(t: Transport, sandboxId: string);
+    list(): Promise<ProcessInfo[]>;
+    get(processId: string): Promise<Process>;
+    /** Output events from `cursor` until the process exits, across stream slices. */
+    follow(processId: string, options?: {
+        cursor?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<OutputEvent>;
+}
+/** A background process: its output, its input, its end. */
+export declare class Process {
+    #private;
+    private readonly t;
+    readonly sandboxId: string;
+    info: ProcessInfo;
+    constructor(t: Transport, sandboxId: string, info: ProcessInfo);
+    get id(): string;
+    /** Every output event from the start (or `cursor`) until exit. */
+    output(options?: {
+        cursor?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<OutputEvent>;
+    /** Waits for the process to end and returns its result. */
+    wait(options?: {
+        signal?: AbortSignal;
+    }): Promise<CommandResult>;
+    /** Sends input. Offsets are tracked for you, so a retried write is never typed twice. */
+    write(data: string | Uint8Array, options?: {
+        eof?: boolean;
+    }): Promise<void>;
+    kill(signal?: "SIGTERM" | "SIGKILL" | "SIGINT" | "SIGHUP" | "SIGQUIT" | "SIGUSR1" | "SIGUSR2"): Promise<void>;
+    resize(cols: number, rows: number): Promise<void>;
+    refresh(): Promise<ProcessInfo>;
+}
+export declare class Terminal {
+    #private;
+    private readonly socket;
+    readonly exited: Promise<number | null>;
+    private constructor();
+    get processId(): string | undefined;
+    static open(socket: WebSocket, onData?: (data: Uint8Array) => void): Promise<Terminal>;
+    write(data: string | Uint8Array): void;
+    resize(cols: number, rows: number): void;
+    close(): void;
+}
+/** Files in the sandbox. Paths are absolute; any path the sandbox user may use. */
+export declare class Files {
+    #private;
+    private readonly t;
+    private readonly sandboxId;
+    constructor(t: Transport, sandboxId: string);
+    /** A file's bytes, any size. */
+    read(path: string, options?: RequestOptions): Promise<Uint8Array>;
+    readText(path: string, options?: RequestOptions): Promise<string>;
+    /** Writes a file of any size, atomically, making parent directories. Large
+     * ones go in parallel 1 MiB chunks checked against their SHA-256. */
+    write(path: string, data: string | Uint8Array, options?: RequestOptions): Promise<{
+        path: string;
+        size: number;
+    }>;
+    /** Directory entries; `depth` goes deeper, `glob` filters (e.g. "**\/*.py"). */
+    list(path?: string, options?: {
+        depth?: number;
+        glob?: string;
+        hidden?: boolean;
+        limit?: number;
+    }): Promise<FileEntry[]>;
+    glob(pattern: string, root?: string): Promise<FileEntry[]>;
+    stat(path: string): Promise<(FileEntry & {
+        exists: true;
+    }) | {
+        exists: false;
+        path: string;
+    }>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string, options?: {
+        parents?: boolean;
+    }): Promise<void>;
+    remove(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<boolean>;
+    rename(from: string, to: string, options?: {
+        overwrite?: boolean;
+    }): Promise<void>;
+    /** Copies a local file or directory into the sandbox. A directory travels as
+     * one gzipped tar and is unpacked in place. */
+    upload(localPath: string, remotePath: string): Promise<void>;
+    /** Copies a file or directory out of the sandbox. */
+    download(remotePath: string, localPath: string): Promise<void>;
+}
+export declare function sandboxPage(t: Transport, body: {
+    data: SandboxInfo[];
+    nextCursor: string | null;
+}, query: Record<string, unknown>): Page<Sandbox>;