@vercel/sandbox 0.0.15 → 0.0.17

package/dist/command.js

@@ -5,8 +5,11 @@ const resolveSignal_1 = require("./utils/resolveSignal");
 /**
  * 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}.
+ * For detached commands, you can {@link wait} to get a {@link CommandFinished} instance
+ * with the populated exit code. For non-detached commands, {@link Sandbox.runCommand}
+ * automatically waits and returns a {@link CommandFinished} instance.
+ *
+ * You can iterate over command output with {@link logs}.
  *
  * @see {@link Sandbox.runCommand} to start a command.
  *
@@ -64,9 +67,14 @@ class Command {
     /**
      * Wait for a command to exit and populate its exit code.
      *
+     * This method is useful for detached commands where you need to wait
+     * for completion. For non-detached commands, {@link Sandbox.runCommand}
+     * automatically waits and returns a {@link CommandFinished} instance.
+     *
      * ```
-     * await cmd.wait()
-     * if (cmd.exitCode != 0) {
+     * const detachedCmd = await sandbox.runCommand({ cmd: 'sleep', args: ['5'], detached: true });
+     * const result = await detachedCmd.wait();
+     * if (result.exitCode !== 0) {
      *   console.error("Something went wrong...")
      * }
      * ```
@@ -145,7 +153,9 @@ exports.Command = Command;
 /**
  * A command that has finished executing.
  *
- * Contains the exit code of the command.
+ * The exit code is immediately available and populated upon creation.
+ * Unlike {@link Command}, you don't need to call wait() - the command
+ * has already completed execution.
  *
  * @hideconstructor
  */
@@ -161,5 +171,16 @@ class CommandFinished extends Command {
         super({ ...params });
         this.exitCode = params.exitCode;
     }
+    /**
+     * The wait method is not needed for CommandFinished instances since
+     * the command has already completed and exitCode is populated.
+     *
+     * @deprecated This method is redundant for CommandFinished instances.
+     * The exitCode is already available.
+     * @returns This CommandFinished instance.
+     */
+    async wait() {
+        return this;
+    }
 }
 exports.CommandFinished = CommandFinished;

package/dist/sandbox.d.ts

@@ -1,4 +1,4 @@
-import type { SandboxData, SandboxRouteData } from "./api-client";
+import type { SandboxMetaData, SandboxRouteData } from "./api-client";
 import type { Writable } from "stream";
 import { APIClient } from "./api-client";
 import { Command, type CommandFinished } from "./command";
@@ -31,7 +31,8 @@ export interface CreateSandboxParams {
         url: string;
     };
     /**
-     * Array of port numbers to expose from the sandbox.
+     * Array of port numbers to expose from the sandbox. Sandboxes can
+     * expose up to 4 ports.
      */
     ports?: number[];
     /**
@@ -113,7 +114,11 @@ export declare class Sandbox {
      */
     get sandboxId(): string;
     /**
-     * Data about this sandbox.
+     * The status of the sandbox.
+     */
+    get status(): SandboxMetaData["status"];
+    /**
+     * Internal metadata about this sandbox.
      */
     private readonly sandbox;
     /**
@@ -140,7 +145,7 @@ export declare class Sandbox {
     constructor({ client, routes, sandbox, }: {
         client: APIClient;
         routes: SandboxRouteData[];
-        sandbox: SandboxData;
+        sandbox: SandboxMetaData;
     });
     /**
      * Get a previously run command by its ID.
@@ -180,7 +185,7 @@ export declare class Sandbox {
      * @returns A {@link Command} or {@link CommandFinished}, depending on `detached`.
      * @internal
      */
