@vercel/sandbox 0.0.21 → 0.0.23

package/dist/sandbox.js

@@ -24,6 +24,12 @@ class Sandbox {
     get status() {
         return this.sandbox.status;
     }
+    /**
+     * The timeout of the sandbox in milliseconds.
+     */
+    get timeout() {
+        return this.sandbox.timeout;
+    }
     /**
      * Allow to get a list of sandboxes for a team narrowed to the given params.
      * It returns both the sandboxes and the pagination metadata to allow getting
@@ -35,7 +41,10 @@ class Sandbox {
             teamId: credentials.teamId,
             token: credentials.token,
         });
-        return client.listSandboxes(params);
+        return client.listSandboxes({
+            ...params,
+            signal: params.signal,
+        });
     }
     /**
      * Create a new sandbox.
@@ -57,6 +66,7 @@ class Sandbox {
             timeout: params?.timeout,
             resources: params?.resources,
             runtime: params?.runtime,
+            signal: params?.signal,
             ...privateParams,
         });
         return new Sandbox({
@@ -79,6 +89,7 @@ class Sandbox {
         });
         const sandbox = await client.getSandbox({
             sandboxId: params.sandboxId,
+            signal: params.signal,
         });
         return new Sandbox({
             client,
@@ -102,12 +113,15 @@ class Sandbox {
      * Get a previously run command by its ID.
      *
      * @param cmdId - ID of the command to retrieve
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel the operation.
      * @returns A {@link Command} instance representing the command
      */
-    async getCommand(cmdId) {
+    async getCommand(cmdId, opts) {
         const command = await this.client.getCommand({
             sandboxId: this.sandbox.id,
             cmdId,
+            signal: opts?.signal,
         });
         return new command_1.Command({
             client: this.client,
@@ -115,9 +129,9 @@ class Sandbox {
             cmd: command.json.command,
         });
     }
-    async runCommand(commandOrParams, args) {
+    async runCommand(commandOrParams, args, opts) {
         return typeof commandOrParams === "string"
-            ? this._runCommand({ cmd: commandOrParams, args })
+            ? this._runCommand({ cmd: commandOrParams, args, signal: opts?.signal })
             : this._runCommand(commandOrParams);
     }
     /**
@@ -135,6 +149,7 @@ class Sandbox {
             cwd: params.cwd,
             env: params.env ?? {},
             sudo: params.sudo ?? false,
+            signal: params.signal,
         });
         const command = new command_1.Command({
             client: this.client,
@@ -143,7 +158,7 @@ class Sandbox {
         });
         if (params.stdout || params.stderr) {
             (async () => {
-                for await (const log of command.logs()) {
+                for await (const log of command.logs({ signal: params.signal })) {
                     if (log.stream === "stdout") {
                         params.stdout?.write(log.data);
                     }
@@ -153,30 +168,36 @@ class Sandbox {
                 }
             })();
         }
-        return params.detached ? command : command.wait();
+        return params.detached ? command : command.wait({ signal: params.signal });
     }
     /**
      * Create a directory in the filesystem of this sandbox.
      *
      * @param path - Path of the directory to create
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel the operation.
      */
-    async mkDir(path) {
+    async mkDir(path, opts) {
         await this.client.mkDir({
             sandboxId: this.sandbox.id,
             path: path,
+            signal: opts?.signal,
         });
     }
     /**
      * Read a file from the filesystem of this sandbox.
      *
      * @param file - File to read, with path and optional cwd
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel the operation.
      * @returns A promise that resolves to a ReadableStream containing the file contents
      */
-    async readFile(file) {
+    async readFile(file, opts) {
         return this.client.readFile({
             sandboxId: this.sandbox.id,
             path: file.path,
             cwd: file.cwd,
+            signal: opts?.signal,
         });
     }
     /**
@@ -185,14 +206,17 @@ class Sandbox {
      * Writes files using the `vercel-sandbox` user.
      *
      * @param files - Array of files with path and stream/buffer contents
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel the operation.
      * @returns A promise that resolves when the files are written
      */
-    async writeFiles(files) {
+    async writeFiles(files, opts) {
         return this.client.writeFiles({
             sandboxId: this.sandbox.id,
             cwd: this.sandbox.cwd,
             extractDir: "/",
             files: files,
+            signal: opts?.signal,
         });
     }
     /**
@@ -214,12 +238,35 @@ class Sandbox {
     /**
      * Stop the sandbox.
      *
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel the operation.
      * @returns A promise that resolves when the sandbox is stopped
      */
-    async stop() {
+    async stop(opts) {
         await this.client.stopSandbox({
             sandboxId: this.sandbox.id,
+            signal: opts?.signal,
+        });
+    }
+    /**
+     * Extend the timeout of the sandbox by the specified duration.
+     *
+     * This allows you to extend the lifetime of a sandbox up until the maximum
+     * execution timeout for your plan.
+     *
+     * @param duration - The duration in milliseconds to extend the timeout by
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel the operation.
+     * @returns A promise that resolves when the timeout is extended
+     */
+    async extendTimeout(duration, opts) {
+        const response = await this.client.extendTimeout({
+            sandboxId: this.sandbox.id,
+            duration,
+            signal: opts?.signal,
         });
+        // Update the internal sandbox metadata with the new timeout value
+        this.sandbox = response.json.sandbox;
     }
 }
 exports.Sandbox = Sandbox;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.0.21";
+export declare const VERSION = "0.0.23";

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.21";
+exports.VERSION = "0.0.23";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/sandbox",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -12,6 +12,7 @@ import {
   EmptyResponse,
   LogLine,
   SandboxesResponse,
+  ExtendTimeoutResponse,
 } from "./validators";
 import { APIError } from "./api-error";
 import { FileWriter } from "./file-writer";
@@ -71,10 +72,12 @@ export class APIClient extends BaseClient {
     });
   }
 
-  async getSandbox(params: { sandboxId: string }) {
+  async getSandbox(params: { sandboxId: string; signal?: AbortSignal }) {
     return parseOrThrow(
       SandboxAndRoutesResponse,
-      await this.request(`/v1/sandboxes/${params.sandboxId}`),
+      await this.request(`/v1/sandboxes/${params.sandboxId}`, {
+        signal: params.signal,
+      }),
     );
   }
 
@@ -95,6 +98,7 @@ export class APIClient extends BaseClient {
       timeout?: number;
       resources?: { vcpus: number };
       runtime?: "node22" | "python3.13" | (string & {});
+      signal?: AbortSignal;
     }>,
   ) {
     const privateParams = getPrivateParams(params);
@@ -111,6 +115,7 @@ export class APIClient extends BaseClient {
           runtime: params.runtime,
           ...privateParams,
         }),
+        signal: params.signal,
       }),
     );
   }
