@rivetjs/router 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denys Severyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @rivetjs/router
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+File routing for Rivet: loaders, actions, guards, a web-standard request handler, Node / static / edge adapters.
+
+Part of Rivet, a compiled, resumable JSX framework. Start a project with `npm create rivet@latest`.
+
+```sh
+npm install @rivetjs/router
+```
+
+Source: https://github.com/N1XUS/rivetjs/tree/main/libs/router · Docs: https://github.com/N1XUS/rivetjs/tree/main/apps/docs/content · Issues: https://github.com/N1XUS/rivetjs/issues

package/adapters/assemble.d.ts

@@ -0,0 +1,32 @@
+import type { ResumeManifest } from "@rivetjs/runtime/server-resume";
+import type { InlineStyleManifest } from "../server/inline-styles.js";
+import type { AppConfig, GeneratedEntry } from "../server/app.js";
+import type { AppHandler } from "../server/handler.js";
+export interface ViteManifestRecord {
+    file: string;
+    src?: string;
+    isEntry?: boolean;
+    css?: string[];
+}
+/** One client build: URL base, resume manifest and Vite manifest. */
+export interface ClientBuild {
+    readonly base: string;
+    readonly manifest: ResumeManifest;
+    readonly vite: Readonly<Record<string, ViteManifestRecord>>;
+}
+/** A client build's manifests (one per locale with i18n), as `loadBuild` reads and `fetch.js` inlines them. */
+export interface BuildManifests {
+    readonly clients: readonly ClientBuild[];
+    /** i18n locales in compiler variant order, one client build each. */
+    readonly locales?: readonly string[];
+    /** `.vite/rivet-route-css.json` of the first client build, when written. */
+    readonly routeStyles?: Readonly<Record<string, string[]>>;
+    /** `.vite/rivet-inline-css.json` of the first client build (the sheets pages may write inline), when written. */
+    readonly inlineStyles?: InlineStyleManifest;
+}
+export type BuildConfig = Pick<AppConfig, "stream" | "onError" | "maxBody" | "csp" | "preload" | "routeRules" | "routeCache" | "renderCache" | "earlyHints"> & {
+    /** i18n: error-page locale when the request has none settled (`createApp` `i18n.resolve`). */
+    readonly resolveLocale?: (request: Request) => string | undefined | Promise<string | undefined>;
+};
+/** Create the app handler from the server bundle's own `createApp` (one runtime instance). */
+export declare function assemble(entry: GeneratedEntry, build: BuildManifests, config?: BuildConfig, where?: string): AppHandler;

package/adapters/assemble.js

@@ -0,0 +1,32 @@
+/** Create the app handler from the server bundle's own `createApp` (one runtime instance). */
+export function assemble(entry, build, config = {}, where = "server entry") {
+    const { clients, locales, routeStyles, inlineStyles } = build;
+    const { resolveLocale, ...app } = config;
+    const first = clients[0];
+    const styles = Object.values(first.vite)
+        // App entries only (router `styles`, CSR app): resume chunks are entries too, their CSS is linked per route.
+        .filter((record) => record.isEntry && !record.src?.includes("rivet-resume-chunk:"))
+        .flatMap((record) => (record.file.endsWith(".css") ? [record.file] : (record.css ?? [])))
+        .map((file) => first.base + file);
+    const createApp = entry.createApp;
+    if (!createApp)
+        throw new TypeError(`${where} does not export createApp`);
+    const i18n = locales?.length
+        ? {
+            i18n: {
+                locales,
+                manifests: Object.fromEntries(locales.map((locale, i) => [locale, clients[i].manifest])),
+                ...(resolveLocale ? { resolve: resolveLocale } : {}),
+            },
+        }
+        : {};
+    return createApp({
+        ...app,
+        entry,
+        manifest: first.manifest,
+        styles: [...new Set(styles)],
+        ...(routeStyles ? { routeStyles } : {}),
+        ...(inlineStyles ? { inlineStyles } : {}),
+        ...i18n,
+    });
+}

