@blaxel/core 0.3.6 → 0.3.7-preview.229

package/dist/esm/common/h2-runtime.js

@@ -0,0 +1,78 @@
+/**
+ * HTTP/2 runtime-capability detection.
+ *
+ * The SDK's pooled HTTP/2 transport relies on the runtime's HTTP/2 client
+ * managing connection-level flow control correctly. One runtime does not:
+ *
+ *   Bun < 1.3.11 never sends a connection-level WINDOW_UPDATE frame. The pooled
+ *   H2 session therefore freezes after exactly 65535 cumulative body bytes (the
+ *   default connection receive window that Bun never grows), and every request
+ *   on that session hangs until the edge resets the streams (~330s).
+ *   Fixed in Bun 1.3.11: https://bun.com/blog/bun-v1.3.11
+ *
+ * This module centralizes the version gate so the settings layer, the unit
+ * tests, and the cross-runtime environment tests all agree on ONE definition of
+ * "is this a Bun that breaks pooled H2". Keeping a single source of truth is the
+ * whole point: the bug this guards against is subtle and the parse is easy to
+ * get subtly wrong (see `stripPrerelease`).
+ */
+/** First Bun release with a working connection-level WINDOW_UPDATE. */
+export const BUN_H2_FIXED_VERSION = "1.3.11";
+/**
+ * The default HTTP/2 connection-level receive window, in bytes (2^16 - 1). This
+ * is the exact number of cumulative body bytes after which a broken-Bun pooled
+ * session freezes: the window opens to 65535 and, absent a WINDOW_UPDATE, never
+ * reopens. Node grows it (see `establishH2`'s `setLocalWindowSize`); Bun < 1.3.11
+ * does not.
+ */
+export const H2_DEFAULT_CONNECTION_WINDOW_BYTES = 65535;
+/**
+ * Parse a `major.minor.patch` version, tolerating a pre-release/build suffix
+ * (e.g. `1.3.11-canary.1`, `1.4.0+build`). Returns `null` when the input is
+ * absent or not a recognizable semver triple.
+ */
+export function parseSemver(version) {
+    if (!version)
+        return null;
+    // Strip any pre-release ("-canary.1") or build ("+abc") metadata first so a
+    // tagged build compares by its release numbers, then take the leading triple.
+    const core = version.split("-")[0].split("+")[0].trim();
+    const parts = core.split(".");
+    if (parts.length === 0)
+        return null;
+    const nums = parts.slice(0, 3).map((p) => Number(p));
+    if (nums.some((n) => !Number.isInteger(n) || n < 0))
+        return null;
+    const [maj = 0, min = 0, patch = 0] = nums;
+    return [maj, min, patch];
+}
+/**
+ * Given a Bun version string, is this a Bun whose HTTP/2 client breaks the
+ * pooled transport (Bun < 1.3.11)? A falsy/undefined version means "not Bun",
+ * which returns `false`. An unparseable version is treated as broken (`true`):
+ * we cannot prove it is safe, and forcing H2 off is the safe default.
+ */
+export function isBrokenBunVersion(version) {
+    if (!version)
+        return false;
+    const parsed = parseSemver(version);
+    if (parsed === null)
+        return true;
+    const [maj, min, patch] = parsed;
+    return maj < 1 || (maj === 1 && (min < 3 || (min === 3 && patch < 11)));
+}
+/**
+ * The running runtime's Bun version, or `undefined` when not on Bun (Node,
+ * Deno, browsers, workers). Deno also exposes `process.versions` but never sets
+ * `.bun`, so this stays `undefined` there.
+ */
+export function detectBunVersion() {
+    return globalThis.process?.versions?.bun;
+}
+/**
+ * Is the CURRENT runtime a Bun that breaks the pooled H2 transport? This is the
+ * predicate the settings layer uses to force H2 off.
+ */
+export function isBrokenBunH2Runtime() {
+    return isBrokenBunVersion(detectBunVersion());
+}

package/dist/esm/common/h2-runtime.test.js

