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

package/dist/cjs/common/settings.js

@@ -30,8 +30,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/cjs/sandbox/mount-drives.js

@@ -0,0 +1,273 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SandboxDriveSetup = exports.SandboxDriveSetupError = exports.MOUNT_DRIVES_CONCURRENCY = void 0;
+exports.validateMountDrives = validateMountDrives;
+const uuid_1 = require("uuid");
+const index_js_1 = require("../drive/index.js");
+/** Most drive lookups/creations, mounts and deletions in flight at once. */
+exports.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.
+ */
+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";
+    }
+}
+exports.SandboxDriveSetupError = 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;
+}
+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.
+ */
+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(exports.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 index_js_1.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-${(0, uuid_1.v4)().replace(/-/g, "").slice(0, 16)}`;
+        entry.name = name;
+        entry.generated = !create.name;
+        try {
+            const drive = await index_js_1.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 index_js_1.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 index_js_1.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(exports.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(exports.MOUNT_DRIVES_CONCURRENCY);
+        await Promise.all(created.filter(entry => !entry.mounted).map(entry => limit(async () => {
+            try {
+                await index_js_1.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);
+    }
+}
+exports.SandboxDriveSetup = SandboxDriveSetup;

package/dist/cjs/sandbox/preview.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SandboxPreviews = exports.SandboxPreview = exports.SandboxPreviewTokens = exports.SandboxPreviewToken = void 0;
 const index_js_1 = require("../client/index.js");
+const logger_js_1 = require("../common/logger.js");
 function isShorthand(preview) {
     return !("metadata" in preview || "spec" in preview);
 }
@@ -259,7 +260,7 @@ class SandboxPreviews {
         return data;
     }
     async waitForDeletion(previewName, timeoutMs = 10000) {
-        console.log(`Waiting for preview deletion: ${previewName}`);
+        logger_js_1.logger.debug(`Waiting for preview deletion: ${previewName}`);
         const pollInterval = 500; // Poll every 500ms
         const startTime = Date.now();
         while (Date.now() - startTime < timeoutMs) {

package/dist/cjs/sandbox/sandbox.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SandboxInstance = exports.SandboxCreationTimeoutError = exports.MAX_CREATION_TIMEOUT_SECONDS = void 0;
+exports.SandboxInstance = exports.SandboxCreationTimeoutError = exports.SandboxDriveSetupError = exports.MAX_CREATION_TIMEOUT_SECONDS = void 0;
 exports.isCreationTimeoutError = isCreationTimeoutError;
 const index_js_1 = require("../client/index.js");
 const logger_js_1 = require("../common/logger.js");
@@ -47,6 +47,7 @@ const index_js_4 = require("./filesystem/index.js");
 const index_js_5 = require("./network/index.js");
 const preview_js_1 = require("./preview.js");
 const index_js_6 = require("./process/index.js");
+const mount_drives_js_1 = require("./mount-drives.js");
 const schedule_js_1 = require("./schedule.js");
 const snapshot_js_1 = require("./snapshot.js");
 const session_js_1 = require("./session.js");
@@ -84,6 +85,8 @@ 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";
 exports.MAX_CREATION_TIMEOUT_SECONDS = 50;
+var mount_drives_js_2 = require("./mount-drives.js");
+Object.defineProperty(exports, "SandboxDriveSetupError", { enumerable: true, get: function () { return mount_drives_js_2.SandboxDriveSetupError; } });
 /**
  * Thrown by SandboxInstance.create / createIfNotExists when the sandbox was
  * not ready within the creation deadline. The control plane has released the
@@ -331,8 +334,31 @@ 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);
+        (0, mount_drives_js_1.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 mount_drives_js_1.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).
@@ -422,6 +448,11 @@ 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_js_1.settings.disableH2) {

package/dist/cjs/types/sandbox/mount-drives.d.ts

@@ -0,0 +1,66 @@
+import type { SandboxInstance } from "./sandbox.js";
+import type { SandboxDriveMountConfiguration } from "./types.js";
+/** Most drive lookups/creations, mounts and deletions in flight at once. */
+export declare 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 declare class SandboxDriveSetupError extends Error {
+    readonly sandbox: SandboxInstance | undefined;
+    readonly driveNames: string[];
+    readonly createdDrives: string[];
+    constructor(sandbox: SandboxInstance | undefined, driveNames: string[], createdDrives: string[], cause: unknown);
+}
+export declare function validateMountDrives(mounts: SandboxDriveMountConfiguration[], createIfNotExist: boolean): void;
+/**
+ * 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 declare class SandboxDriveSetup {
+    private mounts;
+    private stopped;
+    private prepared;
+    private entries;
+    private region;
+    private 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: SandboxDriveMountConfiguration[], region?: string);
+    start(): void;
+    /** Create a drive in the sandbox's region; a named one that already exists is reused. */
+    private createDrive;
+    /**
+     * 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.
+     */
+    discard(cause: unknown): Promise<unknown>;
+    /** Mount each drive as soon as it is ready, then check the sandbox lists the mounts as requested. */
+    mount(sandbox: SandboxInstance): Promise<void>;
+    /**
+     * 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`.
+     */
+    private rollback;
+    private leftNames;
+    private leftCreated;
+}