package/adapters/build.d.ts

@@ -0,0 +1,24 @@
+import type { AppConfig, GeneratedEntry } from "../server/app.js";
+import type { AppHandler } from "../server/handler.js";
+import { type BuildManifests } from "./assemble.js";
+export interface LoadedBuild {
+    readonly entry: GeneratedEntry;
+    readonly handler: AppHandler;
+    /** Built client directory (`<dist>/client`). */
+    readonly client: string;
+}
+export interface LoadBuildOptions {
+    /**
+     * i18n: one client build per locale in `client/<locale>/` (base `/<locale>/`), in compiler variant
+     * order. Pages use their locale's resume manifest; stylesheets come from the first locale's build.
+     */
+    readonly locales?: readonly string[];
+    /** i18n: error-page locale when the request has none settled (e.g. `errorLocale(config)` from `@rivetjs/i18n/router`). */
+    readonly resolveLocale?: (request: Request) => string | undefined | Promise<string | undefined>;
+    /** URL base path of the client build (`/app`); `loadBuild` takes it from the server entry. */
+    readonly base?: string;
+}
+/** Read the client build manifests of `<dist>/client` (per locale with i18n). */
+export declare function readManifests(dist: string, { locales, base }?: LoadBuildOptions): Promise<BuildManifests>;
+/** Import `<dist>/server/entry.server.js` and wire it to the client build's resume manifest and stylesheets. */
+export declare function loadBuild(dist: string, config?: Pick<AppConfig, "stream" | "onError" | "maxBody" | "csp" | "preload" | "routeRules" | "routeCache" | "renderCache" | "earlyHints">, options?: LoadBuildOptions): Promise<LoadedBuild>;

package/adapters/build.js

@@ -0,0 +1,43 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// Load a production build (`vite build` + `vite build --ssr`) into an app handler.
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { assemble } from "./assemble.js";
+/** Read the client build manifests of `<dist>/client` (per locale with i18n). */
+export async function readManifests(dist, { locales, base = "" } = {}) {
+    const root = resolve(dist);
+    const read = async (path) => JSON.parse(await readFile(resolve(root, path), "utf8"));
+    const dirs = locales?.length
+        ? locales.map((locale) => ({ dir: "client/" + locale + "/", base: base + "/" + locale + "/" }))
+        : [{ dir: "client/", base: base + "/" }];
+    const clients = await Promise.all(dirs.map(async ({ dir, base }) => {
+        const [manifest, vite] = await Promise.all([
+            read(dir + ".vite/rivet-resume.json"),
+            read(dir + ".vite/manifest.json"),
+        ]);
+        return { base, manifest, vite };
+    }));
+    // Per-route CSS (route modules' stylesheets), when the client build wrote any.
+    const routeStyles = await read(dirs[0].dir + ".vite/rivet-route-css.json").catch(() => undefined);
+    // Small stylesheets written inline (`rivetRouter({ inlineStylesheets })`), when the client build wrote any.
+    const inlineStyles = await read(dirs[0].dir + ".vite/rivet-inline-css.json").catch(() => undefined);
+    return { clients, ...(locales?.length ? { locales } : {}), ...(routeStyles ? { routeStyles } : {}), ...(inlineStyles ? { inlineStyles } : {}) };
+}
+/** Import `<dist>/server/entry.server.js` and wire it to the client build's resume manifest and stylesheets. */
+export async function loadBuild(dist, config = {}, options = {}) {
+    const root = resolve(dist);
+    const path = resolve(root, "server/entry.server.js");
+    const entry = (await import(__rewriteRelativeImportExtension(pathToFileURL(path).href, true)));
+    const manifests = await readManifests(root, { ...options, base: options.base ?? entry.base ?? "" });
+    // The server bundle carries its own `createApp`: the handler must share the app's runtime instance.
+    const handler = assemble(entry, manifests, { ...config, ...(options.resolveLocale ? { resolveLocale: options.resolveLocale } : {}) }, path);
+    return { entry, handler, client: resolve(root, "client") };
+}