-    _runCommand(params: RunCommandParams): Promise<CommandFinished | Command>;
+    _runCommand(params: RunCommandParams): Promise<Command | CommandFinished>;
     /**
      * Create a directory in the filesystem of this sandbox.
      *
@@ -199,6 +204,8 @@ export declare class Sandbox {
     }): Promise<NodeJS.ReadableStream | null>;
     /**
      * Write files to the filesystem of this sandbox.
+     * Defaults to writing to /vercel/sandbox unless an absolute path is specified.
+     * Writes files using the `vercel-sandbox` user.
      *
      * @param files - Array of files with path and stream/buffer contents
      * @returns A promise that resolves when the files are written

package/dist/sandbox.js

@@ -17,6 +17,12 @@ class Sandbox {
     get sandboxId() {
         return this.sandbox.id;
     }
+    /**
+     * The status of the sandbox.
+     */
+    get status() {
+        return this.sandbox.status;
+    }
     /**
      * Create a new sandbox.
      *
@@ -159,6 +165,8 @@ class Sandbox {
     }
     /**
      * Write files to the filesystem of this sandbox.
+     * Defaults to writing to /vercel/sandbox unless an absolute path is specified.
+     * Writes files using the `vercel-sandbox` user.
      *
      * @param files - Array of files with path and stream/buffer contents
      * @returns A promise that resolves when the files are written
@@ -166,6 +174,8 @@ class Sandbox {
     async writeFiles(files) {
         return this.client.writeFiles({
             sandboxId: this.sandbox.id,
+            cwd: this.sandbox.cwd,
+            extractDir: "/",
             files: files,
         });
     }

package/dist/utils/normalizePath.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Normalize a path and make it relative to `params.extractDir` for inclusion
+ * in our tar archives.
+ *
+ * Relative paths are first resolved to `params.cwd`.
+ * Absolute paths are normalized and resolved relative to `params.extractDir`.
+ *
+ * In addition, paths are normalized so consecutive slashes are removed and
+ * stuff like `../..` is resolved appropriately.
+ *
+ * This function always returns a path relative to `params.extractDir`.
+ */
+export declare function normalizePath(params: {
+    filePath: string;
+    cwd: string;
+    extractDir: string;
+}): string;

