@vercel/sandbox 0.0.1

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @vercel/sandbox@0.0.1 build /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
+> tsc
+

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @vercel/sandbox
+
+## 0.0.1
+
+### Patch Changes
+
+- Initial release ([#11](https://github.com/vercel/sandbox-sdk/pull/11))

package/README.md

@@ -0,0 +1,79 @@
+Vercel Sandbox allows you to run arbitrary code in isolated, ephemeral Linux
+VMs. This product is in private beta.
+
+## What is a sandbox?
+
+A sandbox is an isolated Linux system for your experimentation and use.
+Internally, it is a Firecracker MicroVM that is powered by [the same
+infrastructure][hive] that powers 1M+ builds a day at Vercel.
+
+## Getting started
+
+Vercel Sandbox is in private beta. These examples will not work unless these
+APIs are enabled for your team.
+
+ - Go to your team settings, and copy the team ID.
+ - Go to your Vercel account settings and [create a token][create-token]. Make
+   sure it is scoped to the team ID from the previous step.
+ - Create a new project:
+
+```
+$ mkdir sandbox-test
+$ pnpm init
+$ pnpm add @vercel/sandbox
+$ pnpm add --save-dev tsx
+```
+
+Now create `whoami.ts`:
+
+{@includeCode ../cli/src/example-whoami.ts}
+
+Run it like this:
+
+```
+$ VERCEL_TEAM_ID=<team_id> VERCEL_TOKEN=<token> pnpm tsx ./whoami.ts
+Running as: vercel-sandbox
+Working dir: /vercel/sandbox
+```
+
+Now have a look at the sidebar for which classes exist.
+
+## Limitations
+
+- Sandbox only supports cloning public repositories at the moment.
+- `sudo` is not available. User code is executed as the `vercel-sandbox` user.
+- Max resources: 2 cores, 4096 MiB of memory.
+- All APIs of the SDK are subject to change. **We make no stability promises.**
+
+## System
+
+The base system is an Amazon Linux 2023 system with the following additional
+packages installed.
+
+```
+bind-utils
+bzip2
+findutils
+git
+gzip
+iputils
+libicu
+libjpeg
+libpng
+ncurses-libs
+openssl
+openssl-libs
+procps
+tar
+unzip
+which
+whois
+zstd
+```
+
+- The `node22` system ships a Node 22 runtime under `/vercel/runtimes/node22`.
+- User code is executed as the `vercel-sandbox` user.
+- `/vercel/sandbox` is writable.
+
+[create-token]: https://vercel.com/account/settings/tokens
+[hive]: https://vercel.com/blog/a-deep-dive-into-hive-vercels-builds-infrastructure

package/dist/client/api-error.d.ts

@@ -0,0 +1,14 @@
+import type { Response } from "node-fetch";
+interface Options<ErrorData> {
+    message?: string;
+    json?: ErrorData;
+    text?: string;
+}
+export declare class APIError<ErrorData> extends Error {
+    response: Response;
+    message: string;
+    json?: ErrorData;
+    text?: string;
+    constructor(response: Response, options?: Options<ErrorData>);
+}
+export {};

package/dist/client/api-error.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APIError = void 0;
+class APIError extends Error {
+    constructor(response, options) {
+        super(response.statusText);
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, APIError);
+        }
+        this.response = response;
+        this.message = options?.message ?? "";
+        this.json = options?.json;
+        this.text = options?.text;
+    }
+}
+exports.APIError = APIError;

package/dist/client/base-client.d.ts