package/adapters/bun.d.ts

@@ -0,0 +1,18 @@
+import type { GeneratedEntry } from "../server/app.js";
+import type { BuildManifests } from "./assemble.js";
+import { type FetchOptions } from "./fetch.js";
+import { type ServerTargetOptions } from "./server-target.js";
+interface BunServer {
+    readonly port: number;
+    readonly hostname: string;
+    readonly url: URL;
+    requestIP(request: Request): {
+        address: string;
+    } | null;
+    stop(force?: boolean): Promise<void> | void;
+}
+export interface BunOptions extends Omit<FetchOptions, "serveAssets">, ServerTargetOptions {
+}
+/** Start `Bun.serve`; stops (in-flight requests finish) on SIGTERM / SIGINT. */
+export declare function start(entry: GeneratedEntry, build: BuildManifests, options?: BunOptions): BunServer;
+export {};

package/adapters/bun.js

@@ -0,0 +1,44 @@
+// Bun server (`rivetRouter({ adapter: "bun" })` → `bun dist/server/bun.js`): `Bun.serve`
+// (https://bun.com/docs/api/http) with the built client files first (`files.ts`, sent as `Bun.file`,
+// zero-copy) and the app through the fetch adapter (web-standard Response bodies, Bun's native
+// streams). The Bun `Server` reaches loaders as `event.platform.ctx`; environment: `process.env` /
+// `Bun.env`. Bun.serve does not compress: precompressed `.br` / `.gz` siblings are served for files,
+// pages go out uncompressed (put a compressing proxy / CDN in front for HTML).
+import { fileURLToPath } from "node:url";
+import { createFetch } from "./fetch.js";
+import { staticFiles } from "./files.js";
+import { immutableOf, listenOptions } from "./server-target.js";
+/** Start `Bun.serve`; stops (in-flight requests finish) on SIGTERM / SIGINT. */
+export function start(entry, build, options = {}) {
+    const Bun = globalThis.Bun;
+    if (!Bun)
+        throw new Error('rivetRouter({ adapter: "bun" }): dist/server/bun.js runs under Bun (bun dist/server/bun.js)');
+    const { client, port, hostname, signals, ...fetchOptions } = options;
+    const base = entry.base ?? "";
+    const lookup = client ? staticFiles(typeof client === "string" ? client : fileURLToPath(client), base, immutableOf(base, build)) : () => null;
+    const app = createFetch(entry, build, { address: (request, _env, server) => server.requestIP(request)?.address, ...fetchOptions });
+    const listen = listenOptions({ port, hostname });
+    const server = Bun.serve({
+        ...listen,
+        fetch(request, server) {
+            if (request.method === "GET" || request.method === "HEAD") {
+                const file = lookup(request, new URL(request.url).pathname);
+                if (file === 304)
+                    return new Response(null, { status: 304 });
+                if (file)
+                    return new Response(request.method === "HEAD" ? null : Bun.file(file.path), { headers: file.headers });
+            }
+            return app.fetch(request, undefined, server);
+        },
+    });
+    if (signals !== false) {
+        const stop = async () => {
+            await server.stop();
+            process.exit(0);
+        };
+        for (const signal of ["SIGTERM", "SIGINT"])
+            process.once(signal, stop);
+    }
+    console.log(`Listening on ${server.url.href}`);
+    return server;
+}

package/adapters/cloudflare.d.ts

@@ -0,0 +1,5 @@
+import type { GeneratedEntry } from "../server/app.js";
+import type { BuildManifests } from "./assemble.js";
+import { type FetchModule, type FetchOptions } from "./fetch.js";
+export type CloudflareOptions = FetchOptions;
+export declare function create(entry: GeneratedEntry, build: BuildManifests, options?: CloudflareOptions): FetchModule;

package/adapters/cloudflare.js

