@vercel/sandbox 0.0.5 → 0.0.6

package/src/api-client/api-client.ts

@@ -0,0 +1,225 @@
+import FormData from "form-data";
+import {
+  BaseClient,
+  parseOrThrow,
+  type Parsed,
+  type RequestParams,
+} from "./base-client";
+import {
+  Command,
+  CommandFinished,
+  CreatedCommand,
+  CreatedSandbox,
+  LogLine,
+  StoppedSandbox,
+  WrittenFile,
+} from "./validators";
+import { Readable } from "stream";
+import { APIError } from "./api-error";
+import { LRUCache } from "lru-cache";
+import { VERSION } from "../version";
+import { z } from "zod";
+import jsonlines from "jsonlines";
+import os from "os";
+import ms from "ms";
+
+/**
+ * Allows to track the logs hits for a command un a to maximum of items and
+ * TTL so that we don't incur in memory leaks in a log running process.
+ */
+const logHits = new LRUCache<string, boolean>({
+  ttl: ms("45m"),
+  max: 1000,
+});
+
+export class APIClient extends BaseClient {
+  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",
+        "user-agent": `vercel/sandbox/${VERSION} (Node.js/${process.version}; ${os.platform()}/${os.arch()})`,
+        ...params?.headers,
+      },
+    });
+  }
+
+  async createSandbox(params: {
+    ports?: number[];
+    projectId: string;
+    source?: { type: "git"; url: string } | { type: "tarball"; url: string };
+    timeout?: number;
+    resources?: { cores: number; memory: number };
+  }) {
+    return parseOrThrow(
+      CreatedSandbox,
+      await this.request("/v1/sandboxes", {
+        method: "POST",
+        body: JSON.stringify({
+          projectId: params.projectId,
+          ports: params.ports,
+          source: params.source,
+          timeout: params.timeout,
+          resources: params.resources,
+        }),
+      }),
+    );
+  }
+
+  async runCommand(params: {
+    sandboxId: string;
+    cwd?: string;
+    command: string;
+    args: string[];
+    env: Record<string, 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,
+          env: params.env,
+        }),
+      }),
+    );
+  }
+
+  async getCommand(params: {
+    sandboxId: string;
+    cmdId: string;
+    wait: true;
+  }): Promise<Parsed<z.infer<typeof CommandFinished>>>;
+  async getCommand(params: {
+    sandboxId: string;
+    cmdId: string;
+    wait?: boolean;
+  }): Promise<Parsed<z.infer<typeof Command>>>;
+  async getCommand(params: {
+    sandboxId: string;
+    cmdId: string;
+    wait?: boolean;
+  }) {
+    return params.wait
+      ? parseOrThrow(
+          CommandFinished,
+          await this.request(
+            `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`,
+            { query: { wait: "true" } },
+          ),
+        )
+      : parseOrThrow(
+          Command,
+          await this.request(
+            `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`,
+          ),
+        );
+  }
+
+  async mkDir(params: { sandboxId: string; path: string; cwd?: string }) {
+    return parseOrThrow(
+      WrittenFile,
+      await this.request(`/v1/sandboxes/${params.sandboxId}/fs/mkdir`, {
+        method: "POST",
+        body: JSON.stringify({ path: params.path, cwd: params.cwd }),
+      }),
+    );
+  }
+
+  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;
+  }
+
+  async *getLogs(params: {
+    sandboxId: string;
+    cmdId: string;
+  }): AsyncIterable<z.infer<typeof LogLine>> {
+    const url = `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}/logs`;
+    const response = await this.request(url, { method: "GET" });
+    if (response.headers.get("content-type") !== "application/x-ndjson") {
+      throw new APIError(response, {
+        message: "Expected a stream of logs",
+      });
+    }
+
+    /**
+     * Currently, once we consume logs in the backend we cannot read them
+     * again. This logic writes a warning when the endpoint for a command
+     * logs is consumed more than once to alert the user about this.
+     *
+     * This is a temporary solution, we should be able to handle this in
+     * the backend in the future.
+     */
+    if (logHits.get(url)) {
+      console.warn(
+        `Multiple consumers for logs of command \`${params.cmdId}\`. This may lead to unexpected behavior.`,
+      );
+    }
+
+    logHits.set(url, true);
+    for await (const chunk of response.body.pipe(jsonlines.parse())) {
+      yield LogLine.parse(chunk);
+    }
+  }
+
+  async stopSandbox(params: {
+    sandboxId: string;
+  }): Promise<Parsed<z.infer<typeof StoppedSandbox>>> {
+    const url = `/v1/sandboxes/${params.sandboxId}/stop`;
+    return parseOrThrow(
+      StoppedSandbox,
+      await this.request(url, { method: "POST" }),
+    );
+  }
+}

