@vercel/sandbox 1.8.0 → 2.0.0-beta.0

package/dist/sandbox.js

@@ -1,74 +1,153 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Sandbox = void 0;
-const promises_1 = require("stream/promises");
-const fs_1 = require("fs");
-const promises_2 = require("fs/promises");
-const path_1 = require("path");
 const api_client_1 = require("./api-client");
-const command_1 = require("./command");
+const api_error_1 = require("./api-client/api-error");
 const get_credentials_1 = require("./utils/get-credentials");
 const types_1 = require("./utils/types");
-const snapshot_1 = require("./snapshot");
-const consume_readable_1 = require("./utils/consume-readable");
-const convert_sandbox_1 = require("./utils/convert-sandbox");
+const session_1 = require("./session");
+const network_policy_1 = require("./utils/network-policy");
+const promises_1 = require("node:timers/promises");
+function isSandboxStoppedError(err) {
+    return err instanceof api_error_1.APIError && err.response.status === 410;
+}
+function isSandboxStoppingError(err) {
+    return (err instanceof api_error_1.APIError &&
+        err.response.status === 422 &&
+        err.json?.error?.code === "sandbox_stopping");
+}
 /**
- * A Sandbox is an isolated Linux MicroVM to run commands in.
- *
+ * A Sandbox is a persistent, isolated Linux MicroVMs to run commands in.
  * Use {@link Sandbox.create} or {@link Sandbox.get} to construct.
  * @hideconstructor
  */
 class Sandbox {
     /**
-     * Unique ID of this sandbox.
+     * The name of this sandbox.
      */
-    get sandboxId() {
-        return this.sandbox.id;
+    get name() {
+        return this.namedSandbox.name;
     }
-    get interactivePort() {
-        return this.sandbox.interactivePort ?? undefined;
+    /**
+     * Routes from ports to subdomains.
+     * @hidden
+     */
+    get routes() {
+        return this.session.routes;
     }
     /**
-     * The status of the sandbox.
+     * Whether this sandbox snapshots on shutdown.
      */
-    get status() {
-        return this.sandbox.status;
+    get snapshotOnShutdown() {
+        return this.namedSandbox.snapshotOnShutdown;
+    }
+    /**
+     * The region this sandbox runs in.
+     */
+    get region() {
+        return this.namedSandbox.region;
+    }
+    /**
+     * Number of virtual CPUs allocated.
+     */
+    get vcpus() {
+        return this.namedSandbox.vcpus;
+    }
+    /**
+     * Memory allocated in MB.
+     */
+    get memory() {
+        return this.namedSandbox.memory;
+    }
+    /** Runtime identifier (e.g. "node24", "python3.13"). */
+    get runtime() {
+        return this.namedSandbox.runtime;
     }
     /**
-     * The creation date of the sandbox.
+     * Cumulative egress bytes across all sessions.
+     */
+    get totalEgressBytes() {
+        return this.namedSandbox.totalEgressBytes;
+    }
+    /**
+     * Cumulative ingress bytes across all sessions.
+     */
+    get totalIngressBytes() {
+        return this.namedSandbox.totalIngressBytes;
+    }
+    /**
+     * Cumulative active CPU duration in milliseconds across all sessions.
+     */
+    get totalActiveCpuDurationMs() {
+        return this.namedSandbox.totalActiveCpuDurationMs;
+    }
+    /**
+     * Cumulative wall-clock duration in milliseconds across all sessions.
+     */
+    get totalDurationMs() {
+        return this.namedSandbox.totalDurationMs;
+    }
+    /**
+     * When this sandbox was last updated.
+     */
+    get updatedAt() {
+        return new Date(this.namedSandbox.updatedAt);
+    }
+    /**
+     * When this sandbox was created.
      */
     get createdAt() {
-        return new Date(this.sandbox.createdAt);
+        return new Date(this.namedSandbox.createdAt);
+    }
+    /**
+     * Interactive port.
+     */
+    get interactivePort() {
+        return this.session.interactivePort;
     }
     /**
-     * The timeout of the sandbox in milliseconds.
+     * The status of the current session.
+     */
+    get status() {
+        return this.session.status;
+    }
+    /**
+     * The default timeout of this sandbox in milliseconds.
      */
     get timeout() {
-        return this.sandbox.timeout;
+        return this.namedSandbox.timeout;
     }
     /**
-     * The network policy of the sandbox.
+     * The default network policy of this sandbox.
      */
     get networkPolicy() {
-        return this.sandbox.networkPolicy;
+        return this.namedSandbox.networkPolicy
+            ? (0, network_policy_1.fromAPINetworkPolicy)(this.namedSandbox.networkPolicy)
+            : undefined;
     }
     /**
-     * If the sandbox was created from a snapshot, the ID of that snapshot.
+     * If the session was created from a snapshot, the ID of that snapshot.
      */
     get sourceSnapshotId() {
-        return this.sandbox.sourceSnapshotId;
+        return this.session.sourceSnapshotId;
     }
     /**
-     * The amount of CPU used by the sandbox. Only reported once the VM is stopped.
+     * The current snapshot ID of this sandbox, if any.
+     */
+    get currentSnapshotId() {
+        return this.namedSandbox.currentSnapshotId;
+    }
+    /**
+     * The amount of CPU used by the session. Only reported once the VM is stopped.
      */
     get activeCpuUsageMs() {
-        return this.sandbox.activeCpuDurationMs;
+        return this.session.activeCpuUsageMs;
     }
     /**
-     * The amount of network data used by the sandbox. Only reported once the VM is stopped.
+     * The amount of network data used by the session. Only reported once the VM is stopped.
      */
     get networkTransfer() {
-        return this.sandbox.networkTransfer;
+        return this.session.networkTransfer;
     }
     /**
      * Allow to get a list of sandboxes for a team narrowed to the given params.
@@ -82,7 +161,7 @@ class Sandbox {
             token: credentials.token,
             fetch: params?.fetch,
         });
-        return client.listSandboxes({
+        return client.listNamedSandboxes({
             ...credentials,
             ...params,
         });
@@ -107,7 +186,7 @@ class Sandbox {
             fetch: params?.fetch,
         });
         const privateParams = (0, types_1.getPrivateParams)(params);
-        const sandbox = await client.createSandbox({
+        const response = await client.createSandbox({
             source: params?.source,
             projectId: credentials.projectId,
             ports: params?.ports ?? [],
@@ -117,16 +196,20 @@ class Sandbox {
             networkPolicy: params?.networkPolicy,
             env: params?.env,
             signal: params?.signal,
+            name: params?.name,
+            snapshotOnShutdown: params?.snapshotOnShutdown,
             ...privateParams,
         });
         return new DisposableSandbox({
             client,
-            sandbox: sandbox.json.sandbox,
-            routes: sandbox.json.routes,
+            session: response.json.sandbox,
+            namedSandbox: response.json.namedSandbox,
+            routes: response.json.routes,
+            projectId: credentials.projectId,
         });
     }
     /**
-     * Retrieve an existing sandbox.
+     * Retrieve an existing sandbox and resume its session.
      *
      * @param params - Get parameters and optional credentials.
      * @returns A promise resolving to the {@link Sandbox}.
@@ -138,47 +221,93 @@ class Sandbox {
             token: credentials.token,
             fetch: params.fetch,
         });
-        const privateParams = (0, types_1.getPrivateParams)(params);
-        const sandbox = await client.getSandbox({
-            sandboxId: params.sandboxId,
+        const response = await client.getNamedSandbox({
+            name: params.name,
+            projectId: credentials.projectId,
+            resume: params.resume,
             signal: params.signal,
-            ...privateParams,
         });
         return new Sandbox({
             client,
-            sandbox: sandbox.json.sandbox,
-            routes: sandbox.json.routes,
+            session: response.json.sandbox,
+            namedSandbox: response.json.namedSandbox,
+            routes: response.json.routes,
+            projectId: credentials.projectId,
         });
     }
-    constructor({ client, routes, sandbox, }) {
+    constructor({ client, routes, session, namedSandbox, projectId, }) {
         this.client = client;
-        this.routes = routes;
-        this.sandbox = (0, convert_sandbox_1.convertSandbox)(sandbox);
+        this.session = new session_1.Session({ client, routes, session });
+        this.namedSandbox = namedSandbox;
+        this.projectId = projectId;
     }
     /**
-     * Get a previously run command by its ID.
+     * Get the current session (the running VM) for this sandbox.
      *
-     * @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
+     * @returns The {@link Session} instance.
      */
-    async getCommand(cmdId, opts) {
-        const command = await this.client.getCommand({
-            sandboxId: this.sandbox.id,
-            cmdId,
-            signal: opts?.signal,
+    currentSession() {
+        return this.session;
+    }
+    /**
+     * Resume this sandbox by creating a new session via `getNamedSandbox`.
+     */
+    async resume(signal) {
+        const response = await this.client.getNamedSandbox({
+            name: this.namedSandbox.name,
+            projectId: this.projectId,
+            resume: true,
+            signal,
         });
-        return new command_1.Command({
+        this.session = new session_1.Session({
             client: this.client,
-            sandboxId: this.sandbox.id,
-            cmd: command.json.command,
+            routes: response.json.routes,
+            session: response.json.sandbox,
         });
     }
+    /**
+     * Poll until the current session reaches a terminal state, then resume.
+     */
+    async waitForStopAndResume(signal) {
+        const pollingInterval = 500;
+        let status = this.session.status;
+        while (status === "stopping" || status === "snapshotting") {
+            await (0, promises_1.setTimeout)(pollingInterval, undefined, { signal });
+            const poll = await this.client.getSandbox({
+                sandboxId: this.session.sessionId,
+                signal,
+            });
+            this.session = new session_1.Session({
+                client: this.client,
+                routes: poll.json.routes,
+                session: poll.json.sandbox,
+            });
+            status = poll.json.sandbox.status;
+        }
+        await this.resume(signal);
+    }
+    /**
+     * Execute `fn`, and if the session is stopped/stopping, resume and retry.
+     */
+    async withResume(fn, signal) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            if (isSandboxStoppedError(err)) {
+                await this.resume(signal);
+                return fn();
+            }
+            if (isSandboxStoppingError(err)) {
+                await this.waitForStopAndResume(signal);
+                return fn();
+            }
+            throw err;
+        }
+    }
     async runCommand(commandOrParams, args, opts) {
-        return typeof commandOrParams === "string"
-            ? this._runCommand({ cmd: commandOrParams, args, signal: opts?.signal })
-            : this._runCommand(commandOrParams);
+        const signal = typeof commandOrParams === "string" ? opts?.signal : commandOrParams.signal;
+        return this.withResume(() => this.session.runCommand(commandOrParams, args, opts), signal);
     }
     /**
      * Internal helper to start a command in the sandbox.
@@ -187,71 +316,8 @@ class Sandbox {
      * @returns A {@link Command} or {@link CommandFinished}, depending on `detached`.
      * @internal
      */
-    async _runCommand(params) {
-        const wait = params.detached ? false : true;
-        const getLogs = (command) => {
-            if (params.stdout || params.stderr) {
-                (async () => {
-                    try {
-                        for await (const log of command.logs({ signal: params.signal })) {
-                            if (log.stream === "stdout") {
-                                params.stdout?.write(log.data);
-                            }
-                            else if (log.stream === "stderr") {
-                                params.stderr?.write(log.data);
-                            }
-                        }
-                    }
-                    catch (err) {
-                        if (params.signal?.aborted) {
-                            return;
-                        }
-                        throw err;
-                    }
-                })();
-            }
-        };
-        if (wait) {
-            const commandStream = await this.client.runCommand({
-                sandboxId: this.sandbox.id,
-                command: params.cmd,
-                args: params.args ?? [],
-                cwd: params.cwd,
-                env: params.env ?? {},
-                sudo: params.sudo ?? false,
-                wait: true,
-                signal: params.signal,
-            });
-            const command = new command_1.Command({
-                client: this.client,
-                sandboxId: this.sandbox.id,
-                cmd: commandStream.command,
-            });
-            getLogs(command);
-            const finished = await commandStream.finished;
-            return new command_1.CommandFinished({
-                client: this.client,
-                sandboxId: this.sandbox.id,
-                cmd: finished,
-                exitCode: finished.exitCode ?? 0,
-            });
-        }
-        const commandResponse = await this.client.runCommand({
-            sandboxId: this.sandbox.id,
-            command: params.cmd,
-            args: params.args ?? [],
-            cwd: params.cwd,
-            env: params.env ?? {},
-            sudo: params.sudo ?? false,
-            signal: params.signal,
-        });
-        const command = new command_1.Command({
-            client: this.client,
-            sandboxId: this.sandbox.id,
-            cmd: commandResponse.json.command,
-        });
-        getLogs(command);
-        return command;
+    async getCommand(cmdId, opts) {
+        return this.withResume(() => this.session.getCommand(cmdId, opts), opts?.signal);
     }
     /**
      * Create a directory in the filesystem of this sandbox.
@@ -261,11 +327,7 @@ class Sandbox {
      * @param opts.signal - An AbortSignal to cancel the operation.
      */
     async mkDir(path, opts) {
-        await this.client.mkDir({
-            sandboxId: this.sandbox.id,
-            path: path,
-            signal: opts?.signal,
-        });
+        return this.withResume(() => this.session.mkDir(path, opts), opts?.signal);
     }
     /**
      * Read a file from the filesystem of this sandbox as a stream.
@@ -276,12 +338,7 @@ class Sandbox {
      * @returns A promise that resolves to a ReadableStream containing the file contents, or null if file not found
      */
     async readFile(file, opts) {
-        return this.client.readFile({
-            sandboxId: this.sandbox.id,
-            path: file.path,
-            cwd: file.cwd,
-            signal: opts?.signal,
-        });
+        return this.withResume(() => this.session.readFile(file, opts), opts?.signal);
     }
     /**
      * Read a file from the filesystem of this sandbox as a Buffer.
@@ -292,16 +349,7 @@ class Sandbox {
      * @returns A promise that resolves to the file contents as a Buffer, or null if file not found
      */
     async readFileToBuffer(file, opts) {
-        const stream = await this.client.readFile({
-            sandboxId: this.sandbox.id,
-            path: file.path,
-            cwd: file.cwd,
-            signal: opts?.signal,
-        });
-        if (stream === null) {
-            return null;
-        }
-        return (0, consume_readable_1.consumeReadable)(stream);
+        return this.withResume(() => this.session.readFileToBuffer(file, opts), opts?.signal);
     }
     /**
      * Download a file from the sandbox to the local filesystem.
@@ -314,34 +362,7 @@ class Sandbox {
      * @returns The absolute path to the written file, or null if the source file was not found
      */
     async downloadFile(src, dst, opts) {
-        if (!src?.path) {
-            throw new Error("downloadFile: source path is required");
-        }
-        if (!dst?.path) {
-            throw new Error("downloadFile: destination path is required");
-        }
-        const stream = await this.client.readFile({
-            sandboxId: this.sandbox.id,
-            path: src.path,
-            cwd: src.cwd,
-            signal: opts?.signal,
-        });
-        if (stream === null) {
-            return null;
-        }
-        try {
-            const dstPath = (0, path_1.resolve)(dst.cwd ?? "", dst.path);
-            if (opts?.mkdirRecursive) {
-                await (0, promises_2.mkdir)((0, path_1.dirname)(dstPath), { recursive: true });
-            }
-            await (0, promises_1.pipeline)(stream, (0, fs_1.createWriteStream)(dstPath), {
-                signal: opts?.signal,
-            });
-            return dstPath;
-        }
-        finally {
-            stream.destroy();
-        }
+        return this.withResume(() => this.session.downloadFile(src, dst, opts), opts?.signal);
     }
     /**
      * Write files to the filesystem of this sandbox.
@@ -354,13 +375,7 @@ class Sandbox {
      * @returns A promise that resolves when the files are written
      */
     async writeFiles(files, opts) {
-        return this.client.writeFiles({
-            sandboxId: this.sandbox.id,
-            cwd: this.sandbox.cwd,
-            extractDir: "/",
-            files: files,
-            signal: opts?.signal,
-        });
+        return this.withResume(() => this.session.writeFiles(files, opts), opts?.signal);
     }
     /**
      * Get the public domain of a port of this sandbox.
@@ -370,13 +385,7 @@ class Sandbox {
      * @throws If the port has no associated route
      */
     domain(p) {
-        const route = this.routes.find(({ port }) => port == p);
-        if (route) {
-            return `https://${route.subdomain}.vercel.run`;
-        }
-        else {
-            throw new Error(`No route for port ${p}`);
-        }
+        return this.session.domain(p);
     }
     /**
      * Stop the sandbox.
@@ -387,13 +396,7 @@ class Sandbox {
      * @returns The sandbox metadata at the time the stop was acknowledged, or after fully stopped if `blocking` is true.
      */
     async stop(opts) {
-        const response = await this.client.stopSandbox({
-            sandboxId: this.sandbox.id,
-            signal: opts?.signal,
-            blocking: opts?.blocking,
-        });
-        this.sandbox = (0, convert_sandbox_1.convertSandbox)(response.json.sandbox);
-        return this.sandbox;
+        return this.session.stop(opts);
     }
     /**
      * Update the network policy for this sandbox.
@@ -427,14 +430,7 @@ class Sandbox {
      * await sandbox.updateNetworkPolicy("deny-all");
      */
     async updateNetworkPolicy(networkPolicy, opts) {
-        const response = await this.client.updateNetworkPolicy({
-            sandboxId: this.sandbox.id,
-            networkPolicy: networkPolicy,
-            signal: opts?.signal,
-        });
-        // Update the internal sandbox metadata with the new timeout value
-        this.sandbox = (0, convert_sandbox_1.convertSandbox)(response.json.sandbox);
-        return this.sandbox.networkPolicy;
+        return this.withResume(() => this.session.updateNetworkPolicy(networkPolicy, opts), opts?.signal);
     }
     /**
      * Extend the timeout of the sandbox by the specified duration.
@@ -453,13 +449,7 @@ class Sandbox {
      * await sandbox.extendTimeout(ms('5m'));
      */
     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 = (0, convert_sandbox_1.convertSandbox)(response.json.sandbox);
+        return this.withResume(() => this.session.extendTimeout(duration, opts), opts?.signal);
     }
     /**
      * Create a snapshot from this currently running sandbox. New sandboxes can
@@ -473,15 +463,70 @@ class Sandbox {
      * @returns A promise that resolves to the Snapshot instance
      */
     async snapshot(opts) {
-        const response = await this.client.createSnapshot({
-            sandboxId: this.sandbox.id,
-            expiration: opts?.expiration,
+        return this.withResume(() => this.session.snapshot(opts), opts?.signal);
+    }
+    /**
+     * Update the named sandbox configuration. Only provided fields are modified.
+     *
+     * @param params - Fields to update.
+     * @param opts - Optional abort signal.
+     */
+    async update(params, opts) {
+        const response = await this.client.updateNamedSandbox({
+            name: this.namedSandbox.name,
+            projectId: this.projectId,
+            resources: params.resources,
+            runtime: params.runtime,
+            timeout: params.timeout,
+            networkPolicy: params.networkPolicy,
             signal: opts?.signal,
         });
-        this.sandbox = (0, convert_sandbox_1.convertSandbox)(response.json.sandbox);
-        return new snapshot_1.Snapshot({
-            client: this.client,
-            snapshot: response.json.snapshot,
+        this.namedSandbox = response.json.namedSandbox;
+    }
+    /**
+     * Delete this named sandbox.
+     *
+     * After deletion the instance becomes inert — all further API calls will
+     * throw immediately.
+     */
+    async delete(opts) {
+        await this.client.deleteNamedSandbox({
+            name: this.namedSandbox.name,
+            projectId: this.projectId,
+            preserveSnapshots: opts?.preserveSnapshots,
+            signal: opts?.signal,
+        });
+    }
+    /**
+     * List sessions (VMs) that have been created for this named sandbox.
+     *
+     * @param params - Optional pagination parameters.
+     * @returns The list of sessions and pagination metadata.
+     */
+    async listSessions(params) {
+        return this.client.listSandboxes({
+            projectId: this.projectId,
+            name: this.namedSandbox.name,
+            limit: params?.limit,
+            since: params?.since,
+            until: params?.until,
+            signal: params?.signal,
+        });
+    }
+    /**
+     * List snapshots that belong to this named sandbox.
+     *
+     * @param params - Optional pagination parameters.
+     * @returns The list of snapshots and pagination metadata.
+     */
+    async listSnapshots(params) {
+        return this.client.listSnapshots({
+            projectId: this.projectId,
+            name: this.namedSandbox.name,
+            limit: params?.limit,
+            since: params?.since,
+            until: params?.until,
+            signal: params?.signal,
         });
     }
 }