@vercel/sandbox 0.0.8 → 0.0.10

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.test.ts

@@ -0,0 +1,29 @@
+import { it, beforeEach, afterEach, expect } from "vitest";
+import { consumeReadable } from "./utils/consume-readable";
+import { Sandbox } from "./sandbox";
+
+let sandbox: Sandbox;
+
+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("allows to write files and then read them", async () => {
+  await sandbox.writeFiles([
+    { path: "hello1.txt", stream: Buffer.from("Hello 1") },
+    { path: "hello2.txt", stream: Buffer.from("Hello 2") },
+  ]);
+
+  const content1 = await sandbox.readFile({ path: "hello1.txt" });
+  const content2 = await sandbox.readFile({ path: "hello2.txt" });
+  expect((await consumeReadable(content1!)).toString()).toBe("Hello 1");
+  expect((await consumeReadable(content2!)).toString()).toBe("Hello 2");
+});

package/src/sandbox.ts

@@ -1,7 +1,8 @@
-import { 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 {
@@ -15,7 +16,20 @@ export interface CreateSandboxParams {
    * - `revision`: Clones and checks out a specific commit, branch, or tag
    */
   source?:
-    | { type: "git"; url: string; depth?: number; revision?: string }
+    | {
+        type: "git";
+        url: string;
+        depth?: number;
+        revision?: string;
+      }
+    | {
+        type: "git";
+        url: string;
+        username: string;
+        password: string;
+        depth?: number;
+        revision?: string;
+      }
     | { type: "tarball"; url: string };
   /**
    * Array of port numbers to expose from the sandbox.
@@ -42,10 +56,6 @@ export interface CreateSandboxParams {
 
 /** @inline */
 interface GetSandboxParams {
-  /**
-   * Port-to-subdomain route mappings.
-   */
-  routes: Array<{ subdomain: string; port: number }>;
   /**
    * Unique identifier of the sandbox.
    */
@@ -97,12 +107,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.
@@ -130,7 +147,7 @@ export class Sandbox {
 
     return new Sandbox({
       client,
-      sandboxId: sandbox.json.sandboxId,
+      sandbox: sandbox.json.sandbox,
       routes: sandbox.json.routes,
     });
   }
@@ -150,10 +167,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,
     });
   }
 
@@ -167,15 +188,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;
   }
 
   /**
@@ -184,11 +205,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,
     });
   }
 
@@ -237,7 +263,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,
@@ -246,8 +272,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) {
@@ -272,11 +298,25 @@ export class Sandbox {
    */
   async mkDir(path: string): Promise<void> {
     await this.client.mkDir({
-      sandboxId: this.sandboxId,
+      sandboxId: this.sandbox.id,
       path: path,
     });
   }
 
+  /**
+   * Read a file from the filesystem of this sandbox.
+   *
+   * @param file - File to read, with path and optional cwd
+   * @returns A promise that resolves to a ReadableStream containing the file contents
+   */
+  async readFile(file: { path: string; cwd?: string }) {
+    return this.client.readFile({
+      sandboxId: this.sandbox.id,
+      path: file.path,
+      cwd: file.cwd,
+    });
+  }
+
   /**
    * Write files to the filesystem of this sandbox.
    *
@@ -285,7 +325,7 @@ export class Sandbox {
    */
   async writeFiles(files: { path: string; stream: Buffer }[]) {
     return this.client.writeFiles({
-      sandboxId: this.sandboxId,
+      sandboxId: this.sandbox.id,
       files: files,
     });
   }
@@ -313,7 +353,7 @@ export class Sandbox {
    */
   async stop() {
     await this.client.stopSandbox({
-      sandboxId: this.sandboxId,
+      sandboxId: this.sandbox.id,
     });
   }
 }

package/src/utils/consume-readable.ts

@@ -0,0 +1,12 @@
+/**
+ * Consumes a readable entirely concatenating all content in a single Buffer
+ * @param readable A Readable stream
+ */
+export function consumeReadable(readable: NodeJS.ReadableStream) {
+  return new Promise<Buffer>((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    readable.on("error", (err) => reject(err));
+    readable.on("data", (chunk) => chunks.push(chunk));
+    readable.on("end", () => resolve(Buffer.concat(chunks)));
+  });
+}

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.8";
+export const VERSION = "0.0.10";