@blaxel/core 0.3.12-preview.255 → 0.3.12-preview.256

package/dist/esm-browser/common/h2stats.js

@@ -1,4 +1,5 @@
 import { logger } from "./logger.js";
+import { reportH2TransportDegradation } from "./sentry.js";
 const emptyReasons = () => ({
     "no-session": 0,
     "request-rejected": 0,
@@ -48,6 +49,7 @@ class H2TransportStatsStore {
         catch {
             // Diagnostics must never change transport behavior.
         }
+        reportH2TransportDegradation(domain, "establish-failure");
         publishDebugSnapshot(this.snapshot());
     }
     /** @internal */
@@ -63,6 +65,7 @@ class H2TransportStatsStore {
         catch {
             // Diagnostics must never change transport behavior.
         }
+        reportH2TransportDegradation(domain, reason);
         publishDebugSnapshot(this.snapshot());
     }
     forDomain(domain) {

package/dist/esm-browser/common/sentry.js

@@ -1,3 +1,4 @@
+import { crypto } from "./node.js";
 import { settings } from "./settings.js";
 const PACKAGE_LAYOUT_MARKERS = [
     "/src/common/sentry.ts",
@@ -24,7 +25,11 @@ const SAFE_ERROR_NAMES = new Set([
     "AggregateError",
 ]);
 const MAX_IN_FLIGHT_EVENTS = 20;
+const MAX_ACTIVE_H2_ROLLUPS = 20;
+const MAX_CACHED_DOMAIN_TAGS = 100;
+const MAX_H2_EVENTS_PER_PROCESS = 100;
 const DELIVERY_TIMEOUT_MS = 500;
+const H2_ROLLUP_WINDOW_MS = 60_000;
 const SAFE_FILENAME_SEGMENT = /^[A-Za-z0-9._-]+$/;
 let sentryInitialized = false;
 let handlersRegistered = false;
@@ -32,6 +37,9 @@ let sentryConfig = null;
 let flushPromise = null;
 const capturedExceptions = new WeakSet();
 const inFlightDeliveries = new Set();
+const domainTagCache = new Map();
+const h2DegradationRollups = new Map();
+let h2EventsEmitted = 0;
 /**
  * Normalize stack filenames without resolving or exposing host filesystem data.
  */
@@ -204,6 +212,91 @@ function errorToSentryEvent(error, ownedFrames) {
         },
     };
 }
+function runtimeTag() {
+    const host = globalThis;
+    if (host.process?.versions?.bun)
+        return `bun/${host.process.versions.bun}`;
+    if (host.Deno?.version?.deno)
+        return `deno/${host.Deno.version.deno}`;
+    if (host.process?.versions?.node)
+        return `node/${host.process.versions.node}`;
+    return "browser";
+}
+function normalizeDomain(domain) {
+    const normalized = domain.trim().toLowerCase().replace(/\.$/, "");
+    return normalized.length > 0 ? normalized : null;
+}
+function blaxelEdgeDomainTag(domain) {
+    const edgeSuffixes = [
+        { environment: "prod", suffix: ".bl.run" },
+        { environment: "dev", suffix: ".runv2.blaxel.dev" },
+    ];
+    for (const { environment, suffix } of edgeSuffixes) {
+        if (!domain.endsWith(suffix))
+            continue;
+        const region = domain.slice(0, -suffix.length).split(".").at(-1);
+        if (region && /^[a-z0-9-]+$/.test(region)) {
+            return `blaxel-edge:${environment}:${region}`;
+        }
+        return null;
+    }
+    return null;
+}
+function uncachedDomainTag(domain) {
+    const stableBlaxelDomains = {
+        "api.blaxel.ai": "blaxel-api:prod",
+        "api.blaxel.dev": "blaxel-api:dev",
+        "run.blaxel.ai": "blaxel-run:prod",
+        "run.blaxel.dev": "blaxel-run:dev",
+    };
+    const stableTag = stableBlaxelDomains[domain];
+    if (stableTag)
+        return stableTag;
+    const edgeTag = blaxelEdgeDomainTag(domain);
+    if (edgeTag)
+        return edgeTag;
+    if (!crypto)
+        return null;
+    try {
+        return `sha256:${crypto.createHash("sha256").update(domain).digest("hex")}`;
+    }
+    catch {
+        return null;
+    }
+}
+function domainToTag(domain) {
+    if (domainTagCache.has(domain))
+        return domainTagCache.get(domain) ?? null;
+    const domainTag = uncachedDomainTag(domain);
+    if (domainTagCache.size >= MAX_CACHED_DOMAIN_TAGS) {
+        const oldestDomain = domainTagCache.keys().next().value;
+        if (oldestDomain !== undefined)
+            domainTagCache.delete(oldestDomain);
+    }
+    domainTagCache.set(domain, domainTag);
+    return domainTag;
+}
+function h2DegradationToSentryEvent(reason, domainTag, count) {
+    return {
+        event_id: generateEventId(),
+        timestamp: Date.now() / 1000,
+        platform: "javascript",
+        level: "warning",
+        environment: settings.env,
+        release: `sdk-typescript@${settings.version}`,
+        message: `h2 transport degradation: ${reason}`,
+        fingerprint: ["h2-degradation", reason, domainTag],
+        tags: {
+            "blaxel.version": settings.version,
+            "blaxel.commit": settings.commit,
+            "blaxel.error_source": "h2-transport-degradation",
+            "blaxel.runtime": runtimeTag(),
+            reason,
+            domainTag,
+        },
+        extra: { count },
+    };
+}
 async function sendToSentry(event) {
     if (!sentryConfig)
         return;
@@ -245,12 +338,71 @@ async function sendToSentry(event) {
 }
 function scheduleDelivery(event) {
     if (inFlightDeliveries.size >= MAX_IN_FLIGHT_EVENTS)
-        return;
+        return false;
     // Contain rejections from setup that occurs before sendToSentry's internal
     // fetch guard (for example, a host-provided AbortController implementation).
     const delivery = sendToSentry(event).catch(() => undefined);
     inFlightDeliveries.add(delivery);
     void delivery.then(() => inFlightDeliveries.delete(delivery));
+    return true;
+}
+function emitH2DegradationRollup(key) {
+    const rollup = h2DegradationRollups.get(key);
+    if (!rollup)
+        return;
+    h2DegradationRollups.delete(key);
+    clearTimeout(rollup.timer);
+    if (h2EventsEmitted >= MAX_H2_EVENTS_PER_PROCESS)
+        return;
+    if (scheduleDelivery(h2DegradationToSentryEvent(rollup.reason, rollup.domainTag, rollup.count))) {
+        h2EventsEmitted++;
+    }
+}
+function flushH2DegradationRollups() {
+    for (const key of [...h2DegradationRollups.keys()]) {
+        emitH2DegradationRollup(key);
+    }
+}
+/** @internal */
+export function reportH2TransportDegradation(domain, reason) {
+    if (!sentryInitialized || !sentryConfig)
+        return;
+    try {
+        if (h2EventsEmitted >= MAX_H2_EVENTS_PER_PROCESS)
+            return;
+        const normalizedDomain = normalizeDomain(domain);
+        if (!normalizedDomain)
+            return;
+        const domainTag = domainToTag(normalizedDomain);
+        if (!domainTag)
+            return;
+        const key = `${reason}\0${domainTag}`;
+        const existing = h2DegradationRollups.get(key);
+        if (existing) {
+            existing.count++;
+            return;
+        }
+        if (h2DegradationRollups.size >= MAX_ACTIVE_H2_ROLLUPS)
+            return;
+        const timer = setTimeout(() => {
+            try {
+                emitH2DegradationRollup(key);
+            }
+            catch {
+                // Telemetry must never change transport behavior.
+            }
+        }, H2_ROLLUP_WINDOW_MS);
+        timer.unref?.();
+        h2DegradationRollups.set(key, {
+            count: 1,
+            domainTag,
+            reason,
+            timer,
+        });
+    }
+    catch {
+        // Telemetry must never change transport behavior.
+    }
 }
 function captureException(error) {
     if (!sentryInitialized || !sentryConfig || capturedExceptions.has(error)) {
@@ -318,7 +470,15 @@ export function initSentry() {
  * Events are sent exactly once; flush never re-enqueues them.
  */
 export async function flushSentry(timeout = DELIVERY_TIMEOUT_MS) {
-    if (!sentryInitialized || inFlightDeliveries.size === 0)
+    if (!sentryInitialized)
+        return;
+    try {
+        flushH2DegradationRollups();
+    }
+    catch {
+        // Flushing telemetry must never affect application shutdown.
+    }
+    if (inFlightDeliveries.size === 0)
         return;
     if (flushPromise) {
         await flushPromise;

package/dist/esm-browser/common/sentry.test.js

@@ -41,12 +41,28 @@ function makeTraversalStackError() {
     error.stack = ["Error: application secret", forgedFrame].join("\n");
     return error;
 }
+function createFetchMock() {
+    return vi.fn((input, init) => {
+        void input;
+        void init;
+        return Promise.resolve({ ok: true });
+    });
+}
 function eventFromFetch(fetchMock) {
     const request = fetchMock.mock.calls[0]?.[1];
     if (typeof request?.body !== "string")
         throw new Error("Expected a string Sentry envelope");
     return JSON.parse(request.body.split("\n")[2]);
 }
+function eventsFromFetch(fetchMock) {
+    return fetchMock.mock.calls.map((call) => {
+        const request = call[1];
+        if (typeof request?.body !== "string") {
+            throw new Error("Expected a string Sentry envelope");
+        }
+        return JSON.parse(request.body.split("\n")[2]);
+    });
+}
 function emitUncaughtExceptionMonitor(error) {
     const processWithStringEvents = process;
     return processWithStringEvents.emit("uncaughtExceptionMonitor", error, "uncaughtException");
@@ -61,6 +77,8 @@ describe("SDK Sentry boundary", () => {
         originalMonitorListeners = process.listeners("uncaughtExceptionMonitor");
     });
     afterEach(() => {
+        vi.useRealTimers();
+        vi.doUnmock("./node.js");
         vi.unstubAllGlobals();
         for (const listener of process.listeners("uncaughtExceptionMonitor")) {
             if (!originalMonitorListeners.includes(listener)) {
@@ -70,7 +88,7 @@ describe("SDK Sentry boundary", () => {
         vi.restoreAllMocks();
     });
     it("does not replace console.error or report caught errors", async () => {
-        const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+        const fetchMock = createFetchMock();
         const hostConsoleError = vi.fn();
         vi.stubGlobal("fetch", fetchMock);
         vi.spyOn(console, "error").mockImplementation(hostConsoleError);
@@ -83,7 +101,7 @@ describe("SDK Sentry boundary", () => {
         expect(fetchMock).not.toHaveBeenCalled();
     });
     it("composes with host handlers and reports one sanitized SDK-owned event", async () => {
-        const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+        const fetchMock = createFetchMock();
         const hostMonitor = vi.fn();
         const hostRejection = vi.fn();
         vi.stubGlobal("fetch", fetchMock);
@@ -101,7 +119,7 @@ describe("SDK Sentry boundary", () => {
             expect(process.listeners("unhandledRejection")).toEqual(rejectionListeners);
             expect(fetchMock).toHaveBeenCalledOnce();
             const event = eventFromFetch(fetchMock);
-            expect(event.exception.values[0]).toMatchObject({
+            expect(event.exception?.values[0]).toMatchObject({
                 type: "TypeError",
                 value: "Unhandled SDK exception",
             });
@@ -111,7 +129,7 @@ describe("SDK Sentry boundary", () => {
                 "blaxel.error_source": "unhandled-sdk-exception",
             });
             expect(event.tags).not.toHaveProperty("blaxel.workspace");
-            const frames = event.exception.values[0].stacktrace.frames;
+            const frames = event.exception?.values[0]?.stacktrace.frames ?? [];
             expect(frames.length).toBeGreaterThan(0);
             for (const frame of frames) {
                 expect(frame.filename).toBe("@blaxel/core/src/common/sentry.test.ts");
@@ -128,7 +146,7 @@ describe("SDK Sentry boundary", () => {
         }
     });
     it("does not attribute an application-owned exception with a later SDK frame", async () => {
-        const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+        const fetchMock = createFetchMock();
         vi.stubGlobal("fetch", fetchMock);
         const { initSentry } = await import("./sentry.js");
         initSentry();
@@ -136,7 +154,7 @@ describe("SDK Sentry boundary", () => {
         expect(fetchMock).not.toHaveBeenCalled();
     });
     it("rejects a forged owned path containing parent traversal", async () => {
-        const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+        const fetchMock = createFetchMock();
         vi.stubGlobal("fetch", fetchMock);
         const { initSentry } = await import("./sentry.js");
         initSentry();
@@ -144,7 +162,7 @@ describe("SDK Sentry boundary", () => {
         expect(fetchMock).not.toHaveBeenCalled();
     });
     it("contains delivery setup failures without creating an unhandled rejection", async () => {
-        const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+        const fetchMock = createFetchMock();
         vi.stubGlobal("fetch", fetchMock);
         vi.stubGlobal("AbortController", class FailingAbortController {
             constructor() {
@@ -158,7 +176,7 @@ describe("SDK Sentry boundary", () => {
         expect(fetchMock).not.toHaveBeenCalled();
     });
     it("composes with browser handlers and ignores primitive rejections", async () => {
-        const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+        const fetchMock = createFetchMock();
         const listeners = new Map();
         const addEventListener = vi.fn((type, listener) => {
             listeners.set(type, listener);
@@ -177,13 +195,150 @@ describe("SDK Sentry boundary", () => {
         expect(JSON.stringify(eventFromFetch(fetchMock))).not.toContain("raw rejection secret");
     });
     it("does not initialize when tracking is disabled", async () => {
-        const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+        const fetchMock = createFetchMock();
         vi.stubGlobal("fetch", fetchMock);
         mockSettings.tracking = false;
-        const { initSentry, isSentryInitialized } = await import("./sentry.js");
+        const { flushSentry, initSentry, isSentryInitialized, reportH2TransportDegradation, } = await import("./sentry.js");
         initSentry();
         emitUncaughtExceptionMonitor(makeSdkError());
+        reportH2TransportDegradation("sbx-test-workspace.us-pdx-1.bl.run", "no-session");
+        await flushSentry();
         expect(isSentryInitialized()).toBe(false);
         expect(fetchMock).not.toHaveBeenCalled();
     });
+    it("rolls a 100-fallback burst into one warning event", async () => {
+        vi.useFakeTimers();
+        const fetchMock = createFetchMock();
+        vi.stubGlobal("fetch", fetchMock);
+        const { flushSentry, initSentry, reportH2TransportDegradation } = await import("./sentry.js");
+        initSentry();
+        const domain = "sbx-test-workspace.us-pdx-1.bl.run";
+        const domainTag = "blaxel-edge:prod:us-pdx-1";
+        for (let index = 0; index < 100; index++) {
+            reportH2TransportDegradation(domain, "no-session");
+        }
+        expect(fetchMock).not.toHaveBeenCalled();
+        await vi.advanceTimersByTimeAsync(60_000);
+        await flushSentry();
+        expect(fetchMock).toHaveBeenCalledOnce();
+        expect(eventFromFetch(fetchMock)).toMatchObject({
+            level: "warning",
+            message: "h2 transport degradation: no-session",
+            fingerprint: ["h2-degradation", "no-session", domainTag],
+            tags: {
+                "blaxel.version": "9.9.9",
+                "blaxel.commit": "abcdef0",
+                "blaxel.error_source": "h2-transport-degradation",
+                "blaxel.runtime": `node/${process.versions.node}`,
+                reason: "no-session",
+                domainTag,
+            },
+            extra: { count: 100 },
+        });
+    });
+    it("groups keys independently and hashes external domains", async () => {
+        const fetchMock = createFetchMock();
+        vi.stubGlobal("fetch", fetchMock);
+        const { flushSentry, initSentry, reportH2TransportDegradation } = await import("./sentry.js");
+        initSentry();
+        const externalDomain = "customer.internal.example";
+        const blaxelDomain = "sbx-test-workspace.us-pdx-1.bl.run";
+        reportH2TransportDegradation(externalDomain, "no-session");
+        reportH2TransportDegradation(externalDomain, "no-session");
+        reportH2TransportDegradation(blaxelDomain, "request-rejected");
+        await flushSentry();
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        const events = eventsFromFetch(fetchMock);
+        const externalEvent = events.find((event) => event.tags.reason === "no-session");
+        const blaxelEvent = events.find((event) => event.tags.reason === "request-rejected");
+        expect(externalEvent).toMatchObject({ extra: { count: 2 } });
+        expect(externalEvent?.tags.domainTag).toMatch(/^sha256:[a-f0-9]{64}$/);
+        expect(JSON.stringify(externalEvent)).not.toContain(externalDomain);
+        expect(blaxelEvent).toMatchObject({
+            tags: { domainTag: "blaxel-edge:prod:us-pdx-1" },
+            extra: { count: 1 },
+        });
+    });
+    it("groups Blaxel edge hosts by environment and region", async () => {
+        const fetchMock = createFetchMock();
+        vi.stubGlobal("fetch", fetchMock);
+        const { flushSentry, initSentry, reportH2TransportDegradation } = await import("./sentry.js");
+        initSentry();
+        reportH2TransportDegradation("sbx-first-workspace.us-pdx-1.bl.run", "no-session");
+        reportH2TransportDegradation("sbx-second-workspace.us-pdx-1.bl.run", "no-session");
+        await flushSentry();
+        expect(fetchMock).toHaveBeenCalledOnce();
+        expect(eventFromFetch(fetchMock)).toMatchObject({
+            fingerprint: [
+                "h2-degradation",
+                "no-session",
+                "blaxel-edge:prod:us-pdx-1",
+            ],
+            extra: { count: 2 },
+        });
+    });
+    it("keeps stable Blaxel control-plane domains identifiable", async () => {
+        const fetchMock = createFetchMock();
+        vi.stubGlobal("fetch", fetchMock);
+        const { flushSentry, initSentry, reportH2TransportDegradation } = await import("./sentry.js");
+        initSentry();
+        reportH2TransportDegradation("api.blaxel.ai", "no-session");
+        await flushSentry();
+        expect(eventFromFetch(fetchMock)).toMatchObject({
+            tags: { domainTag: "blaxel-api:prod" },
+            fingerprint: ["h2-degradation", "no-session", "blaxel-api:prod"],
+        });
+    });
+    it("caps active rollup keys at 20", async () => {
+        const fetchMock = createFetchMock();
+        vi.stubGlobal("fetch", fetchMock);
+        const { flushSentry, initSentry, reportH2TransportDegradation } = await import("./sentry.js");
+        initSentry();
+        for (let index = 0; index < 21; index++) {
+            reportH2TransportDegradation(`sbx-test-workspace.us-test-${index}.bl.run`, "no-session");
+        }
+        await flushSentry();
+        expect(fetchMock).toHaveBeenCalledTimes(20);
+    });
+    it("caps H2 degradation events at 100 per process", async () => {
+        const fetchMock = createFetchMock();
+        vi.stubGlobal("fetch", fetchMock);
+        const { flushSentry, initSentry, reportH2TransportDegradation } = await import("./sentry.js");
+        initSentry();
+        for (let index = 0; index < 101; index++) {
+            reportH2TransportDegradation("sbx-test-workspace.us-pdx-1.bl.run", "no-session");
+            await flushSentry();
+        }
+        expect(fetchMock).toHaveBeenCalledTimes(100);
+    });
+    it("fails closed when an external domain cannot be hashed", async () => {
+        const fetchMock = createFetchMock();
+        vi.stubGlobal("fetch", fetchMock);
+        vi.doMock("./node.js", () => ({
+            crypto: {
+                createHash: () => {
+                    throw new Error("hash unavailable");
+                },
+            },
+        }));
+        const { flushSentry, initSentry, reportH2TransportDegradation } = await import("./sentry.js");
+        initSentry();
+        expect(() => reportH2TransportDegradation("private.customer.example", "no-session")).not.toThrow();
+        await flushSentry();
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+    it("reports degradations through the H2 statistics hooks", async () => {
+        const fetchMock = createFetchMock();
+        vi.stubGlobal("fetch", fetchMock);
+        const { flushSentry, initSentry } = await import("./sentry.js");
+        initSentry();
+        const { recordH2Fallback } = await import("./h2stats.js");
+        recordH2Fallback("sbx-test-workspace.us-pdx-1.bl.run", "unsupported-body");
+        await flushSentry();
+        expect(fetchMock).toHaveBeenCalledOnce();
+        expect(eventFromFetch(fetchMock)).toMatchObject({
+            message: "h2 transport degradation: unsupported-body",
+            extra: { count: 1 },
+        });
+    });
 });

package/dist/esm-browser/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.12-preview.255";
-const BUILD_COMMIT = "0a7ecff86c697285b849e61a8cc5219e85b5ba89";
+const BUILD_VERSION = "0.3.12-preview.256";
+const BUILD_COMMIT = "d1beb333d98608709a5a26ace333ff0db5673694";
 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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@blaxel/core",
-	"version": "0.3.12-preview.255",
+	"version": "0.3.12-preview.256",
 	"description": "Blaxel Core SDK for TypeScript",
 	"license": "MIT",
 	"author": "Blaxel, INC (https://blaxel.ai)",