@vercel/sandbox 0.0.1

package/src/client/client.ts

@@ -0,0 +1,181 @@
+import FormData from "form-data";
+import { APIClient, parseOrThrow, type RequestParams } from "./base-client";
+import {
+  Command,
+  CreatedCommand,
+  CreatedSandbox,
+  LogLine,
+  WrittenFile,
+} from "./validators";
+import { Readable } from "stream";
+import { APIError } from "./api-error";
+import { createDeferredGenerator } from "../utils/deferred-generator";
+import { z } from "zod";
+import jsonlines from "jsonlines";
+
+export class SandboxClient extends APIClient {
+  private teamId: string;
+
+  constructor(params: { host?: string; teamId: string; token: string }) {
+    super({
+      host: params.host ?? "https://api.vercel.com",
+      token: params.token,
+      debug: false,
+    });
+
+    this.teamId = params.teamId;
+  }
+
+  protected async request(path: string, params?: RequestParams) {
+    return super.request(path, {
+      ...params,
+      query: { teamId: this.teamId, ...params?.query },
+      headers: {
+        "content-type": "application/json",
+        ...params?.headers,
+      },
+    });
+  }
+
+  async createSandbox(params: {
+    source: { type: "git"; url: string };
+    ports: number[];
+    timeout?: number;
+  }) {
+    return parseOrThrow(
+      CreatedSandbox,
+      await this.request("/v1/sandboxes", {
+        method: "POST",
+        body: JSON.stringify({
+          ports: params.ports,
+          source: params.source,
+          timeout: params.timeout,
+        }),
+      }),
+    );
+  }
+
+  async runCommand(params: {
+    sandboxId: string;
+    cwd?: string;
+    command: string;
+    args: string[];
+  }) {
+    return parseOrThrow(
+      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: {
+    sandboxId: string;
+    cmdId: string;
+    wait?: boolean;
+  }) {
+    return parseOrThrow(
+      Command,
+      await this.request(
+        `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`,
+        { query: { wait: params.wait ? "true" : undefined } },
+      ),
+    );
+  }
+
+  async writeFiles(params: {
+    sandboxId: string;
+    files: { path: string; stream: Readable | Buffer }[];
+  }) {
+    const formData = new FormData();
+
+    for (const file of params.files) {
+      formData.append(file.path, file.stream, file.path);
+    }
+
+    await parseOrThrow(
+      WrittenFile,
+      await this.request(`/v1/sandboxes/${params.sandboxId}/fs/write`, {
+        method: "POST",
+        headers: { ...formData.getHeaders() },
+        body: formData,
+      }),
+    );
+  }
+
+  async readFile(params: {
+    sandboxId: string;
+    path: string;
+    cwd?: string;
+  }): Promise<NodeJS.ReadableStream | null> {
+    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: { sandboxId: string; cmdId: string }) {
+    const deferred = createDeferredGenerator<z.infer<typeof LogLine>, void>();
+
+    (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 APIError(response, {
+          message: "Expected a stream of logs",
+        });
+      }
+
+      const parser = jsonlines.parse();
+      response.body.pipe(parser);
+
+      parser.on("data", (data) => {
+        const parsed = 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();
+  }
+}

package/src/client/validators.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+
+export const CreatedSandbox = z.object({
+  sandboxId: z.string(),
+  routes: z.array(z.object({ subdomain: z.string(), port: z.number() })),
+});
+
+export const CreatedCommand = z.object({
+  cmdId: z.string(),
+});
+
+export const Command = z.object({
+  args: z.array(z.string()),
+  cmdId: z.string(),
+  cwd: z.string(),
+  exitCode: z.number().nullable(),
+  name: z.string(),
+});
+
+export const FinishedCommand = z.object({
+  cmdId: z.string(),
+});
+
+export const WrittenFile = z.object({});
+
+export const LogLine = z.object({
+  stream: z.enum(["stdout", "stderr"]),
+  data: z.string(),
+});

package/src/client/with-retry.ts

@@ -0,0 +1,121 @@
+import type { RequestInit, Response } from "node-fetch";
+import type { Options as RetryOptions } from "async-retry";
+import { APIError } from "./api-error";
+import { setTimeout } from "timers/promises";
+import retry 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 function withRetry<T extends RequestInit>(
+  rawFetch: (url: URL | string, init?: T) => Promise<Response>,
+) {
+  return async (
+    url: URL | string,
+    opts: T & RequestOptions = <T & RequestOptions>{},
+  ) => {
+    /**
+     * 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 retry(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 setTimeout(retryAfter * 1e3);
+            }
+
+            throw new 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 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)) as Response;
+    } 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 APIError) {
+        return error.response;
+      }
+
+      throw error;
+    }
+  };
+}
+
+function isAbortError(error: unknown): error is Error {
+  return (
+    error !== undefined &&
+    error !== null &&
+    (error as Error).name === "AbortError"
+  );
+}

package/src/create-sandbox.ts

@@ -0,0 +1,272 @@
+import { SandboxClient } from "./client/client";
+import { Readable } from "stream";
+
+/**
+ * Create a new instance of the SandboxSDK.
+ *
+ * ````
+ * const teamId = process.env.VERCEL_TEAM_ID
+ * const token = process.env.VERCEL_TOKEN
+ * const sdk = new SandboxSDK({ teamId: teamId!, token: token! });
+ * ````
+ *
+ * @see {@link createSandbox} to start a sandbox.
+ */
+export class SandboxSDK {
+  public client: SandboxClient;
+
+  constructor({ teamId, token }: { teamId: string; token: string }) {
+    this.client = new SandboxClient({ teamId, token });
+  }
+
+  /**
+   * Create a new Sandbox with the given resources, source code, and ports.
+   *
+   * Upon start, the sandbox will perform a `git clone` of the repository given.
+   * This repo needs to be public.
+   *
+   * @param params
+   * @returns a
+   */
+  async createSandbox(params: {
+    source: { type: "git"; url: string };
+    ports: number[];
+    timeout?: number;
+  }) {
+    const { client } = this;
+    const sandbox = await client.createSandbox({
+      source: params.source,
+      ports: params.ports,
+      timeout: params.timeout,
+    });
+
+    return new Sandbox({
+      client,
+      sandboxId: sandbox.json.sandboxId,
+      routes: sandbox.json.routes,
+    });
+  }
+
+  /** @hidden */
+  async getSandbox({
+    routes,
+    sandboxId,
+  }: {
+    routes: { subdomain: string; port: number }[];
+    sandboxId: string;
+  }) {
+    return new Sandbox({
+      client: this.client,
+      sandboxId: sandboxId,
+      routes: routes,
+    });
+  }
+}
+
+/**
+ * A Sandbox is an isolated Linux MicroVM that you can your experiments on.
+ *
+ * @see {@link SandboxSDK.createSandbox} to construct a Sandbox.
+ * @hideconstructor
+ */
+export class Sandbox {
+  private client: SandboxClient;
+
+  /** @hidden */
+  public routes: { subdomain: string; port: number }[];
+
+  /**
+   * The ID of this sandbox.
+   */
+  public sandboxId: string;
+
+  constructor({
+    client,
+    routes,
+    sandboxId,
+  }: {
+    client: SandboxClient;
+    routes: { subdomain: string; port: number }[];
+    sandboxId: string;
+  }) {
+    this.client = client;
+    this.routes = routes;
+    this.sandboxId = sandboxId;
+  }
+
+  /**
+   * Start executing a command in this sandbox.
+   * @param command
+   * @param args
+   * @returns
+   */
+  async runCommand(command: string, args: string[] = []) {
+    const commandResponse = await this.client.runCommand({
+      sandboxId: this.sandboxId,
+      command,
+      args,
+    });
+
+    return new Command({
+      client: this.client,
+      sandboxId: this.sandboxId,
+      cmdId: commandResponse.json.cmdId,
+    });
+  }
+
+  /**
+   * Write files to the filesystem of this sandbox.
+   */
+  async writeFiles(files: { path: string; stream: Readable | Buffer }[]) {
+    return this.client.writeFiles({
+      sandboxId: this.sandboxId,
+      files: files,
+    });
+  }
+
+  /**
+   * Get the public domain of a port of this sandbox.
+   *
+   * E.g. `2grza2l7imxe.vercel.run`
+   */
+  domain(p: number): string {
+    const route = this.routes.find(({ port }) => port == p);
+    if (route) {
+      return `https://${route.subdomain}.vercel.run`;
+    } else {
+      throw new Error(`No route for port ${p}`);
+    }
+  }
+}
+
+/**
+ * A command executed in a Sandbox.
+ *
+ * You can {@link wait} on commands to access their {@link exitCode}, and
+ * iterate over their output with {@link logs}.
+ *
+ * @see {@link Sandbox.runCommand} to start a command.
+ *
+ * @hideconstructor
+ */
+export class Command {
+  private client: SandboxClient;
+  private sandboxId: string;
+  /**
+   * ID of the command execution.
+   */
+  public cmdId: string;
+  /**
+   * The exit code of the command, if available. This is set after
+   * {@link wait} has returned.
+   */
+  public exitCode: number | null;
+
+  constructor({
+    client,
+    sandboxId,
+    cmdId,
+  }: {
+    client: SandboxClient;
+    sandboxId: string;
+    cmdId: string;
+  }) {
+    this.client = client;
+    this.sandboxId = sandboxId;
+    this.cmdId = cmdId;
+    this.exitCode = null;
+  }
+
+  /**
+   * Iterate over the output of this command.
+   *
+   * ```
+   * for await (const log of cmd.logs()) {
+   *   if (log.stream === "stdout") {
+   *     process.stdout.write(log.data);
+   *   } else {
+   *     process.stderr.write(log.data);
+   *   }
+   * }
+   * ```
+   *
+   * @see {@link Command.stdout}, {@link Command.stderr}, and {@link Command.output}
+   * to access output as a string.
+   */
+  logs() {
+    return this.client.getLogs({
+      sandboxId: this.sandboxId,
+      cmdId: this.cmdId,
+    });
+  }
+
+  /**
+   * Wait for a command to exit and populate it's exit code.
+   *
+   * ```
+   * await cmd.wait()
+   * if (cmd.exitCode != 0) {
+   *   console.error("Something went wrong...")
+   * }
+   * ````
+   */
+  async wait() {
+    const command = await this.client.getCommand({
+      sandboxId: this.sandboxId,
+      cmdId: this.cmdId,
+      wait: true,
+    });
+
+    this.exitCode = command.json.exitCode;
+    return this;
+  }
+
+  /**
+   * Print command logs to stdout/stderr
+   */
+  async printLogs() {
+    for await (const log of this.logs()) {
+      if (log.stream === "stdout") {
+        process.stdout.write(log.data);
+      } else {
+        process.stderr.write(log.data);
+      }
+    }
+  }
+
+  /**
+   * Get the output of `stdout` or `stderr` as a string.
+   *
+   * NOTE: This may error with string conversion errors if the command does
+   * not ouptut valid unicode.
+   */
+  async output(stream: "stdout" | "stderr" | "both" = "both") {
+    let data = "";
+    for await (const log of this.logs()) {
+      if (log.stream === stream) {
+        data += log.data;
+      }
+    }
+    return data;
+  }
+
+  /**
+   * Get the output of `stdout` as a string.
+   *
+   * NOTE: This may error with string conversion errors if the command does
+   * not ouptut valid unicode.
+   */
+  async stdout() {
+    return this.output("stdout");
+  }
+
+  /**
+   * Get the output of `stderr` as a string.
+   *
+   * NOTE: This may error with string conversion errors if the command does
+   * not ouptut valid unicode.
+   */
+  async stderr() {
+    return this.output("stderr");
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { SandboxSDK, Sandbox, Command } from "./create-sandbox";
+export { SandboxClient } from "./client/client";

package/src/utils/array.ts

@@ -0,0 +1,15 @@
+/**
+ * Returns an array from the given item. If the  item is an array it will be
+ * returned as a it is, otherwise it will be returned as a single item array.
+ * If the item is undefined or null an empty array will be returned.
+ *
+ * @param item The item to convert to an array.
+ * @returns An array.
+ */
+export function array<T>(item?: null | T | T[]): T[] {
+  return item !== undefined && item !== null
+    ? Array.isArray(item)
+      ? item
+      : [item]
+    : [];
+}

package/src/utils/deferred-generator.ts

@@ -0,0 +1,38 @@
+import { Deferred } from "./deferred";
+
+export interface DeferredGenerator<T, R> {
+  generator(): AsyncGenerator<T, R, void>;
+  next: (value: IteratorResult<T | Promise<T>>) => void;
+}
+
+export function createDeferredGenerator<T, R>(): DeferredGenerator<T, R> {
+  const deferreds = [new Deferred<IteratorResult<Promise<T> | T>>()];
+  let currentIndex = 0;
+
+  const next = (value: IteratorResult<T | Promise<T>, R>) => {
+    const currentDeferred = deferreds[currentIndex];
+    if (!value.done) {
+      deferreds.push(new Deferred<IteratorResult<Promise<T> | T>>());
+      currentIndex++;
+    }
+
+    currentDeferred.resolve(value);
+  };
+
+  function generator(): AsyncGenerator<T, R> {
+    let currentIndex = 0;
+    return (async function* () {
+      while (true) {
+        const result = await deferreds[currentIndex].promise;
+        if (result.done) return result.value;
+        yield result.value;
+        currentIndex++;
+      }
+    })();
+  }
+
+  return {
+    generator,
+    next,
+  };
+}

package/src/utils/deferred.ts

@@ -0,0 +1,12 @@
+export class Deferred<T> {
+  promise: Promise<T>;
+  resolve!: (value: T | PromiseLike<T>) => void;
+  reject!: (reason?: any) => void;
+
+  constructor() {
+    this.promise = new Promise((res, rej) => {
+      this.resolve = res;
+      this.reject = rej;
+    });
+  }
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "outDir": "./dist",
+    "esModuleInterop": true,
+    "lib": [
+      "ESNext"
+    ],
+    "strict": true,
+    "target": "ES2020",
+    "declaration": true,
+    "module": "commonjs"
+  },
+  "include": [
+    "src/**/*"
+  ]
+}

package/typedoc.json

@@ -0,0 +1,7 @@
+{
+  "out": "dist/doc",
+  "sort": ["source-order"],
+  "navigationLinks": {
+    "GitHub": "https://github.com/vercel/sandbox-sdk"
+  }
+}