@blaxel/core 0.3.31 → 0.3.32-preview.332

package/dist/esm/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.31";
-const BUILD_COMMIT = "e08b96df13cebc750a05401ee4d824d42f37a191";
+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/sandbox/drift.js

@@ -0,0 +1,56 @@
+// The control plane masks every env value it reads back, so values can only be compared when it did not.
+const MASKED_ENV_VALUE = "****";
+// The control plane keeps the image reference as submitted: "app" and "app:latest" are the same image.
+function withTag(image) {
+    if (image.includes("@"))
+        return image;
+    return image.indexOf(":", image.lastIndexOf("/") + 1) === -1 ? `${image}:latest` : image;
+}
+function envDrift(requested, existing) {
+    const byName = new Map(existing.map((env) => [env.name, env]));
+    const missing = [];
+    const changed = [];
+    for (const env of requested) {
+        const current = byName.get(env.name);
+        if (!current)
+            missing.push(env.name ?? "");
+        else if (current.value !== undefined && current.value !== MASKED_ENV_VALUE && current.value !== env.value)
+            changed.push(env.name ?? "");
+    }
+    // Names only: env values are often secrets and never go into a log line.
+    const parts = [
+        missing.length ? `not set on the existing sandbox: ${missing.join(", ")}` : "",
+        changed.length ? `different value: ${changed.join(", ")}` : "",
+    ].filter(Boolean);
+    return parts.length ? `envs (${parts.join("; ")})` : undefined;
+}
+/**
+ * Describes how an existing sandbox differs from the configuration that was
+ * asked for, one entry per field (image, memory, region, envs). Empty when
+ * nothing differs. A field the existing sandbox does not report is not drift.
+ */
+export function describeDrift(requested, existing) {
+    const drift = [];
+    const runtime = existing.spec?.runtime;
+    if (requested.image && runtime?.image && withTag(requested.image) !== withTag(runtime.image)) {
+        drift.push(`image (requested ${requested.image}, existing ${runtime.image})`);
+    }
+    if (requested.memory !== undefined && runtime?.memory !== undefined && requested.memory !== runtime.memory) {
+        drift.push(`memory (requested ${requested.memory} MB, existing ${runtime.memory} MB)`);
+    }
+    if (requested.region && existing.spec?.region && requested.region !== existing.spec.region) {
+        drift.push(`region (requested ${requested.region}, existing ${existing.spec.region})`);
+    }
+    if (requested.envs?.length && runtime?.envs) {
+        const envs = envDrift(requested.envs, runtime.envs);
+        if (envs)
+            drift.push(envs);
+    }
+    return drift;
+}
+/** The single warning createIfNotExists logs when the sandbox it returned is not the one that was asked for. */
+export function driftWarning(name, drift) {
+    return (`SandboxInstance.createIfNotExists: sandbox ${name ? `"${name}" ` : ""}already exists, so it was returned as is and the requested configuration was not applied. ` +
+        `It differs on: ${drift.join("; ")}. ` +
+        "Delete the sandbox and create it again to apply the new configuration.");
+}

package/dist/esm/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/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/sandbox/sandbox.js

@@ -5,10 +5,12 @@ import { createPaginatedList } from "../common/pagination.js";
 import { settings } from "../common/settings.js";
 import { SandboxCodegen } from "./codegen/index.js";
 import { SandboxDrive } from "./drive/index.js";
+import { describeDrift, driftWarning } from "./drift.js";
 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";
@@ -46,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
@@ -292,13 +295,39 @@ 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).
         const defaultImage = `blaxel/base-image:latest`;
         const defaultMemory = 4096;
+        // What the caller asked for, read before the defaults below fill the gaps:
+        // createIfNotExists compares only these with the sandbox it gets back.
+        let requested = {};
         // Handle SandboxCreateConfiguration or simple dict with name/image/memory/ports/envs/volumes keys
         if (!sandbox ||
             'name' in sandbox ||
@@ -316,6 +345,7 @@ export class SandboxInstance {
             'standbyGracePeriodSeconds' in sandbox) {
             if (!sandbox)
                 sandbox = {};
+            requested = { image: sandbox.image, memory: sandbox.memory, region: sandbox.region, envs: normalizeEnvs(sandbox.envs) };
             if (!sandbox.image)
                 sandbox.image = defaultImage;
             if (!sandbox.memory)
@@ -362,6 +392,10 @@ export class SandboxInstance {
                 sandbox.spec.runtime.expires = expires.toISOString();
             }
         }
+        else {
+            const { region, runtime } = sandbox.spec ?? {};
+            requested = { image: runtime?.image, memory: runtime?.memory, region, envs: runtime?.envs };
+        }
         sandbox = sandbox;
         if (!sandbox.metadata) {
             // Leave name unset so the server assigns one (ENG-3931).
@@ -375,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) {
@@ -404,6 +443,8 @@ export class SandboxInstance {
                 throw createResult.error;
             }
         }
+        if (createIfNotExist)
+            SandboxInstance.warnOnDrift(requested, data);
         // Inject the H2 session into the config so subsystems can use it
         const config = { ...data, h2Session, h2Domain: settings.disableH2 ? null : edgeDomain };
         const instance = new SandboxInstance(config);
@@ -641,6 +682,21 @@ export class SandboxInstance {
     static async createIfNotExists(sandbox, options = {}) {
         return this.create(sandbox, { ...options, createIfNotExist: true });
     }
+    // createIfNotExists hands back the sandbox already holding the name, whatever
+    // it was created with. Say so when it is not what was asked for; this only
+    // logs and never throws or changes what is returned.
+    static warnOnDrift(requested, existing) {
+        if (!existing)
+            return;
+        try {
+            const drift = describeDrift(requested, existing);
+            if (drift.length)
+                console.warn(driftWarning(existing.metadata?.name, drift));
+        }
+        catch {
+            // Best-effort diagnostics: a failed comparison must not fail the create.
+        }
+    }
     // Poll the record after a create was cut by the edge with a 504 while the
     // control plane is still deploying it. Resolves with the sandbox once it
     // reaches DEPLOYED; throws on FAILED or once the wait budget is spent.