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

package/server/render.js

@@ -0,0 +1,489 @@
+// Stream a page into a web Response: document start, resumable app, document end.
+import { renderToWriter, SlabWriter } from "@rivetjs/runtime/server";
+import { escapeText } from "@rivetjs/runtime/escape";
+import { renderResumable } from "@rivetjs/runtime/server-resume";
+import { withIdScope } from "@rivetjs/runtime/id";
+import { DIRECT_BODY } from "./body.js";
+export { headTags, htmlAttributes, bodyAttributes } from "../shared/head.js";
+/** Coalesced write size (bytes): fewer, larger body chunks. */
+const FLUSH_AT = 16 * 1024;
+/** Bytes handed off but not consumed yet (no reader / sink, or a reader that has not asked) before the renderer waits. */
+const QUEUE = 64 * 1024;
+/** Byte slab the writes coalesce in; chunks are views of it (a slab is reused only after a direct sink released every view). */
+const SLAB = 64 * 1024;
+/** Strings up to this length are copied as ASCII by hand (cheaper than `encodeInto` + a view per write). */
+const ASCII_LOOP = 64;
+const encoder = new TextEncoder();
+// Node / Bun: slabs are Buffers, so the renderer's text paths (`putText`, raw rows) and `write` encode with one
+// native `utf8Write` call instead of a per-char loop / `encodeInto` + a subarray view (ssr-bench text grid,
+// rivet-router lane: putText 24% of CPU on Uint8Array slabs). Other hosts (Deno, workers): plain Uint8Array.
+const NodeBuffer = globalThis.Buffer;
+const nativeSlabs = NodeBuffer !== undefined && typeof NodeBuffer.prototype.utf8Write === "function";
+const allocate = (size) => (nativeSlabs ? NodeBuffer.allocUnsafeSlow(size) : new Uint8Array(size));
+// Process-wide pool of SLAB-sized slabs, refilled only by direct sinks (a web stream consumer never
+// says when a chunk's bytes are free): fresh ArrayBuffers per response add external-memory pressure.
+const pool = [];
+const POOL_LIMIT = 32;
+const recycle = (slab) => {
+    if (slab.bytes.length !== SLAB || pool.length >= POOL_LIMIT)
+        return;
+    slab.retired = false;
+    pool.push(slab);
+};
+const retire = (slab) => {
+    slab.retired = true;
+    if (slab.pending === 0)
+        recycle(slab);
+};
+/**
+ * The body's byte writer (SlabWriter: writeText / writeBytes / writeInteger / raw-slab protocol shared with
+ * NodeStreamWriter). Writes coalesce in a slab and are handed off at FLUSH_AT bytes, on every write while
+ * the consumer is behind (`threshold` 0), or in a microtask (the renderer paused: a pending boundary, the
+ * end), so the shell before an await still leaves at once. The renderer hands over its pre-encoded template
+ * fragments and integers instead of strings to concatenate and encode per chunk.
+ *
+ * Consumer: none yet (chunks park, QUEUE bytes at most before the renderer waits), the web `ReadableStream`
+ * (high-water mark 0: `pull` = a read waits; parked chunks go out, later ones straight to a waiting read),
+ * or a direct sink (`attach`, node adapter: views of pooled slabs, released by the sink; no stream at all).
+ */
+class BodyWriter extends SlabWriter {
+    constructor(enqueued) {
+        super(FLUSH_AT, SLAB, false, undefined);
+        this.slab = null;
+        this.parked = [];
+        this.parkedSlabs = [];
+        this.parkedBytes = 0;
+        this.wanted = false;
+        this.mode = 0;
+        this.sink = null;
+        this.ended = false;
+        this.failure = null;
+        this.cancelled = false;
+        this.full = false;
+        this.waiting = null;
+        this.wake = null;
+        this.enqueued = enqueued;
+        this.later = () => {
+            try {
+                this.flush();
+            }
+            catch {
+                /* Cancelled by the consumer: the next write fails and ends the render. */
+            }
+        };
+    }
+    /** The consumer caught up (or cancelled): writes coalesce again; a waiting renderer resumes. */
+    ready() {
+        this.full = false;
+        this.threshold = FLUSH_AT;
+        const resume = this.wake;
+        this.wake = this.waiting = null;
+        resume?.();
+    }
+    /** Stream `pull`: a read waits. Parked chunks go out at once; otherwise the next hand-off goes to it. */
+    pull() {
+        if (this.mode === 2)
+            return;
+        this.mode = 1;
+        if (this.parked.length) {
+            for (const chunk of this.parked)
+                this.controller.enqueue(chunk);
+            this.unpark();
+        }
+        else if (!this.failure && !this.ended) {
+            this.wanted = true;
+            return;
+        }
+        if (this.failure)
+            this.controller.error(this.failure.error);
+        else if (this.ended)
+            this.controller.close();
+        this.ready();
+    }
+    /** Direct consumer: every parked and later chunk goes to `sink`. False once the stream was read. */
+    attach(sink) {
+        if (this.mode !== 0 || this.cancelled)
+            return false;
+        this.mode = 2;
+        this.sink = sink;
+        const parked = this.parked, slabs = this.parkedSlabs;
+        this.unpark();
+        let wait;
+        for (let i = 0; i < parked.length; i++) {
+            const slab = slabs[i];
+            wait = sink.write(parked[i], () => --slab.pending === 0 && slab.retired && recycle(slab)) ?? wait;
+        }
+        if (this.failure)
+            sink.error(this.failure.error);
+        else if (this.ended)
+            (this.finish(), sink.end());
+        else if (wait) {
+            this.full = true;
+            this.threshold = 0;
+            this.waiting = wait.then(() => this.ready());
+        }
+        else
+            this.ready();
+        return true;
+    }
+    unpark() {
+        this.parked = [];
+        this.parkedSlabs = [];
+        this.parkedBytes = 0;
+    }
+    /** The stream consumer cancelled. */
+    cancel() {
+        this.cancelled = true;
+        this.unpark();
+        this.ready();
+    }
+    /** The body is complete. */
+    close() {
+        this.ended = true;
+        if (this.mode === 2) {
+            this.finish();
+            this.sink.end();
+        }
+        else if (this.mode === 1 && !this.parked.length)
+            this.controller.close();
+    }
+    /** The render failed: the body errors (a consumer that comes later sees the error). */
+    fail(error) {
+        this.failure = { error };
+        this.unpark();
+        if (this.mode === 2) {
+            this.finish();
+            this.sink.error(error);
+        }
+        else if (this.mode === 1)
+            this.controller.error(error);
+    }
+    /** Direct sink: the current slab goes back to the pool once its views are released. */
+    finish() {
+        if (this.slab)
+            retire(this.slab);
+        this.slab = this.bytes = null;
+    }
+    schedule() {
+        this.scheduled = true;
+        queueMicrotask(this.later);
+    }
+    renew(size) {
+        if (this.slab)
+            retire(this.slab);
+        const slab = size <= SLAB ? (pool.pop() ?? { bytes: allocate(SLAB), pending: 0, retired: false }) : { bytes: allocate(size), pending: 0, retired: false };
+        this.slab = slab;
+        this.bytes = slab.bytes;
+        this.start = this.offset = 0;
+    }
+    flush() {
+        this.scheduled = false;
+        if (this.offset !== this.start) {
+            if (this.cancelled)
+                throw new TypeError("Response body cancelled");
+            const slab = this.slab;
+            const chunk = this.bytes.subarray(this.start, this.offset);
+            this.start = this.offset;
+            // The handed-off view keeps its bytes: later writes go past it, or into another slab.
+            slab.pending++;
+            if (this.bytes.length - this.offset < FLUSH_AT)
+                this.renew(0);
+            if (this.mode === 2) {
+                const wait = this.sink.write(chunk, () => --slab.pending === 0 && slab.retired && recycle(slab));
+                this.enqueued();
+                return wait;
+            }
+            if (this.wanted) {
+                this.wanted = false;
+                this.controller.enqueue(chunk);
+            }
+            else {
+                this.parked.push(chunk);
+                this.parkedSlabs.push(slab);
+                this.parkedBytes += chunk.length;
+                if (this.parkedBytes >= QUEUE) {
+                    this.full = true;
+                    this.threshold = 0;
+                }
+            }
+            this.enqueued();
+        }
+        return this.full ? (this.waiting ??= new Promise((done) => (this.wake = done))) : undefined;
+    }
+    write(chunk) {
+        const length = chunk.length;
+        if (!length)
+            return;
+        let waiting;
+        if (this.bytes === null)
+            this.renew(0);
+        if (this.bytes.length - this.offset < length * 3) {
+            waiting = this.flush();
+            this.reserve(length * 3);
+        }
+        const slab = this.bytes;
+        // Explicit length: workerd's (nodejs_compat) Buffer#utf8Write throws ERR_OUT_OF_RANGE without it.
+        if (nativeSlabs)
+            this.offset += slab.utf8Write(chunk, this.offset, slab.length - this.offset);
+        else if (length <= ASCII_LOOP) {
+            // Short strings (escaped text, attribute values): plain ASCII copy, encoder only past it.
+            const offset = this.offset;
+            let i = 0;
+            for (; i < length; i++) {
+                const code = chunk.charCodeAt(i);
+                if (code >= 0x80)
+                    break;
+                slab[offset + i] = code;
+            }
+            this.offset = offset + i;
+            if (i < length)
+                this.offset += encoder.encodeInto(i ? chunk.slice(i) : chunk, slab.subarray(this.offset)).written;
+        }
+        else
+            this.offset += encoder.encodeInto(chunk, slab.subarray(this.offset)).written;
+        if (this.offset - this.start >= this.threshold)
+            return this.flush() ?? waiting;
+        if (!this.scheduled)
+            this.schedule();
+        return waiting;
+    }
+    oversize(bytes) {
+        this.renew(bytes.length);
+        this.bytes.set(bytes);
+        this.offset = bytes.length;
+        return this.flush();
+    }
+}
+/** Root state script: the start of the recorder's tail (state, loader), the last thing it writes. */
+const ROOT_STATE = '<script type="rivet/state" data-region="0"';
+/** A writer that drops everything from the root state script on. */
+const stateless = (writer) => {
+    let cut = false;
+    return {
+        write(chunk) {
+            if (cut)
+                return;
+            const at = chunk.indexOf(ROOT_STATE);
+            if (at < 0)
+                return writer.write(chunk);
+            cut = true;
+            return writer.write(chunk.slice(0, at));
+        },
+    };
+};
+/** `Promise.race([render, TICK])` yields PENDING when the render promise had not settled yet. */
+const PENDING = Symbol("pending");
+const TICK = Promise.resolve(PENDING);
+/** Mid-stream failure marker: tells the page (and monitoring) the document is incomplete. */
+export function failureMarker(nonce, digest) {
+    const attrs = nonce !== undefined ? ` nonce="${nonce.replace(/[^\w+/=-]/g, "")}"` : "";
+    const detail = JSON.stringify({
+        phase: "render",
+        ...(digest ? { digest: digest.replace(/[^\w-]/g, "") } : {}),
+        error: "Render failed" + (digest ? ` (digest ${digest.replace(/[^\w-]/g, "")})` : ""),
+    });
+    return `<script${attrs}>document.dispatchEvent(new CustomEvent("rivet:resume-error",{detail:${detail}}))</script>`;
+}
+/**
+ * Render `factory` between the document parts as a streamed UTF-8 body. Writes respect the
+ * consumer's pace: the renderer waits while the stream's queue is full. Always a `Response`: a
+ * failure before any byte left errors the body (`renderDocument` rejects instead).
+ */
+export function renderPage(factory, input, options, init) {
+    return stream(factory, input, options, init, false);
+}
+/**
+ * `renderPage`, but the `Response` is created once the first body bytes are ready (or the render
+ * ended): a failure before that throws / rejects, so the caller can answer with an error page and
+ * status instead of a 200 with a broken body. A synchronous page answers synchronously.
+ */
+export function renderDocument(factory, input, options, init) {
+    return stream(factory, input, options, init, true);
+}
+// The Response's body stream and direct hook close over the writer only, never over `stream`'s scope (one V8
+// context for all its closures: factory, page data, recorder, the rendered graph). Node keeps a Response's web
+// stream (and its source) alive through scavenges until the next mark-compact, unread or not, so whatever the
+// source reaches outlives the request in the young generation and is promoted: resume /resume 1000 rows promoted
+// ~550 KB per request (its whole render) into old space → a mark-compact every ~75 requests under a 512 MiB
+// container. Through `out` only, the stream holds the writer (slabs released, sink) and nothing of the render.
+const ENDED = () => { };
+/** High-water mark 0: `pull` runs only while a read waits, so an unread body can still be attached. */
+const bodyStream = (out) => new ReadableStream({
+    start(c) {
+        out.controller = c;
+    },
+    pull: () => out.pull(),
+    // Cancelled: the next hand-off throws and the render ends.
+    cancel: () => out.cancel(),
+}, { highWaterMark: 0 });
+const directBody = (out) => (sink) => out.attach(sink);
+function stream(factory, input, options, init, deferred) {
+    const hold = options.hold;
+    let parts = hold ? null : options.document(input);
+    // Deferred: no Response until the renderer is really waiting (pending content, not a failure that
+    // is already settled) and bytes are queued, or the render ended; a failure before it rejects. Eager
+    // (`renderPage`): responded from the start. `queued`: bytes are in the stream, no Response handed out
+    // yet (still free to fail); `armed`: the renderer waits, the next queued bytes open the Response.
+    let responded = !deferred, sent = false, queued = false, armed = false, failure = null, opened = null, failed = null;
+    const respond = () => {
+        responded = true;
+        init.headers.set("content-type", "text/html; charset=utf-8");
+        const response = new Response(body, init);
+        // Host adapters (node) take the bytes straight from the writer (`server/body.ts`).
+        Object.defineProperty(response, DIRECT_BODY, { value: direct });
+        return response;
+    };
+    const out = new BodyWriter(() => {
+        sent = true;
+        if (!responded)
+            armed ? open() : (queued = true);
+    });
+    const flush = () => void out.flush();
+    const arm = () => {
+        armed = true;
+        if (out.offset > out.start)
+            flush();
+        else if (queued)
+            open();
+    };
+    const open = () => {
+        if (!opened)
+            return void (queued = true);
+        const done = opened;
+        opened = null;
+        done(respond());
+    };
+    const direct = directBody(out);
+    const body = bodyStream(out);
+    // Held: chunks queue until the shell is done (the marker after the app), then go out after the start.
+    // Still a byte writer while holding (RA5): pre-encoded fragments queue as they are (the renderer's
+    // cached, never-mutated bytes) and integers as strings, so a component-head page keeps the byte path.
+    let held = hold ? [] : null;
+    const writer = hold
+        ? {
+            write(chunk) {
+                if (held)
+                    return void held.push(chunk);
+                return out.write(chunk);
+            },
+            writeBytes(bytes) {
+                if (held)
+                    return void held.push(bytes);
+                return out.writeBytes(bytes);
+            },
+            writeInteger(value) {
+                if (held)
+                    return void held.push(String(value));
+                return out.writeInteger(value);
+            },
+            writeText(text) {
+                if (held)
+                    return void held.push(escapeText(text));
+                return out.writeText(text);
+            },
+        }
+        : out;
+    const release = () => {
+        if (!held)
+            return null;
+        parts = options.document({ ...input, head: hold.head() });
+        const pending = held;
+        held = null;
+        // Synchronous enqueue: the following writes apply backpressure as usual.
+        void out.write(parts.start);
+        for (const chunk of pending)
+            void (typeof chunk === "string" ? out.write(chunk) : out.writeBytes(chunk));
+        return null;
+    };
+    const app = hold ? () => [factory(), release] : factory;
+    let ended = false;
+    void (async () => {
+        try {
+            // Await only real waits (backpressure, pending content): a bare `await` would yield to the
+            // coalescing microtask and split a synchronous page into several chunks.
+            let wait;
+            if (!hold && (wait = writer.write(parts.start)))
+                await wait;
+            if (options.around && (wait = writer.write(options.around.start)))
+                await wait;
+            const signal = options.signal;
+            const variant = options.variant;
+            // One id counter per render (`rv0`, `rv1`, …): the same page renders the same ids whatever the
+            // process rendered before (reproducible HTML / ETags, incremental prerender canaries). Around the
+            // render call, not inside `factory`: the renderer visits what the factory returns (and pending
+            // `Async` content later) under this owner, so every component sees the scope.
+            wait = withIdScope("rv", () => options.manifest
+                ? renderResumable(app, options.discardState ? stateless(writer) : writer, {
+                    manifest: options.manifest,
+                    // Same-origin URLs in the state serialize relative (prerendered pages: no build-time origin).
+                    origin: input.url.origin,
+                    ...(signal ? { signal } : {}),
+                    ...(options.nonce !== undefined ? { nonce: options.nonce } : {}),
+                    ...(options.stream && !options.discardState ? { stream: options.stream } : {}),
+                    ...(options.preload ? { preload: options.preload } : {}),
+                    ...(variant ? { variant } : {}),
+                })
+                : renderToWriter(app, writer, { ...(signal ? { signal } : {}), ...(variant ? { variant } : {}) }));
+            if (wait) {
+                // Deferred: a failure the renderer already settled (a component threw before any await; the
+                // streamed shell's rejection one tick later) must still reach the caller, so probe twice whether
+                // the render promise is really pending before opening the Response.
+                if (!responded && (await Promise.race([wait, TICK])) === PENDING && (await Promise.race([wait, TICK])) === PENDING)
+                    arm();
+                await wait;
+            }
+            release();
+            if (options.around && (wait = writer.write(options.around.end)))
+                await wait;
+            if ((wait = writer.write(parts.end)))
+                await wait;
+            flush();
+            ended = true;
+            out.close();
+            if (!responded)
+                open();
+        }
+        catch (error) {
+            ended = true;
+            const abort = () => {
+                try {
+                    out.fail(error);
+                }
+                catch {
+                    /* Already cancelled by the consumer. */
+                }
+            };
+            // No Response handed out yet: the caller answers (error page, status; or drops an aborted request).
+            if (!responded) {
+                failure = { error };
+                abort();
+                return failed?.(error);
+            }
+            if (options.signal?.aborted)
+                return abort();
+            const digest = options.onError?.(error) || undefined;
+            // Shell already out: end the document cleanly with the marker (no truncated, errored body).
+            // Nothing sent yet (`renderPage`) or the shell not rendered (held head): the body errors.
+            if (!parts || !sent)
+                return abort();
+            try {
+                void out.write(failureMarker(options.nonce, digest));
+                void out.write(parts.end);
+                flush();
+                out.close();
+            }
+            catch {
+                abort();
+            }
+        }
+        finally {
+            // Ended: the hand-off callback is the writer's last tie to this scope (see `bodyStream`).
+            out.enqueued = ENDED;
+        }
+    })();
+    if (failure)
+        throw failure.error;
+    if (responded || queued || ended)
+        return respond();
+    return new Promise((resolve, reject) => ((opened = resolve), (failed = reject)));
+}

