withruntime 0.3.1 → 0.5.0

package/dist/e2b/commands.js

@@ -0,0 +1,268 @@
+import { request } from "./client.js";
+import { CommandExitError, guard, InvalidArgumentError, NotSupportedError, SandboxError, TimeoutError, translate, } from "./errors.js";
+const DEFAULT_TIMEOUT_MS = 60_000;
+const LONGEST_MS = 86_400_000;
+/** E2B's pids are numbers; Runtime's process ids are strings. The number is a
+ * 31-bit FNV-1a hash of the id, so every client derives the same one. */
+export function pidOf(processId) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < processId.length; i++) {
+        hash ^= processId.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 1 || 1;
+}
+function refuseUser(user) {
+    if (user !== undefined && user !== "user")
+        throw new NotSupportedError(`Running as the user "${user}"`, 'Runtime runs commands as its sandbox owner, with passwordless sudo: prefix the command with "sudo" to run it as root.');
+}
+function timeoutFor(timeoutMs) {
+    if (timeoutMs === undefined)
+        return DEFAULT_TIMEOUT_MS;
+    if (timeoutMs === 0)
+        return LONGEST_MS;
+    return Math.min(timeoutMs, LONGEST_MS);
+}
+function timedOut(timeoutMs) {
+    return new TimeoutError(`Command timed out after ${timeoutMs} ms: this error is likely due to exceeding 'timeoutMs'. ` +
+        "Pass a larger 'timeoutMs', or 0 for no limit.");
+}
+/** A Runtime result as E2B's: a command killed by a signal has no exit code on
+ * Runtime; E2B reports -1. */
+function toResult(result) {
+    const exitCode = result.exitCode ?? -1;
+    return {
+        exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        ...(exitCode === 0
+            ? {}
+            : {
+                error: result.exitCode === null ? "terminated by a signal" : `exit status ${exitCode}`,
+            }),
+    };
+}
+function settle(result, timeoutMs) {
+    if (result.timedOut)
+        throw timedOut(timeoutMs);
+    const out = toResult(result);
+    if (out.exitCode !== 0)
+        throw new CommandExitError(out);
+    return out;
+}
+/** `sandbox.commands`: E2B's command module over Runtime's exec and processes. */
+export class Commands {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    #env(envs) {
+        const merged = { ...this.#ctx.envs, ...envs };
+        return Object.keys(merged).length ? { env: merged } : {};
+    }
+    async run(cmd, opts = {}) {
+        refuseUser(opts.user);
+        await this.#ctx.ensureHome(`${cmd}\n${opts.cwd ?? ""}`);
+        const timeoutMs = timeoutFor(opts.timeoutMs);
+        if (opts.background || opts.stdin) {
+            const handle = await this.#start(cmd, opts, timeoutMs);
+            return opts.background ? handle : handle.wait();
+        }
+        const result = await guard("sandbox", () => this.#ctx.runtime.exec(cmd, {
+            ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+            ...this.#env(opts.envs),
+            timeoutMs,
+            ...(opts.onStdout ? { onStdout: (text) => void opts.onStdout(text) } : {}),
+            ...(opts.onStderr ? { onStderr: (text) => void opts.onStderr(text) } : {}),
+            ...(opts.signal ? { signal: opts.signal } : {}),
+        }));
+        return settle(result, timeoutMs);
+    }
+    async #start(cmd, opts, timeoutMs) {
+        const process = await guard("sandbox", () => this.#ctx.runtime.spawn(cmd, {
+            ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+            ...this.#env(opts.envs),
+            timeoutMs,
+            ...(opts.stdin ? { stdin: "pipe" } : {}),
+            ...request(opts),
+        }));
+        return new CommandHandle(process, {
+            stdin: opts.stdin === true,
+            timeoutMs,
+            ...(opts.onStdout ? { onStdout: opts.onStdout } : {}),
+            ...(opts.onStderr ? { onStderr: opts.onStderr } : {}),
+        });
+    }
+    /** Running commands. */
+    async list(_opts = {}) {
+        const processes = await guard("sandbox", () => this.#ctx.runtime.processes.list());
+        return processes.filter((info) => info.state === "running").map(describe);
+    }
+    async #find(pid) {
+        const processes = await guard("sandbox", () => this.#ctx.runtime.processes.list());
+        return processes.find((info) => pidOf(info.id) === pid && info.state === "running");
+    }
+    async #process(pid) {
+        const info = await this.#find(pid);
+        if (!info)
+            throw new SandboxError(`No running command with pid ${pid}.`);
+        return guard("sandbox", () => this.#ctx.runtime.processes.get(info.id));
+    }
+    /** Kills a command with SIGKILL, as E2B does. False when there is none. */
+    async kill(pid, _opts = {}) {
+        const info = await this.#find(pid);
+        if (!info)
+            return false;
+        const process = await guard("sandbox", () => this.#ctx.runtime.processes.get(info.id));
+        await guard("sandbox", () => process.kill("SIGKILL"));
+        return true;
+    }
+    /** Sends input to a command started with `stdin: true`. */
+    async sendStdin(pid, data, _opts = {}) {
+        const process = await this.#process(pid);
+        if (!process.info.stdinOpen)
+            throw new InvalidArgumentError(`The command with pid ${pid} was not started with stdin: true, so its input is closed.`);
+        await guard("sandbox", () => process.write(data));
+    }
+    async closeStdin(pid, _opts = {}) {
+        const process = await this.#process(pid);
+        await guard("sandbox", () => process.write("", { eof: true }));
+    }
+    /** Attaches to a running command; output from now on reaches the handle. */
+    async connect(pid, opts = {}) {
+        const process = await this.#process(pid);
+        return new CommandHandle(process, {
+            stdin: process.info.stdinOpen,
+            timeoutMs: timeoutFor(opts.timeoutMs),
+            cursor: process.info.outputBytes,
+            ...(opts.onStdout ? { onStdout: opts.onStdout } : {}),
+            ...(opts.onStderr ? { onStderr: opts.onStderr } : {}),
+        });
+    }
+}
+function describe(info) {
+    return {
+        pid: pidOf(info.id),
+        cmd: "/bin/bash",
+        args: ["-c", info.command],
+        envs: {},
+        cwd: info.cwd,
+    };
+}
+/** A command started in the background: E2B's CommandHandle over a Runtime
+ * process. Output streams into `stdout`/`stderr` and the callbacks as it
+ * arrives. */
+export class CommandHandle {
+    pid;
+    #process;
+    #stdin;
+    #timeoutMs;
+    #abort = new AbortController();
+    #done;
+    #stdout = "";
+    #stderr = "";
+    #exit;
+    #failure;
+    #disconnected = false;
+    constructor(process, options) {
+        this.#process = process;
+        this.pid = pidOf(process.id);
+        this.#stdin = options.stdin;
+        this.#timeoutMs = options.timeoutMs;
+        this.#done = this.#follow(options);
+    }
+    async #follow(options) {
+        try {
+            for await (const event of this.#process.output({
+                ...(options.cursor ? { cursor: options.cursor } : {}),
+                signal: this.#abort.signal,
+            })) {
+                if (event.type === "stdout") {
+                    this.#stdout += event.data;
+                    await options.onStdout?.(event.data);
+                }
+                else if (event.type === "stderr") {
+                    this.#stderr += event.data;
+                    await options.onStderr?.(event.data);
+                }
+                else if (event.type === "exit") {
+                    this.#exit = { exitCode: event.exitCode, timedOut: event.timedOut };
+                }
+            }
+        }
+        catch (error) {
+            if (!this.#disconnected) {
+                const translated = translate(error, "sandbox");
+                this.#failure =
+                    translated instanceof Error ? translated : new SandboxError(String(translated));
+            }
+        }
+    }
+    /** The exit code, or undefined while the command runs. */
+    get exitCode() {
+        return this.#exit ? (this.#exit.exitCode ?? -1) : undefined;
+    }
+    get error() {
+        return this.#exit ? this.#result().error : undefined;
+    }
+    get stdout() {
+        return this.#stdout;
+    }
+    get stderr() {
+        return this.#stderr;
+    }
+    #result() {
+        return toResult({
+            exitCode: this.#exit?.exitCode ?? null,
+            stdout: this.#stdout,
+            stderr: this.#stderr,
+        });
+    }
+    /** Waits for the command to end. Throws CommandExitError on a non-zero exit,
+     * as E2B does. */
+    async wait() {
+        await this.#done;
+        if (this.#failure)
+            throw this.#failure;
+        if (!this.#exit)
+            throw new SandboxError(this.#disconnected
+                ? "Disconnected from the command before it ended; reconnect with commands.connect(pid)."
+                : "The command's output ended without an exit.");
+        return settle({
+            exitCode: this.#exit.exitCode,
+            stdout: this.#stdout,
+            stderr: this.#stderr,
+            timedOut: this.#exit.timedOut,
+        }, this.#timeoutMs);
+    }
+    /** Stops receiving output; the command keeps running. */
+    async disconnect() {
+        this.#disconnected = true;
+        this.#abort.abort();
+        await Promise.resolve();
+    }
+    /** Kills the command with SIGKILL. False when it had already ended. */
+    async kill() {
+        if (this.#exit)
+            return false;
+        try {
+            await guard("sandbox", () => this.#process.kill("SIGKILL"));
+            return true;
+        }
+        catch (error) {
+            if (error instanceof SandboxError && error.statusCode === 404)
+                return false;
+            throw error;
+        }
+    }
+    async sendStdin(data, _opts = {}) {
+        if (!this.#stdin)
+            throw new InvalidArgumentError("The command was not started with stdin: true, so its input is closed.");
+        await guard("sandbox", () => this.#process.write(data));
+    }
+    async closeStdin(_opts = {}) {
+        if (!this.#stdin)
+            throw new InvalidArgumentError("The command was not started with stdin: true.");
+        await guard("sandbox", () => this.#process.write("", { eof: true }));
+    }
+}

package/dist/e2b/errors.d.ts

@@ -0,0 +1,72 @@
+/** Base class for E2B's sandbox errors. */
+export declare class SandboxError extends Error {
+    statusCode?: number;
+    code?: string;
+    hint?: string;
+    requestId?: string;
+    constructor(message?: string);
+}
+export declare class TimeoutError extends SandboxError {
+}
+export declare class InvalidArgumentError extends SandboxError {
+}
+export declare class NotEnoughSpaceError extends SandboxError {
+}
+export declare class NotFoundError extends SandboxError {
+}
+export declare class FileNotFoundError extends NotFoundError {
+}
+export declare class SandboxNotFoundError extends NotFoundError {
+}
+export declare class TemplateError extends SandboxError {
+}
+export declare class RateLimitError extends SandboxError {
+}
+/** E2B's AuthenticationError extends Error, not SandboxError. */
+export declare class AuthenticationError extends Error {
+    code?: string;
+    hint?: string;
+    requestId?: string;
+    constructor(message: string);
+}
+/** E2B's ServiceBusyError extends Error, not SandboxError. */
+export declare class ServiceBusyError extends Error {
+    readonly statusCode = 503;
+    code?: string;
+    hint?: string;
+    requestId?: string;
+    constructor(message: string);
+}
+/** A call that E2B supports and Runtime does not, or not in the same way.
+ * Thrown before anything is done, never after doing something different.
+ * `feature` names what was asked for; `alternative` says what to use on
+ * Runtime instead. */
+export declare class NotSupportedError extends SandboxError {
+    readonly feature: string;
+    readonly alternative: string;
+    constructor(feature: string, alternative: string, message?: string);
+}
+/** What `commands.run` resolves with, as in E2B. */
+export interface CommandResult {
+    exitCode: number;
+    error?: string;
+    stdout: string;
+    stderr: string;
+}
+/** Thrown by `commands.run` and `CommandHandle.wait` when the command exits
+ * with a code other than 0. It carries the result, as in E2B. */
+export declare class CommandExitError extends SandboxError implements CommandResult {
+    #private;
+    constructor(result: CommandResult);
+    get exitCode(): number;
+    get error(): string | undefined;
+    get stdout(): string;
+    get stderr(): string;
+}
+/** Which object a call was about, to name a 404 the way E2B would. */
+export type Subject = "sandbox" | "file" | "other";
+/** Turns a Runtime SDK error into the E2B error a caller written for E2B
+ * expects. Anything that is not a Runtime error passes through unchanged. */
+export declare function translate(error: unknown, subject?: Subject): unknown;
+/** Runs `work`, turning any Runtime error into its E2B counterpart. */
+export declare function guard<T>(subject: Subject, work: () => Promise<T>): Promise<T>;

package/dist/e2b/errors.js

@@ -0,0 +1,151 @@
+import { RuntimeError } from "../errors.js";
+function attach(error, detail) {
+    const target = error;
+    if (detail.code !== undefined)
+        target.code = detail.code;
+    if (detail.hint !== undefined)
+        target.hint = detail.hint;
+    if (detail.requestId !== undefined)
+        target.requestId = detail.requestId;
+    if (detail.cause !== undefined)
+        target.cause = detail.cause;
+}
+/** Base class for E2B's sandbox errors. */
+export class SandboxError extends Error {
+    statusCode;
+    code;
+    hint;
+    requestId;
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+export class TimeoutError extends SandboxError {
+}
+export class InvalidArgumentError extends SandboxError {
+}
+export class NotEnoughSpaceError extends SandboxError {
+}
+export class NotFoundError extends SandboxError {
+}
+export class FileNotFoundError extends NotFoundError {
+}
+export class SandboxNotFoundError extends NotFoundError {
+}
+export class TemplateError extends SandboxError {
+}
+export class RateLimitError extends SandboxError {
+}
+/** E2B's AuthenticationError extends Error, not SandboxError. */
+export class AuthenticationError extends Error {
+    code;
+    hint;
+    requestId;
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** E2B's ServiceBusyError extends Error, not SandboxError. */
+export class ServiceBusyError extends Error {
+    statusCode = 503;
+    code;
+    hint;
+    requestId;
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** A call that E2B supports and Runtime does not, or not in the same way.
+ * Thrown before anything is done, never after doing something different.
+ * `feature` names what was asked for; `alternative` says what to use on
+ * Runtime instead. */
+export class NotSupportedError extends SandboxError {
+    feature;
+    alternative;
+    constructor(feature, alternative, message) {
+        super(message ?? `${feature} is not supported on Runtime. ${alternative}`);
+        this.feature = feature;
+        this.alternative = alternative;
+        this.code = "not_supported";
+    }
+}
+/** Thrown by `commands.run` and `CommandHandle.wait` when the command exits
+ * with a code other than 0. It carries the result, as in E2B. */
+export class CommandExitError extends SandboxError {
+    #result;
+    constructor(result) {
+        super(`Command exited with code ${result.exitCode} and error:\n${result.stderr}`);
+        this.#result = result;
+    }
+    get exitCode() {
+        return this.#result.exitCode;
+    }
+    get error() {
+        return this.#result.error;
+    }
+    get stdout() {
+        return this.#result.stdout;
+    }
+    get stderr() {
+        return this.#result.stderr;
+    }
+}
+/** Turns a Runtime SDK error into the E2B error a caller written for E2B
+ * expects. Anything that is not a Runtime error passes through unchanged. */
+export function translate(error, subject = "other") {
+    if (!(error instanceof RuntimeError))
+        return error;
+    const message = [
+        error.message,
+        error.hint ? `Hint: ${error.hint}` : "",
+        error.requestId ? `Request: ${error.requestId}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    let out;
+    if (error.status === 503 && error.code.endsWith("_unavailable"))
+        // A product switched off on purpose (forks, previews): Runtime's own words
+        // say what is off and what to use meanwhile.
+        out = new NotSupportedError(error.code.replace(/_unavailable$/, ""), error.hint ?? "", message);
+    else if (error.status === 401 || error.status === 403)
+        out = new AuthenticationError(message);
+    else if (error.code === "file_not_found" || (error.status === 404 && subject === "file"))
+        out = new FileNotFoundError(message);
+    else if (error.status === 404 && subject === "sandbox")
+        out = new SandboxNotFoundError(message);
+    else if (error.status === 404)
+        out = new NotFoundError(message);
+    else if (error.status === 429)
+        out = new RateLimitError(message);
+    else if (/space|disk_full|no_room/.test(error.code))
+        out = new NotEnoughSpaceError(message);
+    else if (error.status === 400 || error.status === 413 || error.status === 422)
+        out = new InvalidArgumentError(message);
+    else if (error.status === 503)
+        out = new ServiceBusyError(message);
+    else if (error.code === "command_timeout")
+        out = new TimeoutError(message);
+    else
+        out = new SandboxError(message);
+    if (out instanceof SandboxError && error.status)
+        out.statusCode = error.status;
+    attach(out, {
+        code: error.code,
+        ...(error.hint ? { hint: error.hint } : {}),
+        ...(error.requestId ? { requestId: error.requestId } : {}),
+        cause: error,
+    });
+    return out;
+}
+/** Runs `work`, turning any Runtime error into its E2B counterpart. */
+export async function guard(subject, work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        throw translate(error, subject);
+    }
+}

package/dist/e2b/filesystem.d.ts

@@ -0,0 +1,82 @@
+import type { SandboxContext, Username } from "./commands.js";
+export declare enum FileType {
+    FILE = "file",
+    DIR = "dir",
+    SYMLINK = "symlink"
+}
+export interface WriteInfo {
+    name: string;
+    type?: FileType;
+    path: string;
+    metadata?: Record<string, string>;
+}
+export interface EntryInfo extends WriteInfo {
+    size: number;
+    mode: number;
+    permissions: string;
+    /** Runtime's listing does not say who owns a file: always "". */
+    owner: string;
+    /** Runtime's listing does not say a file's group: always "". */
+    group: string;
+    modifiedTime?: Date;
+    symlinkTarget?: string;
+}
+export type WriteEntry = {
+    path: string;
+    data: string | ArrayBuffer | Blob | ReadableStream;
+};
+export interface FilesystemRequestOpts {
+    requestTimeoutMs?: number;
+    signal?: AbortSignal;
+    /** Only the default user; see CommandStartOpts.user. */
+    user?: Username;
+}
+export interface FilesystemReadOpts extends FilesystemRequestOpts {
+    /** Accepted; Runtime's transfer is already compressed where it helps. */
+    gzip?: boolean;
+    streamIdleTimeoutMs?: number;
+}
+export interface FilesystemWriteOpts extends FilesystemRequestOpts {
+    /** Accepted; Runtime chooses the transfer. */
+    gzip?: boolean;
+    useOctetStream?: boolean;
+    /** Refused: Runtime does not keep metadata on files. */
+    metadata?: Record<string, string>;
+}
+export interface FilesystemListOpts extends FilesystemRequestOpts {
+    depth?: number;
+}
+/** `sandbox.files`: E2B's filesystem module over Runtime's files API. Relative
+ * paths resolve against the home directory, as in E2B (Runtime's is
+ * /workspace). */
+export declare class Filesystem {
+    #private;
+    constructor(ctx: SandboxContext);
+    read(path: string, opts?: FilesystemReadOpts & {
+        format?: "text";
+    }): Promise<string>;
+    read(path: string, opts: FilesystemReadOpts & {
+        format: "bytes";
+    }): Promise<Uint8Array>;
+    read(path: string, opts: FilesystemReadOpts & {
+        format: "blob";
+    }): Promise<Blob>;
+    read(path: string, opts: FilesystemReadOpts & {
+        format: "stream";
+    }): Promise<ReadableStream<Uint8Array>>;
+    /** Writes a file, making its directories, and overwrites one that exists. */
+    write(path: string, data: string | ArrayBuffer | Blob | ReadableStream, opts?: FilesystemWriteOpts): Promise<WriteInfo>;
+    write(files: WriteEntry[], opts?: FilesystemWriteOpts): Promise<WriteInfo[]>;
+    writeFiles(files: WriteEntry[], opts?: FilesystemWriteOpts): Promise<WriteInfo[]>;
+    /** A directory's entries, hidden ones included; `depth` goes deeper. */
+    list(path: string, opts?: FilesystemListOpts): Promise<EntryInfo[]>;
+    /** Makes a directory and its parents. False when it already existed. */
+    makeDir(path: string, opts?: FilesystemRequestOpts): Promise<boolean>;
+    /** Moves a file or directory, replacing a file at the new path, as E2B does. */
+    rename(oldPath: string, newPath: string, opts?: FilesystemRequestOpts): Promise<EntryInfo>;
+    /** Removes a file, or a directory with everything in it. */
+    remove(path: string, opts?: FilesystemRequestOpts): Promise<void>;
+    exists(path: string, opts?: FilesystemRequestOpts): Promise<boolean>;
+    getInfo(path: string, opts?: FilesystemRequestOpts): Promise<EntryInfo>;
+    watchDir(): Promise<never>;
+}