@blaxel/core 0.3.31 → 0.3.32-preview.330

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.330";
+const BUILD_COMMIT = "4461bded7579866abc4dcbb166189e2ed15a7ea6";
 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/sandbox.js

@@ -5,6 +5,7 @@ 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";
@@ -299,6 +300,9 @@ export class SandboxInstance {
         // 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 +320,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 +367,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).
@@ -404,6 +413,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 +652,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.