@@ -122,6 +127,7 @@ export class APIClient extends BaseClient {
     args: string[];
     env: Record<string, string>;
     sudo: boolean;
+    signal?: AbortSignal;
   }) {
     return parseOrThrow(
       CommandResponse,
@@ -134,6 +140,7 @@ export class APIClient extends BaseClient {
           env: params.env,
           sudo: params.sudo,
         }),
+        signal: params.signal,
       }),
     );
   }
@@ -142,44 +149,58 @@ export class APIClient extends BaseClient {
     sandboxId: string;
     cmdId: string;
     wait: true;
+    signal?: AbortSignal;
   }): Promise<Parsed<z.infer<typeof CommandFinishedResponse>>>;
   async getCommand(params: {
     sandboxId: string;
     cmdId: string;
     wait?: boolean;
+    signal?: AbortSignal;
   }): Promise<Parsed<z.infer<typeof CommandResponse>>>;
   async getCommand(params: {
     sandboxId: string;
     cmdId: string;
     wait?: boolean;
+    signal?: AbortSignal;
   }) {
     return params.wait
       ? parseOrThrow(
           CommandFinishedResponse,
           await this.request(
             `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`,
-            { query: { wait: "true" } },
+            { signal: params.signal, query: { wait: "true" } },
           ),
         )
       : parseOrThrow(
           CommandResponse,
           await this.request(
             `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`,
+            { signal: params.signal },
           ),
         );
   }
 