@@ -0,0 +1,43 @@
+import type { Options as RetryOptions } from "async-retry";
+import { APIError } from "./api-error";
+import { ZodType } from "zod";
+import { type RequestOptions } from "./with-retry";
+import nodeFetch, { type Response, type RequestInit } from "node-fetch";
+export interface RequestParams extends RequestInit {
+    headers?: Record<string, string>;
+    method?: string;
+    onRetry?(error: any, options: RequestOptions): void;
+    query?: Record<string, number | string | null | undefined | string[]>;
+    retry?: Partial<RetryOptions>;
+}
+/**
+ * A base API client that provides a convenience wrapper for fetching where
+ * we can pass query parameters as an object, support retries, debugging
+ * and automatic authorization.
+ */
+export declare class APIClient {
+    protected token?: string;
+    private fetch;
+    private debug;
+    private host;
+    constructor(params: {
+        debug?: boolean;
+        host: string;
+        token?: string;
+    });
+    protected request(path: string, opts?: RequestParams): Promise<nodeFetch.Response>;
+}
+export interface Parsed<Data> {
+    response: Response;
+    text: string;
+    json: Data;
+}
+/**
+ * Allows to read the response text and parse it as JSON casting to the given
+ * type. If the response is not ok or cannot be parsed it will return error.
+ *
+ * @param response Response to parse.
+ * @returns Parsed response or error.
+ */
+export declare function parse<Data, ErrorData>(validator: ZodType<Data>, response: Response): Promise<Parsed<Data> | APIError<ErrorData>>;
+export declare function parseOrThrow<Data, ErrorData>(validator: ZodType<Data>, response: Response): Promise<Parsed<Data>>;

package/dist/client/base-client.js

@@ -0,0 +1,111 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APIClient = void 0;
+exports.parse = parse;
+exports.parseOrThrow = parseOrThrow;
+const api_error_1 = require("./api-error");
+const array_1 = require("../utils/array");
+const with_retry_1 = require("./with-retry");
+const node_fetch_1 = __importDefault(require("node-fetch"));
+/**
+ * A base API client that provides a convenience wrapper for fetching where
+ * we can pass query parameters as an object, support retries, debugging
+ * and automatic authorization.
+ */
+class APIClient {
+    constructor(params) {
+        this.fetch = (0, with_retry_1.withRetry)(node_fetch_1.default);
+        this.host = params.host;
+        this.debug = params.debug ?? process.env.DEBUG_FETCH === "true";
+        this.token = params.token;
+    }
+    async request(path, opts) {
+        const url = new URL(path, this.host);
+        if (opts?.query) {
+            for (const [key, value] of Object.entries(opts.query)) {
+                (0, array_1.array)(value).forEach((value) => {
+                    url.searchParams.append(key, value.toString());
+                });
+            }
+        }
+        const start = Date.now();
+        const response = await this.fetch(url.toString(), {
+            ...opts,
+            body: opts?.body,
+            method: opts?.method || "GET",
+            headers: this.token
+                ? { Authorization: `Bearer ${this.token}`, ...opts?.headers }
+                : opts?.headers,
+        });
+        if (this.debug) {
+            const duration = Date.now() - start;
+            console.log(`[API] ${url} (${response.status}) ${duration}ms`);
+            if (response.status === 429) {
+                const retry = parseInt(response.headers.get("Retry-After") ?? "", 10);
+                const hours = Math.floor(retry / 60 / 60);
+                const minutes = Math.floor(retry / 60) % 60;
+                const seconds = retry % 60;
+                console.warn(`[API] ${url} Rate Limited, Retry After ${hours}h ${minutes}m ${seconds}s`);
+            }
+        }
+        return response;
+    }
+}
+exports.APIClient = APIClient;
+/**
+ * Allows to read the response text and parse it as JSON casting to the given
+ * type. If the response is not ok or cannot be parsed it will return error.
+ *
+ * @param response Response to parse.
+ * @returns Parsed response or error.
+ */
+async function parse(validator, response) {
+    const text = await response.text().catch((err) => {
+        return new api_error_1.APIError(response, {
+            message: `Can't read response text: ${String(err)}`,
+        });
+    });
+    if (typeof text !== "string") {
+        return text;
+    }
+    let json;
+    try {
+        json = JSON.parse(text || "{}");
+    }
+    catch (error) {
+        return new api_error_1.APIError(response, {
+            message: `Can't parse JSON: ${String(error)}`,
+            text,
+        });
+    }
+    if (!response.ok) {
+        return new api_error_1.APIError(response, {
+            message: `Status code ${response.status} is not ok`,
+            json: json,
+            text,
+        });
+    }
+    const validated = validator.safeParse(json);
+    if (!validated.success) {
+        return new api_error_1.APIError(response, {
+            message: `Response JSON is not valid: ${validated.error}`,
+            json: json,
+            text,
+        });
+    }
+    return {
+        json: validated.data,
+        response,
+        text,
+    };
+}
+async function parseOrThrow(validator, response) {
+    const result = await parse(validator, response);
+    if (result instanceof api_error_1.APIError) {
+        throw result;
+    }
+    return result;
+}

