@braidlabs/sw 0.7.0 → 0.8.0

package/src/lib/fragment-caches.js

@@ -0,0 +1,100 @@
+/**
+ * Where a fragment's cached files live: one Cache Storage cache per fragment (`braid-frag:<id>`),
+ * or, with `buckets: true` where the browser has Storage Buckets (Chromium), that same cache inside
+ * a bucket of the fragment's own.
+ *
+ * A bucket is the browser's unit of eviction, quota and deletion. In one shared Cache Storage, a
+ * device short on space can evict every fragment's files at once, and the deploy-skew save — the
+ * chunk an old page still asks for after a deploy — goes with them. Per-fragment buckets are evicted
+ * one fragment at a time, and pruning a fragment that left the registry deletes its bucket outright.
+ *
+ * Opt-in: turning it on moves where files are kept, so a worker that switches starts with empty
+ * fragment caches once (pruning removes the old ones).
+ */
+/** The per-fragment cache prefix, unless a worker names its own. */
+export const DEFAULT_CACHE_PREFIX = 'braid-frag';
+/** The cache a fragment's files are kept in, or undefined where there is no cache storage. */
+export async function openFragmentCache(fragmentId, options = {}) {
+    const name = `${options.cachePrefix ?? DEFAULT_CACHE_PREFIX}:${fragmentId}`;
+    const buckets = bucketsOf(options);
+    if (buckets) {
+        try {
+            return await (await buckets.open(bucketFor(fragmentId, options))).caches.open(name);
+        }
+        catch {
+            // refused (quota policy, an unsupported context): the shared cache storage still works
+        }
+    }
+    return (options.caches ?? globalThis.caches)?.open(name);
+}
+/**
+ * Deletes the fragment buckets this worker's prefix made, except those for `keep` (all of them when
+ * null). Only names in this worker's exact format: buckets are the whole origin's, and a looser match
+ * would take the realm's database buckets (`braid-db-…`), another worker's, or the app's own.
+ *
+ * `always` deletes even when `buckets` is off, where the API exists: sign-out must not leave a
+ * previous configuration's buckets, which may hold a previous user's offline documents.
+ */
+export async function deleteFragmentBuckets(keep, options = {}, { always = false } = {}) {
+    const buckets = always ? bucketManager(options) : bucketsOf(options);
+    if (!buckets)
+        return [];
+    const format = new RegExp(`^${escapeRegExp(bucketPrefix(options))}_[a-z0-9-]{1,25}_[0-9a-f]{8}$`);
+    const kept = new Set((keep ?? []).map((id) => bucketFor(id, options)));
+    const deleted = [];
+    for (const name of await buckets.keys()) {
+        if (!format.test(name) || kept.has(name))
+            continue;
+        await buckets.delete(name);
+        deleted.push(name);
+    }
+    return deleted;
+}
+/** Whether this worker keeps fragment caches in buckets: asked for, and available. */
+export function usesBuckets(options) {
+    return bucketsOf(options) !== undefined;
+}
+/** The fragments among `keep` whose bucket exists, so their shared caches are superseded. */
+export async function keptWithBuckets(keep, options) {
+    const buckets = bucketsOf(options);
+    if (!buckets)
+        return [];
+    const existing = new Set(await buckets.keys());
+    return keep.filter((id) => existing.has(bucketFor(id, options)));
+}
+function bucketsOf(options) {
+    return options.buckets ? bucketManager(options) : undefined;
+}
+function bucketManager(options) {
+    return options.storageBuckets ?? globalThis.navigator?.storageBuckets;
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * A fragment's bucket name: lowercase letters, digits, `-` and `_`, at most 64 characters, as the
+ * API requires. The readable part may collide once folded; the hash of the exact id keeps two
+ * fragments apart.
+ */
+export function bucketFor(fragmentId, options = {}) {
+    return `${bucketPrefix(options)}_${slug(fragmentId, 25)}_${fnv1a(fragmentId)}`;
+}
+/**
+ * `braid-sw_` and the cache prefix: a namespace the realm's database buckets (`braid-db_`) never use.
+ * Underscores delimit and slugs never contain one, so one prefix's names cannot be read as another's.
+ */
+function bucketPrefix(options) {
+    return `braid-sw_${slug(options.cachePrefix ?? DEFAULT_CACHE_PREFIX, 20)}`;
+}
+function slug(text, length) {
+    return text.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, length) || 'x';
+}
+function fnv1a(text) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, '0');
+}
+//# sourceMappingURL=fragment-caches.js.map