-  async mkDir(params: { sandboxId: string; path: string; cwd?: string }) {
+  async mkDir(params: {
+    sandboxId: string;
+    path: string;
+    cwd?: string;
+    signal?: AbortSignal;
+  }) {
     return parseOrThrow(
       EmptyResponse,
       await this.request(`/v1/sandboxes/${params.sandboxId}/fs/mkdir`, {
         method: "POST",
         body: JSON.stringify({ path: params.path, cwd: params.cwd }),
+        signal: params.signal,
       }),
     );
   }
 
-  getFileWriter(params: { sandboxId: string; extractDir: string }) {
+  getFileWriter(params: {
+    sandboxId: string;
+    extractDir: string;
+    signal?: AbortSignal;
+  }) {
     const writer = new FileWriter();
     return {
       response: (async () => {
@@ -190,6 +211,7 @@ export class APIClient extends BaseClient {
             "x-cwd": params.extractDir,
           },
           body: await consumeReadable(writer.readable),
+          signal: params.signal,
         });
       })(),
       writer,
@@ -217,6 +239,7 @@ export class APIClient extends BaseClient {
      * @example 1540095775951
      */
     until?: number | Date;
+    signal?: AbortSignal;
   }) {
     return parseOrThrow(
       SandboxesResponse,
@@ -234,6 +257,7 @@ export class APIClient extends BaseClient {
               : params.until?.getTime(),
         },
         method: "GET",
+        signal: params.signal,
       }),
     );
   }
@@ -243,10 +267,12 @@ export class APIClient extends BaseClient {
     cwd: string;
     files: { path: string; content: Buffer }[];
     extractDir: string;
+    signal?: AbortSignal;
   }) {
     const { writer, response } = this.getFileWriter({
       sandboxId: params.sandboxId,
       extractDir: params.extractDir,
+      signal: params.signal,
     });
 
     for (const file of params.files) {
@@ -268,12 +294,14 @@ export class APIClient extends BaseClient {
     sandboxId: string;
     path: string;
     cwd?: string;
+    signal?: AbortSignal;
   }): 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 }),
+        signal: params.signal,
       },
     );
 