package/dist/client/client.d.ts

@@ -0,0 +1,63 @@
+import { APIClient, type RequestParams } from "./base-client";
+import { Readable } from "stream";
+export declare class SandboxClient extends APIClient {
+    private teamId;
+    constructor(params: {
+        host?: string;
+        teamId: string;
+        token: string;
+    });
+    protected request(path: string, params?: RequestParams): Promise<import("node-fetch").Response>;
+    createSandbox(params: {
+        source: {
+            type: "git";
+            url: string;
+        };
+        ports: number[];
+        timeout?: number;
+    }): Promise<import("./base-client").Parsed<{
+        sandboxId: string;
+        routes: {
+            port: number;
+            subdomain: string;
+        }[];
+    }>>;
+    runCommand(params: {
+        sandboxId: string;
+        cwd?: string;
+        command: string;
+        args: string[];
+    }): Promise<import("./base-client").Parsed<{
+        cmdId: string;
+    }>>;
+    getCommand(params: {
+        sandboxId: string;
+        cmdId: string;
+        wait?: boolean;
+    }): Promise<import("./base-client").Parsed<{
+        name: string;
+        cwd: string;
+        args: string[];
+        cmdId: string;
+        exitCode: number | null;
+    }>>;
+    writeFiles(params: {
+        sandboxId: string;
+        files: {
+            path: string;
+            stream: Readable | Buffer;
+        }[];
+    }): Promise<void>;
+    readFile(params: {
+        sandboxId: string;
+        path: string;
+        cwd?: string;
+    }): Promise<NodeJS.ReadableStream | null>;
+    getLogs(params: {
+        sandboxId: string;
+        cmdId: string;
+    }): AsyncGenerator<{
+        data: string;
+        stream: "stdout" | "stderr";
+    }, void, void>;
+}

package/dist/client/client.js

@@ -0,0 +1,118 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SandboxClient = void 0;
+const form_data_1 = __importDefault(require("form-data"));
+const base_client_1 = require("./base-client");
+const validators_1 = require("./validators");
+const api_error_1 = require("./api-error");
+const deferred_generator_1 = require("../utils/deferred-generator");
+const jsonlines_1 = __importDefault(require("jsonlines"));
+class SandboxClient extends base_client_1.APIClient {
+    constructor(params) {
+        super({
+            host: params.host ?? "https://api.vercel.com",
+            token: params.token,
+            debug: false,
+        });
+        this.teamId = params.teamId;
+    }
+    async request(path, params) {
+        return super.request(path, {
+            ...params,
+            query: { teamId: this.teamId, ...params?.query },
+            headers: {
+                "content-type": "application/json",
+                ...params?.headers,
+            },
+        });
+    }
+    async createSandbox(params) {
+        return (0, base_client_1.parseOrThrow)(validators_1.CreatedSandbox, await this.request("/v1/sandboxes", {
+            method: "POST",
+            body: JSON.stringify({
+                ports: params.ports,
+                source: params.source,
+                timeout: params.timeout,
+            }),
+        }));
+    }
+    async runCommand(params) {
+        return (0, base_client_1.parseOrThrow)(validators_1.CreatedCommand, await this.request(`/v1/sandboxes/${params.sandboxId}/cmd`, {
+            method: "POST",
+            body: JSON.stringify({
+                command: params.command,
+                args: params.args,
+                cwd: params.cwd,
+            }),
+        }));
+    }
+    async getCommand(params) {
+        return (0, base_client_1.parseOrThrow)(validators_1.Command, await this.request(`/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`, { query: { wait: params.wait ? "true" : undefined } }));
+    }
+    async writeFiles(params) {
+        const formData = new form_data_1.default();
+        for (const file of params.files) {
+            formData.append(file.path, file.stream, file.path);
+        }
+        await (0, base_client_1.parseOrThrow)(validators_1.WrittenFile, await this.request(`/v1/sandboxes/${params.sandboxId}/fs/write`, {
+            method: "POST",
+            headers: { ...formData.getHeaders() },
+            body: formData,
+        }));
+    }
+    async readFile(params) {
+        const response = await this.request(`/v1/sandboxes/${params.sandboxId}/fs/read`, {
+            method: "POST",
+            body: JSON.stringify({ path: params.path, cwd: params.cwd }),
+        });
+        if (response.status === 404) {
+            return null;
+        }
+        return response.body;
+    }
+    getLogs(params) {
+        const deferred = (0, deferred_generator_1.createDeferredGenerator)();
+        (async () => {
+            const response = await this.request(`/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}/logs`, { method: "GET" });
+            if (response.headers.get("content-type") !== "application/x-ndjson") {
+                throw new api_error_1.APIError(response, {
+                    message: "Expected a stream of logs",
+                });
+            }
+            const parser = jsonlines_1.default.parse();
+            response.body.pipe(parser);
+            parser.on("data", (data) => {
+                const parsed = validators_1.LogLine.safeParse(data);
+                if (parsed.success) {
+                    deferred.next({
+                        value: parsed.data,
+                        done: false,
+                    });
+                }
+                else {
+                    deferred.next({
+                        value: Promise.reject(parsed.error),
+                        done: false,
+                    });
+                }
+            });
+            parser.on("error", (err) => {
+                deferred.next({
+                    value: Promise.reject(err),
+                    done: false,
+                });
+            });
+            parser.on("end", () => {
+                deferred.next({
+                    value: undefined,
+                    done: true,
+                });
+            });
+        })();
+        return deferred.generator();
+    }
+}
+exports.SandboxClient = SandboxClient;

