@blaxel/core 0.3.31-preview.328 → 0.3.32-preview.330

package/dist/cjs-browser/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.31-preview.328";
-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/cjs-browser/sandbox/drift.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeDrift = describeDrift;
+exports.driftWarning = driftWarning;
+// 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.
+ */
+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. */
+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/cjs-browser/sandbox/sandbox.js

@@ -42,6 +42,7 @@ const pagination_js_1 = require("../common/pagination.js");
 const settings_js_1 = require("../common/settings.js");
 const index_js_2 = require("./codegen/index.js");
 const index_js_3 = require("./drive/index.js");
+const drift_js_1 = require("./drift.js");
 const index_js_4 = require("./filesystem/index.js");
 const index_js_5 = require("./network/index.js");
 const preview_js_1 = require("./preview.js");
@@ -337,6 +338,9 @@ 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 ||
@@ -354,6 +358,7 @@ class SandboxInstance {
             'standbyGracePeriodSeconds' in sandbox) {
             if (!sandbox)
                 sandbox = {};
+            requested = { image: sandbox.image, memory: sandbox.memory, region: sandbox.region, envs: (0, types_js_1.normalizeEnvs)(sandbox.envs) };
             if (!sandbox.image)
                 sandbox.image = defaultImage;
             if (!sandbox.memory)
@@ -400,6 +405,10 @@ 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).
@@ -442,6 +451,8 @@ 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_js_1.settings.disableH2 ? null : edgeDomain };
         const instance = new SandboxInstance(config);
@@ -679,6 +690,21 @@ 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 = (0, drift_js_1.describeDrift)(requested, existing);
+            if (drift.length)
+                console.warn((0, drift_js_1.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.

package/dist/cjs-browser/types/sandbox/drift.d.ts

@@ -0,0 +1,30 @@
+import type { Env } from "../client/index.js";
+/** The fields of a create request that are compared with an existing sandbox. A field the caller did not set is not compared. */
+export type RequestedSandbox = {
+    image?: string;
+    memory?: number;
+    region?: string;
+    envs?: Env[];
+};
+type ExistingSandbox = {
+    metadata?: {
+        name?: string;
+    };
+    spec?: {
+        region?: string;
+        runtime?: {
+            image?: string;
+            memory?: number;
+            envs?: Env[];
+        };
+    };
+};
+/**
+ * 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 declare function describeDrift(requested: RequestedSandbox, existing: ExistingSandbox): string[];
+/** The single warning createIfNotExists logs when the sandbox it returned is not the one that was asked for. */
+export declare function driftWarning(name: string | undefined, drift: string[]): string;
+export {};

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

@@ -276,6 +276,7 @@ export declare class SandboxInstance {
      * `options` (e.g. `timeout`) are forwarded to `create`.
      */
     static createIfNotExists(sandbox: SandboxModel | SandboxCreateConfiguration, options?: Omit<SandboxCreateOptions, "createIfNotExist">): Promise<SandboxInstance>;
+    private static warnOnDrift;
     private static waitAfterCreateGatewayTimeout;
     static fromSession(session: SessionWithToken): Promise<SandboxInstance>;
 }