@braidlabs/gateway 0.1.1

package/src/rewriter/transforms.js

@@ -0,0 +1,312 @@
+import { BRAID_FRAGMENT_PREFIX } from '../protocol.js';
+import { concatStreams, rewriteHtmlStream } from './html-rewrite-stream.js';
+/**
+ * The composition protocol's HTML transforms, expressed against the owned rewriter.
+ *
+ * These are the normative behaviors a Braid gateway must implement; the conformance vectors in
+ * `transforms.spec.ts` are their oracle, and any second implementation (a native `HTMLRewriter`
+ * path on workerd, say) must pass the same vectors before it is allowed to serve traffic.
+ */
+/** The `<style>` the shell needs for slots and fragment stand-ins to lay out as blocks. */
+export const BRAID_SHELL_STYLES = '<style>fragment-slot { display: block; }</style>';
+/**
+ * The shell's CSP nonce, read from its own response headers.
+ *
+ * **The gateway injects inline markup into someone else's document**, and under a strict policy —
+ * `script-src 'nonce-…'`, `style-src 'nonce-…'` — anything without the right nonce is dropped
+ * silently by the browser. That is the worst possible failure shape: the page renders, the slot
+ * layout rule is gone, and nothing in the server logs mentions it.
+ *
+ * Reading the nonce off the shell's *own* CSP is the only correct source. Minting one here would
+ * be worse than useless: a nonce the shell's policy does not list is not trusted, and a nonce
+ * reused across responses is not a nonce. If the shell does not send a policy, or sends one
+ * without a nonce, this returns null and nothing is stamped — an unrestricted page needs no
+ * attribute, and a policy using hashes or `'unsafe-inline'` is not ours to second-guess.
+ */
+export function cspNonceOf(headers) {
+    const policy = headers.get('content-security-policy');
+    if (!policy)
+        return null;
+    // Only script-src and style-src matter here; those are the two directives governing what this
+    // layer injects. `default-src` counts when the specific directive is absent, per CSP fallback.
+    const match = /(?:^|;)\s*(?:script-src|style-src|default-src)[^;]*'nonce-([A-Za-z0-9+/_-]+=*)'/.exec(policy);
+    return match?.[1] ?? null;
+}
+/** Stamps a nonce onto generated inline markup. A no-op when the shell has no policy. */
+export function withNonce(markup, nonce) {
+    if (!nonce)
+        return markup;
+    return markup.replace(/<(script|style)(?=[\s>])/g, `<$1 nonce="${escapeAttribute(nonce)}"`);
+}
+/** The `<style>` that goes inside every fragment's shadow root. */
+export const BRAID_FRAGMENT_STYLES = '<style>:host, braid-document, braid-html, braid-body { display: block; } braid-head { display: none; }</style>';
+/**
+ * Inline event handler content attributes (`onclick`, `onerror`, …).
+ *
+ * Deliberately `on` + letters only: the browser compiles these into functions **in the document
+ * that owns the node**, which for fragment content is the host page — so they are a wrong-realm
+ * execution path. Framework binding syntaxes that merely look similar (`on-click`, `x-on:click`,
+ * `@click`, `(click)`) contain a non-letter and are left alone; they are interpreted by the
+ * fragment's own framework inside the fragment's realm, so removing them would break the app
+ * without buying any isolation.
+ */
+const INLINE_EVENT_HANDLER = /^on[a-z]+$/;
+/**
+ * Attributes that point at a **subresource** the fragment owns, per element.
+ *
+ * A fragment's markup ends up in the host page's DOM, so these URLs resolve against the *host*
+ * page rather than the fragment — `styles.css` on a host page at `/billing/invoices` would be
+ * fetched from `/billing/styles.css`, which belongs to the host. Rewriting them into the
+ * fragment's namespace is what makes "the fragment is served through the gateway" true for
+ * everything its markup references, not just the code the realm executes.
+ *
+ * Navigation targets (`a[href]`, `form[action]`, `area[href]`) are deliberately absent: those
+ * are page navigations, and in bound mode they belong to the host's URL space. `base[href]` is
+ * absent too — it is what the fragment's own router reads to know its base path, and rewriting
+ * it into the namespace would break routing.
+ */
+const SUBRESOURCE_ATTRIBUTES = {
+    audio: ['src'],
+    embed: ['src'],
+    iframe: ['src'],
+    img: ['src', 'srcset'],
+    input: ['src'],
+    link: ['href'],
+    object: ['data'],
+    script: ['src'],
+    source: ['src', 'srcset'],
+    track: ['src'],
+    use: ['href'],
+    video: ['src', 'poster'],
+};
+const SRCSET_ATTRIBUTES = new Set(['srcset']);
+/**
+ * Prepares a fragment's HTML for life inside the host page:
+ *
+ * - the doctype is stripped (a nested doctype makes some parsers choke, and it materializes
+ *   nothing in the DOM anyway);
+ * - `<html>`/`<head>`/`<body>` become `braid-html`/`braid-head`/`braid-body`, because the DOM
+ *   forbids duplicates of those singletons and would silently drop them;
+ * - every `<script>` is neutralized (`type="inert"`, real type parked in `data-script-type`) so
+ *   it cannot execute in the host's JS context — the client activates it in the fragment's realm;
+ * - script preload/prefetch/modulepreload links become `rel="inert-*"` so they don't trigger a
+ *   duplicate load in the host context;
+ * - inline event handler attributes are removed, and `<meta http-equiv="refresh">` is defanged.
+ *
+ * This is the server half of the born-inert invariant, and the last two rules are what make the
+ * invariant true rather than merely true-of-`<script>`: **no markup a fragment sends can execute
+ * JavaScript in the host realm or navigate the host page.** Both were verified executing in the
+ * host realm before this transform existed.
+ *
+ * Still not neutralized, because they require user interaction rather than executing on parse:
+ * `javascript:` URLs and form `action`s. Those remain within the trusted tier's stated model —
+ * a trusted fragment can navigate the page a user clicks through — and are called out in the
+ * security section of the README.
+ */
+export function prepareFragmentHtml(body, options) {
+    const { fragmentId } = options;
+    // The fragment's own <base href>, which its subresource URLs resolve against. It appears in
+    // <head> before anything that references it, so tracking it as the stream passes is enough.
+    let fragmentBaseHref = '/';
+    return rewriteHtmlStream(body, {
+        stripDoctype: true,
+        handlers: {
+            '*': {
+                element(tag) {
+                    for (const attributeName of tag.attributeNames) {
+                        if (INLINE_EVENT_HANDLER.test(attributeName)) {
+                            tag.removeAttribute(attributeName);
+                        }
+                    }
+                    rewriteSubresourceUrls(tag, fragmentId, fragmentBaseHref);
+                },
+            },
+            base: {
+                element(tag) {
+                    // read, never rewrite: this is what the fragment's router reads as its base path
+                    const href = tag.getAttribute('href');
+                    if (href)
+                        fragmentBaseHref = href;
+                },
+            },
+            html: { element: (tag) => void (tag.tagName = 'braid-html') },
+            head: { element: (tag) => void (tag.tagName = 'braid-head') },
+            body: { element: (tag) => void (tag.tagName = 'braid-body') },
+            script: {
+                element(tag) {
+                    const type = tag.getAttribute('type');
+                    if (type)
+                        tag.setAttribute('data-script-type', type);
+                    tag.setAttribute('type', 'inert');
+                },
+            },
+            link: {
+                element(tag) {
+                    const rel = tag.getAttribute('rel');
+                    if (rel === 'preload' || rel === 'prefetch' || rel === 'modulepreload') {
+                        tag.setAttribute('rel', `inert-${rel}`);
+                    }
+                },
+            },
+            meta: {
+                element(tag) {
+                    // a meta refresh anywhere in the page navigates the whole host document, throwing away
+                    // the shell and every other fragment on it
+                    if (tag.getAttribute('http-equiv')?.trim().toLowerCase() !== 'refresh')
+                        return;
+                    tag.removeAttribute('http-equiv');
+                    tag.setAttribute('data-braid-blocked', 'meta-refresh');
+                },
+            },
+        },
+    });
+}
+/** Rewrites a tag's subresource URLs into the fragment's namespace. */
+function rewriteSubresourceUrls(tag, fragmentId, baseHref) {
+    const attributes = SUBRESOURCE_ATTRIBUTES[tag.tagName];
+    if (!attributes)
+        return;
+    for (const attributeName of attributes) {
+        const value = tag.getAttribute(attributeName);
+        if (!value)
+            continue;
+        const rewritten = SRCSET_ATTRIBUTES.has(attributeName)
+            ? rewriteSrcset(value, fragmentId, baseHref)
+            : namespaceUrl(value, fragmentId, baseHref);
+        if (rewritten !== null) {
+            tag.setAttribute(attributeName, rewritten);
+        }
+    }
+}
+/**
+ * Maps one URL into the fragment's namespace, or returns null to leave it untouched.
+ *
+ * Left alone: anything with a scheme (`https:`, `data:`, `blob:`), protocol-relative URLs, and
+ * pure fragment identifiers — none of those are the fragment's own subresources.
+ */
+function namespaceUrl(rawUrl, fragmentId, baseHref) {
+    const url = rawUrl.trim();
+    if (!url || url.startsWith('#') || url.startsWith('//') || /^[a-z][a-z0-9+.-]*:/i.test(url)) {
+        return null;
+    }
+    // resolve exactly as the browser would have in the fragment's own document, then re-root it
+    const resolved = new URL(url, `http://braid.invalid${baseHref.startsWith('/') ? baseHref : `/${baseHref}`}`);
+    return `${BRAID_FRAGMENT_PREFIX}${encodeURIComponent(fragmentId)}${resolved.pathname}${resolved.search}${resolved.hash}`;
+}
+/** Rewrites each candidate in a `srcset`, preserving its density/width descriptors. */
+function rewriteSrcset(value, fragmentId, baseHref) {
+    const candidates = value.split(',');
+    let changed = false;
+    const rewritten = candidates.map((candidate) => {
+        const match = /^(\s*)(\S+)(\s*.*)$/.exec(candidate);
+        if (!match)
+            return candidate;
+        const [, leading, url, descriptor] = match;
+        const namespaced = namespaceUrl(url, fragmentId, baseHref);
+        if (namespaced === null)
+            return candidate;
+        changed = true;
+        return `${leading}${namespaced}${descriptor}`;
+    });
+    return changed ? rewritten.join(',') : null;
+}
+/**
+ * Pierces a fragment into the shell's HTML stream.
+ *
+ * The fragment's server-rendered content is injected into the matching `<fragment-slot>` as a
+ * declarative shadow root, so the browser parses it into exactly the shape the client runtime
+ * would have built — the slot then adopts it instead of fetching, and the fragment paints as
+ * part of the shell's first response rather than a round trip later.
+ *
+ * Injection is stream-interleaved: the shell streams out until the slot is reached, the
+ * fragment's stream is spliced in as it arrives, then the rest of the shell follows.
+ *
+ * If the shell contains no matching slot, the fragment is appended before `</body>` (or at the
+ * end of the document — `</body>` is optional in HTML and often omitted) inside a slot element
+ * the gateway creates. This keeps piercing working for shells that haven't been marked up yet.
+ */
+export function pierceShellHtml(options) {
+    const { shell, headScript, nonce } = options;
+    const pending = new Map(options.fragments.map((fragment) => [fragment.fragmentId, fragment]));
+    let stylesInjected = false;
+    const shadowRoot = (target) => [
+        '<template shadowrootmode="open">',
+        BRAID_FRAGMENT_STYLES,
+        '<braid-document>',
+        target.content ?? '',
+        '</braid-document></template>',
+    ];
+    /** A slot element the gateway creates because the shell didn't mark one up. */
+    const orphanSlot = (target) => concatStreams([
+        `<fragment-slot name="${escapeAttribute(target.fragmentId)}"` +
+            // A slot the gateway invents has no template to have declared `src`, so the manifest's is
+            // the only source there is.
+            `${target.src ? ` src="${escapeAttribute(target.src)}"` : ''} data-braid-pierced="">`,
+        ...shadowRoot(target),
+        '</fragment-slot>',
+    ]);
+    /** Every fragment that never found a slot, appended in registration order. */
+    const remainingOrphans = () => {
+        const orphans = [...pending.values()].filter((target) => target.content);
+        pending.clear();
+        return orphans.length ? concatStreams(orphans.map(orphanSlot)) : undefined;
+    };
+    return rewriteHtmlStream(shell, {
+        handlers: {
+            head: {
+                element(tag) {
+                    if (stylesInjected)
+                        return;
+                    stylesInjected = true;
+                    // Styles first: the slot layout rules must land before any fragment content is parsed,
+                    // and an async measurement script must never be what delays them.
+                    tag.prepend(withNonce(BRAID_SHELL_STYLES + (headScript ?? ''), nonce ?? null));
+                },
+            },
+            'fragment-slot': {
+                element(tag) {
+                    const name = tag.getAttribute('name');
+                    const target = name ? pending.get(name) : undefined;
+                    if (!target)
+                        return;
+                    pending.delete(target.fragmentId);
+                    const declared = tag.getAttribute('src');
+                    if (target.src && declared && declared !== target.src) {
+                        // Two sources of truth that disagree: the gateway pierced content from one path while
+                        // the client will boot the fragment at another, so the widget changes under the user
+                        // the moment it hydrates. Cheap to say, and invisible otherwise.
+                        console.warn(`braid-gateway: slot for fragment "${target.fragmentId}" declares src="${declared}" ` +
+                            `but its manifest declares src="${target.src}" — the pierced content and the client ` +
+                            `boot would come from different paths`);
+                    }
+                    if (target.src && !declared)
+                        tag.setAttribute('src', target.src);
+                    if (!target.content) {
+                        // nothing to pierce: mark the slot so the page can style a skeleton, and let the
+                        // client runtime fetch the fragment itself
+                        if (target.fallbackReason)
+                            tag.setAttribute('data-braid-fallback', target.fallbackReason);
+                        return;
+                    }
+                    tag.setAttribute('data-braid-pierced', '');
+                    for (const part of shadowRoot(target)) {
+                        tag.prepend(part);
+                    }
+                },
+            },
+            body: {
+                endTag(tag) {
+                    const orphans = remainingOrphans();
+                    if (orphans)
+                        tag.before(orphans);
+                },
+            },
+        },
+        // `</body>` is optional in HTML and frequently omitted — this is the safety net
+        onEnd: remainingOrphans,
+    });
+}
+function escapeAttribute(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;');
+}
+//# sourceMappingURL=transforms.js.map

