feat(vercel-sandbox): support new Snapshot.fromSandbox method

Author: marc-vercel

.changeset/pre.json

@@ -31,6 +31,7 @@
     "open-planets-joke",
     "public-ears-heal",
     "seven-olives-mate",
+    "shiny-bikes-visit",
     "slick-colts-learn",
     "some-numbers-arrive",
     "sour-rocks-grin",

.changeset/shiny-bikes-visit.md

@@ -0,0 +1,6 @@
+---
+"@vercel/sandbox": minor
+"sandbox": minor
+---
+
+Support --sandbox-snapshot parameter in the CLI, and new Snapshot.fromSandbox(...) method

packages/sandbox/CHANGELOG.md

@@ -1,5 +1,16 @@
 # sandbox
 
+## 3.0.0-beta.18
+
+### Minor Changes
+
+- Support --sandbox-snapshot parameter in the CLI, and new Snapshot.fromSandbox(...) method
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @vercel/sandbox@2.0.0-beta.16
+
 ## 3.0.0-beta.17
 
 ### Minor Changes

packages/sandbox/docs/index.md

@@ -1,7 +1,7 @@
 ## `sandbox --help`
 
 ```
-sandbox 3.0.0-beta.17
+sandbox 3.0.0-beta.18
 
 ▲ sandbox [options] <command>
 
@@ -84,6 +84,7 @@ Options:
     --vcpus <COUNT>                        Number of vCPUs to allocate (each vCPU includes 2048 MB of memory) [optional]
     --publish-port <PORT>, -p=<PORT>       Publish sandbox port(s) to DOMAIN.vercel.run
     --snapshot, -s <snapshot_id>           Start the sandbox from a snapshot ID [optional]
+    --sandbox-snapshot <name>              Start the sandbox from another sandbox's current snapshot [optional]
     --env <key=value>, -e=<key=value>      Environment variables to set for the command
     --tag <key=value>, -t=<key=value>      Key-value tags to associate with the sandbox (e.g. --tag env=staging)
     --snapshot-expiration <DURATION|none>  Default snapshot expiration. Use "none" or 0 for no expiration. Example: 7d, 30d [optional]
@@ -138,6 +139,7 @@ Options:
     --vcpus <COUNT>                        Number of vCPUs to allocate (each vCPU includes 2048 MB of memory) [optional]
     --publish-port <PORT>, -p=<PORT>       Publish sandbox port(s) to DOMAIN.vercel.run
     --snapshot, -s <snapshot_id>           Start the sandbox from a snapshot ID [optional]
+    --sandbox-snapshot <name>              Start the sandbox from another sandbox's current snapshot [optional]
     --env <key=value>, -e=<key=value>      Default environment variables for sandbox commands
     --tag <key=value>, -t=<key=value>      Key-value tags to associate with the sandbox (e.g. --tag env=staging)
     --snapshot-expiration <DURATION|none>  Default snapshot expiration. Use "none" or 0 for no expiration. Example: 7d, 30d [optional]

packages/sandbox/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sandbox",
   "description": "Command line interface for Vercel Sandbox",
-  "version": "3.0.0-beta.17",
+  "version": "3.0.0-beta.18",
   "scripts": {
     "clean": "rm -rf node_modules dist",
     "sandbox": "ts-node ./src/sandbox.ts",

packages/sandbox/src/client.ts

@@ -21,10 +21,17 @@ export const sandboxClient: Pick<typeof Sandbox, "get" | "list" | "create"> = {
     ),
 };
 
-export const snapshotClient: Pick<typeof Snapshot, "get" | "list"> = {
+export const snapshotClient: Pick<
+  typeof Snapshot,
+  "get" | "list" | "fromSandbox"
+> = {
   list: (params) =>
     withErrorHandling(Snapshot.list({ fetch: fetchWithUserAgent, ...params })),
   get: (params) => withErrorHandling(Snapshot.get({ ...params })),
+  fromSandbox: (name, opts) =>
+    withErrorHandling(
+      Snapshot.fromSandbox(name, { fetch: fetchWithUserAgent, ...opts }),
+    ),
 };
 
 const fetchWithUserAgent: typeof globalThis.fetch = (input, init) => {

packages/sandbox/src/commands/create.ts

@@ -5,8 +5,9 @@ import { timeout } from "../args/timeout";
 import { vcpus } from "../args/vcpus";
 import chalk from "chalk";
 import { scope } from "../args/scope";
-import { sandboxClient } from "../client";
+import { sandboxClient, snapshotClient } from "../client";
 import { snapshotId } from "../args/snapshot-id";
+import { sandboxName } from "../args/sandbox-name";
 import ora from "ora";
 import * as Exec from "./exec";
 import { networkPolicyArgs } from "../args/network-policy";
@@ -59,6 +60,12 @@ export const args = {
     description: "Start the sandbox from a snapshot ID",
     type: cmd.optional(snapshotId),
   }),
+  sandboxSnapshot: cmd.option({
+    long: "sandbox-snapshot",
+    description:
+      "Start the sandbox from another sandbox's current snapshot",
+    type: cmd.optional(sandboxName),
+  }),
   connect: cmd.flag({
     long: "connect",
     description:
@@ -105,6 +112,7 @@ export const create = cmd.command({
     vcpus,
     silent,
     snapshot,
+    sandboxSnapshot,
     connect,
     envVars,
     tags,
@@ -114,6 +122,15 @@ export const create = cmd.command({
     allowedCIDRs,
     deniedCIDRs,
   }) {
+    if (snapshot && sandboxSnapshot) {
+      throw new Error(
+        [
+          `Cannot use --snapshot and --sandbox-snapshot together.`,
+          `${chalk.bold("hint:")} Pick one source for the new sandbox.`,
+        ].join("\n"),
+      );
+    }
+
     const networkPolicy = buildNetworkPolicy({
       networkPolicy: networkPolicyMode,
       allowedDomains,
@@ -124,11 +141,20 @@ export const create = cmd.command({
     const persistent = !nonPersistent
     const resources = vcpus ? { vcpus } : undefined;
     const tagsObj = Object.keys(tags).length > 0 ? tags : undefined;
+    const resolvedSnapshot =
+      snapshot ??
+      (sandboxSnapshot
+        ? await snapshotClient.fromSandbox(sandboxSnapshot, {
+            teamId: scope.team,
+            projectId: scope.project,
+            token: scope.token,
+          })
+        : undefined);
     const spinner = silent ? undefined : ora("Creating sandbox...").start();
-    const sandbox = snapshot
+    const sandbox = resolvedSnapshot
       ? await sandboxClient.create({
           name,
-          source: { type: "snapshot", snapshotId: snapshot },
+          source: { type: "snapshot", snapshotId: resolvedSnapshot },
           teamId: scope.team,
           projectId: scope.project,
           token: scope.token,

packages/vercel-sandbox/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @vercel/sandbox
 
+## 2.0.0-beta.16
+
+### Minor Changes
+
+- Support --sandbox-snapshot parameter in the CLI, and new Snapshot.fromSandbox(...) method
+
 ## 2.0.0-beta.15
 
 ### Minor Changes

packages/vercel-sandbox/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/sandbox",
-  "version": "2.0.0-beta.15",
+  "version": "2.0.0-beta.16",
   "description": "Software Development Kit for Vercel Sandbox",
   "type": "module",
   "main": "dist/index.cjs",

packages/vercel-sandbox/src/snapshot.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import { Sandbox } from "./sandbox.js";
+import { Snapshot } from "./snapshot.js";
+
+describe.skipIf(process.env.RUN_INTEGRATION_TESTS !== "1")(
+  "Snapshot.fromSandbox",
+  () => {
+    it("resolves a snapshot ID that can seed a new sandbox", async () => {
+      const baseSandbox = await Sandbox.create({ persistent: true });
+      await baseSandbox.writeFiles([
+        { path: "from-base.txt", content: Buffer.from("base content") },
+      ]);
+      await baseSandbox.stop();
+
+      const derived = await Sandbox.create({
+        source: {
+          type: "snapshot",
+          snapshotId: await Snapshot.fromSandbox(baseSandbox.name),
+        },
+      });
+
+      try {
+        expect(derived.sourceSnapshotId).toBe(baseSandbox.currentSnapshotId);
+        const content = await derived.readFileToBuffer({
+          path: "from-base.txt",
+        });
+        expect(content?.toString()).toBe("base content");
+      } finally {
+        await derived.stop();
+      }
+    });
+
+    it("throws when the sandbox has no current snapshot", async () => {
+      const baseSandbox = await Sandbox.create();
+      expect(baseSandbox.currentSnapshotId).toBeUndefined();
+
+      await expect(Snapshot.fromSandbox(baseSandbox.name)).rejects.toThrow(
+        /has no current snapshot/,
+      );
+    });
+  },
+);