@vercel/sandbox 0.0.5 → 0.0.6

package/src/sandbox.ts

@@ -0,0 +1,309 @@
+import { Readable, type Writable } from "stream";
+import { APIClient } from "./api-client";
+import { Command, CommandFinished } from "./command";
+import { getCredentials, type Credentials } from "./utils/get-credentials";
+
+/** @inline */
+export interface CreateSandboxParams {
+  /**
+   * The source of the sandbox.
+   *
+   * Omit this parameter start a sandbox without a source.
+   */
+  source?: { type: "git"; url: string } | { type: "tarball"; url: string };
+  /**
+   * Array of port numbers to expose from the sandbox.
+   */
+  ports?: number[];
+  /**
+   * Timeout in milliseconds before the sandbox auto-terminates.
+   */
+  timeout?: number;
+  /**
+   * Resources to allocate to the sandbox.
+   *
+   * Your sandbox will get the amount of cores you specify here. For memory,
+   * you will get double the amount of cores.
+   */
+  resources?: { cores: number };
+}
+
+/** @inline */
+interface GetSandboxParams {
+  /**
+   * Port-to-subdomain route mappings.
+   */
+  routes: Array<{ subdomain: string; port: number }>;
+  /**
+   * Unique identifier of the sandbox.
+   */
+  sandboxId: string;
+}
+
+/** @inline */
+interface RunCommandParams {
+  /**
+   * The command to execute
+   */
+  cmd: string;
+  /**
+   * Arguments to pass to the command
+   */
+  args?: string[];
+  /**
+   * Working directory to execute the command in
+   */
+  cwd?: string;
+  /**
+   * Environment variables to set for this command
+   */
+  env?: Record<string, string>;
+  /**
+   * If true, the command will return without waiting for `exitCode`
+   */
+  detached?: boolean;
+  /**
+   * A `Writable` stream where `stdout` from the command will be piped
+   */
+  stdout?: Writable;
+  /**
+   * A `Writable` stream where `stderr` from the command will be piped
+   */
+  stderr?: Writable;
+}
+
+/**
+ * A Sandbox is an isolated Linux MicroVM to run commands in.
+ *
+ * Use {@link Sandbox.create} or {@link Sandbox.get} to construct.
+ * @hideconstructor
+ */
+export class Sandbox {
+  private readonly client: APIClient;
+
+  /**
+   * Routes from ports to subdomains.
+  /* @hidden
+   */
+  public readonly routes: { subdomain: string; port: number }[];
+
+  /**
+   * Unique ID of this sandbox.
+   */
+  public readonly sandboxId: string;
+
+  /**
+   * Create a new sandbox.
+   *
+   * @param params - Creation parameters and optional credentials.
+   * @returns A promise resolving to the created {@link Sandbox}.
+   */
+  static async create(
+    params?: CreateSandboxParams | (CreateSandboxParams & Credentials),
+  ): Promise<Sandbox> {
+    const credentials = getCredentials(params);
+    const client = new APIClient({
+      teamId: credentials.teamId,
+      token: credentials.token,
+    });
+
+    const sandbox = await client.createSandbox({
+      source: params?.source,
+      projectId: credentials.projectId,
+      ports: params?.ports ?? [],
+      timeout: params?.timeout,
+      ...(params?.resources && {
+        cores: params.resources.cores,
+        memory: 2048 * params.resources.cores,
+      }),
+    });
+
+    return new Sandbox({
+      client,
+      sandboxId: sandbox.json.sandboxId,
+      routes: sandbox.json.routes,
+    });
+  }
+
+  /**
+   * Retrieve an existing sandbox.
+   *
+   * @param params - Get parameters and optional credentials.
+   * @returns A promise resolving to the {@link Sandbox}.
+   */
+  static async get(
+    params: GetSandboxParams | (GetSandboxParams & Credentials),
+  ): Promise<Sandbox> {
+    const credentials = getCredentials(params);
+    const client = new APIClient({
+      teamId: credentials.teamId,
+      token: credentials.token,
+    });
+
+    return new Sandbox({
+      client,
+      sandboxId: params.sandboxId,
+      routes: params.routes,
+    });
+  }
+
+  /**
+   * Create a new Sandbox instance.
+   *
+   * @param client - API client used to communicate with the backend
+   * @param routes - Port-to-subdomain mappings for exposed ports
+   * @param sandboxId - Unique identifier for the sandbox
+   */
+  constructor({
+    client,
+    routes,
+    sandboxId,
+  }: {
+    client: APIClient;
+    routes: { subdomain: string; port: number }[];
+    sandboxId: string;
+  }) {
+    this.client = client;
+    this.routes = routes;
+    this.sandboxId = sandboxId;
+  }
+
+  /**
+   * Get a previously run command by its ID.
+   *
+   * @param cmdId - ID of the command to retrieve
+   * @returns A {@link Command} instance representing the command
+   */
+  getCommand(cmdId: string): Command {
+    return new Command({
+      client: this.client,
+      sandboxId: this.sandboxId,
+      cmdId,
+    });
+  }
+
+  /**
+   * Start executing a command in this sandbox.
+   *
+   * @param command - The command to execute.
+   * @param args - Arguments to pass to the command.
+   * @returns A {@link CommandFinished} result once execution is done.
+   */
+  async runCommand(command: string, args?: string[]): Promise<CommandFinished>;
+
+  /**
+   * Start executing a command in detached mode.
+   *
+   * @param params - The command parameters.
+   * @returns A {@link Command} instance for the running command.
+   */
+  async runCommand(
+    params: RunCommandParams & { detached: true },
+  ): Promise<Command>;
+
+  /**
+   * Start executing a command in this sandbox.
+   *
+   * @param params - The command parameters.
+   * @returns A {@link CommandFinished} result once execution is done.
+   */
+  async runCommand(params: RunCommandParams): Promise<CommandFinished>;
+
+  async runCommand(
+    commandOrParams: string | RunCommandParams,
+    args?: string[],
+  ): Promise<Command | CommandFinished> {
+    return typeof commandOrParams === "string"
+      ? this._runCommand({ cmd: commandOrParams, args })
+      : this._runCommand(commandOrParams);
+  }
+
+  /**
+   * Internal helper to start a command in the sandbox.
+   *
+   * @param params - Command execution parameters.
+   * @returns A {@link Command} or {@link CommandFinished}, depending on `detached`.
+   * @internal
+   */
+  async _runCommand(params: RunCommandParams) {
+    const commandResponse = await this.client.runCommand({
+      sandboxId: this.sandboxId,
+      command: params.cmd,
+      args: params.args ?? [],
+      cwd: params.cwd,
+      env: params.env ?? {},
+    });
+
+    const command = new Command({
+      client: this.client,
+      sandboxId: this.sandboxId,
+      cmdId: commandResponse.json.cmdId,
+    });
+
+    if (params.stdout || params.stderr) {
+      (async () => {
+        for await (const log of command.logs()) {
+          if (log.stream === "stdout") {
+            params.stdout?.write(log.data);
+          } else if (log.stream === "stderr") {
+            params.stderr?.write(log.data);
+          }
+        }
+      })();
+    }
+
+    return params.detached ? command : command.wait();
+  }
+
+  /**
+   * Create a directory in the filesystem of this sandbox.
+   *
+   * @param path - Path of the directory to create
+   */
+  async mkDir(path: string): Promise<void> {
+    await this.client.mkDir({
+      sandboxId: this.sandboxId,
+      path: path,
+    });
+  }
+
+  /**
+   * Write files to the filesystem of this sandbox.
+   *
+   * @param files - Array of files with path and stream/buffer contents
+   * @returns A promise that resolves when the files are written
+   */
+  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.
+   *
+   * @param p - Port number to resolve
+   * @returns A full domain (e.g. `https://subdomain.vercel.run`)
+   * @throws If the port has no associated route
+   */
+  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}`);
+    }
+  }
+
+  /**
+   * Stop the sandbox.
+   *
+   * @returns A promise that resolves when the sandbox is stopped
+   */
+  async stop() {
+    await this.client.stopSandbox({
+      sandboxId: this.sandboxId,
+    });
+  }
+}

package/src/utils/decode-base64-url.ts

@@ -0,0 +1,14 @@
+/**
+ * Decode a Base64 URL-encoded string into a JSON object.
+ *
+ * @param base64Url - The Base64 URL-encoded string to decode.
+ * @returns The decoded JSON object or null if decoding fails.
+ */
+export function decodeBase64Url(base64Url: string) {
+  return JSON.parse(
+    Buffer.from(
+      base64Url.replace(/-/g, "+").replace(/_/g, "/"),
+      "base64",
+    ).toString("utf8"),
+  );
+}

package/src/utils/get-credentials.ts

@@ -0,0 +1,113 @@
+import { getVercelOidcToken } from "./get-vercel-oidc-token";
+import { decodeBase64Url } from "./decode-base64-url";
+import { z } from "zod";
+
+export interface Credentials {
+  /**
+   * Authentication token for the Vercel API. It could be an OIDC token
+   * or a personal access token.
+   */
+  token: string;
+  /**
+   * The ID of the project to associate Sandbox operations.
+   */
+  projectId: string;
+  /**
+   * The ID of the team to associate Sandbox operations.
+   */
+  teamId: string;
+}
+
+/**
+ * Allow to get credentials to access the Vercel API. Credentials can be
+ * provided in two different ways:
+ *
+ * 1. By passing an object with the `teamId`, `token`, and `projectId` properties.
+ * 2. By using an environment variable VERCEL_OIDC_TOKEN.
+ *
+ * If both methods are used, the object properties take precedence over the
+ * environment variable. If neither method is used, an error is thrown.
+ */
+export function getCredentials<T>(params?: T | Credentials): Credentials {
+  const credentials = getCredentialsFromParams(params ?? {});
+  if (credentials) {
+    return credentials;
+  }
+
+  const oidcToken = getVercelOidcToken();
+  if (oidcToken) {
+    return getCredentialsFromOIDCToken(oidcToken);
+  }
+
+  throw new Error(
+    "You must provide credentials to access the Vercel API \n" +
+      "either through parameters or using OpenID Connect [https://vercel.com/docs/oidc]",
+  );
+}
+
+/**
+ * Attempt to extract credentials from the provided parameters. Either all
+ * required fields (`token`, `teamId`, and `projectId`) must be present
+ * or none of them, otherwise an error is thrown.
+ */
+function getCredentialsFromParams<Params extends Record<string, unknown>>(
+  params: Params | Credentials,
+): Credentials | null {
+  const missing = [
+    "token" in params && typeof params.token === "string" ? null : "token",
+    "teamId" in params && typeof params.teamId === "string" ? null : "teamId",
+    "projectId" in params && typeof params.projectId === "string"
+      ? null
+      : "projectId",
+  ].filter((value) => value !== null);
+
+  if (missing.length === 0) {
+    return {
+      token: params.token as string,
+      projectId: params.projectId as string,
+      teamId: params.teamId as string,
+    };
+  }
+
+  if (missing.length < 3) {
+    throw new Error(
+      `Missing credentials parameters to access the Vercel API: ${missing
+        .filter((value) => value !== null)
+        .join(", ")}`,
+    );
+  }
+
+  return null;
+}
+
+/**
+ * Schema to validate the payload of the Vercel OIDC token where we expect
+ * to find the `teamId` and `projectId`.
+ */
+const schema = z.object({
+  owner_id: z.string(),
+  project_id: z.string(),
+});
+
+/**
+ * Extracts credentials from a Vercel OIDC token. The token is expected to be
+ * a JWT with a payload that contains `project_id` and `owner_id`.
+ *
+ * @param token - The Vercel OIDC token.
+ * @returns An object containing the token, projectId, and teamId.
+ * @throws If the token is invalid or does not contain the required fields.
+ */
+function getCredentialsFromOIDCToken(token: string): Credentials {
+  try {
+    const payload = schema.parse(decodeBase64Url(token.split(".")[1]));
+    return {
+      token,
+      projectId: payload.project_id,
+      teamId: payload.owner_id,
+    };
+  } catch (error) {
+    throw new Error(
+      `Invalid Vercel OIDC token: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}