package/src/lib/fragment-caches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragment-caches.js","sourceRoot":"","sources":["../../../../../libs/braid-sw/src/lib/fragment-caches.ts"],"names":[],"mappings":"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"}

package/src/lib/gateway.d.ts

@@ -0,0 +1,92 @@
+import { type BraidGateway, type GatewayOptions } from '@braidlabs/gateway';
+import { type BraidFetchHandlerOptions } from './asset-handler.js';
+/**
+ * The gateway itself, run inside the worker: composition for an origin that has no server to put
+ * a gateway on — static hosting, a CDN bucket, a shell someone else deploys.
+ *
+ * Not a second gateway. The gateway core is runtime-neutral, so this is the same `createGateway`
+ * the server runs, given the network as its shell. What this module adds is what a worker needs
+ * and a server does not: a decision, made synchronously, about which requests to answer — a
+ * `fetch` listener must call `respondWith` before it returns, long before the gateway knows
+ * whether a page will pierce.
+ *
+ * Two things carry over differently from a server, and both are the browser's rules rather than
+ * this module's. The worker's `fetch` cannot set forbidden headers, so `Cookie` is not forwarded
+ * by name — a same-origin endpoint gets the browser's own cookies, a cross-origin one none, as
+ * for the page's own requests. And a cross-origin endpoint must answer CORS at all, because the
+ * worker reads the response it pierces.
+ */
+/** The gateway's options, less the one that would have the worker serve a worker. */
+export type BraidGatewayHandlerOptions = Omit<GatewayOptions, 'serviceWorker'>;
+export interface BraidGatewayHandler {
+    /**
+     * Answers a request the gateway owns, or returns `null` — synchronously — for one it leaves to
+     * the browser. Pass the event's `preloadResponse` and a navigation's shell is the preloaded one;
+     * a worker that turns preload on should know the browser preloads realm frames too, which this
+     * answers itself, so each also reaches the server.
+     */
+    (request: Request, preloadResponse?: Promise<Response | undefined>): Promise<Response> | null;
+    /**
+     * Any request through the gateway, the network behind it. Hand this to {@link braidFetchHandler}
+     * as its `fetch` and the skew cache sits in front of the in-worker gateway, as it would sit in
+     * front of a server one. Unlike the handler it claims nothing: whatever it is given, it routes.
+     */
+    readonly fetch: typeof fetch;
+    readonly gateway: BraidGateway;
+    /** Whether the handler would claim this request, decided as the handler decides it. */
+    claims(request: Request): boolean;
+}
+/**
+ * Builds the in-worker gateway, to compose into a worker you already own.
+ *
+ * ```js
+ * import { braidGatewayHandler } from '@braidlabs/sw/gateway';
+ *
+ * const braid = braidGatewayHandler({ registry: [{ id: 'billing', endpoint: '/billing-app/', pierce: ['/billing/*'] }] });
+ * self.addEventListener('fetch', (event) => {
+ *   const handled = braid(event.request, event.preloadResponse);
+ *   if (handled) event.respondWith(handled);
+ * });
+ * ```
+ *
+ * Claims a same-origin request in the Braid namespace (under `basePath`, when set), and every GET
+ * navigation — whether a page pierces is the registry's answer, and it arrives too late to decide
+ * on. A navigation no fragment claims goes to the network unchanged, and so does a shell that
+ * answers with a redirect.
+ */
+export declare function braidGatewayHandler(options: BraidGatewayHandlerOptions): BraidGatewayHandler;
+export interface BraidGatewayWorkerOptions extends BraidGatewayHandlerOptions {
+    /**
+     * Keep fragment assets in build-keyed partitions, as {@link braidFetchHandler} does, in front of
+     * the in-worker gateway. Off by default. Not yet supported together with `basePath`, where the
+     * asset handler would not recognise the namespace and cache nothing; combining them throws.
+     */
+    assets?: Omit<BraidFetchHandlerOptions, 'fetch'>;
+    /**
+     * Take over open pages as soon as this worker activates, so the page that installed it composes
+     * without a reload — and answer a page that asks to be claimed, which is how a page loaded with
+     * the worker bypassed (a hard reload) gets it back. Off by default, for the reason it is off in
+     * `setupBraidWorker`: a page mid-session starts being served by a worker it did not load against.
+     */
+    claimClients?: boolean;
+    /**
+     * Declare at install, where the browser supports it (Chromium's static routing), that requests
+     * this worker does not answer go straight to the network, so they never start it. On by default:
+     * this is the whole worker. Turn it off if the same worker file adds its own `fetch` listener,
+     * which the routes would bypass.
+     */
+    staticRoutes?: boolean;
+}
+/** The message a page posts to an active worker that is not controlling it. */
+export declare const BRAID_CLAIM_MESSAGE = "braid-sw:claim";
+/**
+ * Installs the in-worker gateway as the whole worker, and returns the gateway it runs — the one
+ * thing a worker built this way might still want to reach, for `refreshRegistry()` say.
+ *
+ * ```js
+ * // sw.js
+ * import { setupBraidGateway } from '@braidlabs/sw/gateway';
+ * setupBraidGateway({ registry: [{ id: 'billing', endpoint: '/billing-app/', pierce: ['/billing/*'] }] });
+ * ```
+ */
+export declare function setupBraidGateway(options: BraidGatewayWorkerOptions): BraidGateway;