@@ -0,0 +1,165 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { env } from "./env.js";
+import { BUN_H2_FIXED_VERSION, H2_DEFAULT_CONNECTION_WINDOW_BYTES, detectBunVersion, isBrokenBunH2Runtime, isBrokenBunVersion, parseSemver, } from "./h2-runtime.js";
+// The Bun H2 flow-control bug (never sends connection-level WINDOW_UPDATE, so a
+// pooled session freezes after 65535 cumulative body bytes) was fixed in
+// 1.3.11. Everything below < 1.3.11 must be classified "broken"; >= 1.3.11 must
+// be "fixed". A non-Bun runtime (no version) is never broken. This is the
+// single most important gate in the SDK's H2 story, so we pin it exhaustively.
+describe("parseSemver", () => {
+    it("parses a plain major.minor.patch triple", () => {
+        expect(parseSemver("1.3.11")).toEqual([1, 3, 11]);
+        expect(parseSemver("0.0.0")).toEqual([0, 0, 0]);
+        expect(parseSemver("22.14.0")).toEqual([22, 14, 0]);
+    });
+    it("tolerates missing minor/patch", () => {
+        expect(parseSemver("2")).toEqual([2, 0, 0]);
+        expect(parseSemver("1.4")).toEqual([1, 4, 0]);
+    });
+    it("strips pre-release and build metadata before comparing", () => {
+        expect(parseSemver("1.3.11-canary.1")).toEqual([1, 3, 11]);
+        expect(parseSemver("1.3.10-debug")).toEqual([1, 3, 10]);
+        expect(parseSemver("1.4.0+build.7")).toEqual([1, 4, 0]);
+        expect(parseSemver("2.0.0-alpha+exp.sha.5114f85")).toEqual([2, 0, 0]);
+    });
+    it("returns null for absent or non-numeric input", () => {
+        expect(parseSemver(undefined)).toBeNull();
+        expect(parseSemver(null)).toBeNull();
+        expect(parseSemver("")).toBeNull();
+        expect(parseSemver("latest")).toBeNull();
+        expect(parseSemver("v1.2.3")).toBeNull();
+        expect(parseSemver("1.x.0")).toBeNull();
+    });
+});
+describe("isBrokenBunVersion", () => {
+    it("treats a missing version as not-Bun (never broken)", () => {
+        expect(isBrokenBunVersion(undefined)).toBe(false);
+        expect(isBrokenBunVersion(null)).toBe(false);
+        expect(isBrokenBunVersion("")).toBe(false);
+    });
+    // The full boundary matrix. Left column = Bun version string, right = whether
+    // the pooled H2 transport is broken on it.
+    const matrix = [
+        // Ancient / pre-1.0 — all broken.
+        ["0.1.0", true],
+        ["0.8.1", true],
+        ["0.9.9", true],
+        // 1.0.x – 1.2.x — broken.
+        ["1.0.0", true],
+        ["1.1.34", true],
+        ["1.2.0", true],
+        ["1.2.21", true],
+        // 1.3.0 – 1.3.10 — the affected line, still broken.
+        ["1.3.0", true],
+        ["1.3.1", true],
+        ["1.3.9", true],
+        ["1.3.10", true],
+        // 1.3.11 — the exact fix boundary. Fixed.
+        ["1.3.11", false],
+        // Everything after — fixed.
+        ["1.3.12", false],
+        ["1.3.100", false],
+        ["1.4.0", false],
+        ["1.10.0", false],
+        ["2.0.0", false],
+        ["10.0.0", false],
+    ];
+    it.each(matrix)("Bun %s -> broken=%s", (version, expected) => {
+        expect(isBrokenBunVersion(version)).toBe(expected);
+    });
+    // Pre-release / canary builds must compare by their release numbers so a
+    // "1.3.11-canary" is treated as fixed and a "1.3.10-debug" as broken. This is
+    // the exact parse subtlety the earlier duplicated gate got wrong.
+    const prereleaseMatrix = [
+        ["1.3.10-canary.20250101", true],
+        ["1.3.11-canary.20250101", false],
+        ["1.3.11-debug", false],
+        ["1.4.0-canary", false],
+        ["1.2.99-alpha", true],
+    ];
+    it.each(prereleaseMatrix)("Bun %s (pre-release) -> broken=%s", (version, expected) => {
+        expect(isBrokenBunVersion(version)).toBe(expected);
+    });
+    it("classifies an unparseable Bun version as broken (safe default)", () => {
+        // A non-empty but unrecognizable version means we cannot prove it is safe,
+        // so we err toward disabling H2.
+        expect(isBrokenBunVersion("weird-build")).toBe(true);
+        expect(isBrokenBunVersion("nightly")).toBe(true);
+    });
+    it("agrees with the documented fix boundary constant", () => {
+        const [maj, min, patch] = parseSemver(BUN_H2_FIXED_VERSION);
+        // One patch below the fix is broken; the fix itself is not.
+        expect(isBrokenBunVersion(`${maj}.${min}.${patch - 1}`)).toBe(true);
+        expect(isBrokenBunVersion(`${maj}.${min}.${patch}`)).toBe(false);
+    });
+});
+describe("detectBunVersion / isBrokenBunH2Runtime (current runtime)", () => {
+    it("reports the running Bun version, or undefined off Bun", () => {
+        const detected = detectBunVersion();
+        const actual = globalThis.process?.versions?.bun;
+        expect(detected).toBe(actual);
+    });
+    it("runtime predicate matches the version predicate for this runtime", () => {
+        expect(isBrokenBunH2Runtime()).toBe(isBrokenBunVersion(detectBunVersion()));
+    });
+});
+describe("H2_DEFAULT_CONNECTION_WINDOW_BYTES", () => {
+    it("is 2^16 - 1 (the window a broken Bun never grows)", () => {
+        expect(H2_DEFAULT_CONNECTION_WINDOW_BYTES).toBe(65535);
+        expect(H2_DEFAULT_CONNECTION_WINDOW_BYTES).toBe(2 ** 16 - 1);
+    });
+});
+// End-to-end: the settings.disableH2 getter must honor the runtime gate. We
+// simulate different Bun versions by injecting process.versions.bun, since the
+// getter reads it live on every access.
+describe("settings.disableH2 honors the Bun version gate", () => {
+    const originalBun = globalThis.process?.versions?.bun;
+    afterEach(async () => {
+        if (globalThis.process?.versions) {
+            if (originalBun === undefined) {
+                delete globalThis.process.versions.bun;
+            }
+            else {
+                globalThis.process.versions.bun = originalBun;
+            }
+        }
+        delete env.BL_DISABLE_H2;
+        const { settings } = await import("./settings.js");
+        delete settings.config.disableH2;
+    });
+    function setBunVersion(version) {
+        if (!globalThis.process?.versions)
+            return false;
+        if (version === undefined) {
+            delete globalThis.process.versions.bun;
+        }
+        else {
+            globalThis.process.versions.bun = version;
+        }
+        return true;
+    }
+    it("forces H2 OFF on a broken Bun regardless of config/env", async () => {
+        if (!setBunVersion("1.3.10"))
+            return;
+        delete env.BL_DISABLE_H2;
+        const { settings } = await import("./settings.js");
+        // Even explicitly asking for H2 on cannot override the safety gate.
+        settings.config.disableH2 = false;
+        expect(settings.disableH2).toBe(true);
+    });
+    it("leaves H2 ON (default) on a fixed Bun", async () => {
+        if (!setBunVersion("1.3.11"))
+            return;
+        delete env.BL_DISABLE_H2;
+        const { settings } = await import("./settings.js");
+        delete settings.config.disableH2;
+        expect(settings.disableH2).toBe(false);
+    });
+    it("still respects an explicit opt-out on a fixed Bun", async () => {
+        if (!setBunVersion("1.4.0"))
+            return;
+        const { settings } = await import("./settings.js");
+        settings.config.disableH2 = true;
+        expect(settings.disableH2).toBe(true);
+    });
+});

