@nimbus-sh/worker 0.1.0

package/dist/replica/suspension.js

@@ -0,0 +1,49 @@
+/**
+ * replica-suspension.ts — W12 — global replica-suspension counter.
+ *
+ * Per [~lambros/Feedback for DO read replication API](https://wiki.cfdata.org/display/~lambros/Feedback+for+DO+read+replication+API+based+on+D1+read+replication+beta)
+ * (cited in CF research §G.4), DO read replicas error with "Network
+ * connection lost" during high-volume writes. The recommended mitigation
+ * is to disable replicas before a write burst (npm install, git clone)
+ * and re-enable after.
+ *
+ * This module exposes a refcount-style suspend/release API. The counter
+ * is checked by `shouldDelegateToPrimary` (in `replica-routing.ts`):
+ * when `replicasSuspended() === true`, the replica forwards everything
+ * to the primary regardless of route policy.
+ *
+ * Phase 1 of W12 ships the module + the in-DO consultation. Phase 2
+ * (W12.5 if measured demand) wires the npm-installer / git-clone hooks.
+ * Today's behaviour: counter stays at 0 → replicas serve normally; the
+ * SPEC error path is observed as a graceful-degrade (replica's primary
+ * stub returns the error and the user sees a 5xx, same as today's
+ * single-region behaviour).
+ */
+let _suspendCount = 0;
+/**
+ * Increment the suspension count. Returns a release function that
+ * decrements once (subsequent calls are no-ops). Suspends are nestable;
+ * any holder keeping the count > 0 keeps replicas suspended.
+ */
+export function suspendReplicas() {
+    _suspendCount++;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        _suspendCount = Math.max(0, _suspendCount - 1);
+    };
+}
+/** Are any holders currently suspending replicas? */
+export function replicasSuspended() {
+    return _suspendCount > 0;
+}
+/**
+ * Test-only escape hatch. Resets the counter to 0. Production code MUST
+ * NOT call this — use only the suspend/release pair to keep semantics
+ * tight. Exported under a `_` prefix and namespaced for tests.
+ */
+export function _resetSuspensionForTests() {
+    _suspendCount = 0;
+}

package/dist/router/index.d.ts