package/src/lib/gateway.js

@@ -0,0 +1,164 @@
+import { createGateway, toFetchHandler, toWebMiddleware, } from '@braidlabs/gateway';
+import { braidFetchHandler, } from './asset-handler.js';
+import { addStaticRoutes, patternLiteral, } from './static-routes.js';
+/**
+ * Builds the in-worker gateway, to compose into a worker you already own.
+ *
+ * ```js
+ * import { braidGatewayHandler } from '@braidlabs/sw/gateway';
+ *
+ * const braid = braidGatewayHandler({ registry: [{ id: 'billing', endpoint: '/billing-app/', pierce: ['/billing/*'] }] });
+ * self.addEventListener('fetch', (event) => {
+ *   const handled = braid(event.request, event.preloadResponse);
+ *   if (handled) event.respondWith(handled);
+ * });
+ * ```
+ *
+ * Claims a same-origin request in the Braid namespace (under `basePath`, when set), and every GET
+ * navigation — whether a page pierces is the registry's answer, and it arrives too late to decide
+ * on. A navigation no fragment claims goes to the network unchanged, and so does a shell that
+ * answers with a redirect.
+ */
+export function braidGatewayHandler(options) {
+    const gateway = createGateway(options);
+    const namespace = namespaceOf(options.basePath);
+    const network = (request) => globalThis.fetch(request);
+    const viaGateway = toFetchHandler(gateway, network);
+    const compose = toWebMiddleware(gateway);
+    const claims = (request) => {
+        const url = new URL(request.url);
+        // `location` is the worker's own; without one (a test, a non-worker runtime) there is no
+        // origin to compare against, and nothing to leave to a browser either
+        const origin = globalThis.location
+            ?.origin;
+        if (origin !== undefined && url.origin !== origin)
+            return false;
+        return (url.pathname.startsWith(namespace) ||
+            (request.method === 'GET' && isNavigation(request)));
+    };
+    const handler = (request, preloadResponse) => {
+        if (!claims(request))
+            return null;
+        if (new URL(request.url).pathname.startsWith(namespace))
+            return asGatewayRequest(request).then(viaGateway);
+        // The shell is the browser's own navigation — preloaded while the worker booted, when it was,
+        // and asked for again if the preload failed — and the gateway gets a copy it can derive
+        // fragment requests from.
+        const shell = () => Promise.resolve(preloadResponse).then((preloaded) => preloaded ?? network(request), () => network(request));
+        return asGatewayRequest(request).then((copy) => compose(copy, shell));
+    };
+    const fetchViaGateway = (input, init) => asGatewayRequest(input instanceof Request && init === undefined
+        ? input
+        : new Request(input, init)).then(viaGateway);
+    return Object.assign(handler, {
+        fetch: fetchViaGateway,
+        gateway,
+        claims,
+    });
+}
+/** The message a page posts to an active worker that is not controlling it. */
+export const BRAID_CLAIM_MESSAGE = 'braid-sw:claim';
+/**
+ * Installs the in-worker gateway as the whole worker, and returns the gateway it runs — the one
+ * thing a worker built this way might still want to reach, for `refreshRegistry()` say.
+ *
+ * ```js
+ * // sw.js
+ * import { setupBraidGateway } from '@braidlabs/sw/gateway';
+ * setupBraidGateway({ registry: [{ id: 'billing', endpoint: '/billing-app/', pierce: ['/billing/*'] }] });
+ * ```
+ */
+export function setupBraidGateway(options) {
+    const scope = globalThis;
+    const { assets, claimClients, staticRoutes = true, ...gatewayOptions } = options;
+    if (assets && gatewayOptions.basePath) {
+        throw new Error('braid-sw: `assets` is not yet supported together with `basePath`');
+    }
+    const braid = braidGatewayHandler(gatewayOptions);
+    const cached = assets
+        ? braidFetchHandler({ ...assets, fetch: braid.fetch })
+        : null;
+    if (staticRoutes) {
+        scope.addEventListener('install', (event) => {
+            // exactly what `braid.claims` answers: this origin's namespace, and every GET navigation
+            const routed = addStaticRoutes(event, {
+                pathnames: [`${patternLiteral(namespaceOf(gatewayOptions.basePath))}*`],
+                origin: globalThis.location?.origin,
+                navigations: true,
+            });
+            if (routed)
+                event.waitUntil?.(routed);
+        });
+    }
+    scope.addEventListener('activate', (event) => {
+        // Off, though every navigation passes through: the browser preloads *every* navigation in
+        // scope, the realm frames this worker answers itself among them, so each would also reach a
+        // server that has no answer for it. And the setting outlives the worker that set it.
+        const work = [
+            scope.registration?.navigationPreload?.disable().catch(() => undefined) ??
+                Promise.resolve(),
+        ];
+        if (claimClients && scope.clients)
+            work.push(scope.clients.claim());
+        event.waitUntil?.(Promise.all(work));
+    });
+    scope.addEventListener('message', (event) => {
+        if (!claimClients ||
+            event.data?.type !==
+                BRAID_CLAIM_MESSAGE)
+            return;
+        if (scope.clients)
+            event.waitUntil?.(scope.clients.claim());
+    });
+    scope.addEventListener('fetch', (event) => {
+        // the claim decision first: the asset cache matches by path alone, on any origin
+        if (!braid.claims(event.request))
+            return;
+        const handled = cached?.(event.request) ?? braid(event.request, event.preloadResponse);
+        if (handled)
+            event.respondWith?.(handled);
+    });
+    return braid.gateway;
+}
+/**
+ * A navigation, as a request the gateway can build its own from.
+ *
+ * The gateway derives each fragment request with `new Request(url, request)`, which a browser
+ * refuses for a `navigate`-mode request — and the gateway, catching that, would serve every
+ * pierced slot as a placeholder. A server never sees that mode, so only a worker has to do this.
+ *
+ * Credentials go as a page's own `fetch` sends them, same-origin only, rather than as the
+ * navigation's `include`: a pierce must not be a credentialed CORS request where the page's own
+ * requests for the same fragment are not. A body is read up front, since a browser streams a
+ * request body only over HTTP/2.
+ */
+async function asGatewayRequest(request) {
+    if (request.mode !== 'navigate')
+        return request;
+    const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
+    return new Request(request.url, {
+        method: request.method,
+        headers: request.headers,
+        credentials: 'same-origin',
+        // `only-if-cached` is refused outside same-origin mode, which a copy cannot have
+        cache: request.cache === 'only-if-cached' ? 'default' : request.cache,
+        redirect: request.redirect,
+        referrer: request.referrer,
+        referrerPolicy: request.referrerPolicy,
+        signal: request.signal,
+        ...(hasBody ? { body: await request.arrayBuffer() } : {}),
+    });
+}
+/** The Braid namespace under a base path, as the gateway trims it (it has already refused a malformed one). */
+function namespaceOf(basePath) {
+    return `${(basePath ?? '').replace(/\/+$/, '')}/__braid/`;
+}
+/**
+ * Only the browser's own navigations. A page's `fetch` with an HTML `Accept` (htmx, Turbo, a
+ * prefetch) is a fetch, and the gateway — which in a worker cannot see `Sec-Fetch-Dest` — would
+ * otherwise pierce it as a document.
+ */
+function isNavigation(request) {
+    return request.mode === 'navigate';
+}
+//# sourceMappingURL=gateway.js.map