package/src/utils/get-vercel-oidc-token.ts

@@ -0,0 +1,31 @@
+/**
+ * This function is implemented in @vercel/functions but it is asynchronous.
+ * In order to keep it synchronous, we are implementing it here as well.
+ * Ideally we should remove this and use the one from @vercel/functions.
+ */
+export function getVercelOidcToken(): string | undefined {
+  const token =
+    getContext().headers?.["x-vercel-oidc-token"] ??
+    process.env.VERCEL_OIDC_TOKEN;
+
+  if (!token && process.env.NODE_ENV === "production") {
+    throw new Error(
+      `The 'x-vercel-oidc-token' header is missing from the request. Do you have the OIDC option enabled in the Vercel project settings?`,
+    );
+  }
+
+  return token;
+}
+
+const SYMBOL_FOR_REQ_CONTEXT = Symbol.for("@vercel/request-context");
+
+interface Context {
+  headers?: Record<string, string>;
+}
+
+function getContext(): Context {
+  const fromSymbol: typeof globalThis & {
+    [SYMBOL_FOR_REQ_CONTEXT]?: { get?: () => Context };
+  } = globalThis;
+  return fromSymbol[SYMBOL_FOR_REQ_CONTEXT]?.get?.() ?? {};
+}

package/src/version.ts

@@ -1,2 +1,2 @@
 // Autogenerated by inject-version.ts
-export const VERSION = "0.0.5";
+export const VERSION = "0.0.6";

package/tsconfig.json

@@ -9,5 +9,6 @@
     "module": "commonjs",
     "resolveJsonModule": true
   },
-  "include": ["src/**/*"]
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts", "vitest.config.ts", "vitest.setup.ts"]
 }

package/typedoc.json

@@ -3,5 +3,11 @@
   "sort": ["source-order"],
   "navigationLinks": {
     "GitHub": "https://github.com/vercel/sandbox-sdk"
-  }
+  },
+  "compilerOptions": {
+    "exclude": ["src/command.test.ts"],
+    "stripInternal": true
+  },
+  "excludeInternal": false,
+  "excludePrivate": true
 }

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    setupFiles: ["./vitest.setup.ts"],
+    testTimeout: 60_000,
+  },
+});

package/vitest.setup.ts

@@ -0,0 +1,4 @@
+import { config } from "dotenv";
+import { resolve } from "path";
+
+config({ path: resolve(__dirname, ".env.test") });