@@ -0,0 +1,156 @@
+/**
+ * router/index.ts — `createNimbusHandler` factory.
+ *
+ * The Worker entry's `default { fetch }` is now a thin call into this
+ * factory. The factory is the **composable surface** an embedder gets via
+ * `@nimbus-sh/worker`:
+ *
+ *   import { NimbusSession, createNimbusHandler } from '@nimbus-sh/worker';
+ *   export { NimbusSession };
+ *   export default createNimbusHandler({
+ *     // Optional embedder hooks (all default no-op):
+ *     hooks: {
+ *       onSessionStart: async (ctx) => { … },
+ *       onSessionEnd:   async (ctx) => { … },
+ *     },
+ *     // Optional embedder routes that run BEFORE the Nimbus router.
+ *     // Return null to fall through to Nimbus's handling.
+ *     routes: async (req, env, ctx) => {
+ *       if (new URL(req.url).pathname === '/healthz') return new Response('ok');
+ *       return null;
+ *     },
+ *     // Optional auth-mode override (default 'auto').
+ *     auth: { mode: 'auto', legacyPublic: false },
+ *   });
+ *
+ * Why a factory + hooks (not a class)?
+ *   - Closures match the Workers programming model. A factory returns a
+ *     fresh module-export-shaped object that the Workers runtime calls.
+ *   - Hooks let embedders observe lifecycle without forking the DO. They
+ *     run alongside, never block (errors are caught + logged).
+ *   - The default `createNimbusHandler()` (zero args) is the
+ *     "ship-Nimbus-as-is" case — exactly what `apps/dogfood/` does.
+ */
+/**
+ * Lifecycle event a hook receives. Hooks should treat this as read-only.
+ */
+export interface NimbusHookContext {
+    /** Tenant segment used for the DO instance name. */
+    tenantSegment: string;
+    /** Session ID portion of the URL. */
+    sessionId: string;
+    /** The inbound Request (read-only — clone via `request.clone()` to read body). */
+    request: Request;
+    /** Bindings env. */
+    env: any;
+}
+/**
+ * Embedder hooks. Every hook is optional and defaults to no-op. Errors
+ * thrown from a hook are caught and logged via `console.warn`; they do
+ * NOT short-circuit the request.
+ *
+ * `onSessionStart` fires on the first WebSocket upgrade for a session
+ * (not on every HTTP API call). `onSessionEnd` fires when the DO emits a
+ * session-end event (not implemented v1; reserved).
+ */
+export interface NimbusHooks {
+    /**
+     * Called when a new session is first attached via WebSocket. Useful
+     * for embedder-side audit logging, metrics, or token-binding
+     * provenance recording.
+     *
+     * @param ctx Lifecycle context.
+     */
+    onSessionStart?(ctx: NimbusHookContext): void | Promise<void>;
+    /**
+     * Reserved for v0.2. Will fire when a session is destroyed (TTL
+     * elapsed, explicit destroy, or DO eviction).
+     */
+    onSessionEnd?(ctx: NimbusHookContext): void | Promise<void>;
+}
+/**
+ * Auth-mode selector for {@link createNimbusHandler}.
+ *
+ * `'auto'` (default):
+ *   - If `env.JWT_SECRET` is set AND `env.NIMBUS_LEGACY_PUBLIC !== '1'`:
+ *     verify every `/s/<id>/` request against the JWT.
+ *   - Otherwise: legacy-public mode — all `/s/<id>/` requests route to
+ *     the `legacy:public:_` tenant segment (single shared tenant).
+ *
+ * `'enforce'`: always require a valid token; fail closed if `JWT_SECRET`
+ * is missing.
+ *
+ * `'legacy'`: always legacy-public; never verify. Use only for the
+ * live demo / single-tenant deployments where the URL is the auth.
+ */
+export type AuthMode = 'auto' | 'enforce' | 'legacy';
+/** Configuration for the auth surface. */
+export interface NimbusAuthConfig {
+    mode?: AuthMode;
+    /**
+     * Backward-compat opt-in for the legacy single-tenant fallback. Same
+     * effect as `mode: 'legacy'`; provided as a named flag for clarity
+     * in embedder configs. Ignored when `mode` is set explicitly.
+     */
+    legacyPublic?: boolean;
+}
+/**
+ * Custom-routes hook. Runs BEFORE the Nimbus router. Return a `Response`
+ * to short-circuit Nimbus; return `null` to fall through.
+ *
+ * Embedders use this to mount `/api/auth/nimbus-token` (token mint),
+ * `/healthz`, `/metrics`, etc. without proxying through the DO.
+ */
+export type CustomRoutes = (request: Request, env: any, ctx: ExecutionContext) => Response | null | Promise<Response | null>;
+/** Options for {@link createNimbusHandler}. */
+export interface CreateNimbusHandlerOptions {
+    /** Embedder hooks. All optional. */
+    hooks?: NimbusHooks;
+    /** Custom routes that run before Nimbus's router. */
+    routes?: CustomRoutes;
+    /** Auth-mode selector. Default `'auto'`. */
+    auth?: NimbusAuthConfig;
+}
+/**
+ * The shape every `default export` Workers handler must satisfy.
+ * Exported so embedders can type their own composed default export.
+ */
+export interface NimbusHandler {
+    fetch(request: Request, env: any, ctx: ExecutionContext): Promise<Response>;
+}
+/**
+ * Build a Nimbus default-export handler. The returned object is exactly
+ * what `export default` expects in a Workers entry module.
+ *
+ * @example minimal embedder
+ * ```ts
+ * import { NimbusSession, createNimbusHandler } from '@nimbus-sh/worker';
+ * export { NimbusSession };
+ * export default createNimbusHandler();
+ * ```
+ *
+ * @example embedder with auth + a custom route
+ * ```ts
+ * import { NimbusSession, createNimbusHandler } from '@nimbus-sh/worker';
+ * import { issueNimbusToken } from '@nimbus-sh/sdk/token';
+ *
+ * export { NimbusSession };
+ * export default createNimbusHandler({
+ *   auth: { mode: 'enforce' },
+ *   routes: async (req, env) => {
+ *     if (new URL(req.url).pathname === '/api/auth/mint' && req.method === 'POST') {
+ *       const { tenant, sub } = await req.json();
+ *       const token = await issueNimbusToken(env, { tn: tenant, sub });
+ *       return Response.json({ token });
+ *     }
+ *     return null;
+ *   },
+ *   hooks: {
+ *     onSessionStart: ({ tenantSegment, sessionId }) =>
+ *       console.log(`session ${sessionId} for ${tenantSegment}`),
+ *   },
+ * });
+ * ```
+ */
+export declare function createNimbusHandler(options?: CreateNimbusHandlerOptions): NimbusHandler;
+//# sourceMappingURL=index.d.ts.map