package/src/lib/gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.js","sourceRoot":"","sources":["../../../../../libs/braid-sw/src/lib/gateway.ts"],"names":[],"mappings":"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"}

package/src/lib/precache.d.ts

@@ -1,3 +1,4 @@
+import { type FragmentCacheOptions } from './fragment-caches.js';
 /**
  * Realm stub precaching: a fragment boot with no round trip in it.
  *
@@ -9,9 +10,7 @@
  * mean downloading every fragment on the origin whether or not the user ever visits a page that
  * composes them, which trades a round trip the user might make for bandwidth they certainly spend.
  */
-export interface PrecacheOptions {
-    cachePrefix?: string;
-    caches?: CacheStorage;
+export interface PrecacheOptions extends FragmentCacheOptions {
     fetch?: typeof fetch;
     /** Where the stubs live. Defaults to the current origin. */
     origin?: string;

package/src/lib/precache.js

@@ -1,4 +1,5 @@
 import { BRAID_REALM_PREFIX } from '@braidlabs/gateway';
+import { openFragmentCache } from './fragment-caches.js';
 const DEFAULT_CACHE_PREFIX = 'braid-frag';
 /**
  * Fetches and caches each fragment's realm stub.
@@ -23,7 +24,9 @@ export async function precacheRealmStubs(fragmentIds, options = {}) {
                 result.failed.push({ url, reason: `HTTP ${response.status}` });
                 continue;
             }
-            const cache = await cacheStorage.open(`${cachePrefix}:${fragmentId}`);
+            const cache = await openFragmentCache(fragmentId, options);
+            if (!cache)
+                continue;
             await cache.put(url, response);
             result.cached.push(url);
         }

package/src/lib/precache.js.map

@@ -1 +1 @@
-{"version":3,"file":"precache.js","sourceRoot":"","sources":["../../../../../libs/braid-sw/src/lib/precache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AA4BxD,MAAM,oBAAoB,GAAG,YAAY,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,WAA8B,EAC9B,UAA2B,EAAE;IAE7B,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,oBAAoB,CAAC;IAChE,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,IAAK,UAAwC,CAAC,MAAM,CAAC;IACxF,MAAM,YAAY,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IACvD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAK,UAAgD,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,CAAC;IAE1G,MAAM,MAAM,GAAmB,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAC1D,IAAI,CAAC,YAAY;QAAE,OAAO,MAAM,CAAC;IAEjC,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,GAAG,MAAM,GAAG,kBAAkB,GAAG,UAAU,GAAG,CAAC;QAC3D,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC;YACzC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;gBAC/D,SAAS;YACX,CAAC;YACD,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,GAAG,WAAW,IAAI,UAAU,EAAE,CAAC,CAAC;YACtE,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YAC/B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC9F,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"precache.js","sourceRoot":"","sources":["../../../../../libs/braid-sw/src/lib/precache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAA6B,MAAM,sBAAsB,CAAC;AA0BpF,MAAM,oBAAoB,GAAG,YAAY,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,WAA8B,EAC9B,UAA2B,EAAE;IAE7B,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,oBAAoB,CAAC;IAChE,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,IAAK,UAAwC,CAAC,MAAM,CAAC;IACxF,MAAM,YAAY,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IACvD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAK,UAAgD,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,CAAC;IAE1G,MAAM,MAAM,GAAmB,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAC1D,IAAI,CAAC,YAAY;QAAE,OAAO,MAAM,CAAC;IAEjC,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,GAAG,MAAM,GAAG,kBAAkB,GAAG,UAAU,GAAG,CAAC;QAC3D,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC;YACzC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;gBAC/D,SAAS;YACX,CAAC;YACD,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;YAC3D,IAAI,CAAC,KAAK;gBAAE,SAAS;YACrB,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YAC/B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC9F,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/src/lib/static-routes.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Install-time routes: the Service Worker Static Routing API (`InstallEvent.addRoutes`, Chromium).
+ *
+ * A worker with a `fetch` listener is started for every request in its scope, including the ones
+ * its listener then lets pass: the shell's own scripts, images and API calls each wait on a worker
+ * that has nothing to say about them. Routes declared at install let the browser decide without
+ * the worker, so only what the worker actually answers starts it.
+ *
+ * The routes have to say exactly what the worker's listener claims, no more and no less. A route
+ * that sends a claimed request to the network bypasses the worker; one that sends an unclaimed
+ * request to the listener only costs what it costs today. So everything a worker claims is listed
+ * as `fetch-event`, and the network takes the rest.
+ *
+ * Every other `fetch` listener in the same worker is bypassed too, which is why a worker that may
+ * share its file with an application's own listener only does this when asked.
+ */
+/** What a worker answers, as its `fetch` listener decides it. */
+export interface ClaimedRequests {
+    /** Pathname patterns (URLPattern syntax) the worker answers, e.g. `/__braid/*`. */
+    pathnames: readonly string[];
+    /** The origin those pathnames are answered on; any origin when absent. */
+    origin?: string;
+    /** Answer only GET requests under those pathnames. */
+    getOnly?: boolean;
+    /** Whether the worker answers GET navigations, wherever they go. */
+    navigations: boolean;
+}
+/** A condition and source as `addRoutes` takes them. */
+export interface StaticRoute {
+    condition: {
+        urlPattern?: unknown;
+        requestMethod?: string;
+        requestMode?: string;
+    };
+    source: 'network' | 'fetch-event';
+}
+/** The slice of `InstallEvent` used here. */
+export interface RoutableInstallEvent {
+    addRoutes?(rules: StaticRoute | readonly StaticRoute[]): Promise<void>;
+}
+/**
+ * The rules for a worker that answers `claimed`, in the order the browser evaluates them: the
+ * first match wins, so the worker's own requests come first and the catch-all last. Null where
+ * `URLPattern` is missing, since every rule needs one.
+ */
+export declare function staticRoutesFor(claimed: ClaimedRequests): StaticRoute[] | null;
+/**
+ * Registers the routes for `claimed` on an install event, where the browser supports them.
+ *
+ * Returns the registration to wait on, or undefined where there is nothing to do. A browser that
+ * refuses the rules leaves the worker exactly as it was without them — started for everything,
+ * deciding in its listener — so a refusal is a warning, never a failed install.
+ */
+export declare function addStaticRoutes(event: RoutableInstallEvent, claimed: ClaimedRequests): Promise<void> | undefined;
+/** A path prefix as a literal in URLPattern syntax, so a base path is matched as written. */
+export declare function patternLiteral(path: string): string;

package/src/lib/static-routes.js

@@ -0,0 +1,76 @@
+/**
+ * Install-time routes: the Service Worker Static Routing API (`InstallEvent.addRoutes`, Chromium).
+ *
+ * A worker with a `fetch` listener is started for every request in its scope, including the ones
+ * its listener then lets pass: the shell's own scripts, images and API calls each wait on a worker
+ * that has nothing to say about them. Routes declared at install let the browser decide without
+ * the worker, so only what the worker actually answers starts it.
+ *
+ * The routes have to say exactly what the worker's listener claims, no more and no less. A route
+ * that sends a claimed request to the network bypasses the worker; one that sends an unclaimed
+ * request to the listener only costs what it costs today. So everything a worker claims is listed
+ * as `fetch-event`, and the network takes the rest.
+ *
+ * Every other `fetch` listener in the same worker is bypassed too, which is why a worker that may
+ * share its file with an application's own listener only does this when asked.
+ */
+/**
+ * The rules for a worker that answers `claimed`, in the order the browser evaluates them: the
+ * first match wins, so the worker's own requests come first and the catch-all last. Null where
+ * `URLPattern` is missing, since every rule needs one.
+ */
+export function staticRoutesFor(claimed) {
+    const Pattern = globalThis.URLPattern;
+    if (!Pattern)
+        return null;
+    const rules = claimed.pathnames.map((pathname) => ({
+        condition: {
+            urlPattern: new Pattern({ pathname, ...(claimed.origin === undefined ? {} : { baseURL: claimed.origin }) }),
+            ...(claimed.getOnly ? { requestMethod: 'GET' } : {}),
+        },
+        source: 'fetch-event',
+    }));
+    if (claimed.navigations) {
+        // A worker only ever sees navigations into its own scope, so the origin is belt and braces:
+        // it keeps the rule saying exactly what the listener does. Through `baseURL`, which escapes
+        // what it takes, so an IPv6 host (`[::1]`) is not read as pattern syntax.
+        rules.push({
+            condition: {
+                ...(claimed.origin === undefined ? {} : { urlPattern: new Pattern({ pathname: '*', baseURL: claimed.origin }) }),
+                requestMode: 'navigate',
+                requestMethod: 'GET',
+            },
+            source: 'fetch-event',
+        });
+    }
+    rules.push({ condition: { urlPattern: new Pattern({}) }, source: 'network' });
+    return rules;
+}
+/**
+ * Registers the routes for `claimed` on an install event, where the browser supports them.
+ *
+ * Returns the registration to wait on, or undefined where there is nothing to do. A browser that
+ * refuses the rules leaves the worker exactly as it was without them — started for everything,
+ * deciding in its listener — so a refusal is a warning, never a failed install.
+ */
+export function addStaticRoutes(event, claimed) {
+    if (typeof event.addRoutes !== 'function')
+        return undefined;
+    const warn = (error) => console.warn('braid-sw: static routes were not registered; every request will start the worker', error);
+    let rules;
+    try {
+        rules = staticRoutesFor(claimed);
+    }
+    catch (error) {
+        warn(error);
+        return undefined;
+    }
+    if (!rules)
+        return undefined;
+    return event.addRoutes(rules).catch(warn);
+}
+/** A path prefix as a literal in URLPattern syntax, so a base path is matched as written. */
+export function patternLiteral(path) {
+    return path.replace(/[\\:*?+(){}]/g, '\\$&');
+}
+//# sourceMappingURL=static-routes.js.map

package/src/lib/static-routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-routes.js","sourceRoot":"","sources":["../../../../../libs/braid-sw/src/lib/static-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA2BH;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAAwB;IACtD,MAAM,OAAO,GAAI,UAAqD,CAAC,UAAU,CAAC;IAClF,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAE1B,MAAM,KAAK,GAAkB,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAChE,SAAS,EAAE;YACT,UAAU,EAAE,IAAI,OAAO,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;YAC3G,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrD;QACD,MAAM,EAAE,aAAa;KACtB,CAAC,CAAC,CAAC;IACJ,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACxB,4FAA4F;QAC5F,4FAA4F;QAC5F,0EAA0E;QAC1E,KAAK,CAAC,IAAI,CAAC;YACT,SAAS,EAAE;gBACT,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,OAAO,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;gBAChH,WAAW,EAAE,UAAU;gBACvB,aAAa,EAAE,KAAK;aACrB;YACD,MAAM,EAAE,aAAa;SACtB,CAAC,CAAC;IACL,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,EAAE,UAAU,EAAE,IAAI,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IAC9E,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,KAA2B,EAAE,OAAwB;IACnF,IAAI,OAAO,KAAK,CAAC,SAAS,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC;IAC5D,MAAM,IAAI,GAAG,CAAC,KAAc,EAAE,EAAE,CAC9B,OAAO,CAAC,IAAI,CAAC,kFAAkF,EAAE,KAAK,CAAC,CAAC;IAC1G,IAAI,KAA2B,CAAC;IAChC,IAAI,CAAC;QACH,KAAK,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,KAAK,CAAC,CAAC;QACZ,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,OAAO,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;AAC/C,CAAC"}

package/src/lib/worker.d.ts

@@ -39,6 +39,16 @@ export interface BraidWorkerOptions extends BraidFetchHandlerOptions {
      * worth having: a user who hits a broken deploy is a user who closes the tab.
      */
     reports?: Omit<ReportQueueOptions, 'fetch'>;
+    /**
+     * Declare at install, where the browser supports it (Chromium's static routing), that requests
+     * this worker does not answer go straight to the network, so they never start it.
+     *
+     * Off by default: the routes bypass every `fetch` listener in the worker, including any the same
+     * file adds of its own. Turn it on when `setupBraidWorker` is the only thing listening. Ignored
+     * with `offline`, whose navigation handler also answers fetches for HTML, which no route can
+     * single out.
+     */
+    staticRoutes?: boolean;
 }
 /** The subset of the worker global this uses, so a test can supply one without a worker. */
 export interface WorkerScopeLike {

package/src/lib/worker.js

@@ -1,5 +1,7 @@
+import { BRAID_FRAGMENT_PREFIX, BRAID_REALM_PREFIX } from '@braidlabs/gateway';
 import { braidFetchHandler, pruneFragmentCaches } from './asset-handler.js';
-import { braidNavigationHandler } from './compose.js';
+import { addStaticRoutes } from './static-routes.js';
+import { braidNavigationHandler, clearBraidCaches } from './compose.js';
 import { precacheRealmStubs } from './precache.js';
 import { diagnoseSkew } from './skew-report.js';
 import { BRAID_REPORT_SYNC_TAG, createReportQueue } from './reports.js';
@@ -33,7 +35,25 @@ export function setupBraidWorker(options = {}) {
         ...(options.buildId === undefined ? {} : { buildId: options.buildId }),
         ...(options.snapshotId === undefined ? {} : { snapshotId: options.snapshotId }),
     };
+    const navigate = options.offline ? braidNavigationHandler({ ...options, ...options.offline }) : null;
     scope.addEventListener('install', (event) => {
+        if (options.staticRoutes && navigate) {
+            // Offline composition also answers a page's own fetch for HTML (htmx, Turbo), which a route
+            // cannot single out: it can match a request's mode, but not its Accept header. Routing the
+            // rest to the network would bypass those, so a worker that composes offline keeps no routes.
+            console.warn('braid-sw: staticRoutes is ignored with offline composition, which also answers fetches for HTML');
+        }
+        else if (options.staticRoutes) {
+            // exactly what the fetch listener answers: fragment assets and realm stubs on any origin, as
+            // `braidFetchHandler` matches them
+            const routed = addStaticRoutes(event, {
+                pathnames: [`${BRAID_FRAGMENT_PREFIX}*`, `${BRAID_REALM_PREFIX}*`],
+                getOnly: true,
+                navigations: false,
+            });
+            if (routed)
+                event.waitUntil?.(routed);
+        }
         if (!options.precache?.length)
             return;
         // The precache is best-effort by construction: a worker that refuses to install because one
@@ -44,7 +64,6 @@ export function setupBraidWorker(options = {}) {
             }
         }));
     });
