@blaxel/core 0.3.32-preview.330 → 0.3.32-preview.332

package/dist/esm-browser/common/settings.js

@@ -24,8 +24,8 @@ function missingCredentialsMessage() {
     return "No Blaxel credentials found. Set the BL_API_KEY and BL_WORKSPACE environment variables, or run `bl login`.";
 }
 // Build info - these placeholders are replaced at build time by build:replace-imports
-const BUILD_VERSION = "0.3.32-preview.330";
-const BUILD_COMMIT = "4461bded7579866abc4dcbb166189e2ed15a7ea6";
+const BUILD_VERSION = "0.3.32-preview.332";
+const BUILD_COMMIT = "eeb11112e6f23be5c60b770389ef29eda8452fb0";
 const BUILD_SENTRY_DSN = "https://fd5e60e1c9820e1eef5ccebb84a07127@o4508714045276160.ingest.us.sentry.io/4510465864564736";
 const BLAXEL_API_VERSION = "2026-09-22";
 // Bun < 1.3.11 never sends connection-level WINDOW_UPDATE: the pooled h2

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

@@ -0,0 +1,267 @@
+import { v4 as uuidv4 } from "uuid";
+import { DriveInstance } from "../drive/index.js";
+/** Most drive lookups/creations, mounts and deletions in flight at once. */
+export const MOUNT_DRIVES_CONCURRENCY = 5;
+/**
+ * Thrown when `mountDrives` could not be set up. Drives this call created
+ * under a name it generated and did not mount are deleted first; a drive
+ * created under a name you chose is never deleted, since a concurrent call may
+ * be using it. `createdDrives` names the drives this call created (or may have
+ * created, when a response was lost) that are left in place.
+ *
+ * - `sandbox` is set when the sandbox is ready: it and the mounts made so far
+ *   are kept. `driveNames` lists the drives this call looked up or created that
+ *   are left in place.
+ * - `sandbox` is undefined when the sandbox could not be created (its error is
+ *   the `cause`) and some drives created for it could not be deleted. When they
+ *   all could, the sandbox's error is thrown as is instead.
+ */
+export class SandboxDriveSetupError extends Error {
+    sandbox;
+    driveNames;
+    createdDrives;
+    constructor(sandbox, driveNames, createdDrives, cause) {
+        const detail = cause instanceof Error ? cause.message : JSON.stringify(cause);
+        const left = createdDrives.length ? `. Drives this call created (or may have created) are left in place: ${createdDrives.join(", ")}.` : "";
+        super(sandbox
+            ? `Sandbox ${sandbox.metadata.name} is ready, but mounting its drives failed: ${detail}${left}`
+            : `Sandbox creation failed: ${detail}${left}`, { cause });
+        this.sandbox = sandbox;
+        this.driveNames = driveNames;
+        this.createdDrives = createdDrives;
+        this.name = "SandboxDriveSetupError";
+    }
+}
+const cleanPath = (path = "/") => `/${path.split("/").filter(Boolean).join("/")}`;
+/** The HTTP status of an API error, if it has one. */
+function httpStatus(e) {
+    if (typeof e !== "object" || e === null)
+        return undefined;
+    const error = e;
+    for (const value of [error.response?.status, error.status, error.code]) {
+        if (typeof value === "number" && value >= 100 && value < 600)
+            return value;
+    }
+    return undefined;
+}
+const isConflict = (e) => httpStatus(e) === 409 || (typeof e === "object" && e !== null && "code" in e && e.code === "DRIVE_ALREADY_EXISTS");
+/** The server answered and refused the request, so it changed nothing. Anything else (5xx, network error, timeout) may have gone through. */
+function isRejected(e) {
+    const status = httpStatus(e);
+    return status !== undefined && status >= 400 && status < 500 && status !== 408;
+}
+export function validateMountDrives(mounts, createIfNotExist) {
+    for (const { driveName, create } of mounts) {
+        if (!driveName === !create) {
+            throw new TypeError("Each mountDrives entry needs exactly one of 'driveName' or 'create'.");
+        }
+        if (createIfNotExist && create && !create.name) {
+            throw new TypeError("With createIfNotExist, a new drive in mountDrives needs a name; otherwise every call would create another drive.");
+        }
+    }
+}
+/** Runs tasks with at most `limit` in flight; a freed slot goes straight to the next waiter. */
+function limiter(limit) {
+    let active = 0;
+    const waiting = [];
+    return async (task) => {
+        if (active >= limit)
+            await new Promise(resolve => waiting.push(resolve));
+        else
+            active++;
+        try {
+            return await task();
+        }
+        finally {
+            const next = waiting.shift();
+            if (next)
+                next();
+            else
+                active--;
+        }
+    };
+}
+/**
+ * Drives for one `SandboxInstance.create` call. Looking up or creating drives
+ * (`start`) runs alongside the sandbox creation, at most
+ * `MOUNT_DRIVES_CONCURRENCY` at a time; only mounting waits for both the sandbox
+ * and its drive (`mount`). On failure, drives this call created under a
+ * generated name and did not mount are deleted (`discard`, or `mount` when it
+ * fails); drives under a caller's name are kept and reported.
+ */
+export class SandboxDriveSetup {
+    mounts;
+    stopped = false;
+    prepared = [];
+    entries;
+    region;
+    setRegion;
+    /**
+     * `region` is the region the sandbox creation request sends, if any. New
+     * drives are created in it at once; without one they wait for the created
+     * sandbox and use its region.
+     */
+    constructor(mounts, region) {
+        this.mounts = mounts;
+        this.entries = mounts.map(() => ({}));
+        this.region = new Promise(resolve => { this.setRegion = resolve; });
+        if (region)
+            this.setRegion(region);
+    }
+    start() {
+        const limit = limiter(MOUNT_DRIVES_CONCURRENCY);
+        this.prepared = this.mounts.map(async (mount, index) => {
+            // A new drive goes in the sandbox's region, so it waits for it (without holding a slot) if it is not known yet.
+            // Lookups await too, so that entries keep their order in the queue.
+            const region = await (mount.create ? this.region : undefined);
+            return limit(async () => {
+                if (this.stopped)
+                    return undefined;
+                try {
+                    const drive = mount.create ? await this.createDrive(this.entries[index], mount.create, region) : await DriveInstance.get(mount.driveName);
+                    Object.assign(this.entries[index], { name: drive.name, exists: true });
+                    return drive;
+                }
+                catch (e) {
+                    this.stopped = true;
+                    throw e;
+                }
+            });
+        });
+        // Failures surface in mount() or discard().
+        for (const promise of this.prepared)
+            promise.catch(() => { });
+    }
+    /** Create a drive in the sandbox's region; a named one that already exists is reused. */
+    async createDrive(entry, create, region) {
+        if (!region)
+            throw new Error("The sandbox reports no region, so its drives were not created.");
+        const requested = create.region;
+        if (requested && requested !== region) {
+            throw new Error(`Drive region ${requested} does not match the sandbox region ${region}.`);
+        }
+        // Name unnamed drives here so that a create whose response is lost can still be looked up.
+        const name = create.name || `drive-${uuidv4().replace(/-/g, "").slice(0, 16)}`;
+        entry.name = name;
+        entry.generated = !create.name;
+        try {
+            const drive = await DriveInstance.create({ ...create, name, region });
+            entry.created = true;
+            return drive;
+        }
+        catch (e) {
+            if (isConflict(e)) {
+                // Only a name the caller chose can belong to an existing drive worth reusing.
+                if (!create.name)
+                    throw e;
+                return DriveInstance.get(name);
+            }
+            if (isRejected(e))
+                throw e;
+            // The create may have succeeded server-side: look the drive up by its name.
+            entry.unconfirmed = true;
+            const drive = await DriveInstance.get(name).catch(() => { throw e; });
+            entry.unconfirmed = false;
+            // A generated name is this call's own; a chosen one may be an existing drive, which is never deleted.
+            if (!create.name)
+                entry.created = true;
+            return drive;
+        }
+    }
+    /**
+     * The sandbox could not be created: stop, wait for drives in flight and delete
+     * the ones this call created under a generated name. Returns the error to
+     * throw: `cause` itself, or a `SandboxDriveSetupError` naming drives left in place.
+     */
+    async discard(cause) {
+        this.stopped = true;
+        this.setRegion(undefined);
+        await Promise.allSettled(this.prepared);
+        await this.rollback();
+        const left = this.leftCreated();
+        return left.length ? new SandboxDriveSetupError(undefined, this.leftNames(), left, cause) : cause;
+    }
+    /** Mount each drive as soon as it is ready, then check the sandbox lists the mounts as requested. */
+    async mount(sandbox) {
+        const region = sandbox.spec?.region;
+        this.setRegion(region);
+        const limit = limiter(MOUNT_DRIVES_CONCURRENCY);
+        const requests = [];
+        const results = await Promise.allSettled(this.prepared.map(async (prepared, index) => {
+            try {
+                const drive = await prepared;
+                if (!drive)
+                    return;
+                if (drive.region !== region) {
+                    throw new Error(`Drive ${drive.name} is in ${drive.region}, but the sandbox is in ${region}.`);
+                }
+                const { mountPath, drivePath = "/", readOnly = false } = this.mounts[index];
+                const request = { driveName: drive.name, mountPath, drivePath, readOnly };
+                await limit(async () => {
+                    if (this.stopped)
+                        return;
+                    requests.push(request);
+                    this.entries[index].mounted = true;
+                    await sandbox.drives.mount(request);
+                });
+            }
+            catch (e) {
+                this.stopped = true;
+                throw e;
+            }
+        }));
+        try {
+            const failed = results.find((result) => result.status === "rejected");
+            if (failed)
+                throw failed.reason;
+            // Mounting reports success even if an existing mount at that path keeps a different readOnly, so check.
+            const mounted = await sandbox.drives.list();
+            for (const request of requests) {
+                const actual = mounted.find(mount => cleanPath(mount.mountPath) === cleanPath(request.mountPath));
+                if (actual?.driveName !== request.driveName || cleanPath(actual.drivePath) !== cleanPath(request.drivePath) || (actual.readOnly ?? false) !== request.readOnly) {
+                    throw new Error(`${request.mountPath} is not mounted as requested; see sandbox.drives.list().`);
+                }
+            }
+        }
+        catch (cause) {
+            await this.rollback(sandbox);
+            throw new SandboxDriveSetupError(sandbox, this.leftNames(), this.leftCreated(), cause);
+        }
+    }
+    /**
+     * Delete the drives this call created under a generated name and did not mount.
+     * A drive under a caller's name may already be mounted by a concurrent call that
+     * reused it, so it is kept. Drives left in place are listed in `leftCreated`.
+     */
+    async rollback(sandbox) {
+        const created = this.entries.filter(entry => entry.created && entry.generated && entry.exists);
+        if (sandbox && created.some(entry => entry.mounted)) {
+            // A failed mount call may still have mounted its drive (a lost response), and a
+            // successful one may not have (the path was already mounted): ask the sandbox.
+            try {
+                const mounted = new Set((await sandbox.drives.list()).map(mount => mount.driveName));
+                for (const entry of created)
+                    entry.mounted = mounted.has(entry.name);
+            }
+            catch {
+                // Unknown: keep every drive a mount was attempted for.
+            }
+        }
+        const limit = limiter(MOUNT_DRIVES_CONCURRENCY);
+        await Promise.all(created.filter(entry => !entry.mounted).map(entry => limit(async () => {
+            try {
+                await DriveInstance.delete(entry.name);
+                entry.exists = false;
+            }
+            catch {
+                // Reported through SandboxDriveSetupError.createdDrives.
+            }
+        })));
+    }
+    leftNames() {
+        return this.entries.filter(entry => entry.exists).map(entry => entry.name);
+    }
+    leftCreated() {
+        return this.entries.filter(entry => (entry.created && entry.exists) || entry.unconfirmed).map(entry => entry.name);
+    }
+}

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

