@blaxel/core 0.3.23 → 0.3.24

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.23";
-const BUILD_COMMIT = "3f7319f88bf305c481c80932c29c7513c85b543d";
+const BUILD_VERSION = "0.3.24";
+const BUILD_COMMIT = "d3dcd1599047a3cadaacac6805f29e210e57aaad";
 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/sandbox.js

@@ -58,6 +58,62 @@ const ARCHIVE_ENTRY_MAX_WAIT_MS = 30_000;
 const CREATE_GATEWAY_TIMEOUT_MAX_WAIT_MS = 120_000;
 const CREATE_GATEWAY_TIMEOUT_BASE_POLL_MS = 1_000;
 const CREATE_GATEWAY_TIMEOUT_MAX_POLL_MS = 5_000;
+// A creation deadline the caller sets per request through an undocumented
+// header; it can only shorten the control plane's default. Capped below the
+// edge's 60s origin-read timeout so the control plane's 408 always reaches the
+// client instead of being masked by an edge 504.
+const CREATION_TIMEOUT_HEADER = "X-Blaxel-Creation-Timeout";
+export const MAX_CREATION_TIMEOUT_SECONDS = 50;
+/**
+ * Thrown by SandboxInstance.create / createIfNotExists when the sandbox was
+ * not ready within the creation deadline. The control plane has released the
+ * sandbox, so the name is free again and the creation can simply be started
+ * over. Catch it with `err instanceof SandboxCreationTimeoutError` or
+ * `isCreationTimeoutError(err)`.
+ */
+export class SandboxCreationTimeoutError extends Error {
+    sandboxName;
+    timeout;
+    code = "CREATION_TIMEOUT";
+    status = 408;
+    /** Raw error body returned by the control plane. */
+    data;
+    constructor(
+    /** Name of the sandbox that was being created, if one was requested. */
+    sandboxName, 
+    /** The `timeout` option of the call, in seconds; undefined when the control plane's default applied. */
+    timeout, data) {
+        const detail = typeof data === "object" && data !== null && typeof data.message === "string"
+            ? data.message
+            : undefined;
+        const target = sandboxName ? `Sandbox ${sandboxName}` : "Sandbox";
+        const deadline = timeout !== undefined ? ` within ${timeout}s` : " within the creation deadline";
+        super(`${target} was not ready${deadline}; the creation was cancelled.${detail ? ` ${detail}` : ""}`);
+        this.sandboxName = sandboxName;
+        this.timeout = timeout;
+        this.name = "SandboxCreationTimeoutError";
+        this.data = data;
+    }
+}
+/** True when `err` is a sandbox creation timeout (408 CREATION_TIMEOUT). */
+export function isCreationTimeoutError(err) {
+    return err instanceof SandboxCreationTimeoutError;
+}
+const isCreationTimeoutResponse = (status, e) => {
+    if (status === 408)
+        return true;
+    if (typeof e !== "object" || e === null)
+        return false;
+    return e.code === "CREATION_TIMEOUT";
+};
+function validateCreateOptions({ timeout }) {
+    if (timeout === undefined)
+        return {};
+    if (!Number.isInteger(timeout) || timeout < 1 || timeout > MAX_CREATION_TIMEOUT_SECONDS) {
+        throw new Error(`SandboxInstance.create: 'timeout' must be a whole number of seconds between 1 and ${MAX_CREATION_TIMEOUT_SECONDS}, got ${timeout}.`);
+    }
+    return { timeout };
+}
 const isSandboxNotFound = (e) => {
     if (typeof e !== "object" || e === null)
         return false;
@@ -252,7 +308,9 @@ export class SandboxInstance {
         logger.warn("⚠️  Warning: sandbox.wait() is deprecated. You don't need to wait for the sandbox to be deployed anymore.");
         return this;
     }
-    static async create(sandbox, { safe = false, createIfNotExist = false } = {}) {
+    static async create(sandbox, options = {}) {
+        const { safe = false, createIfNotExist = false } = options;
+        const { timeout } = validateCreateOptions(options);
         // 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).
@@ -334,16 +392,21 @@ export class SandboxInstance {
         if (edgeDomain && !settings.disableH2) {
             import("../common/h2pool.js").then(({ h2Pool }) => h2Pool.warm(edgeDomain)).catch(() => { });
         }
+        const headers = timeout !== undefined ? { [CREATION_TIMEOUT_HEADER]: String(timeout) } : undefined;
         const [createResult, h2Session] = await Promise.all([
             createSandbox({
                 body: sandbox,
                 query: createIfNotExist ? { createIfNotExist } : undefined,
+                headers,
             }),
             edgeDomain && !settings.disableH2 ? import("../common/h2pool.js").then(({ h2Pool }) => h2Pool.get(edgeDomain)).catch(() => null) : Promise.resolve(null),
         ]);
         let data = createResult.data;
         if (createResult.error !== undefined) {
             const name = sandbox.metadata.name;
+            if (isCreationTimeoutResponse(createResult.response.status, createResult.error)) {
+                throw new SandboxCreationTimeoutError(name, timeout, createResult.error);
+            }
             if (createResult.response.status === 504 && name) {
                 // The edge gave up on the connection but the creation is still running
                 // server-side; wait for the record instead of failing (ENG-3662).
@@ -578,7 +641,7 @@ export class SandboxInstance {
         const instance = new SandboxInstance(data);
         return SandboxInstance.attachH2Session(instance);
     }
-    static async createIfNotExists(sandbox) {
+    static async createIfNotExists(sandbox, options = {}) {
         const ATTEMPTS = 3;
         let lastStatus = "unknown";
         // The 'vanished' window (create 409s while get 404s) is driven by the same
@@ -590,7 +653,7 @@ export class SandboxInstance {
         for (let i = 0; i < ATTEMPTS; ++i) {
             const finalAttempt = i === ATTEMPTS - 1;
             try {
-                return await this.create(sandbox, { createIfNotExist: true });
+                return await this.create(sandbox, { ...options, createIfNotExist: true });
             }
             catch (e) {
                 if (typeof e === "object" && e !== null && "code" in e && (e.code === 409 || e.code === 'SANDBOX_ALREADY_EXISTS')) {