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

package/server/route-cache.d.ts

@@ -0,0 +1,245 @@
+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;
+    /**
+     * Shell cache (partial prerendering, `server/shell-cache.ts`): the document up to its first streamed boundary (the shell:
+     * everything outside `<Async fallback>` holes reading deferred loaders) is stored once and sent at once on later
+     * requests — signed-in ones too (cookies never bypass it, never key it) — while the holes render live per request in
+     * the same response. `true`: the rule's `cache` / `swr` / `isr` times, else stored until `revalidate()` (needs a fixed
+     * `origin`, like `isr`); an object sets them. Fills that read request input outside the key (cookies, headers, locals,
+     * unkeyed query parameters) are not stored (dev logs why). `false` turns off a less specific rule's shell. Not with `cdn`.
+     */
+    readonly shell?: boolean | ShellRule;
+}
+/** `RouteRule.shell` times and keys (defaults: the rule's `cache` / `swr` / `isr`, else stored until `revalidate()`). */
+export interface ShellRule {
+    readonly maxAge?: number;
+    readonly swr?: number | true;
+    readonly tags?: readonly string[];
+    /** Request headers whose values key separate shells (never `cookie` / `authorization`). */
+    readonly varies?: readonly string[];
+    /** `true` (default): one shell per query string; `false`: query-less URLs only; a list: those parameters (other URLs render without the shell). */
+    readonly query?: boolean | readonly string[];
+}
+/**
+ * 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[];
+}
+/** @internal A rule's normalised cache (exported for `shell-cache.ts`). */
+export type { Cache as _Cache };
+/** @internal */
+export interface Resolved {
+    readonly headers: readonly (readonly [string, string])[];
+    readonly cache: Cache | undefined;
+    /** Shell cache (`RouteRule.shell`): wins over `cache` for documents. */
+    readonly shell?: Cache;
+}
+/**
+ * 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;
+/** Bounded page store, CLOCK eviction (a hit sets one bit). Shell entries (`shell-cache.ts`) live here too (key `…\0shell`). */
+declare class Store {
+    readonly pages: Map<string, CachedPage>;
+    /** Shell cache: rejected fills per route id (3 in a row → no more attempts until a `revalidate()`). */
+    readonly sticky: Map<string, number>;
+    bytes: number;
+    /** Fills running now (`path`, `tags`): a `revalidate()` matching one voids it (it answers but does not store). */
+    readonly filling: Set<{
+        readonly path: string;
+        readonly tags: readonly string[];
+        void: boolean;
+    }>;
+    readonly maxBytes: number;
+    readonly maxEntries: number;
+    readonly base: string;
+    constructor(maxBytes: number, maxEntries: number, base: string);
+    get(key: string): CachedPage | undefined;
+    set(page: CachedPage): void;
+    /** `page` (stored) grew by `bytes`. */
+    grow(page: CachedPage, bytes: number): void;
+    private evict;
+    delete(key: string): boolean;
+}
+/** @internal The page store type (`shell-cache.ts` keeps its entries in it). */
+export type { Store as _Store };
+/**
+ * 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;
+/** @internal What `withRouteRules` hands the shell cache (`shell-cache.ts` `createShells`). */
+export interface ShellHost {
+    readonly handler: AppHandler;
+    readonly store: Store;
+    readonly csp: CachePolicy;
+    readonly fixed: string | undefined;
+    readonly dev: boolean;
+    /** Build identity (the resume runtime's URL): part of each shell's `h`. */
+    readonly build: string;
+    keyOf(cache: Cache, origin: string, path: string, search: string, header: HeaderOf): string;
+    secondMiss(cache: Cache, search: string, header: HeaderOf): boolean;
+    readonly doorkeeper: Set<string>;
+    withHeaders(response: Response, headers: Resolved["headers"]): Response;
+}
+/** @internal The shell cache's request entry (`shell-cache.ts`); undefined: render without it. */
+export type ShellServe = (request: Request, context: Parameters<AppHandler>[1], resolved: Resolved, origin: string, path: string, search: string) => Promise<Response> | undefined;
+/**
+ * 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). `shells`: the shell cache module (`createApp` loads it only for
+ * rules with `shell`); `internal.dev`: shell rules only probe (never store; reasons logged), `internal.build`: build id.
+ */
+export declare function withRouteRules(handler: AppHandler, rules: RouteRules, csp: CachePolicy, base?: string, options?: RouteCacheOptions, shells?: {
+    createShells(host: ShellHost): ShellServe;
+}, internal?: {
+    dev?: boolean;
+    build?: string;
+}): CachingHandler;