package/dist/utils/normalizePath.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePath = normalizePath;
+const path_1 = __importDefault(require("path"));
+/**
+ * Normalize a path and make it relative to `params.extractDir` for inclusion
+ * in our tar archives.
+ *
+ * Relative paths are first resolved to `params.cwd`.
+ * Absolute paths are normalized and resolved relative to `params.extractDir`.
+ *
+ * In addition, paths are normalized so consecutive slashes are removed and
+ * stuff like `../..` is resolved appropriately.
+ *
+ * This function always returns a path relative to `params.extractDir`.
+ */
+function normalizePath(params) {
+    if (!path_1.default.posix.isAbsolute(params.cwd)) {
+        throw new Error("cwd dir must be absolute");
+    }
+    if (!path_1.default.posix.isAbsolute(params.extractDir)) {
+        throw new Error("extractDir must be absolute");
+    }
+    const basePath = path_1.default.posix.isAbsolute(params.filePath)
+        ? path_1.default.posix.normalize(params.filePath)
+        : path_1.default.posix.join(params.cwd, params.filePath);
+    return path_1.default.posix.relative(params.extractDir, basePath);
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.0.15";
+export declare const VERSION = "0.0.17";

package/dist/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // Autogenerated by inject-version.ts
-exports.VERSION = "0.0.15";
+exports.VERSION = "0.0.17";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/sandbox",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,10 +11,8 @@
   "dependencies": {
     "@vercel/oidc": "^2.0.0",
     "async-retry": "1.3.3",
-    "form-data": "3.0.0",
     "jsonlines": "0.1.1",
     "ms": "2.1.3",
-    "node-fetch": "2.6.11",
     "tar-stream": "3.1.7",
     "zod": "3.24.4"
   },
@@ -23,7 +21,6 @@
     "@types/jsonlines": "0.1.5",
     "@types/ms": "2.1.0",
     "@types/node": "22.15.12",
-    "@types/node-fetch": "2.6.12",
     "@types/tar-stream": "3.1.4",
     "dotenv": "16.5.0",
     "typedoc": "0.28.5",

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

@@ -19,6 +19,8 @@ import { consumeReadable } from "../utils/consume-readable";
 import { z } from "zod";
 import jsonlines from "jsonlines";
 import os from "os";
+import { Readable } from "stream";
+import { normalizePath } from "../utils/normalizePath";
 
 export class APIClient extends BaseClient {
   private teamId: string;
@@ -149,13 +151,16 @@ export class APIClient extends BaseClient {
     );
   }
 
-  getFileWriter(params: { sandboxId: string }) {
+  getFileWriter(params: { sandboxId: string; extractDir: string }) {
     const writer = new FileWriter();
     return {
       response: (async () => {
         return this.request(`/v1/sandboxes/${params.sandboxId}/fs/write`, {
           method: "POST",
-          headers: { "content-type": "application/gzip" },
+          headers: {
+            "content-type": "application/gzip",
+            "x-cwd": params.extractDir,
+          },
           body: await consumeReadable(writer.readable),
         });
       })(),
@@ -165,14 +170,24 @@ export class APIClient extends BaseClient {
 
   async writeFiles(params: {
     sandboxId: string;
+    cwd: string;
     files: { path: string; content: Buffer }[];
+    extractDir: string;
   }) {
     const { writer, response } = this.getFileWriter({
       sandboxId: params.sandboxId,
+      extractDir: params.extractDir,
     });
 
     for (const file of params.files) {
-      await writer.addFile({ name: file.path, content: file.content });
+      await writer.addFile({
+        name: normalizePath({
+          filePath: file.path,
+          extractDir: params.extractDir,
+          cwd: params.cwd,
+        }),
+        content: file.content,
+      });
     }
 
     writer.end();
@@ -196,7 +211,11 @@ export class APIClient extends BaseClient {
       return null;
     }
 
-    return response.body;
+    if (response.body === null) {
+      return null;
+    }
+
+    return Readable.fromWeb(response.body);
   }
 
   async killCommand(params: {
@@ -228,7 +247,15 @@ export class APIClient extends BaseClient {
       });
     }
 
-    for await (const chunk of response.body.pipe(jsonlines.parse())) {
+    if (response.body === null) {
+      throw new APIError(response, {
+        message: "No response body",
+      });
+    }
+
+    for await (const chunk of Readable.fromWeb(response.body).pipe(
+      jsonlines.parse(),
+    )) {
       yield LogLine.parse(chunk);
     }
   }

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

@@ -1,5 +1,3 @@
-import type { Response } from "node-fetch";
-
 interface Options<ErrorData> {
   message?: string;
   json?: ErrorData;

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

@@ -3,7 +3,6 @@ import { APIError } from "./api-error";
 import { ZodType } from "zod";
 import { array } from "../utils/array";
 import { withRetry, type RequestOptions } from "./with-retry";
-import nodeFetch, { type Response, type RequestInit } from "node-fetch";
 
 export interface RequestParams extends RequestInit {
   headers?: Record<string, string>;
@@ -25,7 +24,7 @@ export class BaseClient {
   private host: string;
 
   constructor(params: { debug?: boolean; host: string; token?: string }) {
-    this.fetch = withRetry(nodeFetch);
+    this.fetch = withRetry(globalThis.fetch);
     this.host = params.host;
     this.debug = params.debug ?? process.env.DEBUG_FETCH === "true";
     this.token = params.token;

package/src/api-client/validators.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 
-export type SandboxData = z.infer<typeof Sandbox>;
+export type SandboxMetaData = z.infer<typeof Sandbox>;
 
 export const Sandbox = z.object({
   id: z.string(),
@@ -16,6 +16,7 @@ export const Sandbox = z.object({
   stoppedAt: z.number().optional(),
   duration: z.number().optional(),
   createdAt: z.number(),
+  cwd: z.string(),
   updatedAt: z.number(),
 });
 

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

@@ -1,4 +1,3 @@
-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";

package/src/command.ts

@@ -4,8 +4,11 @@ import { Signal, resolveSignal } from "./utils/resolveSignal";
 /**
  * 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}.
+ * For detached commands, you can {@link wait} to get a {@link CommandFinished} instance
+ * with the populated exit code. For non-detached commands, {@link Sandbox.runCommand}
+ * automatically waits and returns a {@link CommandFinished} instance.
+ *
+ * You can iterate over command output with {@link logs}.
  *
  * @see {@link Sandbox.runCommand} to start a command.
  *
@@ -94,9 +97,14 @@ export class Command {
   /**
    * Wait for a command to exit and populate its exit code.
    *
+   * This method is useful for detached commands where you need to wait
+   * for completion. For non-detached commands, {@link Sandbox.runCommand}
+   * automatically waits and returns a {@link CommandFinished} instance.
+   *
    * ```
-   * await cmd.wait()
-   * if (cmd.exitCode != 0) {
+   * const detachedCmd = await sandbox.runCommand({ cmd: 'sleep', args: ['5'], detached: true });
+   * const result = await detachedCmd.wait();
+   * if (result.exitCode !== 0) {
    *   console.error("Something went wrong...")
    * }
    * ```
@@ -180,14 +188,16 @@ export class Command {
 /**
  * A command that has finished executing.
  *
- * Contains the exit code of the command.
+ * The exit code is immediately available and populated upon creation.
+ * Unlike {@link Command}, you don't need to call wait() - the command
+ * has already completed execution.
  *
  * @hideconstructor
  */
 export class CommandFinished extends Command {
   /**
-   * The exit code of the command, if available. This is set after
-   * {@link wait} has returned.
+   * The exit code of the command. This is always populated for
+   * CommandFinished instances.
    */
   public exitCode: number;
 
@@ -207,4 +217,16 @@ export class CommandFinished extends Command {
     super({ ...params });
     this.exitCode = params.exitCode;
   }
+
+  /**
+   * The wait method is not needed for CommandFinished instances since
+   * the command has already completed and exitCode is populated.
+   *
+   * @deprecated This method is redundant for CommandFinished instances.
+   * The exitCode is already available.
+   * @returns This CommandFinished instance.
+   */
+  async wait(): Promise<CommandFinished> {
+    return this;
+  }
 }

package/src/sandbox.test.ts

@@ -2,10 +2,11 @@ import { it, beforeEach, afterEach, expect } from "vitest";
 import { consumeReadable } from "./utils/consume-readable";
 import { Sandbox } from "./sandbox";
 
+const PORTS = [3000, 4000];
 let sandbox: Sandbox;
 
 beforeEach(async () => {
-  sandbox = await Sandbox.create();
+  sandbox = await Sandbox.create({ ports: PORTS });
 });
 
 afterEach(async () => {
@@ -23,3 +24,43 @@ it("allows to write files and then read them", async () => {
   expect((await consumeReadable(content1!)).toString()).toBe("Hello 1");
   expect((await consumeReadable(content2!)).toString()).toBe("Hello 2");
 });
+
+it("verifies port forwarding works correctly", async () => {
+  const serverScript = `
+const http = require('http');
+const ports = process.argv.slice(2);
+
+for (const port of ports) {
+  const server = http.createServer((req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/plain' });
+    res.end(\`hello port \${port}\`);
+  });
+
+  server.listen(port, () => {
+    console.log(\`Server running on port \${port}\`);
+  });
+}
+`;
+
+  await sandbox.writeFiles([
+    { path: "server.js", content: Buffer.from(serverScript) },
+  ]);
+
+  const server = await sandbox.runCommand({
+    cmd: "node",
+    args: ["server.js", ...PORTS.map(String)],
+    detached: true,
+    stdout: process.stdout,
+    stderr: process.stderr,
+  });
+
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+
+  for (const port of PORTS) {
+    const response = await fetch(sandbox.domain(port));
+    const text = await response.text();
+    expect(text).toBe(`hello port ${port}`);
+  }
+
+  await server.kill();
+});

package/src/sandbox.ts

@@ -1,4 +1,4 @@
-import type { SandboxData, SandboxRouteData } from "./api-client";
+import type { SandboxMetaData, SandboxRouteData } from "./api-client";
 import type { Writable } from "stream";
 import { APIClient } from "./api-client";
 import { Command, type CommandFinished } from "./command";
@@ -32,7 +32,8 @@ export interface CreateSandboxParams {
       }
     | { type: "tarball"; url: string };
   /**
-   * Array of port numbers to expose from the sandbox.
+   * Array of port numbers to expose from the sandbox. Sandboxes can
+   * expose up to 4 ports.
    */
   ports?: number[];
   /**
@@ -121,9 +122,16 @@ export class Sandbox {
   }
 
   /**
-   * Data about this sandbox.
+   * The status of the sandbox.
    */
-  private readonly sandbox: SandboxData;
+  public get status(): SandboxMetaData["status"] {
+    return this.sandbox.status;
+  }
+
+  /**
+   * Internal metadata about this sandbox.
+   */
+  private readonly sandbox: SandboxMetaData;
 
   /**
    * Create a new sandbox.
@@ -196,7 +204,7 @@ export class Sandbox {
   }: {
     client: APIClient;
     routes: SandboxRouteData[];
-    sandbox: SandboxData;
+    sandbox: SandboxMetaData;
   }) {
     this.client = client;
     this.routes = routes;
@@ -324,6 +332,8 @@ export class Sandbox {
 
   /**
    * Write files to the filesystem of this sandbox.
+   * Defaults to writing to /vercel/sandbox unless an absolute path is specified.
+   * Writes files using the `vercel-sandbox` user.
    *
    * @param files - Array of files with path and stream/buffer contents
    * @returns A promise that resolves when the files are written
@@ -331,6 +341,8 @@ export class Sandbox {
   async writeFiles(files: { path: string; content: Buffer }[]) {
     return this.client.writeFiles({
       sandboxId: this.sandbox.id,
+      cwd: this.sandbox.cwd,
+      extractDir: "/",
       files: files,
     });
   }

package/src/utils/normalizePath.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from "vitest";
+import { normalizePath } from "./normalizePath";
+
+describe("normalizePath", () => {
+  it("handles base cases", () => {
+    expect(
+      normalizePath({
+        filePath: "foo.txt",
+        cwd: "/vercel/sandbox",
+        extractDir: "/",
+      }),
+    ).toBe("vercel/sandbox/foo.txt");
+    expect(
+      normalizePath({
+        filePath: "foo/bar/baz.txt",
+        cwd: "/vercel/sandbox",
+        extractDir: "/",
+      }),
+    ).toBe("vercel/sandbox/foo/bar/baz.txt");
+    expect(
+      normalizePath({ filePath: "bar.txt", cwd: "/", extractDir: "/" }),
+    ).toBe("bar.txt");
+    expect(
+      normalizePath({
+        filePath: "/some/other/dir/foo.txt",
+        cwd: "/bar",
+        extractDir: "/",
+      }),
+    ).toBe("some/other/dir/foo.txt");
+  });
+
+  it("handles base cases (extract dir)", () => {
+    expect(
+      normalizePath({
+        filePath: "foo.txt",
+        cwd: "/vercel/sandbox",
+        extractDir: "/vercel",
+      }),
+    ).toBe("sandbox/foo.txt");
+    expect(
+      normalizePath({
+        filePath: "foo/bar/baz.txt",
+        cwd: "/vercel/sandbox",
+        extractDir: "/vercel",
+      }),
+    ).toBe("sandbox/foo/bar/baz.txt");
+
+    // TODO: Should this be allowed?
+    expect(
+      normalizePath({ filePath: "bar.txt", cwd: "/", extractDir: "/vercel" }),
+    ).toBe("../bar.txt");
+  });
+
+  it("handles normalization", () => {
+    expect(
+      normalizePath({
+        filePath: "/resolves/../this/stuff/foo.txt",
+        cwd: "/bar",
+        extractDir: "/",
+      }),
+    ).toBe("this/stuff/foo.txt");
+    expect(
+      normalizePath({
+        filePath: "/handles//extra-slashes",
+        cwd: "/",
+        extractDir: "/",
+      }),
+    ).toBe("handles/extra-slashes");
+  });
+
+  it("resolves relative paths", () => {
+    expect(
+      normalizePath({
+        filePath: "/../../../foo.txt",
+        cwd: "/",
+        extractDir: "/",
+      }),
+    ).toBe("foo.txt");
+    expect(
+      normalizePath({
+        filePath: "../../../../foo.txt",
+        cwd: "/vercel/sandbox",
+        extractDir: "/",
+      }),
+    ).toBe("foo.txt");
+    expect(
+      normalizePath({
+        filePath: "../foo.txt",
+        cwd: "/vercel/sandbox",
+        extractDir: "/",
+      }),
+    ).toBe("vercel/foo.txt");
+  });
+
+  it("validates the cwd", () => {
+    expect(() => {
+      normalizePath({
+        filePath: "doesn't matter",
+        cwd: "relative/root",
+        extractDir: "/",
+      });
+    }).toThrow("cwd dir must be absolute");
+  });
+
+  it("validates the cwd", () => {
+    expect(() => {
+      normalizePath({
+        filePath: "doesn't matter",
+        cwd: "/",
+        extractDir: "some/relative/path",
+      });
+    }).toThrow("extractDir must be absolute");
+  });
+});