package/dist/router/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAsBH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,OAAO,EAAE,OAAO,CAAC;IACjB,oBAAoB;IACpB,GAAG,EAAE,GAAG,CAAC;CACV;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,cAAc,CAAC,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9D;;;OAGG;IACH,YAAY,CAAC,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAErD,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,CACzB,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,GAAG,EACR,GAAG,EAAE,gBAAgB,KAClB,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;AAEhD,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,oCAAoC;IACpC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,qDAAqD;IACrD,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,0BAA+B,GACvC,aAAa,CA+Gf"}

package/dist/router/index.js

@@ -0,0 +1,220 @@
+/**
+ * router/index.ts — `createNimbusHandler` factory.
+ *
+ * The Worker entry's `default { fetch }` is now a thin call into this
+ * factory. The factory is the **composable surface** an embedder gets via
+ * `@nimbus-sh/worker`:
+ *
+ *   import { NimbusSession, createNimbusHandler } from '@nimbus-sh/worker';
+ *   export { NimbusSession };
+ *   export default createNimbusHandler({
+ *     // Optional embedder hooks (all default no-op):
+ *     hooks: {
+ *       onSessionStart: async (ctx) => { … },
+ *       onSessionEnd:   async (ctx) => { … },
+ *     },
+ *     // Optional embedder routes that run BEFORE the Nimbus router.
+ *     // Return null to fall through to Nimbus's handling.
+ *     routes: async (req, env, ctx) => {
+ *       if (new URL(req.url).pathname === '/healthz') return new Response('ok');
+ *       return null;
+ *     },
+ *     // Optional auth-mode override (default 'auto').
+ *     auth: { mode: 'auto', legacyPublic: false },
+ *   });
+ *
+ * Why a factory + hooks (not a class)?
+ *   - Closures match the Workers programming model. A factory returns a
+ *     fresh module-export-shaped object that the Workers runtime calls.
+ *   - Hooks let embedders observe lifecycle without forking the DO. They
+ *     run alongside, never block (errors are caught + logged).
+ *   - The default `createNimbusHandler()` (zero args) is the
+ *     "ship-Nimbus-as-is" case — exactly what `apps/dogfood/` does.
+ */
+import { generateSessionId, isValidSessionId, } from '../_shared/session-id.js';
+import { parseSessionRoute, forwardToSession, renderInvalidSessionHtml, SESSION_ROUTE_PREFIX, LEGACY_PUBLIC_DO_SEGMENT, } from '../_shared/session-router.js';
+import { verifyRequestToken, authErrorResponse, NimbusAuthError, NimbusTokenMalformedError, } from '../auth/index.js';
+import { setCtxExports } from '../session/ctx-exports.js';
+/**
+ * Build a Nimbus default-export handler. The returned object is exactly
+ * what `export default` expects in a Workers entry module.
+ *
+ * @example minimal embedder
+ * ```ts
+ * import { NimbusSession, createNimbusHandler } from '@nimbus-sh/worker';
+ * export { NimbusSession };
+ * export default createNimbusHandler();
+ * ```
+ *
+ * @example embedder with auth + a custom route
+ * ```ts
+ * import { NimbusSession, createNimbusHandler } from '@nimbus-sh/worker';
+ * import { issueNimbusToken } from '@nimbus-sh/sdk/token';
+ *
+ * export { NimbusSession };
+ * export default createNimbusHandler({
+ *   auth: { mode: 'enforce' },
+ *   routes: async (req, env) => {
+ *     if (new URL(req.url).pathname === '/api/auth/mint' && req.method === 'POST') {
+ *       const { tenant, sub } = await req.json();
+ *       const token = await issueNimbusToken(env, { tn: tenant, sub });
+ *       return Response.json({ token });
+ *     }
+ *     return null;
+ *   },
+ *   hooks: {
+ *     onSessionStart: ({ tenantSegment, sessionId }) =>
+ *       console.log(`session ${sessionId} for ${tenantSegment}`),
+ *   },
+ * });
+ * ```
+ */
+export function createNimbusHandler(options = {}) {
+    const hooks = options.hooks ?? {};
+    const customRoutes = options.routes;
+    const authConfig = options.auth ?? {};
+    // Resolve auth mode at factory-construction time.
+    const explicitMode = authConfig.mode
+        ?? (authConfig.legacyPublic ? 'legacy' : undefined);
+    return {
+        async fetch(request, env, ctx) {
+            // Capture ctx.exports on first call (loopback bindings for facets).
+            if (ctx?.exports)
+                setCtxExports(ctx.exports);
+            // Embedder custom routes run first.
+            if (customRoutes) {
+                try {
+                    const r = await customRoutes(request, env, ctx);
+                    if (r)
+                        return r;
+                }
+                catch (e) {
+                    console.error('[nimbus] custom route threw:', e?.stack || e);
+                    return new Response('Internal error in embedder route', { status: 500 });
+                }
+            }
+            const url = new URL(request.url);
+            // ── /new — spawn a fresh session and redirect ───────────────────
+            if (url.pathname === '/new') {
+                if (request.method !== 'POST' && request.method !== 'GET') {
+                    return new Response('Method not allowed', { status: 405 });
+                }
+                const sessionId = generateSessionId();
+                return new Response(null, {
+                    status: 302,
+                    headers: {
+                        Location: `${SESSION_ROUTE_PREFIX}/${sessionId}/`,
+                        'Cache-Control': 'no-store',
+                    },
+                });
+            }
+            // ── /s/<id>/... — session-scoped routes ─────────────────────────
+            const route = parseSessionRoute(url.pathname);
+            if (route) {
+                if (!isValidSessionId(route.sessionId)) {
+                    return new Response(renderInvalidSessionHtml(route.sessionId), {
+                        status: 400,
+                        headers: {
+                            'Content-Type': 'text/html; charset=utf-8',
+                            'Cache-Control': 'no-store',
+                        },
+                    });
+                }
+                // Resolve tenant segment per auth mode.
+                const tenantSegment = await resolveTenantSegment(request, env, explicitMode);
+                if (tenantSegment instanceof Response)
+                    return tenantSegment;
+                // `/s/<id>` and `/s/<id>/` (no inner path) → serve the xterm UI shell.
+                if (route.innerPath === '/' || route.innerPath === '') {
+                    if (env.ASSETS) {
+                        const shellUrl = new URL('/s/index.html', url.origin);
+                        return env.ASSETS.fetch(new Request(shellUrl.toString(), {
+                            method: 'GET',
+                            headers: request.headers,
+                        }));
+                    }
+                    return new Response('<!DOCTYPE html><meta http-equiv="refresh" content="0; url=/"><title>Nimbus</title>', { status: 200, headers: { 'Content-Type': 'text/html; charset=utf-8' } });
+                }
+                // Best-effort fire onSessionStart on WebSocket upgrade. Hooks
+                // never block: schedule via ctx.waitUntil.
+                if (hooks.onSessionStart && request.headers.get('Upgrade') === 'websocket') {
+                    try {
+                        const p = Promise.resolve(hooks.onSessionStart({
+                            tenantSegment,
+                            sessionId: route.sessionId,
+                            request,
+                            env,
+                        })).catch((e) => console.warn('[nimbus] onSessionStart hook threw:', e?.stack || e));
+                        ctx?.waitUntil?.(p);
+                    }
+                    catch (e) {
+                        console.warn('[nimbus] onSessionStart hook threw synchronously:', e);
+                    }
+                }
+                return forwardToSession(request, route, env, { tenantSegment });
+            }
+            // ── Back-compat legacy root paths → landing page ────────────────
+            if (isLegacyRootPath(url.pathname)) {
+                return new Response(null, {
+                    status: 302,
+                    headers: { Location: '/', 'Cache-Control': 'no-store' },
+                });
+            }
+            return new Response('Not found', { status: 404 });
+        },
+    };
+}
+// ── Internal helpers ─────────────────────────────────────────────────────
+const LEGACY_ROOT_PATHS = ['/ws', '/api/', '/preview', '/worker', '/__nimbus/', '/port/'];
+function isLegacyRootPath(pathname) {
+    for (const p of LEGACY_ROOT_PATHS) {
+        if (p.endsWith('/')) {
+            if (pathname.startsWith(p))
+                return true;
+        }
+        else {
+            if (pathname === p || pathname.startsWith(p + '/'))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Decide which tenant segment to use for DO naming. Returns either the
+ * segment string or a short-circuit Response (auth failure).
+ *
+ * Mode `'auto'`:
+ *   - If JWT_SECRET is set AND legacy env var not "1" → enforce verify.
+ *   - Otherwise → legacy public.
+ *
+ * Mode `'enforce'`: always verify; 401 on missing/invalid token.
+ *
+ * Mode `'legacy'`: always legacy public.
+ */
+async function resolveTenantSegment(request, env, explicitMode) {
+    const envLegacyFlag = (env?.NIMBUS_LEGACY_PUBLIC === '1' || env?.NIMBUS_LEGACY_PUBLIC === true);
+    const hasSecret = typeof env?.JWT_SECRET === 'string' && env.JWT_SECRET.length > 0;
+    const mode = explicitMode
+        ?? (hasSecret && !envLegacyFlag ? 'enforce' : 'legacy');
+    if (mode === 'legacy')
+        return LEGACY_PUBLIC_DO_SEGMENT;
+    if (!hasSecret) {
+        // Enforce mode but no secret — config error. 500, no info leak.
+        console.error('[nimbus] auth.mode="enforce" but JWT_SECRET is missing');
+        return new Response(JSON.stringify({ error: 'Server auth misconfigured', code: 'E_AUTH_CONFIG_MISSING' }), { status: 500, headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' } });
+    }
+    try {
+        const verified = await verifyRequestToken(request, env);
+        return verified.doInstanceName;
+    }
+    catch (e) {
+        if (e instanceof NimbusAuthError) {
+            return authErrorResponse(e);
+        }
+        if (e instanceof NimbusTokenMalformedError) {
+            return authErrorResponse(e);
+        }
+        console.error('[nimbus] unexpected auth error:', e);
+        return new Response(JSON.stringify({ error: 'Internal auth error', code: 'E_AUTH_UNKNOWN' }), { status: 500, headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' } });
+    }
+}

package/dist/runtime/assets-loader.d.ts

@@ -0,0 +1,71 @@
+/**
+ * runtime/assets-loader.ts — Lazy fetch of large static blobs from the
+ * ASSETS binding.
+ *
+ * Background: the Worker bundle ships ~9.8 MB of generated TypeScript
+ * blobs (cirrus-npm-cjs, cirrus-plugin-react, real-vite-bundle, ...).
+ * Inlining them at module-load doubles cold-start parse time and
+ * inflates deploy uploads. The ASSETS binding lets us serve them as
+ * static files (cached at the edge), fetched on first use, kept in a
+ * per-isolate cache for subsequent calls.
+ *
+ * Same pattern as `esbuild-wasm-bytes.ts` (proven in production —
+ * see esbuild-wasm-bundle.generated.ts header for history). We
+ * generalize it here so future asset promotions are one-line.
+ *
+ * @example a bundle script writes the big string to
+ * `public/_assets/cirrus-plugin-react.bundle.js` and emits a thin
+ * `.generated.ts` that re-exports {@link loadAssetText} bound to that
+ * path:
+ *
+ * ```ts
+ * // src/cirrus-plugin-react.generated.ts (post-promotion)
+ * import { loadAssetText } from './runtime/assets-loader.js';
+ * export const CIRRUS_PLUGIN_REACT_VERSION = "4.3.4";
+ * export const CIRRUS_PLUGIN_REACT_BUNDLE_PATH = '/_assets/cirrus-plugin-react.bundle.js';
+ * export async function getCirrusPluginReactBundle(env: { ASSETS: Fetcher }): Promise<string> {
+ *   return loadAssetText(env.ASSETS, CIRRUS_PLUGIN_REACT_BUNDLE_PATH);
+ * }
+ * ```
+ *
+ * Cache discipline: keyed by `${path}` (no env or origin in the key)
+ * because ASSETS is content-addressed at the deploy level — a redeploy
+ * generates new asset bundles and the new isolate sees no stale cache.
+ * Within a single isolate's lifetime, the same path always returns the
+ * same content.
+ */
+/**
+ * Asset fetch error. Thrown when ASSETS binding is missing or returns
+ * a non-200.
+ */
+export declare class NimbusAssetLoadError extends Error {
+    readonly code: 'E_ASSETS_BINDING_MISSING' | 'E_ASSET_NOT_FOUND' | 'E_ASSET_FETCH_FAILED';
+    readonly status?: number;
+    readonly path: string;
+    constructor(message: string, code: NimbusAssetLoadError['code'], path: string, status?: number);
+}
+/** Minimal fetcher shape so callers don't need to import a Cloudflare type. */
+export interface AssetsFetcher {
+    fetch(input: RequestInfo, init?: RequestInit): Promise<Response>;
+}
+/**
+ * Load an asset's bytes by path. Subsequent calls in the same isolate
+ * return from cache.
+ *
+ * @param assets `env.ASSETS` binding.
+ * @param path Asset path (e.g. `/_assets/foo.bin`). Leading `/`
+ *             required.
+ * @throws {NimbusAssetLoadError} on binding missing or non-2xx.
+ */
+export declare function loadAssetBytes(assets: AssetsFetcher | undefined, path: string): Promise<Uint8Array>;
+/**
+ * Load an asset as a UTF-8 string. Same caching discipline as
+ * {@link loadAssetBytes}.
+ */
+export declare function loadAssetText(assets: AssetsFetcher | undefined, path: string): Promise<string>;
+/**
+ * Test-only: drop the per-isolate cache. Real isolates never call this;
+ * the cache exists for the isolate's lifetime.
+ */
+export declare function _resetAssetsCacheForTests(): void;
+//# sourceMappingURL=assets-loader.d.ts.map

package/dist/runtime/assets-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets-loader.d.ts","sourceRoot":"","sources":["../../src/runtime/assets-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAUH;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,0BAA0B,GAAG,mBAAmB,GAAG,sBAAsB,CAAC;IACzF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEpB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,EAClC,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM;CAQlB;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAClE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,UAAU,CAAC,CAwCrB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,CAoCjB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAGhD"}

package/dist/runtime/assets-loader.js

@@ -0,0 +1,128 @@
+/**
+ * runtime/assets-loader.ts — Lazy fetch of large static blobs from the
+ * ASSETS binding.
+ *
+ * Background: the Worker bundle ships ~9.8 MB of generated TypeScript
+ * blobs (cirrus-npm-cjs, cirrus-plugin-react, real-vite-bundle, ...).
+ * Inlining them at module-load doubles cold-start parse time and
+ * inflates deploy uploads. The ASSETS binding lets us serve them as
+ * static files (cached at the edge), fetched on first use, kept in a
+ * per-isolate cache for subsequent calls.
+ *
+ * Same pattern as `esbuild-wasm-bytes.ts` (proven in production —
+ * see esbuild-wasm-bundle.generated.ts header for history). We
+ * generalize it here so future asset promotions are one-line.
+ *
+ * @example a bundle script writes the big string to
+ * `public/_assets/cirrus-plugin-react.bundle.js` and emits a thin
+ * `.generated.ts` that re-exports {@link loadAssetText} bound to that
+ * path:
+ *
+ * ```ts
+ * // src/cirrus-plugin-react.generated.ts (post-promotion)
+ * import { loadAssetText } from './runtime/assets-loader.js';
+ * export const CIRRUS_PLUGIN_REACT_VERSION = "4.3.4";
+ * export const CIRRUS_PLUGIN_REACT_BUNDLE_PATH = '/_assets/cirrus-plugin-react.bundle.js';
+ * export async function getCirrusPluginReactBundle(env: { ASSETS: Fetcher }): Promise<string> {
+ *   return loadAssetText(env.ASSETS, CIRRUS_PLUGIN_REACT_BUNDLE_PATH);
+ * }
+ * ```
+ *
+ * Cache discipline: keyed by `${path}` (no env or origin in the key)
+ * because ASSETS is content-addressed at the deploy level — a redeploy
+ * generates new asset bundles and the new isolate sees no stale cache.
+ * Within a single isolate's lifetime, the same path always returns the
+ * same content.
+ */
+/**
+ * Per-isolate cache. Keys are asset paths (e.g. `/_assets/foo.js`).
+ * Values are settled promises so concurrent callers share the same
+ * fetch.
+ */
+const __assetTextCache = new Map();
+const __assetBytesCache = new Map();
+/**
+ * Asset fetch error. Thrown when ASSETS binding is missing or returns
+ * a non-200.
+ */
+export class NimbusAssetLoadError extends Error {
+    code;
+    status;
+    path;
+    constructor(message, code, path, status) {
+        super(message);
+        this.name = 'NimbusAssetLoadError';
+        this.code = code;
+        this.path = path;
+        this.status = status;
+    }
+}
+/**
+ * Load an asset's bytes by path. Subsequent calls in the same isolate
+ * return from cache.
+ *
+ * @param assets `env.ASSETS` binding.
+ * @param path Asset path (e.g. `/_assets/foo.bin`). Leading `/`
+ *             required.
+ * @throws {NimbusAssetLoadError} on binding missing or non-2xx.
+ */
+export function loadAssetBytes(assets, path) {
+    if (!assets || typeof assets.fetch !== 'function') {
+        return Promise.reject(new NimbusAssetLoadError(`ASSETS binding missing — cannot load ${path}. Did you forget the assets.binding=ASSETS in wrangler.jsonc?`, 'E_ASSETS_BINDING_MISSING', path));
+    }
+    const cached = __assetBytesCache.get(path);
+    if (cached)
+        return cached;
+    const promise = (async () => {
+        // ASSETS.fetch requires an absolute URL, but the origin is ignored
+        // — it just routes by pathname. Use a stable sentinel origin.
+        const url = `https://assets.invalid${path}`;
+        const r = await assets.fetch(url);
+        if (r.status === 404) {
+            throw new NimbusAssetLoadError(`Asset not found: ${path}`, 'E_ASSET_NOT_FOUND', path, 404);
+        }
+        if (!r.ok) {
+            throw new NimbusAssetLoadError(`Asset fetch failed: ${path} → ${r.status}`, 'E_ASSET_FETCH_FAILED', path, r.status);
+        }
+        const buf = await r.arrayBuffer();
+        return new Uint8Array(buf);
+    })();
+    __assetBytesCache.set(path, promise);
+    // Evict on failure so subsequent calls retry.
+    promise.catch(() => __assetBytesCache.delete(path));
+    return promise;
+}
+/**
+ * Load an asset as a UTF-8 string. Same caching discipline as
+ * {@link loadAssetBytes}.
+ */
+export function loadAssetText(assets, path) {
+    if (!assets || typeof assets.fetch !== 'function') {
+        return Promise.reject(new NimbusAssetLoadError(`ASSETS binding missing — cannot load ${path}. Did you forget the assets.binding=ASSETS in wrangler.jsonc?`, 'E_ASSETS_BINDING_MISSING', path));
+    }
+    const cached = __assetTextCache.get(path);
+    if (cached)
+        return cached;
+    const promise = (async () => {
+        const url = `https://assets.invalid${path}`;
+        const r = await assets.fetch(url);
+        if (r.status === 404) {
+            throw new NimbusAssetLoadError(`Asset not found: ${path}`, 'E_ASSET_NOT_FOUND', path, 404);
+        }
+        if (!r.ok) {
+            throw new NimbusAssetLoadError(`Asset fetch failed: ${path} → ${r.status}`, 'E_ASSET_FETCH_FAILED', path, r.status);
+        }
+        return r.text();
+    })();
+    __assetTextCache.set(path, promise);
+    promise.catch(() => __assetTextCache.delete(path));
+    return promise;
+}
+/**
+ * Test-only: drop the per-isolate cache. Real isolates never call this;
+ * the cache exists for the isolate's lifetime.
+ */
+export function _resetAssetsCacheForTests() {
+    __assetTextCache.clear();
+    __assetBytesCache.clear();
+}