package/dist/cjs/types/sandbox/sandbox.d.ts

@@ -10,7 +10,7 @@ import { SandboxSchedules } from "./schedule.js";
 import { SandboxSnapshotsResource } from "./snapshot.js";
 import { SandboxSessions } from "./session.js";
 import { SandboxSystem } from "./system.js";
-import { SandboxConfiguration, SandboxCreateConfiguration, SandboxUpdateMetadata, SandboxUpdateNetwork, SessionWithToken } from "./types.js";
+import { SandboxConfiguration, SandboxCreateConfiguration, SandboxDriveMountConfiguration, SandboxUpdateMetadata, SandboxUpdateNetwork, SessionWithToken } from "./types.js";
 export type SandboxListQuery = NonNullable<ListSandboxesData["query"]>;
 export type SandboxForkOptions = {
     /** Resource type to fork into. Defaults to "sandbox". */
@@ -66,7 +66,20 @@ export type SandboxCreateOptions = {
      * control plane's default deadline applies.
      */
     timeout?: number;
+    /**
+     * Drives to mount on the sandbox. Drives are looked up or created while the
+     * sandbox is being created (a few at a time), in the region the request sends
+     * (or, without one, in the region the sandbox gets), and each is mounted as
+     * soon as the sandbox and that drive are ready. On failure, unnamed drives
+     * this call created and did not mount are deleted; named ones are kept (a
+     * concurrent call may be using them) and listed in the error. If drive setup
+     * fails the sandbox is kept and a SandboxDriveSetupError is thrown; if the
+     * sandbox cannot be created, its error is thrown (wrapped in a
+     * SandboxDriveSetupError only if a drive created for it is left in place).
+     */
+    mountDrives?: SandboxDriveMountConfiguration[];
 };
+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
@@ -188,6 +201,12 @@ export declare class SandboxInstance {
         interval?: number;
     }): Promise<this>;
     static create(sandbox?: SandboxModel | SandboxCreateConfiguration, options?: SandboxCreateOptions): Promise<SandboxInstance>;
+    /**
+     * 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).
+     */
+    private static toSandboxModel;
+    private static createSandboxInstance;
     /**
      * Archive a sandbox: keep its filesystem, stop the sandbox.
      *

package/dist/cjs/types/sandbox/types.d.ts

@@ -1,4 +1,5 @@
 import type http2 from "http2";
+import type { DriveCreateConfiguration } from "../drive/index.js";
 import { Port, Sandbox, SandboxLifecycle, VolumeAttachment, SandboxNetwork } from "../client/types.gen";
 import { PostProcessResponse, ProcessRequest } from "./client";
 export interface SessionCreateOptions {
@@ -38,6 +39,21 @@ export type SandboxUpdateMetadata = {
 export type SandboxUpdateNetwork = {
     network?: SandboxNetwork;
 };
+/**
+ * A drive to mount on the sandbox: `driveName` for a drive that already
+ * exists, `create` for a new one. New drives are created in the sandbox's region.
+ */
+export type SandboxDriveMountConfiguration = {
+    mountPath: string;
+    drivePath?: string;
+    readOnly?: boolean;
+} & ({
+    driveName: string;
+    create?: never;
+} | {
+    create: Omit<DriveCreateConfiguration, "region">;
+    driveName?: never;
+});
 export type SandboxPreviewCreateConfiguration = {
     port: number;
     /** Defaults to preview-<port> within this sandbox. */