@blaxel/core 0.3.13 → 0.3.18-dev.283

package/dist/esm-browser/sandbox/sandbox.js

@@ -1,4 +1,4 @@
-import { createSandbox, createSandboxSnapshot, deleteSandbox, deleteSandboxSnapshot, forkSandbox, getSandbox, getSandboxByExternalId, listSandboxes, listSandboxSnapshots, updateSandbox } from "../client/index.js";
+import { archiveSandbox, createSandbox, createSandboxSnapshot, deleteSandbox, deleteSandboxSnapshot, forkSandbox, getSandbox, getSandboxByExternalId, listSandboxes, listSandboxSnapshots, restoreSandboxSnapshot, unarchiveSandbox, updateSandbox } from "../client/index.js";
 import { logger } from "../common/logger.js";
 import { backoffDelayMs } from "../common/transient-retry.js";
 import { createPaginatedList } from "../common/pagination.js";
@@ -31,6 +31,23 @@ const TRANSIENT_SANDBOX_STATUSES = new Set([
 ]);
 const TRANSIENT_STATUS_MAX_WAIT_MS = 30_000;
 const TRANSIENT_STATUS_POLL_MS = 500;
+// Archiving a filesystem, and restoring it, take as long as that filesystem is
+// big — minutes for a few gigabytes.
+const ARCHIVE_MAX_WAIT_MS = 1_800_000;
+const ARCHIVE_WAIT_POLL_MS = 2_000;
+// An archive is done when the sandbox is ARCHIVED; it is still under way while
+// the record holds one of these.
+const ARCHIVING_STATUSES = new Set(["ARCHIVING"]);
+// A restore is done when the sandbox is DEPLOYED again; the instance is recreated
+// before the archived filesystem is written back over its image.
+const UNARCHIVING_STATUSES = new Set(["UNARCHIVING", "DEPLOYING", "BUILDING", "UPLOADING"]);
+// The status the sandbox holds before the operation moves it, tolerated only
+// while the operation is starting: an archive that fails hands the sandbox back
+// as DEPLOYED and a restore that fails leaves it ARCHIVED, so reading the entry
+// status once the operation has begun means it is over, not still running.
+const ARCHIVE_ENTRY_STATUS = "DEPLOYED";
+const UNARCHIVE_ENTRY_STATUS = "ARCHIVED";
+const ARCHIVE_ENTRY_MAX_WAIT_MS = 30_000;
 // A create that outlives the edge's 60s origin-read timeout gets a 504 from
 // CloudFront while the control plane keeps deploying the sandbox for up to
 // 300s (ENG-3662 timeout ladder inversion). The 504 body is edge HTML with no
@@ -170,6 +187,24 @@ export class SandboxInstance {
             throwOnError: true,
         });
     }