package/src/rewriter/transforms.js.map

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

package/src/single-flight.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Collapses concurrent identical fragment fetches into one.
+ *
+ * **Not a cache, and the distinction is the whole design.** A cache answers from the past and has
+ * to reason about staleness, invalidation, and — on ECS or any multi-instance deployment — which
+ * instance holds the entry. This holds nothing: it only notices that a fetch it is *already making*
+ * is the one a second request wants, and lets both use the result. Nothing outlives the request
+ * that started it, so there is no TTL to tune, no invalidation to get wrong, and instance affinity
+ * is irrelevant.
+ *
+ * That is why this belongs in the gateway while response caching belongs in a CDN. A CDN in front
+ * of the gateway caches the composed document beautifully and does nothing at all for the N origin
+ * fetches a cache *miss* still costs. An unbound widget pierced into `/` and `/*` is fetched once
+ * per page render; fifty concurrent renders are fifty fetches of identical content. This makes them
+ * one.
+ */
+export interface SingleFlight {
+    /**
+     * Runs `fetcher`, or joins the identical call already in progress.
+     *
+     * Every participant receives its own `Response` — bodies are single-use, so joiners cannot be
+     * handed the same object.
+     */
+    run(key: string, fetcher: () => Promise<Response>): Promise<Response>;
+    /** In-flight entries. For tests and for a health endpoint that wants to show the collapse rate. */
+    size(): number;
+}
+export declare function createSingleFlight(): SingleFlight;
+/**
+ * The key two requests must agree on before their fetches may be shared.
+ *
+ * **This is a correctness boundary, not an optimization knob.** Two requests get one response, so
+ * anything that could make the endpoint answer differently has to be in the key — otherwise one
+ * user is served a render personalized for another, which is a data leak wearing a performance
+ * feature's clothes.
+ *
+ * So `cookie` and `authorization` are included verbatim. The honest consequence is that
+ * coalescing helps anonymous and shared-identity traffic a great deal and personalized fragments
+ * not at all: two signed-in users have different cookies and therefore never share a flight. That
+ * is the correct behaviour, not a limitation to tune away.
+ *
+ * `user-agent` is in the key for the same reason, and it is the one that matters now that this is
+ * on by default: server-side device detection is common and completely invisible from the
+ * manifest, so an endpoint rendering a mobile layout would otherwise have it served to the next
+ * desktop request that happened to arrive alongside it. It costs collapse rate — user-agent
+ * strings are diverse — and that is the right trade for a default.
+ *
+ * What this cannot see is an endpoint varying on something unusual: a tenant header, a
+ * feature-flag header, anything bespoke. Those set `coalesce: false` on the manifest.
+ *
+ * Returns null when the request must not be shared at all.
+ */
+export declare function singleFlightKey(request: Request, url: string): string | null;

