@sandboxrouter/sdk 0.1.0 → 0.3.0

package/dist/providers/boat.js

@@ -0,0 +1,263 @@
+import { BOAT_SIZES } from "../catalog.js";
+import { ProviderError } from "../types.js";
+import { DEFAULT_EXEC_TIMEOUT_S, dirname, killedByTimeout, shq, timeoutError, toBytes, wrapCommand } from "../util.js";
+/**
+ * Boat (boat.dev) over plain REST. One host, one key: Authorization: Bearer boat_... (BOAT_API_KEY).
+ *   POST   /sandboxes                         create (202, state "provisioning"); poll GET until ready
+ *   GET    /sandboxes/{id}                    state: provisioning ... ready | idle | running | archived | error | cancelled
+ *   POST   /sandboxes/{id}/commands           {command, timeoutSeconds<=600, stream}; stream: true answers NDJSON frames
+ *   GET|PUT /sandboxes/{id}/files             JSON {path, content, encoding: base64}; 5 MiB; only under /home/user or /tmp
+ *   POST   /sandboxes/{id}/files/folder       mkdir -p
+ *   POST   /sandboxes/{id}/stop | /resume     stop keeps the disk as a snapshot; resume boots it again
+ *   DELETE /sandboxes/{id}                    permanent; needs X-Ascii-Confirm-Delete: {id}
+ * Docs: https://docs.boat.dev/llms.txt
+ * API reference (OpenAPI 3.1): https://boat.dev/openapi.yaml  (server https://boat.dev/api/v1)
+ * Sizes/pricing: https://docs.boat.dev/machines.md, https://docs.boat.dev/pricing.md
+ * Limits: https://docs.boat.dev/limits.md
+ */
+const ID = "boat";
+export class BoatProvider {
+    apiKey;
+    baseUrl;
+    id = ID;
+    constructor(apiKey = process.env.BOAT_API_KEY, baseUrl = process.env.BOAT_API_URL ?? "https://boat.dev/api/v1") {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    /** @internal */
+    async request(method, path, init = {}) {
+        if (!this.apiKey)
+            throw new ProviderError(this.id, "BOAT_API_KEY is not set");
+        const headers = { Authorization: `Bearer ${this.apiKey}`, ...init.headers };
+        let body;
+        if (init.json !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(init.json);
+        }
+        const res = await fetch(`${this.baseUrl}${path}`, { method, headers, body });
+        if (!res.ok) {
+            const text = await res.text();
+            let detail = text.slice(0, 300);
+            let code;
+            try {
+                // ErrorEnvelope: {ok:false, status, code, message, requestId, error:{code,message,status}}
+                const j = JSON.parse(text);
+                code = j?.code ?? j?.error?.code;
+                const message = j?.message ?? j?.error?.message ?? "";
+                if (code)
+                    detail = `${code}: ${message}`;
+            }
+            catch {
+                /* non-JSON body */
+            }
+            throw new BoatError(`${method} ${path.split("?")[0]} -> ${res.status} ${detail}`, res.status, code);
+        }
+        return res;
+    }
+    /** @internal */
+    async json(method, path, json, headers) {
+        const text = await (await this.request(method, path, { json, headers })).text();
+        return (text ? JSON.parse(text) : {});
+    }
+    /** @internal Poll until the sandbox can take commands. Resumes it first when it is stopped. */
+    async ready(id, timeoutMs = 300_000) {
+        const deadline = Date.now() + timeoutMs;
+        let resumed = false;
+        for (;;) {
+            const { sandbox } = await this.json("GET", `/sandboxes/${encodeURIComponent(id)}`);
+            const state = sandbox.state;
+            if (READY.has(state))
+                return sandbox;
+            if (state === "error" || state === "cancelled") {
+                throw new ProviderError(this.id, `sandbox ${id} is ${state}${sandbox.error ? `: ${sandbox.error}` : ""}`);
+            }
+            if (STOPPED.has(state) && !resumed) {
+                await this.json("POST", `/sandboxes/${encodeURIComponent(id)}/resume`, {});
+                resumed = true;
+            }
+            if (Date.now() > deadline)
+                throw new ProviderError(this.id, `sandbox ${id} not ready after ${timeoutMs / 1000}s (state: ${state})`);
+            await sleep(1000);
+        }
+    }
+    async create(spec) {
+        const body = {
+            type: machineType(spec.vcpu ?? 2, spec.memoryGb ?? 4),
+            // Auto-stop (archive) after the router's hard lifetime. Max 30 days.
+            ttlSeconds: Math.min(2_592_000, Math.max(60, Math.round((spec.timeoutMinutes ?? 30) * 60))),
+        };
+        const from = spec.image?.boat;
+        if (from)
+            body.from = from; // a saved snapshot name or share code
+        if (spec.env)
+            body.env = spec.env;
+        if (spec.metadata)
+            body.labels = spec.metadata;
+        const created = await this.json("POST", "/sandboxes", body);
+        const id = created.sandbox.id;
+        try {
+            await this.ready(id);
+        }
+        catch (err) {
+            await this.request("DELETE", `/sandboxes/${encodeURIComponent(id)}`, { headers: { "X-Ascii-Confirm-Delete": id } }).catch(() => { });
+            throw err;
+        }
+        return new BoatSandbox(this, id);
+    }
+    async connect(nativeId) {
+        await this.ready(nativeId);
+        return new BoatSandbox(this, nativeId);
+    }
+}
+class BoatError extends ProviderError {
+    code;
+    constructor(message, status, code) {
+        super(ID, message, status);
+        this.code = code;
+    }
+}
+const READY = new Set(["ready", "idle", "running"]);
+const STOPPED = new Set(["archived", "stopped"]);
+/** Boat has four fixed sizes (catalog.ts). Pick the smallest that covers the request. */
+function machineType(vcpu, memoryGb) {
+    const fit = BOAT_SIZES.find((s) => s.vcpu >= vcpu && s.memoryGb >= memoryGb);
+    if (!fit)
+        throw new ProviderError(ID, `no Boat size has ${vcpu} vCPU / ${memoryGb} GB (max xlarge: 16 vCPU / 32 GB)`);
+    return fit.type;
+}
+/** The files API only reaches these two trees; anything else goes through a command with sudo. */
+function filesApiPath(path) {
+    if (!path.startsWith("/"))
+        return !path.split("/").includes("..");
+    return /^\/(home\/user|tmp)(\/|$)/.test(path) && !path.split("/").includes("..");
+}
+class BoatSandbox {
+    p;
+    nativeId;
+    base;
+    constructor(p, nativeId) {
+        this.p = p;
+        this.nativeId = nativeId;
+        this.base = `/sandboxes/${encodeURIComponent(nativeId)}`;
+    }
+    /** Data call; when the sandbox is stopped (409 sandbox_not_ready) or still starting, wait/resume once and retry. */
+    async call(method, path, json) {
+        try {
+            return await this.p.request(method, `${this.base}${path}`, { json });
+        }
+        catch (err) {
+            if (!(err instanceof BoatError && err.status === 409 && (err.code === "sandbox_not_ready" || err.code === "boat_starting")))
+                throw err;
+            await this.p.ready(this.nativeId);
+            return this.p.request(method, `${this.base}${path}`, { json });
+        }
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const streaming = !!(opts.onStdout || opts.onStderr);
+        // Boat caps a command at 600 s; it stops the command at the deadline and flags it as timedOut.
+        const seconds = Math.min(600, Math.max(1, Math.round(opts.timeoutSeconds ?? DEFAULT_EXEC_TIMEOUT_S)));
+        const res = await this.call("POST", "/commands", {
+            command: wrapCommand(cmd, { cwd: opts.cwd, env: opts.env }),
+            timeoutSeconds: seconds,
+            stream: streaming,
+        });
+        let result;
+        if (streaming && res.headers.get("content-type")?.includes("ndjson")) {
+            let stdout = "";
+            let stderr = "";
+            let exit;
+            for await (const line of readLines(res)) {
+                const frame = JSON.parse(line);
+                if (frame.type === "stdout") {
+                    stdout += frame.data ?? "";
+                    opts.onStdout?.(frame.data ?? "");
+                }
+                else if (frame.type === "stderr") {
+                    stderr += frame.data ?? "";
+                    opts.onStderr?.(frame.data ?? "");
+                }
+                else if (frame.type === "exit")
+                    exit = frame;
+                else if (frame.type === "error")
+                    throw new ProviderError(ID, `${frame.error ?? "error"}: ${frame.message ?? ""}`);
+            }
+            if (!exit)
+                throw new ProviderError(ID, "output stream closed before the command finished");
+            result = { exitCode: exit.exitCode ?? null, stdout, stderr, timedOut: exit.timedOut };
+        }
+        else {
+            result = (await res.json());
+            if (result.stdout)
+                opts.onStdout?.(result.stdout);
+            if (result.stderr)
+                opts.onStderr?.(result.stderr);
+        }
+        const durationMs = Date.now() - t0;
+        if (result.timedOut || killedByTimeout(result.exitCode ?? -1, durationMs, seconds))
+            throw timeoutError(ID, seconds);
+        return { exitCode: result.exitCode ?? -1, stdout: result.stdout ?? "", stderr: result.stderr ?? "", durationMs };
+    }
+    async writeFile(path, content) {
+        const b64 = Buffer.from(toBytes(content)).toString("base64");
+        if (filesApiPath(path)) {
+            const dir = dirname(path);
+            if (path.includes("/") && !/^\/(home\/user|tmp)$/.test(dir))
+                await this.call("POST", "/files/folder", { path: dir });
+            await this.call("PUT", "/files", { path, content: b64, encoding: "base64" });
+            return;
+        }
+        // Outside /home/user and /tmp: passwordless sudo through a command.
+        const r = await this.exec(`sudo mkdir -p ${shq(dirname(path))} && printf %s ${shq(b64)} | base64 -d | sudo tee ${shq(path)} > /dev/null`);
+        if (r.exitCode !== 0)
+            throw new ProviderError(ID, `writeFile ${path}: ${r.stderr.trim() || `exit ${r.exitCode}`}`);
+    }
+    async readFile(path) {
+        if (filesApiPath(path)) {
+            const res = await this.call("GET", `/files?path=${encodeURIComponent(path)}&encoding=base64`);
+            const j = (await res.json());
+            return j.encoding === "utf8" ? new TextEncoder().encode(j.content) : new Uint8Array(Buffer.from(j.content, "base64"));
+        }
+        const r = await this.exec(`sudo base64 -w0 ${shq(path)}`);
+        if (r.exitCode !== 0)
+            throw new ProviderError(ID, `readFile ${path}: ${r.stderr.trim() || `exit ${r.exitCode}`}`);
+        return new Uint8Array(Buffer.from(r.stdout.trim(), "base64"));
+    }
+    /** Stop: the disk is kept as a snapshot (>= 14 days), running processes end. connect() or the next call resumes it. */
+    async pause() {
+        await this.p.request("POST", `${this.base}/stop`, { json: {} });
+    }
+    async kill() {
+        await this.p.request("DELETE", this.base, { headers: { "X-Ascii-Confirm-Delete": this.nativeId } });
+    }
+}
+/** Newline-delimited JSON reader for a fetch Response. */
+async function* readLines(res) {
+    if (!res.body)
+        return;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });
+        let nl;
+        while ((nl = buffer.indexOf("\n")) !== -1) {
+            const line = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            if (line)
+                yield line;
+        }
+        if (done) {
+            if (buffer.trim())
+                yield buffer.trim();
+            return;
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/providers/cloudflare.d.ts

@@ -0,0 +1,30 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/**
+ * Cloudflare Sandboxes through a bridge Worker you deploy to your own account
+ * (bridges/cloudflare in this repo). Cloudflare sandboxes are Containers started from a
+ * Durable Object, so they can only be driven from inside a Worker; the bridge exposes them over HTTPS.
+ *   POST   /sandboxes                 {env, instance, image?, timeoutMinutes} -> {id}
+ *   GET    /sandboxes/:id             -> {id, running, expiresAt}
+ *   POST   /sandboxes/:id/exec        with Accept: text/event-stream it streams stdout/stderr events
+ *   GET|PUT /sandboxes/:id/files?path= raw bytes
+ *   DELETE /sandboxes/:id
+ * Auth: Authorization: Bearer CLOUDFLARE_SANDBOX_TOKEN (the bridge's BRIDGE_TOKEN secret).
+ * Docs: https://developers.cloudflare.com/sandbox/
+ */
+export declare class CloudflareProvider implements Provider {
+    private baseUrl;
+    private token;
+    readonly id: "cloudflare";
+    constructor(baseUrl?: string | undefined, token?: string | undefined);
+    configured(): boolean;
+    /** @internal */
+    request(method: string, path: string, init?: {
+        json?: unknown;
+        bytes?: Uint8Array;
+        headers?: Record<string, string>;
+    }): Promise<Response>;
+    /** @internal */
+    json<T>(method: string, path: string, json?: unknown): Promise<T>;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/cloudflare.js

@@ -0,0 +1,152 @@
+import { CLOUDFLARE_INSTANCES, DEFAULT_MEMORY_GB, DEFAULT_VCPU, cloudflareInstance } from "../catalog.js";
+import { ProviderError } from "../types.js";
+import { DEFAULT_EXEC_TIMEOUT_S, killedByTimeout, timeoutError, toBytes } from "../util.js";
+import { readSSE } from "../sse.js";
+/**
+ * Cloudflare Sandboxes through a bridge Worker you deploy to your own account
+ * (bridges/cloudflare in this repo). Cloudflare sandboxes are Containers started from a
+ * Durable Object, so they can only be driven from inside a Worker; the bridge exposes them over HTTPS.
+ *   POST   /sandboxes                 {env, instance, image?, timeoutMinutes} -> {id}
+ *   GET    /sandboxes/:id             -> {id, running, expiresAt}
+ *   POST   /sandboxes/:id/exec        with Accept: text/event-stream it streams stdout/stderr events
+ *   GET|PUT /sandboxes/:id/files?path= raw bytes
+ *   DELETE /sandboxes/:id
+ * Auth: Authorization: Bearer CLOUDFLARE_SANDBOX_TOKEN (the bridge's BRIDGE_TOKEN secret).
+ * Docs: https://developers.cloudflare.com/sandbox/
+ */
+export class CloudflareProvider {
+    baseUrl;
+    token;
+    id = "cloudflare";
+    constructor(baseUrl = process.env.CLOUDFLARE_SANDBOX_URL, token = process.env.CLOUDFLARE_SANDBOX_TOKEN) {
+        this.baseUrl = baseUrl;
+        this.token = token;
+    }
+    configured() {
+        return !!(this.baseUrl && this.token);
+    }
+    /** @internal */
+    async request(method, path, init = {}) {
+        if (!this.baseUrl)
+            throw new ProviderError(this.id, "CLOUDFLARE_SANDBOX_URL is not set");
+        if (!this.token)
+            throw new ProviderError(this.id, "CLOUDFLARE_SANDBOX_TOKEN is not set");
+        const headers = { ...init.headers, Authorization: `Bearer ${this.token}` };
+        let body;
+        if (init.json !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(init.json);
+        }
+        else if (init.bytes) {
+            headers["Content-Type"] = "application/octet-stream";
+            body = init.bytes;
+        }
+        const res = await fetch(`${this.baseUrl.replace(/\/+$/, "")}${path}`, { method, headers, body });
+        if (!res.ok) {
+            const text = await res.text();
+            let detail = text.slice(0, 300);
+            try {
+                const j = JSON.parse(text);
+                if (j?.code)
+                    detail = `${j.code}: ${j.message ?? ""}`;
+            }
+            catch {
+                /* non-JSON body */
+            }
+            throw new ProviderError(this.id, `${method} ${path.split("?")[0]} -> ${res.status} ${detail}`, res.status);
+        }
+        return res;
+    }
+    /** @internal */
+    async json(method, path, json) {
+        const text = await (await this.request(method, path, { json })).text();
+        return (text ? JSON.parse(text) : {});
+    }
+    async create(spec) {
+        const body = {
+            instance: instanceFor(spec.vcpu ?? DEFAULT_VCPU, spec.memoryGb ?? DEFAULT_MEMORY_GB),
+            timeoutMinutes: clamp(Math.round(spec.timeoutMinutes ?? 30), 1, 1440),
+        };
+        if (spec.env)
+            body.env = spec.env;
+        // Names an entry under containers[].images in the bridge's wrangler.jsonc (default "sandbox").
+        if (spec.image?.cloudflare)
+            body.image = spec.image.cloudflare;
+        const { id } = await this.json("POST", "/sandboxes", body);
+        return new CloudflareSandbox(this, id);
+    }
+    async connect(nativeId) {
+        const sbx = await this.json("GET", `/sandboxes/${encodeURIComponent(nativeId)}`);
+        return new CloudflareSandbox(this, sbx.id);
+    }
+}
+/**
+ * Smallest predefined instance type that covers the request, else the largest.
+ * https://developers.cloudflare.com/containers/platform/limits/#instance-types
+ */
+void CLOUDFLARE_INSTANCES; // instance types live in the catalog so pricing and sizing agree
+function instanceFor(vcpu, memoryGb) {
+    return cloudflareInstance(vcpu, memoryGb).name;
+}
+class CloudflareSandbox {
+    p;
+    nativeId;
+    base;
+    constructor(p, nativeId) {
+        this.p = p;
+        this.nativeId = nativeId;
+        this.base = `/sandboxes/${encodeURIComponent(nativeId)}`;
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const seconds = opts.timeoutSeconds ?? DEFAULT_EXEC_TIMEOUT_S;
+        const body = { cmd, cwd: opts.cwd, env: opts.env, timeoutSeconds: seconds };
+        const streaming = !!(opts.onStdout || opts.onStderr);
+        const res = await this.p.request("POST", `${this.base}/exec`, {
+            json: body,
+            headers: streaming ? { Accept: "text/event-stream" } : {},
+        });
+        let result;
+        if (streaming && res.headers.get("content-type")?.includes("text/event-stream")) {
+            for await (const ev of readSSE(res)) {
+                const payload = JSON.parse(ev.data);
+                if (ev.event === "stdout")
+                    opts.onStdout?.(payload);
+                else if (ev.event === "stderr")
+                    opts.onStderr?.(payload);
+                else if (ev.event === "result")
+                    result = payload;
+                else if (ev.event === "error")
+                    throw new ProviderError("cloudflare", `${payload?.code ?? "error"}: ${payload?.message ?? ev.data}`);
+            }
+            if (!result)
+                throw new ProviderError("cloudflare", "output stream closed before the command finished");
+        }
+        else {
+            result = JSON.parse(await res.text());
+            // Bridge answered without streaming: deliver the output in one chunk.
+            if (result.stdout)
+                opts.onStdout?.(result.stdout);
+            if (result.stderr)
+                opts.onStderr?.(result.stderr);
+        }
+        const durationMs = Date.now() - t0;
+        // The bridge runs the command under coreutils `timeout`: a kill at the deadline is exit 124 (137 after SIGKILL).
+        if (killedByTimeout(result.exitCode ?? -1, durationMs, seconds))
+            throw timeoutError("cloudflare", seconds);
+        return { exitCode: result.exitCode ?? -1, stdout: result.stdout ?? "", stderr: result.stderr ?? "", durationMs };
+    }
+    async writeFile(path, content) {
+        await this.p.request("PUT", `${this.base}/files?path=${encodeURIComponent(path)}`, { bytes: toBytes(content) });
+    }
+    async readFile(path) {
+        const res = await this.p.request("GET", `${this.base}/files?path=${encodeURIComponent(path)}`);
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    async kill() {
+        await this.p.request("DELETE", this.base);
+    }
+}
+function clamp(n, lo, hi) {
+    return Math.min(hi, Math.max(lo, n));
+}

package/dist/providers/codesandbox.d.ts

@@ -0,0 +1,59 @@
+import { CODESANDBOX_TIERS, codesandboxTier } from "../catalog.js";
+export { CODESANDBOX_TIERS, codesandboxTier };
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+interface CsbCommand {
+    waitUntilComplete(): Promise<string>;
+    kill(): Promise<void>;
+}
+interface CsbClient {
+    commands: {
+        runBackground(command: string, opts?: Record<string, unknown>): Promise<CsbCommand>;
+    };
+    fs: {
+        writeFile(path: string, content: Uint8Array, opts?: {
+            create?: boolean;
+            overwrite?: boolean;
+        }): Promise<void>;
+        readFile(path: string): Promise<Uint8Array>;
+        mkdir(path: string, recursive?: boolean): Promise<void>;
+        remove(path: string, recursive?: boolean): Promise<void>;
+    };
+    disconnect(): Promise<void>;
+}
+interface CsbSandbox {
+    id: string;
+    connect(): Promise<CsbClient>;
+}
+interface CsbSdk {
+    sandboxes: {
+        create(opts: Record<string, unknown>): Promise<CsbSandbox>;
+        resume(id: string): Promise<CsbSandbox>;
+        hibernate(id: string): Promise<void>;
+        shutdown(id: string): Promise<void>;
+        delete(id: string): Promise<void>;
+    };
+}
+/** The slice of `@codesandbox/sdk` this adapter uses. */
+interface CsbModule {
+    CodeSandbox: new (apiToken?: string, opts?: {
+        baseUrl?: string;
+    }) => CsbSdk;
+    VMTier: {
+        fromName(name: string): unknown;
+    };
+}
+export declare class CodeSandboxProvider implements Provider {
+    private apiKey;
+    private baseUrl;
+    readonly id: "codesandbox";
+    private sdk?;
+    constructor(apiKey?: string | undefined, baseUrl?: string | undefined);
+    configured(): boolean;
+    /** @internal */
+    module(): Promise<CsbModule>;
+    /** @internal */
+    client(): Promise<CsbSdk>;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    /** Reattach by id; a hibernated sandbox is resumed (shut-down ones boot clean). */
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}