@@ -292,6 +320,7 @@ export class APIClient extends BaseClient {
     sandboxId: string;
     commandId: string;
     signal: number;
+    abortSignal?: AbortSignal;
   }) {
     return parseOrThrow(
       CommandResponse,
@@ -300,6 +329,7 @@ export class APIClient extends BaseClient {
         {
           method: "POST",
           body: JSON.stringify({ signal: params.signal }),
+          signal: params.abortSignal,
         },
       ),
     );
@@ -356,11 +386,28 @@ export class APIClient extends BaseClient {
 
   async stopSandbox(params: {
     sandboxId: string;
+    signal?: AbortSignal;
   }): Promise<Parsed<z.infer<typeof SandboxResponse>>> {
     const url = `/v1/sandboxes/${params.sandboxId}/stop`;
     return parseOrThrow(
       SandboxResponse,
-      await this.request(url, { method: "POST" }),
+      await this.request(url, { method: "POST", signal: params.signal }),
+    );
+  }
+
+  async extendTimeout(params: {
+    sandboxId: string;
+    duration: number;
+    signal?: AbortSignal;
+  }): Promise<Parsed<z.infer<typeof ExtendTimeoutResponse>>> {
+    const url = `/v1/sandboxes/${params.sandboxId}/extend-timeout`;
+    return parseOrThrow(
+      ExtendTimeoutResponse,
+      await this.request(url, {
+        method: "POST",
+        body: JSON.stringify({ duration: params.duration }),
+        signal: params.signal,
+      }),
     );
   }
 }

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

@@ -55,6 +55,7 @@ export class BaseClient {
         : opts?.headers,
       // @ts-expect-error Node.js' and undici's Agent have different types
       dispatcher: this.agent,
+      signal: opts?.signal,
     });
 
     if (this.debug) {

package/src/api-client/validators.ts

@@ -89,3 +89,7 @@ export const SandboxesResponse = z.object({
   sandboxes: z.array(Sandbox),
   pagination: Pagination,
 });
+
+export const ExtendTimeoutResponse = z.object({
+  sandbox: Sandbox,
+});

package/src/command.ts

@@ -112,13 +112,18 @@ export class Command {
    * }
    * ```
    *
+   * @param params - Optional parameters.
+   * @param params.signal - An AbortSignal to cancel waiting.
    * @returns A {@link CommandFinished} instance with populated exit code.
    */
-  async wait() {
+  async wait(params?: { signal?: AbortSignal }) {
+    params?.signal?.throwIfAborted();
+
     const command = await this.client.getCommand({
       sandboxId: this.sandboxId,
       cmdId: this.cmd.id,
       wait: true,
+      signal: params?.signal,
     });
 
     return new CommandFinished({
@@ -136,11 +141,16 @@ export class Command {
    * not output valid Unicode.
    *
    * @param stream - The output stream to read: "stdout", "stderr", or "both".
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel output streaming.
    * @returns The output of the specified stream(s) as a string.
    */
-  async output(stream: "stdout" | "stderr" | "both" = "both") {
+  async output(
+    stream: "stdout" | "stderr" | "both" = "both",
+    opts?: { signal?: AbortSignal },
+  ) {
     let data = "";
-    for await (const log of this.logs()) {
+    for await (const log of this.logs({ signal: opts?.signal })) {
       if (stream === "both" || log.stream === stream) {
         data += log.data;
       }
@@ -154,10 +164,12 @@ export class Command {
    * NOTE: This may throw string conversion errors if the command does
    * not output valid Unicode.
    *
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel output streaming.
    * @returns The standard output of the command.
    */
-  async stdout() {
-    return this.output("stdout");
+  async stdout(opts?: { signal?: AbortSignal }) {
+    return this.output("stdout", opts);
   }
 
   /**
@@ -166,24 +178,28 @@ export class Command {
    * NOTE: This may throw string conversion errors if the command does
    * not output valid Unicode.
    *
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel output streaming.
    * @returns The standard error output of the command.
    */
-  async stderr() {
-    return this.output("stderr");
+  async stderr(opts?: { signal?: AbortSignal }) {
+    return this.output("stderr", opts);
   }
 
   /**
    * Kill a running command in a sandbox.
    *
-   * @param params - commandId and the signal to send the running process.
-   * Defaults to SIGTERM.
+   * @param signal - The signal to send the running process. Defaults to SIGTERM.
+   * @param opts - Optional parameters.
+   * @param opts.abortSignal - An AbortSignal to cancel the kill operation.
    * @returns Promise<void>.
    */
-  async kill(signal?: Signal) {
+  async kill(signal?: Signal, opts?: { abortSignal?: AbortSignal }) {
     await this.client.killCommand({
       sandboxId: this.sandboxId,
       commandId: this.cmd.id,
       signal: resolveSignal(signal ?? "SIGTERM"),
+      abortSignal: opts?.abortSignal,
     });
   }
 }

package/src/sandbox.test.ts

@@ -1,6 +1,8 @@
 import { it, beforeEach, afterEach, expect } from "vitest";
 import { consumeReadable } from "./utils/consume-readable";
 import { Sandbox } from "./sandbox";
+import { APIError } from "./api-client/api-error";
+import ms from "ms";
 
 const PORTS = [3000, 4000];
 let sandbox: Sandbox;
@@ -64,3 +66,26 @@ for (const port of ports) {
 
   await server.kill();
 });
+
+it("allows extending the sandbox timeout", async () => {
+  const originalTimeout = sandbox.timeout;
+  const extensionDuration = ms("5m");
+
+  await sandbox.extendTimeout(extensionDuration);
+  expect(sandbox.timeout).toEqual(originalTimeout + extensionDuration);
+});
+
+it("raises an error when the timeout cannot be updated", async () => {
+  try {
+    await sandbox.extendTimeout(ms("5d"));
+    expect.fail("Expected extendTimeout to throw an error");
+  } catch (error) {
+    expect(error).toBeInstanceOf(APIError);
+    expect(error).toMatchObject({
+      response: { status: 400 },
+      json: {
+        error: { code: "sandbox_timeout_invalid" },
+      },
+    });
+  }
+});