package/src/single-flight.js

@@ -0,0 +1,97 @@
+/**
+ * Collapses concurrent identical fragment fetches into one.
+ *
+ * **Not a cache, and the distinction is the whole design.** A cache answers from the past and has
+ * to reason about staleness, invalidation, and — on ECS or any multi-instance deployment — which
+ * instance holds the entry. This holds nothing: it only notices that a fetch it is *already making*
+ * is the one a second request wants, and lets both use the result. Nothing outlives the request
+ * that started it, so there is no TTL to tune, no invalidation to get wrong, and instance affinity
+ * is irrelevant.
+ *
+ * That is why this belongs in the gateway while response caching belongs in a CDN. A CDN in front
+ * of the gateway caches the composed document beautifully and does nothing at all for the N origin
+ * fetches a cache *miss* still costs. An unbound widget pierced into `/` and `/*` is fetched once
+ * per page render; fifty concurrent renders are fifty fetches of identical content. This makes them
+ * one.
+ */
+export function createSingleFlight() {
+    const inflight = new Map();
+    return {
+        async run(key, fetcher) {
+            const existing = inflight.get(key);
+            if (existing)
+                return (await existing).clone();
+            const flight = fetcher();
+            inflight.set(key, flight);
+            let response;
+            try {
+                response = await flight;
+            }
+            finally {
+                // Removed as soon as it settles: a request arriving after this point must start its own
+                // fetch rather than join a completed one, which is what keeps this a coalescer and not a
+                // cache with an accidental TTL.
+                inflight.delete(key);
+            }
+            const mine = response.clone();
+            /**
+             * Release the branch nobody reads.
+             *
+             * Every participant — including this one — takes a clone, so the original is left unread.
+             * `clone()` tees the body, and a tee buffers without bound for whichever branch lags, so an
+             * abandoned original would hold the whole response in memory. Cancelling it stops that.
+             *
+             * On a macrotask rather than a microtask because the joiners' `await` continuations are
+             * microtasks: cancelling sooner would race them and destroy the body they are about to
+             * clone. Cancelling one tee branch does not disturb the others.
+             */
+            setTimeout(() => void response.body?.cancel().catch(() => undefined), 0);
+            return mine;
+        },
+        size: () => inflight.size,
+    };
+}
+/**
+ * The key two requests must agree on before their fetches may be shared.
+ *
+ * **This is a correctness boundary, not an optimization knob.** Two requests get one response, so
+ * anything that could make the endpoint answer differently has to be in the key — otherwise one
+ * user is served a render personalized for another, which is a data leak wearing a performance
+ * feature's clothes.
+ *
+ * So `cookie` and `authorization` are included verbatim. The honest consequence is that
+ * coalescing helps anonymous and shared-identity traffic a great deal and personalized fragments
+ * not at all: two signed-in users have different cookies and therefore never share a flight. That
+ * is the correct behaviour, not a limitation to tune away.
+ *
+ * `user-agent` is in the key for the same reason, and it is the one that matters now that this is
+ * on by default: server-side device detection is common and completely invisible from the
+ * manifest, so an endpoint rendering a mobile layout would otherwise have it served to the next
+ * desktop request that happened to arrive alongside it. It costs collapse rate — user-agent
+ * strings are diverse — and that is the right trade for a default.
+ *
+ * What this cannot see is an endpoint varying on something unusual: a tenant header, a
+ * feature-flag header, anything bespoke. Those set `coalesce: false` on the manifest.
+ *
+ * Returns null when the request must not be shared at all.
+ */
+export function singleFlightKey(request, url) {
+    // Only safe methods. A POST is an action, and two identical actions are still two actions.
+    if (request.method !== 'GET' && request.method !== 'HEAD')
+        return null;
+    // A range request is a slice of a body; sharing one response across different ranges would hand
+    // callers bytes they did not ask for.
+    if (request.headers.has('range'))
+        return null;
+    return [
+        request.method,
+        url,
+        request.headers.get('cookie') ?? '',
+        request.headers.get('authorization') ?? '',
+        // Content negotiation the endpoint may legitimately vary on.
+        request.headers.get('accept-language') ?? '',
+        request.headers.get('accept') ?? '',
+        request.headers.get('user-agent') ?? '',
+    ].join('\n');
+}
+//# sourceMappingURL=single-flight.js.map