@@ -0,0 +1,8 @@
+import { createFetch } from "./fetch.js";
+export function create(entry, build, options = {}) {
+    return createFetch(entry, build, {
+        // Cloudflare sets it to the connecting client's address (clients cannot override it).
+        address: (request) => request.headers.get("cf-connecting-ip") ?? undefined,
+        ...options,
+    });
+}

package/adapters/cluster.d.ts

@@ -0,0 +1,7 @@
+import type { PrimaryServing, ServerServing } from "./node.js";
+/** In a worker: `run()` (one-worker `start`), then IPC: relay `revalidate()`, drain + exit on the primary's close. */
+export declare function worker(run: () => Promise<ServerServing>): Promise<ServerServing>;
+/** In the primary: fork `count` workers, restart crashed ones, relay revalidations; resolves once all listen. */
+export declare function primary(count: number, grace: number, log: (error: unknown) => void): Promise<PrimaryServing>;
+/** `cluster.isPrimary` (true outside a cluster). */
+export declare const isPrimary: () => boolean;

package/adapters/cluster.js

@@ -0,0 +1,130 @@
+// Multi-core serving for the node adapter (`start({ workers })`, loaded only when `workers` > 1): the primary forks
+// `workers` processes running the same script; each worker runs `start()` with one worker, and the primary hands out
+// connections (node:cluster round robin) or, with `reusePort`, each worker binds its own socket and the kernel
+// balances (Linux / FreeBSD). The primary loads no build and renders nothing. `revalidate()` reaches every worker:
+// the worker that calls it drops its own pages and the primary relays the target to the others (IPC).
+import cluster, {} from "node:cluster";
+// `server/route-cache.ts`: the local drop (registered at module load) and the hook its `revalidate()` calls after it.
+const LOCAL = Symbol.for("rivet.revalidate.local");
+const BROADCAST = Symbol.for("rivet.revalidate.broadcast");
+/** A `revalidate()` target from IPC: `{ path?: string, tag?: string }`, at least one. */
+const targetOf = (value) => {
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const { path, tag } = value;
+    if ((path !== undefined && typeof path !== "string") || (tag !== undefined && typeof tag !== "string") || (path === undefined && tag === undefined))
+        return undefined;
+    return { path: path, tag: tag };
+};
+const global = globalThis;
+/** In a worker: `run()` (one-worker `start`), then IPC: relay `revalidate()`, drain + exit on the primary's close. */
+export async function worker(run) {
+    const serving = await run();
+    // The local drop already happened: a closed IPC channel only means the other workers keep theirs.
+    global[BROADCAST] = (target) => {
+        if (process.connected)
+            process.send?.({ type: "rivet:revalidate", target }, undefined, undefined, () => { });
+    };
+    const stop = () => void serving.close().then(() => process.exit(0), () => process.exit(1));
+    process.on("message", (message) => {
+        if (message?.type === "rivet:revalidate") {
+            const target = targetOf(message.target);
+            if (target)
+                try {
+                    global[LOCAL]?.(target);
+                }
+                catch {
+                    // A malformed path: nothing to drop here.
+                }
+        }
+        else if (message?.type === "rivet:close")
+            stop();
+    });
+    // The primary went away (crash, kill -9): finish what is in flight, then exit.
+    process.once("disconnect", stop);
+    return serving;
+}
+/** In the primary: fork `count` workers, restart crashed ones, relay revalidations; resolves once all listen. */
+export function primary(count, grace, log) {
+    let closing = false;
+    // Replacements only once every first worker listens: a worker failing at start rejects `start()` instead.
+    let started = false;
+    const crashes = [];
+    const live = new Set();
+    let url = "";
+    const fork = () => {
+        const child = cluster.fork();
+        live.add(child);
+        child.on("message", (message) => {
+            if (message?.type !== "rivet:revalidate")
+                return;
+            const target = targetOf(message.target);
+            if (!target)
+                return;
+            for (const other of live)
+                if (other !== child && other.isConnected())
+                    other.send({ type: "rivet:revalidate", target }, undefined, () => { });
+        });
+        child.once("exit", (code, signal) => {
+            live.delete(child);
+            if (closing || !started)
+                return;
+            // A crashed worker is replaced, unless workers keep crashing (5 in 10 s): then the primary stops forking.
+            const now = Date.now();
+            crashes.push(now);
+            while (crashes[0] < now - 10_000)
+                crashes.shift();
+            if (crashes.length > 5) {
+                log(new Error(`rivet: workers keep exiting (last: ${signal ?? code}); not restarting`));
+                // Nothing serves any more: exit, so the process manager / orchestrator restarts the whole server.
+                if (live.size === 0)
+                    process.exit(1);
+                return;
+            }
+            log(new Error(`rivet: worker ${child.process.pid} exited (${signal ?? code}); starting another`));
+            void fork().catch(log);
+        });
+        return new Promise((done, fail) => {
+            child.once("listening", (address) => {
+                const host = address.address === undefined || address.address === null ? "127.0.0.1" : address.addressType === 6 ? `[${address.address}]` : address.address;
+                url ||= `http://${host}:${address.port}`;
+                done();
+            });
+            child.once("exit", (code) => fail(new Error(`rivet: worker exited (${code}) before listening`)));
+        });
+    };
+    const stopAll = () => {
+        closing = true;
+        for (const child of live)
+            child.process.kill("SIGTERM");
+    };
+    return Promise.all(Array.from({ length: count }, fork)).then(() => {
+        started = true;
+        let closed = null;
+        return {
+            url,
+            workers: count,
+            close: () => (closed ??= (async () => {
+                closing = true;
+                await Promise.all([...live].map((child) => new Promise((done) => {
+                    if (child.isDead())
+                        return done();
+                    child.once("exit", () => done());
+                    // Drain (the worker's own `grace`), then force.
+                    const force = setTimeout(() => child.process.kill("SIGKILL"), grace + 2_000);
+                    force.unref();
+                    if (child.isConnected())
+                        child.send({ type: "rivet:close" });
+                    else
+                        child.process.kill("SIGTERM");
+                })));
+            })()),
+        };
+    }, (error) => {
+        // A worker failed before listening (bad build, port taken): stop the others, `start()` rejects.
+        stopAll();
+        throw error;
+    });
+}
+/** `cluster.isPrimary` (true outside a cluster). */
+export const isPrimary = () => cluster.isPrimary;