package/dist/esm/common/settings.js

@@ -5,6 +5,7 @@ import { MissingCredentials } from "../authentication/credentials.js";
 import { authentication } from "../authentication/index.js";
 import { env } from "../common/env.js";
 import { CredentialsError } from "../common/errors.js";
+import { isBrokenBunH2Runtime } from "../common/h2-runtime.js";
 import { logger } from "../common/logger.js";
 import { fs, os, path } from "../common/node.js";
 /**
@@ -23,21 +24,17 @@ 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.6";
-const BUILD_COMMIT = "3189881cfb78a38e368844ba3fc867f83933cade";
+const BUILD_VERSION = "0.3.7-preview.229";
+const BUILD_COMMIT = "23d40862a7ff5f350d98700c4c2e47adb91eddc5";
 const BUILD_SENTRY_DSN = "https://fd5e60e1c9820e1eef5ccebb84a07127@o4508714045276160.ingest.us.sentry.io/4510465864564736";
 const BLAXEL_API_VERSION = "2026-04-28";
 // Bun < 1.3.11 never sends connection-level WINDOW_UPDATE: the pooled h2
 // session freezes after exactly 65535 cumulative body bytes and every request
 // on it hangs until the edge resets the streams (~330s).
 // Fixed in Bun 1.3.11: https://bun.com/blog/bun-v1.3.11
-function isBrokenBunH2() {
-    const v = globalThis.process?.versions?.bun;
-    if (!v)
-        return false;
-    const [maj = 0, min = 0, patch = 0] = v.split("-")[0].split(".").map(Number);
-    return maj < 1 || (maj === 1 && (min < 3 || (min === 3 && patch < 11)));
-}
+// The version gate lives in ./h2-runtime.ts so settings, unit tests, and the
+// cross-runtime environment tests share ONE definition.
+const isBrokenBunH2 = isBrokenBunH2Runtime;
 // Warn at most once when H2 is force-disabled on a broken Bun runtime.
 let brokenBunH2Warned = false;
 // Cache for config.yaml tracking value

package/dist/esm/common/settings.test.js

@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { ApiKey } from '../authentication/apikey.js';
 import { env } from './env.js';
+import { isBrokenBunH2Runtime } from './h2-runtime.js';
 describe('Settings.apiVersion', () => {
     beforeEach(() => {
         // Reset the module-level settings singleton between tests if needed
@@ -33,13 +34,10 @@ describe('Settings.disableH2', () => {
         const { settings } = await import('./settings.js');
         delete settings.config.disableH2;
     });
-    const onBrokenBun = (() => {
-        const v = globalThis.process?.versions?.bun;
-        if (!v)
-            return false;
-        const [maj = 0, min = 0, patch = 0] = v.split('.').map(Number);
-        return maj < 1 || (maj === 1 && (min < 3 || (min === 3 && patch < 11)));
-    })();
+    // On a broken-Bun runtime the getter force-returns true regardless of
+    // config/env, so the "H2 on by default" expectations below do not hold there.
+    // Use the SAME predicate the getter uses so the skip and the behavior agree.
+    const onBrokenBun = isBrokenBunH2Runtime();
     it.skipIf(onBrokenBun)('enables H2 by default', async () => {
         delete env.BL_DISABLE_H2;
         const { settings } = await import('./settings.js');
@@ -52,3 +50,169 @@ describe('Settings.disableH2', () => {
         expect(settings.disableH2).toBe(true);
     });
 });
+// The H2 tuning knobs all share the same resolution order: an explicit
+// `settings.config` value wins, then the env var (`env` reads through to
+// process.env), then a hard-coded default. Numeric knobs also reject
+// unparseable/out-of-range env strings and fall back to the default. These are
+// the values that flow into establishH2 (window sizes) and the per-domain
+// concurrency gates, so an off-by-one here silently changes transport behavior.
+describe('Settings H2 tuning knobs (config > env > default)', () => {
+    // Snapshot every H2 env var so a test that sets one cannot leak into another.
+    const H2_ENV_VARS = [
+        'BL_DISABLE_CONTROL_PLANE_H2',
+        'BL_FORCE_CONTROL_PLANE_H2',
+        'BL_MAX_H2_INFLIGHT',
+        'BL_MAX_UPLOAD_H2_INFLIGHT',
+        'BL_H2_STREAM_WINDOW',
+        'BL_H2_CONNECTION_WINDOW',
+    ];
+    const originalEnv = {};
+    beforeEach(() => {
+        for (const key of H2_ENV_VARS) {
+            originalEnv[key] = process.env[key];
+            delete process.env[key];
+        }
+    });
+    afterEach(async () => {
+        for (const key of H2_ENV_VARS) {
+            if (originalEnv[key] === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = originalEnv[key];
+        }
+        const { settings } = await import('./settings.js');
+        delete settings.config.disableControlPlaneH2;
+        delete settings.config.forceControlPlaneH2;
+        delete settings.config.maxConcurrentH2Requests;
+        delete settings.config.maxConcurrentUploadH2Requests;
+        delete settings.config.h2StreamWindowSize;
+        delete settings.config.h2ConnectionWindowSize;
+    });
+    describe('disableControlPlaneH2', () => {
+        it('defaults to false', async () => {
+            const { settings } = await import('./settings.js');
+            expect(settings.disableControlPlaneH2).toBe(false);
+        });
+        it.each(['1', 'true', 'yes', 'on', 'TRUE', 'On'])('treats env %s as true', async (value) => {
+            process.env.BL_DISABLE_CONTROL_PLANE_H2 = value;
+            const { settings } = await import('./settings.js');
+            expect(settings.disableControlPlaneH2).toBe(true);
+        });
+        it.each(['0', 'false', 'no', 'off', ''])('treats env %s as false', async (value) => {
+            process.env.BL_DISABLE_CONTROL_PLANE_H2 = value;
+            const { settings } = await import('./settings.js');
+            expect(settings.disableControlPlaneH2).toBe(false);
+        });
+        it('config value wins over the env var', async () => {
+            process.env.BL_DISABLE_CONTROL_PLANE_H2 = '1';
+            const { settings } = await import('./settings.js');
+            settings.config.disableControlPlaneH2 = false;
+            expect(settings.disableControlPlaneH2).toBe(false);
+        });
+    });
+    describe('forceControlPlaneH2', () => {
+        it('defaults to false', async () => {
+            const { settings } = await import('./settings.js');
+            expect(settings.forceControlPlaneH2).toBe(false);
+        });
+        it('reads a truthy env var', async () => {
+            process.env.BL_FORCE_CONTROL_PLANE_H2 = 'yes';
+            const { settings } = await import('./settings.js');
+            expect(settings.forceControlPlaneH2).toBe(true);
+        });
+        it('config value wins over the env var', async () => {
+            process.env.BL_FORCE_CONTROL_PLANE_H2 = '1';
+            const { settings } = await import('./settings.js');
+            settings.config.forceControlPlaneH2 = false;
+            expect(settings.forceControlPlaneH2).toBe(false);
+        });
+    });
+    describe('maxConcurrentH2Requests', () => {
+        it('defaults to 0 (unlimited)', async () => {
+            const { settings } = await import('./settings.js');
+            expect(settings.maxConcurrentH2Requests).toBe(0);
+        });
+        it('parses the env var', async () => {
+            process.env.BL_MAX_H2_INFLIGHT = '8';
+            const { settings } = await import('./settings.js');
+            expect(settings.maxConcurrentH2Requests).toBe(8);
+        });
+        it('config value wins over the env var', async () => {
+            process.env.BL_MAX_H2_INFLIGHT = '8';
+            const { settings } = await import('./settings.js');
+            settings.config.maxConcurrentH2Requests = 3;
+            expect(settings.maxConcurrentH2Requests).toBe(3);
+        });
+        it('falls back to the default on an unparseable env var', async () => {
+            process.env.BL_MAX_H2_INFLIGHT = 'not-a-number';
+            const { settings } = await import('./settings.js');
+            expect(settings.maxConcurrentH2Requests).toBe(0);
+        });
+    });
+    describe('maxConcurrentUploadH2Requests', () => {
+        it('defaults to 2 (the measured rapid-reset-safe cap)', async () => {
+            const { settings } = await import('./settings.js');
+            expect(settings.maxConcurrentUploadH2Requests).toBe(2);
+        });
+        it('parses the env var, including 0 to disable the cap', async () => {
+            process.env.BL_MAX_UPLOAD_H2_INFLIGHT = '0';
+            const { settings } = await import('./settings.js');
+            expect(settings.maxConcurrentUploadH2Requests).toBe(0);
+        });
+        it('config value wins over the env var', async () => {
+            process.env.BL_MAX_UPLOAD_H2_INFLIGHT = '5';
+            const { settings } = await import('./settings.js');
+            settings.config.maxConcurrentUploadH2Requests = 4;
+            expect(settings.maxConcurrentUploadH2Requests).toBe(4);
+        });
+        it('falls back to the default on an unparseable env var', async () => {
+            process.env.BL_MAX_UPLOAD_H2_INFLIGHT = 'xyz';
+            const { settings } = await import('./settings.js');
+            expect(settings.maxConcurrentUploadH2Requests).toBe(2);
+        });
+    });
+    describe('h2StreamWindowSize', () => {
+        it('defaults to 16 MiB', async () => {
+            const { settings } = await import('./settings.js');
+            expect(settings.h2StreamWindowSize).toBe(16 * 1024 * 1024);
+        });
+        it('parses a positive env var', async () => {
+            process.env.BL_H2_STREAM_WINDOW = String(4 * 1024 * 1024);
+            const { settings } = await import('./settings.js');
+            expect(settings.h2StreamWindowSize).toBe(4 * 1024 * 1024);
+        });
+        it('config value wins over the env var', async () => {
+            process.env.BL_H2_STREAM_WINDOW = '123456';
+            const { settings } = await import('./settings.js');
+            settings.config.h2StreamWindowSize = 654321;
+            expect(settings.h2StreamWindowSize).toBe(654321);
+        });
+        it.each(['0', '-1', 'nan'])('ignores non-positive/unparseable env value %s and uses the default', async (value) => {
+            process.env.BL_H2_STREAM_WINDOW = value;
+            const { settings } = await import('./settings.js');
+            expect(settings.h2StreamWindowSize).toBe(16 * 1024 * 1024);
+        });
+    });
+    describe('h2ConnectionWindowSize', () => {
+        it('defaults to 32 MiB', async () => {
+            const { settings } = await import('./settings.js');
+            expect(settings.h2ConnectionWindowSize).toBe(32 * 1024 * 1024);
+        });
+        it('parses a positive env var', async () => {
+            process.env.BL_H2_CONNECTION_WINDOW = String(8 * 1024 * 1024);
+            const { settings } = await import('./settings.js');
+            expect(settings.h2ConnectionWindowSize).toBe(8 * 1024 * 1024);
+        });
+        it('config value wins over the env var', async () => {
+            process.env.BL_H2_CONNECTION_WINDOW = '111';
+            const { settings } = await import('./settings.js');
+            settings.config.h2ConnectionWindowSize = 222;
+            expect(settings.h2ConnectionWindowSize).toBe(222);
+        });
+        it.each(['0', '-100', 'foo'])('ignores non-positive/unparseable env value %s and uses the default', async (value) => {
+            process.env.BL_H2_CONNECTION_WINDOW = value;
+            const { settings } = await import('./settings.js');
+            expect(settings.h2ConnectionWindowSize).toBe(32 * 1024 * 1024);
+        });
+    });
+});

package/dist/esm/index.js

@@ -3,6 +3,7 @@ export * from "./agents/index.js";
 export * from "./client/client.js";
 export * from "./common/autoload.js";
 export * from "./common/env.js";
+export * from "./common/h2-runtime.js";
 export * from "./common/node.js";
 export * from "./common/errors.js";
 export * from "./common/internal.js";