package/src/{client → api-client}/base-client.ts

@@ -18,7 +18,7 @@ export interface RequestParams extends RequestInit {
  * we can pass query parameters as an object, support retries, debugging
  * and automatic authorization.
  */
-export class APIClient {
+export class BaseClient {
   protected token?: string;
   private fetch: ReturnType<typeof withRetry<RequestInit>>;
   private debug: boolean;

package/src/api-client/index.ts

@@ -0,0 +1 @@
+export { APIClient } from "./api-client";

package/src/{client → api-client}/validators.ts

@@ -17,12 +17,20 @@ export const Command = z.object({
   name: z.string(),
 });
 
-export const FinishedCommand = z.object({
+export const CommandFinished = z.object({
+  args: z.array(z.string()),
   cmdId: z.string(),
+  cwd: z.string(),
+  exitCode: z.number(),
+  name: z.string(),
 });
 
 export const WrittenFile = z.object({});
 
+export const StoppedSandbox = z.object({
+  sandboxId: z.string(),
+});
+
 export const LogLine = z.object({
   stream: z.enum(["stdout", "stderr"]),
   data: z.string(),

package/src/command.test.ts

@@ -0,0 +1,51 @@
+import { it, expect, vi } from "vitest";
+import { Sandbox } from "./sandbox";
+
+it("warns when there is more than one logs consumer", async () => {
+  const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  const stdoutSpy = vi
+    .spyOn(process.stdout, "write")
+    .mockImplementation(() => true);
+
+  const sandbox = await Sandbox.create({
+    projectId: process.env.VERCEL_PROJECT_ID!,
+    teamId: process.env.VERCEL_TEAM_ID!,
+    token: process.env.VERCEL_TOKEN!,
+  });
+
+  const cmd = await sandbox.runCommand({
+    cmd: "echo",
+    args: ["Hello World!"],
+    stdout: process.stdout,
+  });
+
+  expect(await cmd.stdout()).toEqual("");
+  expect(stdoutSpy).toHaveBeenCalledWith("Hello World!\n");
+  expect(warnSpy).toHaveBeenCalledWith(
+    expect.stringMatching(
+      /Multiple consumers for logs of command `[^`]+`\.\sThis may lead to unexpected behavior\./,
+    ),
+  );
+
+  await sandbox.stop();
+});
+
+it("does not warn when there is only one logs consumer", async () => {
+  const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+  const sandbox = await Sandbox.create({
+    projectId: process.env.VERCEL_PROJECT_ID!,
+    teamId: process.env.VERCEL_TEAM_ID!,
+    token: process.env.VERCEL_TOKEN!,
+  });
+
+  const cmd = await sandbox.runCommand({
+    cmd: "echo",
+    args: ["Hello World!"],
+  });
+
+  expect(await cmd.stdout()).toEqual("Hello World!\n");
+  expect(warnSpy).not.toHaveBeenCalled();
+
+  await sandbox.stop();
+});

package/src/command.ts

@@ -0,0 +1,176 @@
+import { APIClient } from "./api-client";
+
+/**
+ * A command executed in a Sandbox.
+ *
+ * You can {@link wait} on commands to access their {@link CommandFinished.exitCode}, and
+ * iterate over their output with {@link logs}.
+ *
+ * @see {@link Sandbox.runCommand} to start a command.
+ *
+ * @hideconstructor
+ */
+export class Command {
+  /**
+   * @internal
+   * @private
+   */
+  protected client: APIClient;
+
+  /**
+   * ID of the sandbox this command is running in.
+   */
+  private sandboxId: string;
+
+  /**
+   * ID of the command execution.
+   */
+  public cmdId: string;
+
+  /**
+   * @param params - Object containing the client, sandbox ID, and command ID.
+   * @param params.client - API client used to interact with the backend.
+   * @param params.sandboxId - The ID of the sandbox where the command is running.
+   * @param params.cmdId - The ID of the command execution.
+   */
+  constructor({
+    client,
+    sandboxId,
+    cmdId,
+  }: {
+    client: APIClient;
+    sandboxId: string;
+    cmdId: string;
+  }) {
+    this.client = client;
+    this.sandboxId = sandboxId;
+    this.cmdId = cmdId;
+  }
+
+  /**
+   * 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);
+   *   }
+   * }
+   * ```
+   *
+   * @returns An async iterable of log entries from the command output.
+   *
+   * @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 its exit code.
+   *
+   * ```
+   * await cmd.wait()
+   * if (cmd.exitCode != 0) {
+   *   console.error("Something went wrong...")
+   * }
+   * ```
+   *
+   * @returns A {@link CommandFinished} instance with populated exit code.
+   */
+  async wait() {
+    const command = await this.client.getCommand({
+      sandboxId: this.sandboxId,
+      cmdId: this.cmdId,
+      wait: true,
+    });
+
+    return new CommandFinished({
+      client: this.client,
+      sandboxId: this.sandboxId,
+      cmdId: command.json.cmdId,
+      exitCode: command.json.exitCode,
+    });
+  }
+
+  /**
+   * Get the output of `stdout`, `stderr`, or both as a string.
+   *
+   * NOTE: This may throw string conversion errors if the command does
+   * not output valid Unicode.
+   *
+   * @param stream - The output stream to read: "stdout", "stderr", or "both".
+   * @returns The output of the specified stream(s) as a string.
+   */
+  async output(stream: "stdout" | "stderr" | "both" = "both") {
+    let data = "";
+    for await (const log of this.logs()) {
+      if (stream === "both" || log.stream === stream) {
+        data += log.data;
+      }
+    }
+    return data;
+  }
+
+  /**
+   * Get the output of `stdout` as a string.
+   *
+   * NOTE: This may throw string conversion errors if the command does
+   * not output valid Unicode.
+   *
+   * @returns The standard output of the command.
+   */
+  async stdout() {
+    return this.output("stdout");
+  }
+
+  /**
+   * Get the output of `stderr` as a string.
+   *
+   * NOTE: This may throw string conversion errors if the command does
+   * not output valid Unicode.
+   *
+   * @returns The standard error output of the command.
+   */
+  async stderr() {
+    return this.output("stderr");
+  }
+}
+
+/**
+ * A command that has finished executing.
+ *
+ * Contains the exit code of the command.
+ *
+ * @hideconstructor
+ */
+export class CommandFinished extends Command {
+  /**
+   * The exit code of the command, if available. This is set after
+   * {@link wait} has returned.
+   */
+  public exitCode: number;
+
+  /**
+   * @param params - Object containing client, sandbox ID, command ID, and exit code.
+   * @param params.client - API client used to interact with the backend.
+   * @param params.sandboxId - The ID of the sandbox where the command ran.
+   * @param params.cmdId - The ID of the command execution.
+   * @param params.exitCode - The exit code of the completed command.
+   */
+  constructor(params: {
+    client: APIClient;
+    sandboxId: string;
+    cmdId: string;
+    exitCode: number;
+  }) {
+    super({ ...params });
+    this.exitCode = params.exitCode;
+  }
+}

package/src/index.ts

@@ -1 +1,2 @@
-export { SDK, Sandbox, Command } from "./create-sandbox";
+export { Sandbox } from "./sandbox";
+export { Command, CommandFinished } from "./command";