package/adapters/csr.d.ts

@@ -0,0 +1,12 @@
+import type { DocumentShell } from "../server/render.js";
+/** Options of the CSR `index.html` shell. */
+export interface ShellOptions {
+    /** Module script URL of the client entry. */
+    script: string;
+    /** Stylesheet URLs. */
+    styles?: readonly string[];
+    /** URL the shell is built for (the document sees it; default `http://localhost/`). */
+    url?: URL;
+}
+/** `index.html` for a CSR app from its document shell: the app mounts into the shell's container. */
+export declare function shellHTML(document: DocumentShell, { script, styles, url }: ShellOptions): string;

package/adapters/csr.js

@@ -0,0 +1,11 @@
+// CSR adapter: a single-page shell that mounts the app in the browser. No server, so route
+// modules have no `.server.ts` (codegen rejects them) and pages render without loader data.
+import { escapeAttribute } from "@rivetjs/runtime/escape";
+/** `index.html` for a CSR app from its document shell: the app mounts into the shell's container. */
+export function shellHTML(document, { script, styles = [], url = new URL("http://localhost/") }) {
+    const { start, end } = document({ head: undefined, nonce: undefined, url, status: 200, styles });
+    const tag = `<script type="module" src="${escapeAttribute(script)}"></script>`;
+    if (!start.includes("</head>"))
+        throw new Error("CSR shell: the document start has no </head>");
+    return start.replace("</head>", tag + "</head>") + end;
+}

