@braidlabs/gateway 0.1.1

package/src/gateway.d.ts

@@ -0,0 +1,241 @@
+import { Principal, RegistrySource } from './registry.js';
+import { DiscoveryOptions } from './discovery.js';
+import { type BreakerOptions } from './breaker.js';
+import { type TelemetryOptions } from './telemetry.js';
+/**
+ * Gateway core: fetch-native, platform-neutral origin-front middleware.
+ *
+ * Two responsibilities:
+ *
+ * 1. **Namespace routing**: requests under `/__braid/frag/:id/*` address a fragment by id,
+ *    exactly — realm stubs, assets, and data. No pattern matching, no request sniffing.
+ * 2. **Piercing**: for document requests whose page URL a fragment declares in its
+ *    `pierce` patterns, the fragment's server-rendered HTML is interleaved into the shell's
+ *    response stream, so fragments paint with the shell's first response.
+ *
+ * Everything else passes through to the shell untouched.
+ */
+export interface GatewayOptions {
+    /** The fragment registry: inline manifests, a JSON URL, or an async loader. */
+    registry: RegistrySource;
+    /** 'development' enables verbose error bodies; defaults to 'development'. */
+    mode?: 'production' | 'development';
+    /** Additional headers set on every request forwarded to a fragment endpoint. */
+    additionalHeaders?: Record<string, string>;
+    /**
+     * Publishes a paginated listing of the fragments this gateway serves, for shells that build
+     * their UI from the registry instead of hard-coding slot names.
+     *
+     * Off unless configured: a registry describes internal topology, so exposing it is a choice.
+     * See {@link DiscoveryOptions}.
+     */
+    discovery?: DiscoveryOptions;
+    /**
+     * Resolves who is asking, for manifests that declare `access` rules.
+     *
+     * Wire it to whatever your app already uses for sessions. It is only called for fragments that
+     * actually restrict something, so fully public registries never pay for it — and a fragment
+     * with `access` rules but no resolver treats every caller as anonymous.
+     */
+    principal?: (request: Request) => Principal | undefined | Promise<Principal | undefined>;
+    /**
+     * Whether to pass an incoming `x-forwarded-proto` / `x-forwarded-host` through to fragment
+     * endpoints instead of overwriting them from the request's own URL. Defaults to false.
+     *
+     * Leave it off unless a proxy you control is the only way requests reach this gateway.
+     * Otherwise a client can name any host it likes, and a fragment that builds absolute URLs
+     * from those headers (reset links, cache keys, redirects) will build them for the attacker's
+     * host.
+     */
+    trustForwardedHeaders?: boolean;
+    /**
+     * What to do with `Cache-Control` on a page URL some fragment declares in `pierce`.
+     *
+     * - `'private'` (default) — keep it out of shared caches: `public` and `s-maxage` are dropped
+     *   and `private` is added. The browser may still cache it.
+     * - `'preserve'` — leave the shell's own headers untouched.
+     *
+     * The default exists because such a URL has two representations (composed for a navigation,
+     * plain for a soft-navigation fetch) and `Vary: sec-fetch-dest` is not enough to protect them:
+     * most CDNs, Cloudflare among them, honor `Vary` only for `Accept-Encoding`. A shared cache
+     * that ignores it will store one representation and serve it as the other — the fragment
+     * silently vanishes from the page, or appears in a payload a router is trying to parse as JSON.
+     * Composed pages are also usually personalized, and caching one freezes the fragment's HTML at
+     * the shell's TTL, so a fragment deploy stays invisible until the page expires.
+     *
+     * Choose `'preserve'` only when the pages are genuinely anonymous **and** you have put
+     * `sec-fetch-dest` into the edge's cache key. See `docs/braid-cdn.md`.
+     */
+    pierceCacheControl?: 'private' | 'preserve';
+    /**
+     * Called for every document request that reaches the shell, with which fragments composed into
+     * it. This is what makes traffic-informed impact analysis possible: "after this change, 43 of
+     * the 412 page URLs we actually serve stop composing billing".
+     *
+     * **On the request path, so it must be cheap.** It is called synchronously and never awaited;
+     * a sink that does real work should buffer and flush elsewhere. It is also called *outside* any
+     * try/catch — a throwing observer will fail the request, which is the honest behavior for a
+     * broken observer rather than one that silently records nothing.
+     *
+     * Off unless configured. Recording the paths a site serves is a data-retention decision, not a
+     * default: paths carry identifiers, and sometimes personal ones.
+     */
+    observe?: (event: RoutingEvent) => void;
+    /**
+     * Report what the gateway did, and optionally what the browser experienced — per fragment.
+     *
+     * Distinct from {@link GatewayOptions.observe}, which records *which* fragments composed where
+     * so a registry change can be analysed offline. This one records how they *behaved*: fetch
+     * outcomes and durations on the server, and web vitals in the browser attributed to the fragment
+     * whose subtree they happened in.
+     *
+     * Off unless configured. Unlike `observe`, the hook is wrapped — a throwing telemetry sink is
+     * reported once and then ignored, because a feature meant to be left on in production must not
+     * be able to take the site down with it.
+     */
+    telemetry?: TelemetryOptions;
+    /**
+     * Stop paying a broken fragment's timeout on every request.
+     *
+     * A fragment endpoint that is down already costs its full `timeoutMs`; without a breaker it
+     * costs that *again* on the next request, and the one after. This converts a slow repeated
+     * failure into a fast one — the fallback the manifest already declares is served immediately
+     * instead of after the budget expires.
+     *
+     * `true` takes the defaults (3 consecutive failures, 10s cooldown). Off unless configured,
+     * because shedding load is a behaviour change and a deployment should opt into it knowingly.
+     */
+    breaker?: boolean | Partial<BreakerOptions>;
+    /**
+     * Collapse concurrent identical fragment fetches into one.
+     *
+     * A CDN in front of this gateway caches the composed document and does nothing for the origin
+     * fetches a cache *miss* still costs. An unbound widget pierced into every page is fetched once
+     * per render; fifty concurrent renders are fifty identical fetches. This makes them one.
+     *
+     * Not a cache: nothing outlives the request that started it, so there is no TTL, no
+     * invalidation, and no dependence on which instance a request lands on — which is what makes it
+     * safe on ECS or any horizontally scaled deployment.
+     *
+     * Requests only share a fetch when their `cookie`, `authorization`, `user-agent`, and
+     * negotiation headers match exactly, so personalized fragments are never shared between users,
+     * and a fragment declaring `access` rules is never shared at all.
+     *
+     * **On by default**, because it changes how many times an identical fetch is made and nothing
+     * else: no response is stored, reused later, or shared across identities. A fragment whose
+     * endpoint varies on something the gateway cannot see sets `coalesce: false` on its manifest;
+     * set this to `false` to turn the whole mechanism off.
+     */
+    coalesceFragmentFetches?: boolean;
+    /**
+     * Serve Braid's service worker from `/__braid/sw.js`. Off by default.
+     *
+     * Worth doing here for a reason that is not convenience. **A worker's scope is capped by the path
+     * it is served from**, so a script at `/__braid/sw.js` defaults to controlling `/__braid/` — which
+     * would intercept fragment assets but not the shell's own, making it useless for the chunk-failure
+     * case that matters most. Widening it needs a `Service-Worker-Allowed` header on the script
+     * response, and the gateway is the one component already sitting in front of the origin that can
+     * send it without additional infrastructure configuration.
+     *
+     * The default scope is `/`. That sounds broad and costs nothing: scope precedence is
+     * longest-match, so a worker registered at `/legacy/` still controls clients under `/legacy/`
+     * whatever Braid claims — the root is a fallback, not an exclusion, and the handler ignores
+     * everything outside the namespace anyway. The override exists for a gateway mounted under a path
+     * on an origin it does not own.
+     */
+    serviceWorker?: boolean | ServiceWorkerOptions;
+}
+export interface ServiceWorkerOptions {
+    /** The scope to claim, sent as `Service-Worker-Allowed`. Defaults to `/`. */
+    scope?: string;
+    /**
+     * The module the generated worker imports `setupBraidWorker` from.
+     *
+     * A URL your origin serves — the worker runs in its own realm and cannot resolve a bare specifier.
+     * Defaults to `/braid-sw.js`, which is where a build that copies `@braidlabs/sw` normally
+     * lands it.
+     */
+    module?: string;
+    /** Fragment ids whose realm stubs the worker precaches at install. */
+    precache?: readonly string[];
+    /** Stamped into the worker so it can report disagreement with the page it is serving. */
+    buildId?: string;
+}
+/**
+ * One document request, and what composed into it.
+ *
+ * Emitted for *every* document request the shell handles, not only pierce-matched ones. A path
+ * that composes nothing today is exactly the path that a widened pattern would start composing
+ * tomorrow, and analysis needs both sides to report a gain.
+ */
+export interface RoutingEvent {
+    /** Page pathname. Search is excluded — it never affects pierce matching. */
+    pathname: string;
+    /** Fragment ids that composed into this response, in registration order. */
+    fragmentIds: string[];
+    at: number;
+}
+export interface BraidGateway {
+    /**
+     * Handles a request if it belongs to Braid: a fragment-namespace request, or a document
+     * request that pierces one or more fragments. Returns null for everything else — the caller
+     * passes those through to the shell.
+     *
+     * @param next fetches the shell application's response. Required for piercing; without it,
+     *             document requests are passed through and fragments boot client-side instead.
+     */
+    handle(request: Request, next?: () => Promise<Response>): Promise<Response | null>;
+    /**
+     * Resolves a websocket upgrade addressed to a fragment.
+     *
+     * Dev servers push reloads over websockets, and live apps use them for real work. Both are
+     * addressed through the fragment namespace, so the gateway has to say where they go — the
+     * socket plumbing itself belongs to the platform binding.
+     *
+     * @returns the endpoint URL to dial, or null when the request is not a fragment upgrade, the
+     *          fragment is unknown, or the caller may not load it.
+     */
+    resolveUpgrade(request: Request): Promise<{
+        fragmentId: string;
+        target: URL;
+    } | null>;
+}
+export declare function createGateway(options: GatewayOptions): BraidGateway;
+/**
+ * Wraps a gateway as web middleware: braid requests are handled — including document requests
+ * that pierce fragments into the shell — and everything else goes to the shell via `next()`.
+ *
+ * `next` is memoized, so the shell application runs at most once per request no matter how the
+ * gateway and the caller interleave.
+ */
+export declare function toWebMiddleware(gateway: BraidGateway): (request: Request, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Wraps a fetch handler — the shell application as `(Request) => Response` — with the gateway.
+ *
+ * This is the binding for every web-standard runtime: Cloudflare Workers, Deno, Bun, and
+ * h3/Nitro (via `toWebHandler(app)`). It is also the only in-process way to pierce on those
+ * runtimes, because piercing needs to *read* the shell's response, which a middleware chain
+ * with no return value cannot give it.
+ *
+ * ```ts
+ * // h3 / Nitro
+ * import { toWebHandler } from 'h3';
+ * export default toFetchHandler(gateway, toWebHandler(app));
+ * ```
+ */
+export declare function toFetchHandler(gateway: BraidGateway, appHandler: (request: Request) => Response | Promise<Response>): (request: Request) => Promise<Response>;
+/**
+ * Resolves a namespace-stripped request against a fragment's endpoint, **within the endpoint's
+ * own path**.
+ *
+ * `new URL('/admin', 'https://internal/apps/billing/')` yields `https://internal/admin`: an
+ * absolute path replaces the endpoint's path entirely. Left alone, that turns the gateway into
+ * a proxy for the endpoint host's whole origin rather than the subtree the manifest declared.
+ * So the endpoint's path is treated as a prefix.
+ *
+ * The containment check afterwards is belt-and-braces: dot segments, including percent-encoded
+ * ones (`%2e%2e`), are already normalized when the incoming request URL is parsed, which takes
+ * such a request out of the fragment namespace entirely before it ever reaches here. The check
+ * costs nothing and does not assume every runtime normalizes identically.
+ */
+export declare function resolveEndpointUrl(endpoint: string, strippedUrl: URL, fragmentId: string): URL;