@vercel/sandbox 0.0.7 → 0.0.9

package/src/command.test.ts

@@ -1,17 +1,25 @@
-import { it, expect, vi } from "vitest";
+import { expect, it, vi, beforeEach, afterEach } 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);
+let sandbox: Sandbox;
 
-  const sandbox = await Sandbox.create({
+beforeEach(async () => {
+  sandbox = await Sandbox.create({
     projectId: process.env.VERCEL_PROJECT_ID!,
     teamId: process.env.VERCEL_TEAM_ID!,
     token: process.env.VERCEL_TOKEN!,
   });
+});
+
+afterEach(async () => {
+  await sandbox.stop();
+});
+
+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 cmd = await sandbox.runCommand({
     cmd: "echo",
@@ -26,19 +34,11 @@ it("warns when there is more than one logs consumer", async () => {
       /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!"],
@@ -46,6 +46,29 @@ it("does not warn when there is only one logs consumer", async () => {
 
   expect(await cmd.stdout()).toEqual("Hello World!\n");
   expect(warnSpy).not.toHaveBeenCalled();
+});
 
-  await sandbox.stop();
+it("Kills a command with a SIGINT", async () => {
+  const cmd = await sandbox.runCommand({
+    cmd: "sleep",
+    args: ["200000"],
+    detached: true,
+  });
+
+  await cmd.kill("SIGINT");
+  const result = await cmd.wait();
+  expect(result.exitCode).toBe(130); // 128 + 2
+});
+
+it("Kills a command with a SIGTERM", async () => {
+  const cmd = await sandbox.runCommand({
+    cmd: "sleep",
+    args: ["200000"],
+    detached: true,
+  });
+
+  await cmd.kill("SIGTERM");
+
+  const result = await cmd.wait();
+  expect(result.exitCode).toBe(143); // 128 + 15
 });

package/src/command.ts

@@ -1,4 +1,5 @@
-import { APIClient } from "./api-client";
+import { APIClient, type CommandData } from "./api-client";
+import { Signal, resolveSignal } from "./utils/resolveSignal";
 
 /**
  * A command executed in a Sandbox.
@@ -22,10 +23,17 @@ export class Command {
    */
   private sandboxId: string;
 
+  /**
+   * Data for the command execution.
+   */
+  private cmd: CommandData;
+
   /**
    * ID of the command execution.
    */
-  public cmdId: string;
+  get cmdId() {
+    return this.cmd.id;
+  }
 
   /**
    * @param params - Object containing the client, sandbox ID, and command ID.
@@ -36,15 +44,15 @@ export class Command {
   constructor({
     client,
     sandboxId,
-    cmdId,
+    cmd,
   }: {
     client: APIClient;
     sandboxId: string;
-    cmdId: string;
+    cmd: CommandData;
   }) {
     this.client = client;
     this.sandboxId = sandboxId;
-    this.cmdId = cmdId;
+    this.cmd = cmd;
   }
 
   /**
@@ -68,7 +76,7 @@ export class Command {
   logs() {
     return this.client.getLogs({
       sandboxId: this.sandboxId,
-      cmdId: this.cmdId,
+      cmdId: this.cmd.id,
     });
   }
 
@@ -87,15 +95,15 @@ export class Command {
   async wait() {
     const command = await this.client.getCommand({
       sandboxId: this.sandboxId,
-      cmdId: this.cmdId,
+      cmdId: this.cmd.id,
       wait: true,
     });
 
     return new CommandFinished({
       client: this.client,
       sandboxId: this.sandboxId,
-      cmdId: command.json.cmdId,
-      exitCode: command.json.exitCode,
+      cmd: command.json.command,
+      exitCode: command.json.command.exitCode,
     });
   }
 
@@ -141,6 +149,21 @@ export class Command {
   async stderr() {
     return this.output("stderr");
   }
+
+  /**
+   * Kill a running command in a sandbox.
+   *
+   * @param params - commandId and the signal to send the running process.
+   * Defaults to SIGTERM.
+   * @returns Promise<void>.
+   */
+  async kill(signal?: Signal) {
+    await this.client.killCommand({
+      sandboxId: this.sandboxId,
+      commandId: this.cmd.id,
+      signal: resolveSignal(signal ?? "SIGTERM"),
+    });
+  }
 }
 
 /**
@@ -167,7 +190,7 @@ export class CommandFinished extends Command {
   constructor(params: {
     client: APIClient;
     sandboxId: string;
-    cmdId: string;
+    cmd: CommandData;
     exitCode: number;
   }) {
     super({ ...params });

package/src/sandbox.ts

@@ -1,7 +1,8 @@
-import { Readable, type Writable } from "stream";
+import type { SandboxData, SandboxRouteData } from "./api-client";
+import type { Writable } from "stream";
 import { APIClient } from "./api-client";
-import { Command, CommandFinished } from "./command";
-import { getCredentials, type Credentials } from "./utils/get-credentials";
+import { Command, type CommandFinished } from "./command";
+import { type Credentials, getCredentials } from "./utils/get-credentials";
 
 /** @inline */
 export interface CreateSandboxParams {
@@ -9,8 +10,14 @@ export interface CreateSandboxParams {
    * The source of the sandbox.
    *
    * Omit this parameter start a sandbox without a source.
+   *
+   * For git sources:
+   * - `depth`: Creates shallow clones with limited commit history (minimum: 1)
+   * - `revision`: Clones and checks out a specific commit, branch, or tag
    */
-  source?: { type: "git"; url: string } | { type: "tarball"; url: string };
+  source?:
+    | { type: "git"; url: string; depth?: number; revision?: string }
+    | { type: "tarball"; url: string };
   /**
    * Array of port numbers to expose from the sandbox.
    */
@@ -26,6 +33,12 @@ export interface CreateSandboxParams {
    * 2048 MB of memory per vCPU.
    */
   resources?: { vcpus: number };
+
+  /**
+   * The runtime of the sandbox, currently only `node22` and `python3.13` are supported.
+   * If not specified, the default runtime `node22` will be used.
+   */
+  runtime?: "node22" | "python3.13";
 }
 
 /** @inline */
@@ -85,12 +98,19 @@ export class Sandbox {
    * Routes from ports to subdomains.
   /* @hidden
    */
-  public readonly routes: { subdomain: string; port: number }[];
+  public readonly routes: SandboxRouteData[];
 
   /**
    * Unique ID of this sandbox.
    */
-  public readonly sandboxId: string;
+  public get sandboxId(): string {
+    return this.sandbox.id;
+  }
+
+  /**
+   * Data about this sandbox.
+   */
+  private readonly sandbox: SandboxData;
 
   /**
    * Create a new sandbox.
@@ -113,11 +133,12 @@ export class Sandbox {
       ports: params?.ports ?? [],
       timeout: params?.timeout,
       resources: params?.resources,
+      runtime: params?.runtime,
     });
 
     return new Sandbox({
       client,
-      sandboxId: sandbox.json.sandboxId,
+      sandbox: sandbox.json.sandbox,
       routes: sandbox.json.routes,
     });
   }
@@ -137,10 +158,14 @@ export class Sandbox {
       token: credentials.token,
     });
 
+    const sandbox = await client.getSandbox({
+      sandboxId: params.sandboxId,
+    });
+
     return new Sandbox({
       client,
-      sandboxId: params.sandboxId,
-      routes: params.routes,
+      sandbox: sandbox.json.sandbox,
+      routes: sandbox.json.routes,
     });
   }
 
@@ -154,15 +179,15 @@ export class Sandbox {
   constructor({
     client,
     routes,
-    sandboxId,
+    sandbox,
   }: {
     client: APIClient;
-    routes: { subdomain: string; port: number }[];
-    sandboxId: string;
+    routes: SandboxRouteData[];
+    sandbox: SandboxData;
   }) {
     this.client = client;
     this.routes = routes;
-    this.sandboxId = sandboxId;
+    this.sandbox = sandbox;
   }
 
   /**
@@ -171,11 +196,16 @@ export class Sandbox {
    * @param cmdId - ID of the command to retrieve
    * @returns A {@link Command} instance representing the command
    */
-  getCommand(cmdId: string): Command {
+  async getCommand(cmdId: string): Promise<Command> {
+    const command = await this.client.getCommand({
+      sandboxId: this.sandbox.id,
+      cmdId,
+    });
+
     return new Command({
       client: this.client,
-      sandboxId: this.sandboxId,
-      cmdId,
+      sandboxId: this.sandbox.id,
+      cmd: command.json.command,
     });
   }
 
@@ -224,7 +254,7 @@ export class Sandbox {
    */
   async _runCommand(params: RunCommandParams) {
     const commandResponse = await this.client.runCommand({
-      sandboxId: this.sandboxId,
+      sandboxId: this.sandbox.id,
       command: params.cmd,
       args: params.args ?? [],
       cwd: params.cwd,
@@ -233,8 +263,8 @@ export class Sandbox {
 
     const command = new Command({
       client: this.client,
-      sandboxId: this.sandboxId,
-      cmdId: commandResponse.json.cmdId,
+      sandboxId: this.sandbox.id,
+      cmd: commandResponse.json.command,
     });
 
     if (params.stdout || params.stderr) {
@@ -259,7 +289,7 @@ export class Sandbox {
    */
   async mkDir(path: string): Promise<void> {
     await this.client.mkDir({
-      sandboxId: this.sandboxId,
+      sandboxId: this.sandbox.id,
       path: path,
     });
   }
@@ -270,9 +300,9 @@ export class 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 }[]) {
+  async writeFiles(files: { path: string; stream: Buffer }[]) {
     return this.client.writeFiles({
-      sandboxId: this.sandboxId,
+      sandboxId: this.sandbox.id,
       files: files,
     });
   }
@@ -300,7 +330,7 @@ export class Sandbox {
    */
   async stop() {
     await this.client.stopSandbox({
-      sandboxId: this.sandboxId,
+      sandboxId: this.sandbox.id,
     });
   }
 }

package/src/utils/resolveSignal.ts

@@ -0,0 +1,24 @@
+const linuxSignalMapping = {
+  SIGHUP: 1,
+  SIGINT: 2,
+  SIGQUIT: 3,
+  SIGKILL: 9,
+  SIGTERM: 15,
+  SIGCONT: 18,
+  SIGSTOP: 19,
+} as const;
+
+type CommonLinuxSignals = keyof typeof linuxSignalMapping;
+
+export type Signal = CommonLinuxSignals | number;
+
+export function resolveSignal(signal: Signal): number {
+  if (typeof signal === "number") {
+    return signal;
+  }
+
+  if (signal in linuxSignalMapping) {
+    return linuxSignalMapping[signal];
+  }
+  throw new Error(`Unknown signal name: ${String(signal)}`);
+}

package/src/version.ts

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