+    /**
+     * Restore this sandbox to one of its own snapshots. The sandbox keeps its
+     * name, its URLs and its previews: the running instance is torn down and
+     * rebuilt from the snapshot, so everything written since it was taken is
+     * lost unless it was snapshotted too.
+     *
+     * The restore is asked for without waiting on the guest, the same way a fork
+     * is: connections to a sandbox still resuming are retried by the gateway.
+     *
+     * @param snapshotId - ID of the snapshot to restore this sandbox to.
+     */
+    async restore(snapshotId) {
+        const { data } = await restoreSandboxSnapshot({
+            path: { sandboxName: this.metadata.name, snapshotId },
+            throwOnError: true,
+        });
+        return data;
+    }
     /**
      * Fork this sandbox into a new sandbox or application.
      *
@@ -318,6 +353,95 @@ export class SandboxInstance {
         }
         return instance;
     }
+    /**
+     * Archive a sandbox: keep its filesystem, stop the sandbox.
+     *
+     * The filesystem changes made over the image are exported to the archive store
+     * and the sandbox is shut down; memory and running processes are lost, and the
+     * saved processes start again from their configuration when the sandbox is
+     * unarchived. The export runs in the background: this waits until the sandbox
+     * is ARCHIVED, pass `{ wait: false }` to return as soon as it is launched.
+     */
+    static async archive(sandboxName, options = {}) {
+        const { data } = await archiveSandbox({
+            path: { sandboxName },
+            throwOnError: true,
+        });
+        return SandboxInstance.waitForArchiveStatus(sandboxName, data, "ARCHIVED", ARCHIVING_STATUSES, ARCHIVE_ENTRY_STATUS, "archive", options);
+    }
+    /**
+     * Archive this sandbox: keep its filesystem, stop the sandbox.
+     *
+     * @see SandboxInstance.archive
+     */
+    async archive(options = {}) {
+        const instance = await SandboxInstance.archive(this.metadata.name, options);
+        this.refreshFrom(instance);
+        return this;
+    }
+    /**
+     * Recreate an archived sandbox from its archive.
+     *
+     * The sandbox is started again from its image, and the archived filesystem is
+     * written back over it. The sandbox answers, and its terminal is reachable, while the archived
+     * filesystem is written back over its image. This waits until the restore is
+     * done and the saved processes are running again; pass `{ wait: false }` to
+     * return while the sandbox is still UNARCHIVING.
+     */
+    static async unarchive(sandboxName, options = {}) {
+        const { data } = await unarchiveSandbox({
+            path: { sandboxName },
+            throwOnError: true,
+        });
+        return SandboxInstance.waitForArchiveStatus(sandboxName, data, "DEPLOYED", UNARCHIVING_STATUSES, UNARCHIVE_ENTRY_STATUS, "unarchive", options);
+    }
+    /**
+     * Recreate this sandbox from its archive.
+     *
+     * @see SandboxInstance.unarchive
+     */
+    async unarchive(options = {}) {
+        const instance = await SandboxInstance.unarchive(this.metadata.name, options);
+        this.refreshFrom(instance);
+        return this;
+    }
+    // The subsystems (fs, process, previews, ...) hold the configuration object
+    // this instance was built with, so a refresh writes into it rather than
+    // replacing it. Anything the read did not carry, the forced URL of a session
+    // above all, is kept.
+    refreshFrom(instance) {
+        Object.assign(this.sandbox, instance.sandbox);
+    }
+    static async waitForArchiveStatus(sandboxName, launched, target, pending, entry, action, { wait = true, maxWait = ARCHIVE_MAX_WAIT_MS, interval = ARCHIVE_WAIT_POLL_MS }) {
+        if (!wait || launched.status === target) {
+            return SandboxInstance.attachH2Session(new SandboxInstance(launched));
+        }
+        const deadline = Date.now() + maxWait;
+        // The status the sandbox is given back at is tolerated while the operation
+        // turns into a status change, but never past the wait the caller asked for.
+        const entryDeadline = Date.now() + Math.min(ARCHIVE_ENTRY_MAX_WAIT_MS, maxWait);
+        let started = false;
+        for (;;) {
+            await new Promise((resolve) => setTimeout(resolve, interval));
+            const instance = await SandboxInstance.get(sandboxName);
+            const status = instance.status;
+            if (status === target) {
+                return instance;
+            }
+            if (pending.has(status ?? "")) {
+                started = true;
+            }
+            else if (status === entry && !started && Date.now() < entryDeadline) {
+                continue;
+            }
+            if (!pending.has(status ?? "")) {
+                throw new Error(`Sandbox ${sandboxName} is ${status} while it should ${action}`);
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`Sandbox ${sandboxName} is still ${status} after waiting ${Math.round(maxWait / 1000)}s for it to ${action}`);
+            }
+        }
+    }
     static async get(sandboxName) {
         const { data } = await getSandbox({
             path: {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@blaxel/core",
-	"version": "0.3.13",
+	"version": "0.3.18-dev.283",
 	"description": "Blaxel Core SDK for TypeScript",
 	"license": "MIT",
 	"author": "Blaxel, INC (https://blaxel.ai)",