package/adapters/deno.d.ts

@@ -0,0 +1,13 @@
+import type { GeneratedEntry } from "../server/app.js";
+import type { BuildManifests } from "./assemble.js";
+import { type FetchOptions } from "./fetch.js";
+import { type ServerTargetOptions } from "./server-target.js";
+interface DenoServer {
+    readonly finished: Promise<void>;
+    shutdown(): Promise<void>;
+}
+export interface DenoOptions extends Omit<FetchOptions, "serveAssets">, ServerTargetOptions {
+}
+/** Start `Deno.serve`; shuts down (in-flight requests finish) on SIGTERM / SIGINT. */
+export declare function start(entry: GeneratedEntry, build: BuildManifests, options?: DenoOptions): DenoServer;
+export {};

package/adapters/deno.js

@@ -0,0 +1,35 @@
+// Deno server (`rivetRouter({ adapter: "deno" })` → `deno run --allow-net --allow-read --allow-env dist/server/deno.js`):
+// `Deno.serve` (https://docs.deno.com/runtime/fundamentals/http_server/) with the built client files
+// first (`files.ts`, streamed from `Deno.open`) and the app through the fetch adapter (Uint8Array
+// web streams). Deno compresses compressible responses itself (gzip / brotli by `Accept-Encoding`).
+// The handler's `info` (`remoteAddr`) reaches loaders as `event.platform.ctx`; environment: `Deno.env.get()`.
+import { fileURLToPath } from "node:url";
+import { createFetch } from "./fetch.js";
+import { staticFiles } from "./files.js";
+import { immutableOf, listenOptions } from "./server-target.js";
+/** Start `Deno.serve`; shuts down (in-flight requests finish) on SIGTERM / SIGINT. */
+export function start(entry, build, options = {}) {
+    const Deno = globalThis.Deno;
+    if (!Deno)
+        throw new Error('rivetRouter({ adapter: "deno" }): dist/server/deno.js runs under Deno (deno run -A dist/server/deno.js)');
+    const { client, port, hostname, signals, ...fetchOptions } = options;
+    const base = entry.base ?? "";
+    const lookup = client ? staticFiles(typeof client === "string" ? client : fileURLToPath(client), base, immutableOf(base, build)) : () => null;
+    const app = createFetch(entry, build, { address: (_request, _env, info) => info.remoteAddr.hostname, ...fetchOptions });
+    const server = Deno.serve({ ...listenOptions({ port, hostname }), onListen: ({ hostname, port }) => console.log(`Listening on http://${hostname}:${port}/`) }, async (request, info) => {
+        if (request.method === "GET" || request.method === "HEAD") {
+            const file = lookup(request, new URL(request.url).pathname);
+            if (file === 304)
+                return new Response(null, { status: 304 });
+            if (file)
+                return new Response(request.method === "HEAD" ? null : (await Deno.open(file.path)).readable, { headers: file.headers });
+        }
+        return app.fetch(request, undefined, info);
+    });
+    if (signals !== false) {
+        const stop = () => void server.shutdown().then(() => Deno.exit(0));
+        for (const signal of ["SIGTERM", "SIGINT"])
+            Deno.addSignalListener(signal, stop);
+    }
+    return server;
+}

package/adapters/fetch.d.ts

