@blaxel/core 0.3.23 → 0.3.24-preview.303

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

@@ -33,7 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SandboxInstance = void 0;
+exports.SandboxInstance = exports.SandboxCreationTimeoutError = 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");
 const transient_retry_js_1 = require("../common/transient-retry.js");
@@ -94,6 +95,63 @@ 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";
+exports.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)`.
+ */
+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;
+    }
+}
+exports.SandboxCreationTimeoutError = SandboxCreationTimeoutError;
+/** True when `err` is a sandbox creation timeout (408 CREATION_TIMEOUT). */
+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 > exports.MAX_CREATION_TIMEOUT_SECONDS) {
+        throw new Error(`SandboxInstance.create: 'timeout' must be a whole number of seconds between 1 and ${exports.MAX_CREATION_TIMEOUT_SECONDS}, got ${timeout}.`);
+    }
+    return { timeout };
+}
 const isSandboxNotFound = (e) => {
     if (typeof e !== "object" || e === null)
         return false;
@@ -288,7 +346,9 @@ class SandboxInstance {
         logger_js_1.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).
@@ -370,16 +430,21 @@ class SandboxInstance {
         if (edgeDomain && !settings_js_1.settings.disableH2) {
             Promise.resolve().then(() => __importStar(require("../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([
             (0, index_js_1.createSandbox)({
                 body: sandbox,
                 query: createIfNotExist ? { createIfNotExist } : undefined,
+                headers,
             }),
             edgeDomain && !settings_js_1.settings.disableH2 ? Promise.resolve().then(() => __importStar(require("../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).
@@ -614,7 +679,7 @@ 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
@@ -626,7 +691,7 @@ 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')) {

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

@@ -46,6 +46,45 @@ export type SandboxArchiveOptions = {
     /** Milliseconds between two reads of the sandbox. Defaults to 2 seconds. */
     interval?: number;
 };
+export declare const MAX_CREATION_TIMEOUT_SECONDS = 50;
+/** Options of SandboxInstance.create / createIfNotExists. */
+export type SandboxCreateOptions = {
+    /** Check the sandbox answers (fs.ls) and delete it if it does not. Defaults to false. */
+    safe?: boolean;
+    /** Return the existing sandbox instead of failing when the name is taken. */
+    createIfNotExist?: boolean;
+    /**
+     * Give up on the creation after this many seconds (whole number, 1 to
+     * MAX_CREATION_TIMEOUT_SECONDS). The control plane releases the sandbox
+     * and the call rejects with a SandboxCreationTimeoutError. Unset, the
+     * control plane's default deadline applies.
+     */
+    timeout?: number;
+};
+/**
+ * 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 declare class SandboxCreationTimeoutError extends Error {
+    /** Name of the sandbox that was being created, if one was requested. */
+    readonly sandboxName: string | undefined;
+    /** The `timeout` option of the call, in seconds; undefined when the control plane's default applied. */
+    readonly timeout: number | undefined;
+    readonly code = "CREATION_TIMEOUT";
+    readonly status = 408;
+    /** Raw error body returned by the control plane. */
+    readonly data: unknown;
+    constructor(
+    /** Name of the sandbox that was being created, if one was requested. */
+    sandboxName: string | undefined, 
+    /** The `timeout` option of the call, in seconds; undefined when the control plane's default applied. */
+    timeout: number | undefined, data: unknown);
+}
+/** True when `err` is a sandbox creation timeout (408 CREATION_TIMEOUT). */
+export declare function isCreationTimeoutError(err: unknown): err is SandboxCreationTimeoutError;
 export declare class SandboxInstance {
     private sandbox;
     fs: SandboxFileSystem;
@@ -142,10 +181,7 @@ export declare class SandboxInstance {
         maxWait?: number;
         interval?: number;
     }): Promise<this>;
-    static create(sandbox?: SandboxModel | SandboxCreateConfiguration, { safe, createIfNotExist }?: {
-        safe?: boolean;
-        createIfNotExist?: boolean;
-    }): Promise<SandboxInstance>;
+    static create(sandbox?: SandboxModel | SandboxCreateConfiguration, options?: SandboxCreateOptions): Promise<SandboxInstance>;
     /**
      * Archive a sandbox: keep its filesystem, stop the sandbox.
      *
@@ -224,7 +260,7 @@ export declare class SandboxInstance {
     static updateTtl(sandboxName: string, ttl: string | null): Promise<SandboxInstance>;
     static updateLifecycle(sandboxName: string, lifecycle: SandboxLifecycle | null): Promise<SandboxInstance>;
     static updateNetwork(sandboxName: string, network: SandboxUpdateNetwork): Promise<SandboxInstance>;
-    static createIfNotExists(sandbox: SandboxModel | SandboxCreateConfiguration): Promise<SandboxInstance>;
+    static createIfNotExists(sandbox: SandboxModel | SandboxCreateConfiguration, options?: Omit<SandboxCreateOptions, "createIfNotExist">): Promise<SandboxInstance>;
     private static waitAfterCreateGatewayTimeout;
     private static waitWhileSandboxDying;
     static fromSession(session: SessionWithToken): Promise<SandboxInstance>;