@@ -1,4 +1,5 @@
 import { createSandboxPreview, createSandboxPreviewToken, deleteSandboxPreview, deleteSandboxPreviewToken, getSandboxPreview, listSandboxPreviews, listSandboxPreviewTokens } from "../client/index.js";
+import { logger } from "../common/logger.js";
 function isShorthand(preview) {
     return !("metadata" in preview || "spec" in preview);
 }
@@ -253,7 +254,7 @@ export class SandboxPreviews {
         return data;
     }
     async waitForDeletion(previewName, timeoutMs = 10000) {
-        console.log(`Waiting for preview deletion: ${previewName}`);
+        logger.debug(`Waiting for preview deletion: ${previewName}`);
         const pollInterval = 500; // Poll every 500ms
         const startTime = Date.now();
         while (Date.now() - startTime < timeoutMs) {

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

@@ -10,6 +10,7 @@ import { SandboxFileSystem } from "./filesystem/index.js";
 import { SandboxNetwork } from "./network/index.js";
 import { SandboxPreviews } from "./preview.js";
 import { SandboxProcess } from "./process/index.js";
+import { SandboxDriveSetup, validateMountDrives } from "./mount-drives.js";
 import { SandboxSchedules } from "./schedule.js";
 import { SandboxSnapshotsResource } from "./snapshot.js";
 import { SandboxSessions } from "./session.js";
@@ -47,6 +48,7 @@ const CREATE_GATEWAY_TIMEOUT_MAX_POLL_MS = 5_000;
 // client instead of being masked by an edge 504.
 const CREATION_TIMEOUT_HEADER = "X-Blaxel-Creation-Timeout";
 export const MAX_CREATION_TIMEOUT_SECONDS = 50;
+export { SandboxDriveSetupError } from "./mount-drives.js";
 /**
  * Thrown by SandboxInstance.create / createIfNotExists when the sandbox was
  * not ready within the creation deadline. The control plane has released the
@@ -293,8 +295,31 @@ export class SandboxInstance {
         return this;
     }
     static async create(sandbox, options = {}) {
-        const { safe = false, createIfNotExist = false } = options;
-        const { timeout } = validateCreateOptions(options);
+        const { mountDrives = [], createIfNotExist = false } = options;
+        validateCreateOptions(options);
+        validateMountDrives(mountDrives, createIfNotExist);
+        const { model, requested } = SandboxInstance.toSandboxModel(sandbox);
+        if (!mountDrives.length)
+            return SandboxInstance.createSandboxInstance(model, requested, options);
+        // Drives are set up alongside the sandbox, in the region this request sends (if it
+        // sends none, the control plane picks one and new drives wait for the sandbox).
+        const drives = new SandboxDriveSetup(mountDrives, model.spec?.region);
+        drives.start();
+        let instance;
+        try {
+            instance = await SandboxInstance.createSandboxInstance(model, requested, options);
+        }
+        catch (err) {
+            throw await drives.discard(err);
+        }
+        await drives.mount(instance);
+        return instance;
+    }
+    /**
+     * The creation request body, with the SDK's defaults (image, memory, region from BL_REGION) applied,
+     * plus what the caller explicitly asked for (before defaults).
+     */
+    static toSandboxModel(sandbox) {
         // No client-side default name: when the caller omits a name we send the
         // creation without metadata.name so the server can assign one and unnamed
         // creations become eligible for warm sandbox pools (ENG-3931).
@@ -384,6 +409,11 @@ export class SandboxInstance {
         }
         sandbox.spec.runtime.image = sandbox.spec.runtime.image || defaultImage;
         sandbox.spec.runtime.memory = sandbox.spec.runtime.memory || defaultMemory;
+        return { model: sandbox, requested };
+    }
+    static async createSandboxInstance(sandbox, requested, options) {
+        const { safe = false, createIfNotExist = false } = options;
+        const { timeout } = validateCreateOptions(options);
         const edgeDomain = SandboxInstance.edgeDomainForRegion(sandbox.spec?.region);
         // Kick off warming so h2Pool.get() can join it during the API call
         if (edgeDomain && !settings.disableH2) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@blaxel/core",
-	"version": "0.3.32-preview.330",
+	"version": "0.3.32-preview.332",
 	"description": "Blaxel Core SDK for TypeScript",
 	"license": "MIT",
 	"author": "Blaxel, INC (https://blaxel.ai)",