-    const navigate = options.offline ? braidNavigationHandler({ ...options, ...options.offline }) : null;
     scope.addEventListener('activate', (event) => {
         const work = [];
         // A worker that handles navigations sits in front of every one of them, so without this each
@@ -91,6 +110,20 @@ export function setupBraidWorker(options = {}) {
      */
     scope.addEventListener('message', (event) => {
         const data = event.data;
+        // Sign-out: drop what offline composition kept, then say so, so the page can wait for it.
+        if (data?.type === 'braid-sw:clear') {
+            // The options composition itself writes with: `offline` overrides the top-level ones.
+            const composing = { ...options, ...options.offline };
+            const cleared = clearBraidCaches({
+                ...(composing.caches === undefined ? {} : { caches: composing.caches }),
+                ...(composing.cachePrefix === undefined ? {} : { cachePrefix: composing.cachePrefix }),
+                ...(composing.buckets === undefined ? {} : { buckets: composing.buckets }),
+            }).then(() => event.source?.postMessage?.({ type: 'braid-sw:cleared', ok: true }), 
+            // Answered either way, so a page waiting on the reply at sign-out is never left hanging.
+            () => event.source?.postMessage?.({ type: 'braid-sw:cleared', ok: false }));
+            event.waitUntil?.(cleared);
+            return;
+        }
         if (data?.type !== 'braid-sw:hello')
             return;
         const diagnosis = diagnoseSkew(version, data.page ?? {});