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

package/adapters/files.js

@@ -0,0 +1,103 @@
+// Static files for the Bun and Deno servers: the client directory indexed once at start (both
+// runtimes implement `node:fs` / `node:path`), looked up per GET/HEAD by URL path. Same rules as the
+// node adapter: below the base only, no `\0` or dot segments (except a root `.well-known/`), hashed
+// `<base>/assets/` immutable, everything else `no-cache` + weak ETag (304 on `If-None-Match`),
+// precompressed `.br` / `.gz` siblings when the client accepts them. Directory pages
+// (`a/index.html`, `a.html`, as the static adapter writes them) answer at `/a` and `/a/`.
+import { readdirSync, realpathSync, statSync } from "node:fs";
+import { extname, join, relative, sep } from "node:path";
+const MIME = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".map": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".txt": "text/plain; charset=utf-8",
+    ".xml": "application/xml; charset=utf-8",
+    ".webmanifest": "application/manifest+json",
+    ".wasm": "application/wasm",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+    ".ico": "image/x-icon",
+    ".woff2": "font/woff2",
+    ".woff": "font/woff",
+};
+/** Index `client` (served under `base`); returns the per-request lookup. */
+export function staticFiles(client, base, immutable) {
+    const files = new Map();
+    let root;
+    try {
+        root = realpathSync(client);
+    }
+    catch {
+        return () => null;
+    }
+    const entries = readdirSync(root, { recursive: true, withFileTypes: true });
+    const names = new Set(entries.filter((entry) => entry.isFile()).map((entry) => join(entry.parentPath, entry.name)));
+    for (const full of names) {
+        const key = relative(root, full).split(sep).join("/");
+        const segments = key.split("/");
+        if (segments.some((segment, i) => segment.startsWith(".") && !(i === 0 && segment === ".well-known")))
+            continue;
+        if (/\.(br|gz)$/.test(key) && names.has(full.slice(0, -3)))
+            continue;
+        const info = statSync(full);
+        const url = base + "/" + key;
+        const file = {
+            path: full,
+            type: MIME[extname(key).toLowerCase()] ?? "application/octet-stream",
+            etag: `W/"${info.size.toString(16)}-${Math.floor(info.mtimeMs).toString(16)}"`,
+            modified: info.mtime.toUTCString(),
+            immutable: immutable.some((prefix) => url.startsWith(prefix)),
+            ...(names.has(full + ".br") ? { br: full + ".br" } : {}),
+            ...(names.has(full + ".gz") ? { gz: full + ".gz" } : {}),
+        };
+        files.set(url, file);
+        const page = /^(.*?)(?:\/?index)?\.html$/.exec(key);
+        if (page && key !== "404.html" && key !== "200.html") {
+            const at = page[1] ? base + "/" + page[1] : base;
+            for (const alias of [at || "/", at + "/"])
+                if (!files.has(alias))
+                    files.set(alias, file);
+        }
+    }
+    return (request, pathname) => {
+        let decoded;
+        try {
+            decoded = decodeURIComponent(pathname);
+        }
+        catch {
+            return null;
+        }
+        if (decoded.includes("\0"))
+            return null;
+        const file = files.get(decoded);
+        if (!file)
+            return null;
+        const match = request.headers.get("if-none-match");
+        if (match && match.split(",").some((tag) => tag.trim() === "*" || tag.trim().replace(/^W\//, "") === file.etag.slice(2)))
+            return 304;
+        const headers = {
+            "Content-Type": file.type,
+            "Cache-Control": file.immutable ? "public, max-age=31536000, immutable" : "no-cache",
+            ETag: file.etag,
+            "Last-Modified": file.modified,
+        };
+        if (file.br || file.gz) {
+            headers.Vary = "Accept-Encoding";
+            const accept = request.headers.get("accept-encoding") ?? "";
+            const encoding = file.br && /\bbr\b/.test(accept) ? "br" : file.gz && /\bgzip\b/.test(accept) ? "gzip" : null;
+            if (encoding) {
+                headers["Content-Encoding"] = encoding;
+                return { path: encoding === "br" ? file.br : file.gz, headers };
+            }
+        }
+        return { path: file.path, headers };
+    };
+}

package/adapters/idle-memory.d.ts

@@ -0,0 +1,23 @@
+export interface IdleMemoryOptions {
+    /** Quiet time (ms) after the last request ends before the first check. Default 1000. */
+    delay?: number;
+    /** Time (ms) between a nudge and the next check: two memory-reducer ticks (8 s each) plus slack. Default 17000. */
+    recheck?: number;
+    /** Nudges per idle period before accepting the current heap as settled. Default 5 (inside V8's ~110 s smoothing window). */
+    attempts?: number;
+    /** Committed V8 heap bytes (default `getHeapStatistics().total_heap_size`). Tests replace it. */
+    committed?: () => number;
+    /** The embedder allocation (default `new Script("")`). Tests replace it. */
+    nudge?: () => void;
+}
+export interface IdleMemory {
+    /** A request started (counter only). */
+    request(): void;
+    /** The last in-flight request ended. */
+    idle(): void;
+    /** Stop for good (server closing). */
+    stop(): void;
+}
+/** True on Node; Bun (JSC) and Deno have different heaps and are left alone. */
+export declare const idleMemorySupported: () => boolean;
+export declare function idleMemory(inflight: () => number, options?: IdleMemoryOptions): IdleMemory;

package/adapters/idle-memory.js

@@ -0,0 +1,91 @@
+// Idle memory return for the Node adapter: lets V8's memory reducer shrink the heap once a server goes
+// quiet after traffic. Node-only (`node:v8`, `node:vm`).
+//
+// Why: V8's memory reducer starts its shrinking GCs only when young, old AND embedder (cppgc) allocation
+// rates are all "low" (`Heap::HasLowAllocationRate`). A rate of exactly 0 counts as high
+// (`ComputeMutatorUtilizationImpl` returns 0 for a zero mutator speed). A Node process that has never
+// allocated a cppgc object has an embedder rate of exactly 0 forever, so after a traffic spike the
+// reducer reports "high alloc" on every 8 s tick and the committed heap + pooled pages stay resident until
+// its 100 s watchdog fires (measured: Node 24 / V8 13.6 and Node 26 / V8 14.6). One tiny embedder
+// allocation (a `vm.Script`, whose wrapper is a 56-byte cppgc object since Node 22) makes the smoothed
+// embedder rate non-zero; one reducer tick later it has decayed to near zero, which is "low", and the
+// reducer runs as V8 intends. See docs/design/research/2026-10-07-v8-memory-reducer-embedder-rate.md.
+//
+// Cost model: per request only a counter increment (`request()`) and, when the last in-flight request
+// ends, an `idle()` call that arms a timer if none is pending. At most one unref'd timer exists; while
+// requests keep coming it fires at most once per `delay` and re-arms only when the server is idle at that
+// moment. Nothing runs on a server that has never served a request, and an idle server stops after the
+// heap shrank, after `attempts` tries, or when committed memory is not above the last settled level.
+import { getHeapStatistics } from "node:v8";
+import { Script } from "node:vm";
+const MiB = 1024 * 1024;
+/** True when committed memory grew past the settled level by V8's own memory-reducer re-arm rule (×1.1 or +10 MiB). */
+const grown = (committed, settled) => committed >= Math.max(settled * 1.1, settled + 10 * MiB);
+/** True on Node; Bun (JSC) and Deno have different heaps and are left alone. */
+export const idleMemorySupported = () => {
+    const versions = process.versions;
+    return typeof versions.v8 === "string" && versions.bun === undefined && versions.deno === undefined;
+};
+export function idleMemory(inflight, options = {}) {
+    const { delay = 1000, recheck = 17_000, attempts = 5 } = options;
+    const committed = options.committed ?? (() => getHeapStatistics().total_heap_size);
+    const nudge = options.nudge ??
+        (() => {
+            new Script("");
+        });
+    let timer = null, stopped = false, seen = 0, // requests started (wraps harmlessly: only compared for equality)
+    mark = 0, // `seen` when the pending timer was armed
+    attempt = 0, before = 0, // committed bytes at the last nudge
+    settled = committed(); // committed bytes once the heap was last left as is (boot, shrink, give-up)
+    const arm = (ms) => {
+        mark = seen;
+        timer = setTimeout(check, ms);
+        timer.unref();
+    };
+    const settle = (bytes) => {
+        settled = bytes;
+        attempt = 0;
+    };
+    function check() {
+        timer = null;
+        if (stopped)
+            return;
+        if (inflight() > 0) {
+            // Busy: the next `idle()` arms again.
+            attempt = 0;
+            return;
+        }
+        if (seen !== mark) {
+            // Requests came and went: wait for a full quiet `delay`.
+            attempt = 0;
+            arm(delay);
+            return;
+        }
+        const now = committed();
+        if (attempt > 0 && now < before * 0.9)
+            return settle(now); // the reducer ran: memory returned
+        if (!grown(now, settled))
+            return settle(Math.min(settled, now)); // nothing worth returning
+        if (attempt >= attempts)
+            return settle(now); // live set grew: accept it until the next spike
+        before = now;
+        attempt++;
+        nudge();
+        arm(recheck);
+    }
+    return {
+        request: () => {
+            seen = (seen + 1) | 0;
+        },
+        idle: () => {
+            if (timer === null && !stopped)
+                arm(delay);
+        },
+        stop: () => {
+            stopped = true;
+            if (timer !== null)
+                clearTimeout(timer);
+            timer = null;
+        },
+    };
+}

package/adapters/netlify.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";
+export interface NetlifyOptions extends Omit<FetchOptions, "serveAssets"> {
+    /**
+     * Edge Functions run before static files: GET/HEAD requests for these URL paths return `undefined`,
+     * which hands the request on to Netlify's static file (the packaged edge function lists the
+     * publish directory's files). Functions v2 use `preferStatic` instead.
+     */
+    staticPaths?: readonly string[];
+}
+export type NetlifyHandler = (request: Request, context?: unknown) => Promise<Response> | undefined;
+export declare function create(entry: GeneratedEntry, build: BuildManifests, options?: NetlifyOptions): NetlifyHandler;

package/adapters/netlify.js

@@ -0,0 +1,15 @@
+import { createFetch } from "./fetch.js";
+export function create(entry, build, options = {}) {
+    const { staticPaths, ...fetchOptions } = options;
+    const app = createFetch(entry, build, {
+        // Netlify's context carries the client address it saw.
+        address: (_request, _env, context) => context?.ip,
+        ...fetchOptions,
+    });
+    const files = staticPaths?.length ? new Set(staticPaths) : null;
+    return (request, context) => {
+        if (files && (request.method === "GET" || request.method === "HEAD") && files.has(new URL(request.url).pathname))
+            return undefined;
+        return app.fetch(request, undefined, context);
+    };
+}

package/adapters/node.d.ts

@@ -0,0 +1,163 @@
+import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import type { BodyLimit } from "../server/security.js";
+import type { ErrorInfo } from "../server/handler.js";
+import type { AppConfig } from "../server/app.js";
+/** Per-request context passed to the handler. */
+export interface RequestContext {
+    /** Fresh CSP nonce (base64) for inline scripts the handler emits. */
+    readonly nonce: string;
+    /** Client address, when known. */
+    readonly address?: string;
+}
+/** A request handler (web `Request` → `Response`) served by the Node adapter. */
+export type Handler = (request: Request, context: RequestContext) => Response | Promise<Response>;
+/** Options of `serve()`. */
+export interface ServeOptions {
+    handler: Handler;
+    /** Built client directory served before the handler (e.g. `dist/client`). */
+    client?: string;
+    /** Paths (URL pathname) whose files are content-hashed: `Cache-Control: immutable`. Default: `<base>/assets/`. */
+    immutable?: (pathname: string) => boolean;
+    /** URL base path (`/app`): client files are served under it (`/app/assets/x.js` → `<client>/assets/x.js`); other paths reach the handler. */
+    base?: string;
+    port?: number;
+    host?: string;
+    /**
+     * How `client` files are found. Default `"index"`: the directory is indexed once at start (real
+     * paths, sizes, precompressed `.br`/`.gz` siblings), so page requests cost a map lookup; files added
+     * later are not served. `"fs"`: look each GET up on disk (a directory that changes while serving).
+     */
+    static?: "index" | "fs";
+    /** Compress responses by `Accept-Encoding` (default true). */
+    compress?: boolean;
+    /**
+     * Send `103 Early Hints` when the app asks (`createApp({ earlyHints })`; `start({ earlyHints })` sets both), to
+     * HTTP/1.1 clients only (1xx are not allowed for 1.0). Browsers use 103s over HTTP/2+ only: behind a proxy or CDN
+     * that forwards them (nginx `early_hints`, Cloudflare, Fastly). Default false.
+     */
+    earlyHints?: boolean;
+    /**
+     * Bind with `SO_REUSEPORT` (Node ≥ 22.12): several processes listen on the same `port` and the kernel balances new
+     * connections between them. Linux and FreeBSD only (elsewhere `serve()` throws: macOS does not balance, Windows
+     * refuses). With `start({ workers })` each worker then binds its own socket instead of taking connections from the
+     * primary. Needs a fixed `port` (0 throws). Default false.
+     */
+    reusePort?: boolean;
+    /** Milliseconds to drain in-flight requests on close (default 10000). */
+    grace?: number;
+    /** Log unexpected failures (default console.error); app failures get `info` (`digest`, `phase`, `route`). */
+    onError?: (error: unknown, request?: Request, info?: ErrorInfo) => void;
+    /** Extra headers on every response; defaults add nosniff + referrer policy. */
+    headers?: Record<string, string>;
+    /**
+     * Fixed public origin (`https://shop.example`) for request URLs, regardless of `Host`: set it behind
+     * a proxy so the handler's same-origin checks compare with what the browser sees.
+     */
+    origin?: string;
+    /**
+     * Off by default: `X-Forwarded-*` headers are ignored (clients can send any). Behind reverse proxies
+     * you control, say which hops to trust; the client address is then the `X-Forwarded-For` entry the
+     * outermost trusted proxy appended (entries left of it are client-supplied), and protocol / host come
+     * from `X-Forwarded-Proto` / `X-Forwarded-Host` at the same hop (their leftmost value when shorter).
+     * - `true` or `1`: one proxy (the peer connecting to this server); `n`: the last `n` hops.
+     * - `(address, hop) => boolean`: trust per hop from the socket inward (hop 0 = the peer), like
+     *   Express `trust proxy`; the first untrusted address is the client. Ignored for the origin when
+     *   `origin` is set.
+     */
+    trustProxy?: boolean | number | ((address: string, hop: number) => boolean);
+    /**
+     * Return memory to the OS when the server goes idle after traffic (default true on Node). V8's memory
+     * reducer never runs in a process without embedder (cppgc) allocations, so a heap grown by a spike
+     * stays resident for ~100 s; after 1 s without requests the adapter makes one tiny embedder allocation
+     * (re-checked every 17 s, at most 5 times) while committed heap is above its settled level. No work
+     * per request beyond a counter; one unref'd timer at most. `false` turns it off.
+     */
+    idleMemory?: boolean;
+}
+/**
+ * A running server returned by `start()`: this process's own HTTP server (`ServerServing`, also what `serve()` and
+ * `start()` without `workers` return), or the primary of `start({ workers })` (`PrimaryServing`, no server).
+ * Narrow on `server` or `workers`.
+ */
+export type Serving = ServerServing | PrimaryServing;
+/** A server listening in this process: `serve()`, `start()` with one worker, and each `start({ workers })` worker. */
+export interface ServerServing {
+    readonly server: Server;
+    readonly url: string;
+    readonly workers?: undefined;
+    /** Stop accepting, report not-ready, drain within `grace`, then destroy remaining sockets. */
+    close(): Promise<void>;
+}
+/** The primary process of `start({ workers })`: forks the workers and serves nothing itself. */
+export interface PrimaryServing {
+    readonly server?: undefined;
+    readonly url: string;
+    /** How many worker processes serve. */
+    readonly workers: number;
+    /** Drain every worker (each within its `grace`), then resolve once all exited. */
+    close(): Promise<void>;
+}
+/** Pick `br` or `gzip` from an Accept-Encoding header: the higher `q` (a tie: `br`); q=0 excludes. */
+export declare function negotiate(header: string | null | undefined): "br" | "gzip" | null;
+/** `If-None-Match` (a list, `*`, weak or strong tags) matches `etag` (weak comparison, as for GET). */
+export declare function etagMatches(header: string | undefined, etag: string): boolean;
+/**
+ * A single `Range: bytes=…` of a `size`-byte file: `[start, end]` (inclusive), `"unsatisfiable"`
+ * (416), or null to send the whole file (no header, several ranges, another unit, malformed).
+ */
+export declare function byteRange(header: string | undefined, size: number): [number, number] | "unsatisfiable" | null;
+/** Create the Node request listener (exposed for custom servers and tests). */
+export declare function createListener(options: ServeOptions): {
+    listener: (req: IncomingMessage, res: ServerResponse) => void;
+    drain: () => void;
+    idle: () => Promise<void>;
+};
+/** Listen on `port` (0 = ephemeral). Resolves once listening. */
+export declare function serve(options: ServeOptions): Promise<ServerServing>;
+/** Close on SIGTERM/SIGINT once; exits the process after draining. */
+export declare function closeOnSignals(serving: Serving, signals?: NodeJS.Signals[]): void;
+/** Options of `start()`: serve a build output directory. */
+export interface StartOptions extends Omit<ServeOptions, "handler" | "client" | "earlyHints"> {
+    /** Build output with `client/` and `server/` (default `dist`). */
+    dist?: string;
+    /** Out-of-order streaming for pending `Async` boundaries. */
+    stream?: {
+        deadline?: number;
+    };
+    /** i18n: per-locale client builds (`client/<locale>/`, see `loadBuild`); their `assets/` are immutable. */
+    locales?: readonly string[];
+    /** Request body limit for unsafe methods (413 past it); default 1 MiB, multipart 10 MiB. */
+    maxBody?: BodyLimit;
+    /** i18n: error-page locale when the request has none settled (see `loadBuild`). */
+    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; stored pages are served before a Request is built. */
+    routeRules?: AppConfig["routeRules"];
+    /** The route rules' page store (`createApp` `routeCache`: bounds, `origin`; default `origin`: this adapter's). */
+    routeCache?: AppConfig["routeCache"];
+    /** Cross-request fragment cache (`createApp` `renderCache`, `createRenderCache()` from `@rivetjs/runtime/server-cache`). */
+    renderCache?: AppConfig["renderCache"];
+    /**
+     * Worker processes (node:cluster): `"auto"` = `os.availableParallelism()`, default 1 (this process serves). With
+     * more, this process becomes the primary: it forks that many copies of the running script, each serving the build,
+     * restarts crashed ones and resolves with `{ url, workers, close }` (close drains every worker). Connections are
+     * handed out round robin by the primary, or balanced by the kernel with `reusePort` (Linux). The route cache is per
+     * worker; `revalidate()` reaches every worker through the primary. Call `start()` at the top level of the script
+     * (workers run it again).
+     */
+    workers?: number | "auto";
+    /** Early hints (`createApp` `earlyHints`): `103 Early Hints` + `Link` headers for pages (stylesheets, build-asset fonts, `links`; `runtime: true` adds the resume entry). Default off. */
+    earlyHints?: AppConfig["earlyHints"];
+}
+/**
+ * Serve a production build of a file-routed app: resume manifest, entry stylesheets, client assets. Without `workers`
+ * (or `workers: 1`) resolves with this process's server; with `workers` resolves with a `ServerServing` in each
+ * worker and a `PrimaryServing` (no `server`) in the primary.
+ */
+export declare function start(options?: StartOptions & {
+    workers?: 1;
+}): Promise<ServerServing>;
+export declare function start(options?: StartOptions): Promise<Serving>;