package/src/single-flight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"single-flight.js","sourceRoot":"","sources":["../../../../libs/braid-gateway/src/single-flight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAcH,MAAM,UAAU,kBAAkB;IAChC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA6B,CAAC;IAEtD,OAAO;QACL,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO;YACpB,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACnC,IAAI,QAAQ;gBAAE,OAAO,CAAC,MAAM,QAAQ,CAAC,CAAC,KAAK,EAAE,CAAC;YAE9C,MAAM,MAAM,GAAG,OAAO,EAAE,CAAC;YACzB,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAE1B,IAAI,QAAkB,CAAC;YACvB,IAAI,CAAC;gBACH,QAAQ,GAAG,MAAM,MAAM,CAAC;YAC1B,CAAC;oBAAS,CAAC;gBACT,wFAAwF;gBACxF,yFAAyF;gBACzF,gCAAgC;gBAChC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,CAAC;YAED,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAC;YAE9B;;;;;;;;;;eAUG;YACH,UAAU,CAAC,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;YAEzE,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB,EAAE,GAAW;IAC3D,2FAA2F;IAC3F,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IAEvE,gGAAgG;IAChG,sCAAsC;IACtC,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAE9C,OAAO;QACL,OAAO,CAAC,MAAM;QACd,GAAG;QACH,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE;QACnC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE;QAC1C,6DAA6D;QAC7D,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,EAAE;QAC5C,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE;QACnC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE;KACxC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/src/telemetry.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Optional telemetry: what the gateway did on the server, and what the user experienced in the
+ * browser — both attributed to the fragment responsible.
+ *
+ * **The attribution is the point.** Server-side timings per fragment are ordinary; a reverse proxy
+ * gives you those. Web vitals per *fragment* are not, because in a composed page the page-level
+ * number is an average over apps owned by different teams. "The page has a CLS of 0.31" starts an
+ * argument. "Ninety percent of the layout shift happened inside `reviews`" ends it.
+ *
+ * Off unless configured, and configured as one hook rather than a sink: what to do with an event —
+ * OpenTelemetry, a log line, a counter, nothing — is the deployment's decision, and a gateway that
+ * picked for you would be a dependency you did not ask for.
+ */
+/** Fires when the gateway fetches a fragment's endpoint. Server-side, always available. */
+export interface FragmentFetchEvent {
+    kind: 'fragment-fetch';
+    fragmentId: string;
+    /**
+     * Why the fetch happened: composing a document, or serving a request addressed to the
+     * fragment's namespace. Worth distinguishing — a slow pierce delays the page, while a slow
+     * namespace asset delays only that fragment.
+     */
+    phase: 'pierce' | 'namespace';
+    /**
+     * `'shed'` means the breaker refused the request without making it — no endpoint was contacted,
+     * so there is no status and the duration is ~0. Distinct from `error` on purpose: an operator
+     * counting failures must not count our own load-shedding as the endpoint failing again.
+     */
+    outcome: 'ok' | 'error' | 'timeout' | 'shed';
+    /** Absent when the fetch threw before a response existed. */
+    status?: number;
+    durationMs: number;
+    at: number;
+}
+export type WebVitalName = 'LCP' | 'CLS' | 'INP' | 'FCP' | 'TTFB';
+/** Fires when a browser reports a web vital, attributed to a fragment where one can be blamed. */
+export interface WebVitalEvent {
+    kind: 'web-vital';
+    name: WebVitalName;
+    value: number;
+    rating: 'good' | 'needs-improvement' | 'poor';
+    /**
+     * The fragment whose subtree the metric was attributed to.
+     *
+     * `null` is a real answer, not a gap: TTFB belongs to the document, and an LCP element in the
+     * shell's own markup is genuinely the shell's. Blaming a fragment for those would be worse than
+     * saying nothing.
+     */
+    fragmentId: string | null;
+    pathname: string;
+    at: number;
+}
+/** Fires when a fragment's circuit breaker changes state. Never per request — only on the edges. */
+export interface BreakerEvent {
+    kind: 'breaker';
+    fragmentId: string;
+    from: 'closed' | 'open' | 'half-open';
+    to: 'closed' | 'open' | 'half-open';
+    /** Consecutive failures at the moment of the transition. */
+    failures: number;
+    at: number;
+}
+export type TelemetryEvent = FragmentFetchEvent | WebVitalEvent | BreakerEvent;
+export interface TelemetryOptions {
+    /**
+     * Called for every event.
+     *
+     * **On the request path for server events, so it must be cheap.** Called synchronously and never
+     * awaited; a sink that does real work should buffer and flush elsewhere. Unlike `observe`, this
+     * one *is* wrapped — a broken telemetry sink must not fail the request it is describing, because
+     * the whole point is to be safe to leave on in production.
+     */
+    on: (event: TelemetryEvent) => void;
+    /**
+     * Collect web vitals in the browser and report them here. Off by default.
+     *
+     * Turning this on serves a small collector from the gateway and injects it into composed
+     * documents. It is off by default because it adds a script to every pierced page, and that is
+     * not a decision a library should make for a deployment.
+     */
+    webVitals?: boolean;
+    /**
+     * Fraction of *browser sessions* that report, 0–1. Defaults to 1.
+     *
+     * Sampled per session rather than per metric on purpose: a session that reports its LCP but not
+     * its CLS produces a dataset where the two cannot be correlated, which quietly ruins the
+     * analysis they were collected for.
+     */
+    sampleRate?: number;
+}
+export declare function rateVital(name: WebVitalName, value: number): WebVitalEvent['rating'];
+/**
+ * Parses a beacon body into events.
+ *
+ * **Everything here arrives from a browser, so none of it is trusted.** A metric name that is not
+ * one of the five, a value that is not finite, or a fragment id that is not registered is dropped
+ * rather than forwarded — a telemetry endpoint that relays whatever it is posted is an open
+ * ingestion API for anyone who can reach it, and the sink downstream would be the thing paying for
+ * that. `known` is the registry's fragment ids; pass an empty set to accept none.
+ */
+export declare function parseVitalsBeacon(body: unknown, known: ReadonlySet<string>, now?: number): WebVitalEvent[];
+/**
+ * The browser-side collector, as a source string.
+ *
+ * Hand-written rather than pulling in `web-vitals`: the library is excellent and mostly solves a
+ * problem this does not have — cross-browser normalization for metrics whose polyfills matter on
+ * browsers that cannot run Braid's realms anyway. What is left is four `PerformanceObserver`
+ * registrations, and shipping them inline keeps this dependency-free and keeps the injected script
+ * small enough that measuring a page does not measurably change it.
+ *
+ * The part that is not boilerplate is {@link ownerOf}: attributing an element to the fragment that
+ * rendered it means climbing *out of shadow roots*, since a pierced fragment's DOM lives inside a
+ * declarative shadow root and `closest()` stops at that boundary.
+ */
+export declare function vitalsCollectorScript(endpoint: string, sampleRate: number): string;