package/server/route-cache.d.ts

@@ -0,0 +1,175 @@
+import type { AppHandler } from "./handler.js";
+import type { CSPOptions } from "../shared/csp.js";
+/** How a matched route's rendered pages are cached (`RouteRule.cache`). */
+export interface CacheRule {
+    /** Seconds a stored page is served without rendering (fresh). */
+    readonly maxAge: number;
+    /**
+     * Seconds after `maxAge` the stored page is still served while one background render refreshes it
+     * (stale-while-revalidate); `true`: without limit. Default 0 (an expired page renders on the request).
+     */
+    readonly swr?: number | true;
+    /** Names `revalidate({ tag })` drops these pages by. */
+    readonly tags?: readonly string[];
+    /**
+     * Request headers whose values key separate copies (`accept-language`, …); case-insensitive; never `cookie` /
+     * `authorization`. Sent as `Vary` with every stored page. A response `Vary` naming other headers adds them to the key
+     * too; one naming `cookie` / `authorization` (the i18n guard's) is stored only when `varies` names a header.
+     */
+    readonly varies?: readonly string[];
+    /**
+     * Query strings: `true` (default) keys a copy per query string (a new query string is stored on its second
+     * request), `false` ignores the query (one copy per path), a list keys only those parameters.
+     */
+    readonly query?: boolean | readonly string[];
+    /**
+     * `true`: requests with a `Cookie` header are served from the cache too (cookies are not part of the key) — and every
+     * page of the rule renders without the request's `Cookie` / `Authorization` (anonymous: a loader never sees a session),
+     * so one visitor's page is never stored for everyone. Default: requests with cookies bypass the cache.
+     */
+    readonly cookies?: boolean;
+}
+/** What shared caches / CDNs are told (`RouteRule.cdn`): `s-maxage` / `stale-while-revalidate` seconds. */
+export interface CdnRule {
+    readonly maxAge: number;
+    readonly swr?: number | true;
+}
+/** What applies to the requests whose path matches a pattern. */
+export interface RouteRule {
+    /** Response headers set on every response of the matched paths (pages, data requests, endpoints, 304s). */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Cache rendered pages; `false` turns off a less specific rule's cache. */
+    readonly cache?: CacheRule | false;
+    /** Shorthand: `swr: n` = `cache: { maxAge: n, swr: true }`. */
+    readonly swr?: number | true;
+    /**
+     * Shorthand: `isr: n` = `cache: { maxAge: n, swr: true }`; `isr: true` = stored until `revalidate()`. Needs a fixed
+     * `origin` (`routeCache.origin`, or the adapter's). CDNs get `s-maxage=0, must-revalidate` (`revalidate()` is
+     * process-local: it cannot purge a CDN) unless `cdn` says otherwise.
+     */
+    readonly isr?: number | true;
+    /**
+     * `Cache-Control` for shared caches / CDNs of the stored pages (`s-maxage`, `stale-while-revalidate`). Default: the
+     * cache's own `maxAge` / `swr`, `isr` (and `maxAge: Infinity`) rules `s-maxage=0, must-revalidate`.
+     */
+    readonly cdn?: CdnRule;
+}
+/**
+ * Rules by path pattern (pathname below the app's base): `/about` exact, `*` one segment (`/blog/*`), a trailing
+ * `/**` the path and everything below it (`/docs/**`, `/**`). Every matching rule applies, the less specific first
+ * (fewer literal characters): headers merge by name, the most specific `cache` (or shorthand) wins.
+ */
+export type RouteRules = Readonly<Record<string, RouteRule>>;
+/** Bounds of the in-process page store (`createApp({ routeCache })`). */
+export interface RouteCacheOptions {
+    /** Stored bytes — bodies, their br / gzip copies, keys, headers (default 32 MiB); a page over a quarter of it is never stored. */
+    readonly maxBytes?: number;
+    /** Stored pages (default 5000). */
+    readonly maxEntries?: number;
+    /**
+     * The public origin pages are stored for (`https://shop.example`); requests for another origin bypass the cache.
+     * Required by `isr` rules. Without it the request's origin (from `Host` / trusted forwarded headers) is part of the
+     * key: a forged `Host` renders and stores a copy of its own (never served to other hosts) — set it, or a fixed
+     * `origin` on the node / fetch adapter (`start()` / `createFetchHandler()` pass theirs on).
+     */
+    readonly origin?: string;
+}
+/** A stored page (exported for the node adapter's fast path). */
+export interface CachedPage {
+    readonly key: string;
+    /** Pathname below the base (decoded). */
+    readonly path: string;
+    readonly tags: readonly string[];
+    /** The stored body (a nonce-free document when the app's policy was converted to hashes). */
+    readonly body: Uint8Array;
+    /** Response headers (lower-case names): content type, cache-control, CSP, validators, rule headers. */
+    readonly headers: readonly (readonly [string, string])[];
+    readonly etag: string;
+    /** `Last-Modified` (HTTP date) and its time (ms, second precision). */
+    readonly modified: string;
+    readonly modifiedAt: number;
+    /** Times (ms): stored, fresh until, served stale until. */
+    readonly created: number;
+    readonly fresh: number;
+    readonly stale: number;
+    /** CLOCK reference bit. */
+    used: boolean;
+    /** Bytes counted against `maxBytes` (body, key, headers, `charge`d copies). */
+    size: number;
+    /** Background refreshes that failed in a row, and when the next may start (ms; exponential backoff). */
+    failures: number;
+    retry: number;
+    /** Count `bytes` more against the store's `maxBytes` (an adapter's compressed copy of the body). */
+    charge(bytes: number): void;
+}
+/** Request header lookup (lower-case name). */
+export type HeaderOf = (name: string) => string | null | undefined;
+/** Fresh stored page for a GET / HEAD request, if any (node adapter fast path: before a `Request` exists). `origin`: the request URL's. */
+export type CacheLookup = (method: string, origin: string, pathname: string, search: string, header: HeaderOf) => CachedPage | undefined;
+/** Own property of a handler with route rules: the cache lookup. */
+export declare const ROUTE_CACHE: unique symbol;
+/** A handler with route rules. */
+export type CachingHandler = AppHandler & {
+    readonly [ROUTE_CACHE]: CacheLookup;
+};
+interface Cache {
+    readonly maxAge: number;
+    readonly swr: number;
+    readonly tags: readonly string[];
+    readonly varies: readonly string[];
+    readonly query: boolean | readonly string[];
+    readonly cookies: boolean;
+    /** The `Cache-Control` stored pages answer with. */
+    readonly control: string;
+    /** Headers responses named in `Vary` (beyond `varies`): part of the key from then on. */
+    readonly learned: string[];
+}
+interface Resolved {
+    readonly headers: readonly (readonly [string, string])[];
+    readonly cache: Cache | undefined;
+}
+/**
+ * Compile `rules` (throws `TypeError` on a malformed pattern or rule) into a pathname → rule lookup. `origin`: a fixed
+ * origin is configured (`isr` rules need one).
+ */
+export declare function compileRules(rules: RouteRules, origin?: boolean): (pathname: string) => Resolved | undefined;
+/**
+ * The router's view of a raw pathname: `match` — segments percent-decoded (a decoded `/` stays `%2F`: one segment),
+ * what rules match and keys use; `canonical` — the raw path is that path's one encoding (only those are stored, so
+ * `/%61dmin` neither escapes an `/admin/**` rule nor adds a copy of `/admin`). Malformed escapes: not canonical.
+ */
+export declare function normalPath(pathname: string): {
+    readonly match: string;
+    readonly canonical: boolean;
+};
+/**
+ * Drop stored pages (every app's in this process): by `path` (pathname, with or without the app's base; a trailing
+ * `/**` drops everything below it) and / or `tag` (`CacheRule.tags`). The next request renders; a render already
+ * running does not store its page. Returns how many pages were dropped here. Node `start({ workers })`: the other
+ * workers drop theirs too (relayed by the primary, asynchronously). Other servers and CDNs keep theirs until they
+ * expire.
+ */
+export declare function revalidate(target: {
+    readonly path?: string;
+    readonly tag?: string;
+}): number;
+/** `If-None-Match` (weak comparison) / `If-Modified-Since` (when no `If-None-Match`) hold for `page`. */
+export declare function notModified(page: CachedPage, match: string | null | undefined, since: string | null | undefined): boolean;
+/** Content-Security-Policy handling of stored pages (from `createApp` `csp`). */
+export interface CachePolicy {
+    /** The app's policy for a nonce (`false`: none). A stored response whose policy differs (a route's own) is kept as rendered. */
+    readonly policy: (nonce: string) => string | false;
+    /**
+     * Convert the app's nonce policy to hashes of the page's nonce'd inline code (default / `CSPOptions` apps); `null`:
+     * no conversion (a `csp` function) — a page whose policy allows its nonce is then not stored (one nonce for every visitor).
+     */
+    readonly hash: CSPOptions | null;
+}
+/** Own property the app sets on a request whose render reported a failure (`onError`: an error fallback was rendered). */
+export declare const RENDER_FAILED: unique symbol;
+/**
+ * Wrap the app's handler with route rules. `base`: the app's base path (stripped before matching). The result
+ * carries `ROUTE_CACHE` (node adapter fast path).
+ */
+export declare function withRouteRules(handler: AppHandler, rules: RouteRules, csp: CachePolicy, base?: string, options?: RouteCacheOptions): CachingHandler;
+export {};