package/dist/client/validators.d.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+export declare const CreatedSandbox: z.ZodObject<{
+    sandboxId: z.ZodString;
+    routes: z.ZodArray<z.ZodObject<{
+        subdomain: z.ZodString;
+        port: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        port: number;
+        subdomain: string;
+    }, {
+        port: number;
+        subdomain: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    sandboxId: string;
+    routes: {
+        port: number;
+        subdomain: string;
+    }[];
+}, {
+    sandboxId: string;
+    routes: {
+        port: number;
+        subdomain: string;
+    }[];
+}>;
+export declare const CreatedCommand: z.ZodObject<{
+    cmdId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    cmdId: string;
+}, {
+    cmdId: string;
+}>;
+export declare const Command: z.ZodObject<{
+    args: z.ZodArray<z.ZodString, "many">;
+    cmdId: z.ZodString;
+    cwd: z.ZodString;
+    exitCode: z.ZodNullable<z.ZodNumber>;
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    cwd: string;
+    args: string[];
+    cmdId: string;
+    exitCode: number | null;
+}, {
+    name: string;
+    cwd: string;
+    args: string[];
+    cmdId: string;
+    exitCode: number | null;
+}>;
+export declare const FinishedCommand: z.ZodObject<{
+    cmdId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    cmdId: string;
+}, {
+    cmdId: string;
+}>;
+export declare const WrittenFile: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const LogLine: z.ZodObject<{
+    stream: z.ZodEnum<["stdout", "stderr"]>;
+    data: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    data: string;
+    stream: "stdout" | "stderr";
+}, {
+    data: string;
+    stream: "stdout" | "stderr";
+}>;

package/dist/client/validators.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogLine = exports.WrittenFile = exports.FinishedCommand = exports.Command = exports.CreatedCommand = exports.CreatedSandbox = void 0;
+const zod_1 = require("zod");
+exports.CreatedSandbox = zod_1.z.object({
+    sandboxId: zod_1.z.string(),
+    routes: zod_1.z.array(zod_1.z.object({ subdomain: zod_1.z.string(), port: zod_1.z.number() })),
+});
+exports.CreatedCommand = zod_1.z.object({
+    cmdId: zod_1.z.string(),
+});
+exports.Command = zod_1.z.object({
+    args: zod_1.z.array(zod_1.z.string()),
+    cmdId: zod_1.z.string(),
+    cwd: zod_1.z.string(),
+    exitCode: zod_1.z.number().nullable(),
+    name: zod_1.z.string(),
+});
+exports.FinishedCommand = zod_1.z.object({
+    cmdId: zod_1.z.string(),
+});
+exports.WrittenFile = zod_1.z.object({});
+exports.LogLine = zod_1.z.object({
+    stream: zod_1.z.enum(["stdout", "stderr"]),
+    data: zod_1.z.string(),
+});

package/dist/client/with-retry.d.ts

@@ -0,0 +1,15 @@
+import type { RequestInit, Response } from "node-fetch";
+import type { Options as RetryOptions } from "async-retry";
+export interface RequestOptions {
+    onRetry?(error: any, options: RequestOptions): void;
+    retry?: Partial<RetryOptions>;
+}
+/**
+ * Wraps a fetch function with retry logic. The retry logic will retry
+ * on network errors, 429 responses and 5xx responses. The retry logic
+ * will not retry on 4xx responses.
+ *
+ * @param rawFetch The fetch function to wrap.
+ * @returns The wrapped fetch function.
+ */
+export declare function withRetry<T extends RequestInit>(rawFetch: (url: URL | string, init?: T) => Promise<Response>): (url: URL | string, opts?: T & RequestOptions) => Promise<Response>;

package/dist/client/with-retry.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = withRetry;
+const api_error_1 = require("./api-error");
+const promises_1 = require("timers/promises");
+const async_retry_1 = __importDefault(require("async-retry"));
+/**
+ * Wraps a fetch function with retry logic. The retry logic will retry
+ * on network errors, 429 responses and 5xx responses. The retry logic
+ * will not retry on 4xx responses.
+ *
+ * @param rawFetch The fetch function to wrap.
+ * @returns The wrapped fetch function.
+ */
+function withRetry(rawFetch) {
+    return async (url, opts = {}) => {
+        /**
+         * Timeouts by default will be [10, 60, 360, 2160, 12960]
+         * before randomization is added.
+         */
+        const retryOpts = Object.assign({
+            minTimeout: 10,
+            retries: 5,
+            factor: 6,
+            maxRetryAfter: 20,
+        }, opts.retry);
+        if (opts.onRetry) {
+            retryOpts.onRetry = (error, attempts) => {
+                opts.onRetry(error, opts);
+                if (opts.retry && opts.retry.onRetry) {
+                    opts.retry.onRetry(error, attempts);
+                }
+            };
+        }
+        try {
+            return (await (0, async_retry_1.default)(async (bail) => {
+                try {
+                    const response = await rawFetch(url, opts);
+                    /**
+                     * When the response is 429 we will try to parse the Retry-After
+                     * header. If the header exists we will try to parse it and, if
+                     * the wait time is higher than the maximum defined, we respond.
+                     * Otherwise we wait for the time given in the header and throw
+                     * to retry.
+                     */
+                    if (response.status === 429) {
+                        const retryAfter = parseInt(response.headers.get("retry-after") || "", 10);
+                        if (retryAfter && !isNaN(retryAfter)) {
+                            if (retryAfter > retryOpts.maxRetryAfter) {
+                                return response;
+                            }
+                            await (0, promises_1.setTimeout)(retryAfter * 1e3);
+                        }
+                        throw new api_error_1.APIError(response);
+                    }
+                    /**
+                     * If the response is a a retryable error, we throw in
+                     * order to retry.
+                     */
+                    if (response.status >= 500 && response.status < 600) {
+                        throw new api_error_1.APIError(response);
+                    }
+                    return response;
+                }
+                catch (error) {
+                    /**
+                     * If the request was aborted using the AbortController
+                     * we bail from retrying throwing the original error.
+                     */
+                    if (isAbortError(error)) {
+                        return bail(error);
+                    }
+                    throw error;
+                }
+            }, retryOpts));
+        }
+        catch (error) {
+            /**
+             * The ResponseError is only intended for retries so in case we
+             * ran out of attempts we will respond with the last response
+             * we obtained.
+             */
+            if (error instanceof api_error_1.APIError) {
+                return error.response;
+            }
+            throw error;
+        }
+    };
+}
+function isAbortError(error) {
+    return (error !== undefined &&
+        error !== null &&
+        error.name === "AbortError");
+}