@@ -0,0 +1,55 @@
+import type { AppConfig, GeneratedEntry } from "../server/app.js";
+import type { BodyLimit } from "../server/security.js";
+import type { ErrorInfo } from "../server/handler.js";
+import { type BuildManifests } from "./assemble.js";
+import { nonce } from "../shared/nonce.js";
+/** Workers-style module: `export default { fetch }`. */
+export interface FetchModule {
+    fetch(request: Request, env?: unknown, ctx?: unknown): Promise<Response>;
+}
+type Maybe<T> = T | undefined | Promise<T | undefined>;
+export interface FetchOptions {
+    /**
+     * Fixed public origin (`https://shop.example`) for request URLs: set it when the platform hands the
+     * handler an internal URL, so same-origin checks compare with what the browser sees.
+     */
+    origin?: string;
+    /** Request body limit for unsafe methods (413 past it); default 1 MiB, multipart 10 MiB. */
+    maxBody?: BodyLimit;
+    /** Out-of-order streaming for pending `Async` boundaries. */
+    stream?: {
+        deadline?: number;
+    };
+    /** Extra headers on every handler response; defaults add nosniff + referrer policy (as node). */
+    headers?: Record<string, string>;
+    /** Log unexpected failures (default console.error); app failures get `info` (`digest`, `phase`, `route`). */
+    onError?: (error: unknown, request?: Request, info?: ErrorInfo) => void;
+    /**
+     * Static files before the handler (GET/HEAD): return a Response to answer, undefined to render.
+     * E.g. Workers `(request, env) => env.ASSETS.fetch(request)` filtered by path; most platforms serve
+     * `dist/client` before the function and need none.
+     */
+    serveAssets?: (request: Request, env: unknown, ctx: unknown) => Maybe<Response>;
+    /** i18n: error-page locale when the request has none settled (e.g. `errorLocale(config)` from `@rivetjs/i18n/router`). */
+    resolveLocale?: (request: Request) => string | undefined | Promise<string | undefined>;
+    /** HTML pages' Content-Security-Policy (`createApp` `csp`): default `strictCSP`; `{ trustedTypes, directives }` (`strictCSP` with them), a `(nonce) => policy` function, or `false` (none). */
+    csp?: AppConfig["csp"];
+    /** Preload planner (`createApp` `preload`): `background` byte budget of idle-time visible prefetch, `lean` (nothing before an interaction); per page when a function. */
+    preload?: AppConfig["preload"];
+    /** Route rules (`createApp` `routeRules`; default: the entry's, `rivetRouter({ routeRules })`): headers + in-process page cache per path pattern. */
+    routeRules?: AppConfig["routeRules"];
+    /** The route rules' page store (`createApp` `routeCache`: bounds, `origin`; default `origin`: this adapter's). */
+    routeCache?: AppConfig["routeCache"];
+    /**
+     * Early hints (`createApp` `earlyHints`): a `Link` header on HTML pages (linked stylesheets, the head's build-asset
+     * font preloads, `links`, `runtime: true` the resume entry). Cloudflare / Fastly turn it into `103 Early Hints` for
+     * later requests; a fetch handler cannot write a 103 itself. Default off.
+     */
+    earlyHints?: AppConfig["earlyHints"];
+    /** Client address for `event.platform.clientAddress` (e.g. `(r) => r.headers.get("cf-connecting-ip") ?? undefined`). */
+    address?: (request: Request, env: unknown, ctx: unknown) => string | undefined;
+}
+/** Fresh 128-bit CSP nonce (base64), shared with the node adapter. */
+export { nonce };
+/** Wrap a server entry and its (inlined) client manifests into a fetch module. */
+export declare function createFetch(entry: GeneratedEntry, build: BuildManifests, options?: FetchOptions): FetchModule;

package/adapters/fetch.js

@@ -0,0 +1,72 @@
+import { assemble } from "./assemble.js";
+import { nonce } from "../shared/nonce.js";
+/** Fresh 128-bit CSP nonce (base64), shared with the node adapter. */
+export { nonce };
+/** Wrap a server entry and its (inlined) client manifests into a fetch module. */
+export function createFetch(entry, build, options = {}) {
+    const { onError = (error) => console.error(error), serveAssets, address } = options;
+    const handler = assemble(entry, build, {
+        ...(options.stream ? { stream: options.stream } : {}),
+        ...(options.onError ? { onError: options.onError } : {}),
+        ...(options.maxBody !== undefined ? { maxBody: options.maxBody } : {}),
+        ...(options.csp !== undefined ? { csp: options.csp } : {}),
+        ...(options.preload ? { preload: options.preload } : {}),
+        ...(options.routeRules ? { routeRules: options.routeRules } : {}),
+        // The fixed public origin is the one stored pages are for (`isr` rules need one).
+        ...(options.routeCache || options.origin ? { routeCache: { ...(options.origin ? { origin: options.origin } : {}), ...options.routeCache } } : {}),
+        ...(options.resolveLocale ? { resolveLocale: options.resolveLocale } : {}),
+        ...(options.earlyHints ? { earlyHints: options.earlyHints } : {}),
+    }, "fetch entry");
+    const base = Object.entries({ "X-Content-Type-Options": "nosniff", "Referrer-Policy": "strict-origin-when-cross-origin", ...options.headers });
+    const fixedOrigin = options.origin ? new URL(options.origin).origin : null;
+    /** Add the base headers the response lacks (immutable headers, e.g. a proxied `fetch()`: copy). */
+    const finish = (response, head) => {
+        const missing = base.filter(([name]) => !response.headers.has(name));
+        if (head && response.body) {
+            void response.body.cancel().catch(() => { });
+            response = new Response(null, response);
+        }
+        if (!missing.length)
+            return response;
+        try {
+            for (const [name, value] of missing)
+                response.headers.set(name, value);
+            return response;
+        }
+        catch {
+            const copy = new Response(response.body, response);
+            for (const [name, value] of missing)
+                copy.headers.set(name, value);
+            return copy;
+        }
+    };
+    return {
+        async fetch(request, env, ctx) {
+            const head = request.method === "HEAD";
+            try {
+                if (serveAssets && (head || request.method === "GET")) {
+                    const asset = await serveAssets(request, env, ctx);
+                    if (asset)
+                        return asset;
+                }
+                if (fixedOrigin) {
+                    const url = new URL(request.url);
+                    if (url.origin !== fixedOrigin)
+                        request = new Request(fixedOrigin + url.pathname + url.search, request);
+                }
+                const clientAddress = address?.(request, env, ctx);
+                const platform = env !== undefined || ctx !== undefined || clientAddress
+                    ? { ...(env !== undefined ? { env } : {}), ...(ctx !== undefined ? { ctx } : {}) }
+                    : undefined;
+                const response = await handler(request, { nonce: nonce(), ...(clientAddress ? { address: clientAddress } : {}), ...(platform ? { platform } : {}) });
+                return finish(response, head);
+            }
+            catch (error) {
+                if (request.signal.aborted)
+                    throw error;
+                onError(error, request);
+                return finish(new Response("Internal Server Error", { status: 500, headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" } }), head);
+            }
+        },
+    };
+}

package/adapters/files.d.ts

@@ -0,0 +1,20 @@
+export interface StaticFile {
+    /** Absolute file path to send (the precompressed sibling when `encoding` is set). */
+    readonly path: string;
+    readonly headers: Record<string, string>;
+}
+/** A response encoding the adapters produce. */
+export type Encoding = "zstd" | "br" | "gzip" | null;
+/**
+ * `q` per content coding of an `Accept-Encoding` header, parsed once per distinct string (browsers send a handful;
+ * bounded: client-controlled text). `weightOf` applies `*` to codings the header does not name.
+ */
+export declare function acceptWeights(header: string): Map<string, number>;
+export declare const weightOf: (accepted: Map<string, number>, name: string) => number;
+/**
+ * Pick `zstd`, `br` or `gzip` from an Accept-Encoding header: the highest `q` (a tie: `zstd`, then `br`); q=0 excludes.
+ * `zstd: false` never picks zstd (`serve({ compress: { zstd: false } })`).
+ */
+export declare function negotiate(header: string | null | undefined, zstd?: boolean): Encoding;
+/** Index `client` (served under `base`); returns the per-request lookup. */
+export declare function staticFiles(client: string, base: string, immutable: readonly string[]): (request: Request, pathname: string) => StaticFile | 304 | null;