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

package/server/handler.js

@@ -0,0 +1,661 @@
+// Web-standard request handler: route match → guards → parallel loaders → render, plus the data
+// endpoint client navigation uses (so guards always run on the server) and form actions.
+import { compileRoutes } from "@rivetjs/runtime/router/server";
+import { createEncoder, _builtinKinds } from "@rivetjs/runtime/resume-format";
+import { HttpError, isHttpError } from "../shared/errors.js";
+import { isActionFailure } from "../shared/actions.js";
+import { DATA_PARAM, KEEP_PAGE, KEEP_PARAM, withoutRivet } from "../shared/data.js";
+export { DATA_PARAM } from "../shared/data.js";
+import { loadServer } from "./module.js";
+import { crossSite, limitBody } from "./security.js";
+import { ABSOLUTE, unsafeTarget } from "../shared/redirect.js";
+import { slashPath, TRAILING_SLASH } from "../shared/slash.js";
+import { parseCookies } from "../shared/cookie.js";
+/** @internal Request property carrying a `ShellRequest` (`Symbol.for("rivet.shell")`). */
+export const SHELL = Symbol.for("rivet.shell");
+/** @internal Short random id tying a hidden 5xx message to its server log entry. */
+export const _digest = () => {
+    const bytes = crypto.getRandomValues(new Uint8Array(5));
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+};
+const METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]);
+const ON = { GET: "onGet", POST: "onPost", PUT: "onPut", PATCH: "onPatch", DELETE: "onDelete" };
+/** `byURL` when no layout loader read the URL (shared: a server render always reports it). */
+const NO_LAYOUTS = Object.freeze([]);
+const TOKEN = /^[!#$%&'*+\-.^_`|~\w]+$/;
+/** RFC 6265 path-value: no CTLs, no `;` (it would start another attribute). */
+const PATH = /^\/[^\u0000-\u001f\u007f;]*$/;
+/** Host name or IP literal, optional leading dot. */
+const DOMAIN = /^\.?[a-z\d](?:[a-z\d-]*[a-z\d])?(?:\.[a-z\d](?:[a-z\d-]*[a-z\d])?)*$/i;
+const SAME_SITE = { lax: "Lax", strict: "Strict", none: "None" };
+/** Browsers drop cookies whose name + value exceed 4096 bytes. */
+const COOKIE_MAX = 4096;
+function serializeCookie(name, value, options = {}) {
+    if (!TOKEN.test(name))
+        throw new TypeError("Invalid cookie name");
+    const path = options.path ?? "/";
+    if (!PATH.test(path))
+        throw new TypeError(`Invalid cookie path ${JSON.stringify(path)}`);
+    const encoded = encodeURIComponent(value);
+    if (name.length + encoded.length > COOKIE_MAX)
+        throw new TypeError(`Cookie "${name}" is larger than ${COOKIE_MAX} bytes (browsers drop it)`);
+    const secure = options.secure ?? true;
+    const sameSite = options.sameSite ?? "lax";
+    if (!Object.hasOwn(SAME_SITE, sameSite))
+        throw new TypeError(`Invalid cookie sameSite ${JSON.stringify(sameSite)}`);
+    if (sameSite === "none" && !secure)
+        throw new TypeError(`Cookie "${name}": sameSite "none" requires secure (browsers reject it)`);
+    if ((name.startsWith("__Secure-") || name.startsWith("__Host-")) && !secure)
+        throw new TypeError(`Cookie "${name}": the prefix requires secure`);
+    if (name.startsWith("__Host-") && (path !== "/" || options.domain))
+        throw new TypeError(`Cookie "${name}": __Host- requires path "/" and no domain`);
+    let out = name + "=" + encoded + "; Path=" + path;
+    if (options.domain) {
+        if (!DOMAIN.test(options.domain))
+            throw new TypeError(`Invalid cookie domain ${JSON.stringify(options.domain)}`);
+        out += "; Domain=" + options.domain;
+    }
+    if (options.maxAge !== undefined) {
+        if (!Number.isFinite(options.maxAge))
+            throw new TypeError(`Invalid cookie maxAge ${options.maxAge}`);
+        out += "; Max-Age=" + Math.floor(options.maxAge);
+    }
+    if (options.expires) {
+        if (!(options.expires instanceof Date) || Number.isNaN(options.expires.getTime()))
+            throw new TypeError("Invalid cookie expires date");
+        out += "; Expires=" + options.expires.toUTCString();
+    }
+    if (options.httpOnly ?? true)
+        out += "; HttpOnly";
+    if (secure)
+        out += "; Secure";
+    out += "; SameSite=" + SAME_SITE[sameSite];
+    return out;
+}
+/**
+ * A response that sets a cookie must not be stored by shared caches (it would hand the cookie to
+ * every visitor): `Cache-Control` gets `private`; `public` and `s-maxage` go, other directives stay.
+ */
+function privateCache(headers) {
+    const kept = (headers.get("cache-control") ?? "")
+        .split(",")
+        .map((d) => d.trim())
+        .filter((d) => d && !/^(?:public|private|s-maxage)\b/i.test(d));
+    headers.set("cache-control", ["private", ...kept].join(", "));
+}
+/**
+ * Encode a value with the resume table (Date/Map/Set/BigInt/undefined/cycles survive). With built-in entries (RegExp /
+ * URLSearchParams / binary / errors) and a `builtins` chunk URL, `x` names it: the client imports it before decoding.
+ */
+export function encodeData(value, builtins, origin) {
+    const encoder = createEncoder({ origin });
+    const root = encoder.ref(value);
+    return JSON.stringify(builtins && _builtinKinds(encoder.table) ? { t: encoder.table, r: root, x: builtins } : { t: encoder.table, r: root });
+}
+const isRedirect = (e) => e.location !== undefined;
+/** A same-origin redirect target that is the page itself without a query (`url`: the action request's URL). */
+function backHere(location, url) {
+    const target = new URL(location, url);
+    return target.origin === url.origin && target.pathname === url.pathname && !target.search && !target.hash;
+}
+/** A redirect from an action without an explicit status answers 303 (the browser follows with GET). */
+const seeOther = (failure) => {
+    if (!isHttpError(failure) || !failure.defaultStatus)
+        return failure;
+    const out = new HttpError(303, failure.message, failure.location);
+    if (failure.external)
+        Object.defineProperty(out, "external", { value: true });
+    return out;
+};
+const NO_PLATFORM = Object.freeze({});
+/** `load(fn, { defer: true })` marker (`shared/server-exports.ts` `DEFER`). */
+const DEFER = Symbol.for("rivet.defer");
+let deferredModule;
+// `event.depends()` outside loaders.
+const noDeps = () => { };
+// Dev hint, once per layout: a layout loader that denies or redirects acts as access control, but
+// client navigations that keep the layout's data (`_rivet_keep`, client-controlled) skip it.
+const hinted = new Set();
+function accessHint(route, index, failure) {
+    const layout = route.keys?.[index] ?? String(index);
+    if (isHttpError(failure) && (failure.status === 401 || failure.status === 403 || isRedirect(failure)) && !hinted.has(layout)) {
+        hinted.add(layout);
+        console.warn(`[rivet] The loader of layout "${layout}" ${isRedirect(failure) ? "redirected" : "answered " + failure.status}: loaders are not access control. ` +
+            "Client navigations that keep this layout's data skip its loader, so pages below it would load anyway. Check access in a `guard(…)` export (guards always run).");
+    }
+    throw failure;
+}
+/**
+ * One loader's view of the request event (`loaderEvent`): every member reads through to the event, `depends()`
+ * records this loader's keys and, for layouts (`byURL`), reading `url` / `request` notes that it depends on the
+ * URL. A class instead of `Object.create(event, descriptors)`: that built a dictionary-mode object with fresh
+ * closures per loader, per request (~0.6 µs + garbage each). Destructuring loaders read members once each.
+ */
+class LoaderEvent {
+    #event;
+    #index;
+    #byURL;
+    #deps;
+    constructor(event, index, byURL, deps) {
+        this.#event = event;
+        this.#index = index;
+        this.#byURL = byURL;
+        this.#deps = deps;
+    }
+    get request() {
+        this.#byURL?.add(this.#index);
+        return this.#event.request;
+    }
+    get url() {
+        this.#byURL?.add(this.#index);
+        return this.#event.url;
+    }
+    // A getter (closure made when read): loaders destructure it (`({ depends }) => …`).
+    get depends() {
+        const deps = this.#deps, index = this.#index;
+        return (...keys) => {
+            const set = (deps[index] ??= new Set());
+            for (const key of keys)
+                set.add(String(key));
+        };
+    }
+    get params() {
+        return this.#event.params;
+    }
+    get locals() {
+        return this.#event.locals;
+    }
+    get signal() {
+        return this.#event.signal;
+    }
+    get cookies() {
+        return this.#event.cookies;
+    }
+    get dev() {
+        return this.#event.dev;
+    }
+    get route() {
+        return this.#event.route;
+    }
+    get isDataRequest() {
+        return this.#event.isDataRequest;
+    }
+    get platform() {
+        return this.#event.platform;
+    }
+    get setHeader() {
+        return this.#event.setHeader;
+    }
+    get setHeaders() {
+        return this.#event.setHeaders;
+    }
+}
+/** Create the app's request handler. */
+export function createHandler(options) {
+    const { routes, render, dev = false } = options;
+    // `origin`: same-origin URLs in the data serialize relative (prerendered `_data.json`: no build-time origin).
+    const reply = (value, status, headers, origin) => json(value, status, headers, options.builtins?.(), origin);
+    const report = options.onError ?? ((error, _request, info) => console.error("[rivet] digest " + info?.digest + ":", error));
+    const match = compileRoutes(routes.map((route) => ({ path: route.pattern, render: () => route })));
+    // The root layout's server module (layout id `/`): unmatched URLs' error pages render inside it.
+    const rootLayout = routes.find((route) => route.keys?.[0] === "/");
+    return async (request, context = {}) => {
+        const url = new URL(request.url);
+        // `url.searchParams` only when the query names the router's params (document requests skip it);
+        // they are removed textually (re-serializing would turn `?flag&q=a%20b` into `?flag=&q=a+b`).
+        const data = url.search.includes(DATA_PARAM) && url.searchParams.get(DATA_PARAM) === "data";
+        // Layouts whose data the client still has (`_rivet_keep=id,id`): their loaders are skipped (guards still run).
+        const kept = data ? url.searchParams.get(KEEP_PARAM) : null;
+        if (data)
+            url.search = withoutRivet(url.search);
+        const headers = new Headers();
+        const nonce = context.nonce;
+        // Seeded by the caller (`context.locals`): a copy, so guards writing `locals` never reach the caller's object.
+        const seed = context.locals;
+        const locals = seed ? { ...seed } : {};
+        const found = match(url);
+        const route = found ? found.route.render(undefined, found) : undefined;
+        const method = request.method === "HEAD" ? "GET" : request.method;
+        // `?/save&next=/b`: the action name ends at the first `&`. Bad percent-encoding → 400 (after CSRF).
+        let action;
+        let malformed = false;
+        if (method === "POST" && url.search.startsWith("?/")) {
+            action = url.search.slice(2).split("&", 1)[0];
+            try {
+                action = decodeURIComponent(action);
+            }
+            catch {
+                malformed = true;
+            }
+        }
+        // Enhanced form submits (JSON) get redirects and failures as JSON, like data requests.
+        const wantsJSON = data || (action !== undefined && (request.headers.get("accept") ?? "").includes("application/json"));
+        // Error pages keep the outermost layouts whose guards passed (`guarded` modules) and whose loaders
+        // succeeded: loaders that already ran are reused, the others run now (guards passed for them).
+        let guarded = 0;
+        let modules = [];
+        const loads = [];
+        const errorLayouts = async () => {
+            const out = [];
+            for (let i = 0; i < Math.min(guarded, route ? route.layouts.length : 1); i++) {
+                try {
+                    out.push(await (loads[i] ??= Promise.resolve(modules[i]?.load?.(event))));
+                }
+                catch {
+                    break;
+                }
+            }
+            return out;
+        };
+        // Set by `event.cookies`: the response gets `privateCache` once its headers are final.
+        let setsCookie = false;
+        const fail = async (status, message) => {
+            if (setsCookie)
+                privateCache(headers);
+            if (wantsJSON)
+                return reply({ error: { status, message } }, status, headers, url.origin);
+            const layouts = options.renderError && guarded ? await errorLayouts() : [];
+            const input = { request, url, route, status, message, headers, nonce, locals, ...(layouts.length ? { layouts } : {}) };
+            if (options.renderError)
+                return options.renderError(input);
+            headers.set("content-type", "text/plain; charset=utf-8");
+            return new Response(message, { status, headers });
+        };
+        const body = { exceeded: false };
+        let phase = "handler";
+        const settle = async (failure) => {
+            if (body.exceeded)
+                return fail(413, "Payload too large");
+            // Absolute redirect targets must stay on this origin unless `redirect(url, { external: true })`.
+            if (isHttpError(failure) &&
+                isRedirect(failure) &&
+                !failure.external &&
+                ABSOLUTE.test(failure.location) &&
+                new URL(failure.location).origin !== url.origin)
+                failure = new Error(`redirect() to another origin (${failure.location}); pass { external: true } to allow it`);
+            if (isHttpError(failure)) {
+                if (isRedirect(failure)) {
+                    if (setsCookie)
+                        privateCache(headers);
+                    if (wantsJSON)
+                        return reply({ redirect: failure.location, status: failure.status }, 200, headers, url.origin);
+                    headers.set("location", failure.location);
+                    return new Response(null, { status: failure.status, headers });
+                }
+                if (failure.status < 500)
+                    return fail(failure.status, failure.expose || dev ? failure.message : "Internal Server Error");
+                const digest = _digest();
+                report(failure, request, { digest, phase, route: route.id });
+                return fail(failure.status, failure.expose || dev ? failure.message : `Internal Server Error (digest ${digest})`);
+            }
+            if (request.signal.aborted)
+                throw failure;
+            const digest = _digest();
+            report(failure, request, { digest, phase, route: route.id });
+            return fail(500, dev && failure instanceof Error ? failure.message : `Internal Server Error (digest ${digest})`);
+        };
+        // Parsed on first cookie access (most requests never read one).
+        let jar;
+        const cookieJar = () => (jar ??= parseCookies(request.headers.get("cookie")));
+        const event = {
+            request,
+            url,
+            params: found?.params ?? {},
+            locals,
+            signal: request.signal,
+            dev,
+            cookies: {
+                get: (name) => cookieJar().get(name),
+                getAll: () => Array.from(cookieJar(), ([name, value]) => ({ name, value })),
+                set: (name, value, cookie) => {
+                    cookieJar().set(name, value);
+                    setsCookie = true;
+                    headers.append("set-cookie", serializeCookie(name, value, cookie));
+                },
+                delete: (name, cookie) => {
+                    cookieJar().delete(name);
+                    setsCookie = true;
+                    headers.append("set-cookie", serializeCookie(name, "", { ...cookie, maxAge: 0, expires: new Date(0) }));
+                },
+            },
+            setHeader: (name, value) => headers.set(name, value),
+            setHeaders: (values) => {
+                for (const name in values) {
+                    if (name.toLowerCase() === "set-cookie")
+                        throw new TypeError("setHeaders: use event.cookies.set for set-cookie");
+                    headers.set(name, values[name]);
+                }
+            },
+            route: { id: route?.id ?? null },
+            isDataRequest: data,
+            platform: context.platform || context.address ? { ...(context.address ? { clientAddress: context.address } : {}), ...context.platform } : NO_PLATFORM,
+            depends: noDeps,
+        };
+        // Each loader gets its own view of the event: `depends()` records its keys (route data index);
+        // `track` (layouts) also notes reads of the URL or request (such data is not kept across URL changes).
+        const deps = [];
+        const byURL = new Set();
+        const loaderEvent = (i, track) => new LoaderEvent(event, i, track ? byURL : null, deps);
+        // Only when a loader called `depends()`: one entry per loader, undefined for the others.
+        const depsOf = () => (deps.length ? { deps: Array.from(modules, (_, i) => (deps[i] ? [...deps[i]] : undefined)) } : {});
+        // A Response from a request handler, guard, action or endpoint keeps what the request set: event
+        // cookies are appended, other event headers fill in what it lacks (its own win). Immutable headers
+        // (`Response.redirect()`, a proxied `fetch()`) are copied first.
+        const merge = (response) => {
+            const cookies = headers.getSetCookie();
+            let own = false;
+            headers.forEach((_, name) => (own ||= name !== "set-cookie"));
+            if (!cookies.length && !own)
+                return response;
+            const apply = (target) => {
+                headers.forEach((value, name) => name !== "set-cookie" && !target.has(name) && target.set(name, value));
+                for (const cookie of cookies)
+                    target.append("set-cookie", cookie);
+                if (setsCookie)
+                    privateCache(target);
+            };
+            try {
+                apply(response.headers);
+                return response;
+            }
+            catch {
+                const copy = new Response(response.body, response);
+                apply(copy.headers);
+                return copy;
+            }
+        };
+        // Data requests: a guard's or request handler's Response becomes the JSON the client follows
+        // (3xx → `{ redirect }`, anything else → `{ reload }`); enhanced actions get redirects as JSON.
+        // A target the client must not follow itself (`javascript:`, `//evil`, control characters): the
+        // client loads the document instead, where the browser applies the real response.
+        const early = (response) => {
+            if (!wantsJSON)
+                return merge(response);
+            for (const cookie of response.headers.getSetCookie())
+                headers.append("set-cookie", cookie);
+            if (!headers.has("cache-control"))
+                headers.set("cache-control", "no-store");
+            else if (setsCookie || headers.has("set-cookie"))
+                privateCache(headers);
+            const location = response.status >= 300 && response.status < 400 ? response.headers.get("location") : null;
+            if (location !== null && !unsafeTarget(location) && (!ABSOLUTE.test(location) || /^https?:/i.test(location)))
+                return reply({ redirect: location, status: response.status }, 200, headers, url.origin);
+            return data || location !== null ? reply({ reload: true }, 200, headers, url.origin) : merge(response);
+        };
+        if (!found || !route) {
+            // The 404 page renders inside the root layout when its guard passes (its loader runs in `fail`).
+            if (rootLayout && options.renderError && !wantsJSON && method === "GET") {
+                try {
+                    modules = [await loadServer(rootLayout.layouts[0])];
+                    const verdict = await modules[0]?.guard?.(event);
+                    if (verdict === undefined)
+                        guarded = 1;
+                }
+                catch {
+                    /* No layout around the 404 page. */
+                }
+            }
+            return fail(404, "Not found");
+        }
+        // `rivetRouter({ trailingSlash })` (build-time constant, folded away when unset): page GET/HEAD in
+        // the other form → 308 to the canonical path (query kept; data requests get `{ redirect }`), before
+        // any handler runs. `/`, endpoints and other methods are left alone.
+        if (TRAILING_SLASH !== "ignore" && method === "GET" && route.page) {
+            const canonical = slashPath(url.pathname, TRAILING_SLASH);
+            if (canonical !== url.pathname) {
+                headers.set("location", canonical + url.search);
+                return early(new Response(null, { status: 308, headers }));
+            }
+        }
+        if (!METHODS.has(method)) {
+            if (route.page)
+                headers.set("allow", "GET, HEAD, POST");
+            return fail(405, "Method not allowed");
+        }
+        try {
+            modules = await Promise.all([...route.layouts.map(loadServer), loadServer(route.server)]);
+            const own = modules[modules.length - 1];
+            const on = method === "OPTIONS" ? "onOptions" : ON[method];
+            // Unsafe methods: cross-site check before any handler, guard or action; then the body limit.
+            // OPTIONS (CORS preflight) is safe: no check, no body.
+            if (method !== "GET" && method !== "OPTIONS") {
+                if (own?.csrf !== false && crossSite(request, url.origin, dev))
+                    throw new HttpError(403, "Cross-site request rejected");
+                request = limitBody(request, options.maxBody, body);
+                event.request = request;
+            }
+            if (malformed)
+                throw new HttpError(400, "Malformed action name");
+            // Page routes take GET, actions, and methods the route module handles (`onPost`…).
+            // `Allow`: page routes take GET/HEAD, POST (actions) and the methods the route module handles;
+            // endpoints what they export. 405 answers list those; OPTIONS answers add OPTIONS.
+            const allow = (options) => [
+                ...(route.page
+                    ? ["GET, HEAD, POST", ...["PUT", "PATCH", "DELETE"].filter((m) => own?.[ON[m]])]
+                    : Object.keys(ON).filter((m) => own?.[ON[m]]).map((m) => (m === "GET" ? "GET, HEAD" : m))),
+                ...(options ? ["OPTIONS"] : []),
+            ].join(", ");
+            if (route.page && method !== "GET" && method !== "OPTIONS" && action === undefined && !own?.[on]) {
+                headers.set("allow", allow(false));
+                return fail(405, "Method not allowed");
+            }
+            // Request handlers: outermost first, `onRequest` then `on<Method>`; an endpoint route's own
+            // `on<Method>` produces its response below. OPTIONS: `onRequest` then `onOptions` (own module too).
+            for (const module of modules) {
+                if (!module)
+                    continue;
+                const first = module.onRequest;
+                if (first) {
+                    const result = await first(event);
+                    if (result instanceof Response)
+                        return early(result);
+                    if (isHttpError(result))
+                        throw result;
+                }
+                const second = route.page || module !== own || method === "OPTIONS" ? module[on] : undefined;
+                if (second) {
+                    const result = await second(event);
+                    if (result instanceof Response)
+                        return early(result);
+                    if (isHttpError(result))
+                        throw result;
+                }
+            }
+            // OPTIONS no handler answered: what the route allows (no guards, loaders or render).
+            if (method === "OPTIONS") {
+                headers.set("allow", allow(true));
+                return new Response(null, { status: 204, headers });
+            }
+            // Early hints: before guards and loaders (the slow part of data-backed pages); public asset URLs only.
+            if (options.earlyHints && method === "GET" && route.page && !wantsJSON && action === undefined)
+                options.earlyHints(route, request);
+            // Guards run outermost first and stop the chain on the first non-void result.
+            phase = "guard";
+            for (const module of modules) {
+                const guard = module?.guard;
+                if (guard) {
+                    const verdict = await guard(event);
+                    if (verdict instanceof Response)
+                        return early(verdict);
+                    if (isHttpError(verdict))
+                        throw verdict;
+                }
+                guarded++;
+            }
+            phase = "handler";
+            for (const module of modules) {
+                const extra = module?.headers?.(event);
+                if (extra)
+                    new Headers(extra).forEach((value, name) => headers.set(name, value));
+            }
+            // Route rule `shell` (document GET of a page): a hit sends the stored shell now; a fill tracks request reads.
+            const shell = route.page && action === undefined && !data ? request[SHELL]?.begin(route, event, headers) : undefined;
+            if (!route.page) {
+                const endpoint = own?.[on];
+                if (!endpoint) {
+                    headers.set("allow", allow(false));
+                    return fail(405, "Method not allowed");
+                }
+                const response = await endpoint(event);
+                if (body.exceeded)
+                    return fail(413, "Payload too large");
+                if (!(response instanceof Response))
+                    throw new Error(`${route.id}: ${on} must return a Response`);
+                return merge(response);
+            }
+            let performed;
+            let status = 200;
+            if (action !== undefined) {
+                phase = "action";
+                // Own function members only: `?/toString`, `?/constructor`, `?/__proto__` are unknown actions.
+                const actions = own?.actions;
+                const run = actions && Object.hasOwn(actions, action) ? actions[action] : undefined;
+                if (typeof run !== "function")
+                    throw new HttpError(404, `Unknown action "${action}"`);
+                let result;
+                try {
+                    result = await run(event);
+                }
+                catch (failure) {
+                    result = failure;
+                    if (!isHttpError(failure))
+                        throw failure;
+                }
+                if (body.exceeded)
+                    return fail(413, "Payload too large");
+                if (isHttpError(result)) {
+                    const failure = seeOther(result);
+                    // Single flight for post/redirect/get back to this page (`redirect()` to its path, no query): the
+                    // enhanced submit gets the page's fresh loader data with the redirect (no second data request).
+                    if (wantsJSON && request.headers.has("x-rivet-revalidate") && isRedirect(failure) && backHere(failure.location, url)) {
+                        if (!headers.has("cache-control"))
+                            headers.set("cache-control", "no-store");
+                        if (setsCookie)
+                            privateCache(headers);
+                        url.search = "";
+                        phase = "loader";
+                        const fresh = await Promise.all(modules.map((module, i) => module?.load?.(loaderEvent(i, false))));
+                        const head = await options.head?.(route, fresh, { params: found.params, url });
+                        return reply({ redirect: failure.location, status: failure.status, data: fresh, ...(head ? { head } : {}), ...depsOf() }, 200, headers, url.origin);
+                    }
+                    throw failure;
+                }
+                if (result instanceof Response)
+                    return early(result);
+                if (isActionFailure(result)) {
+                    status = result.status;
+                    performed = { name: action, result: result.data, status };
+                }
+                else
+                    performed = { name: action, result };
+                url.search = "";
+                if (wantsJSON) {
+                    if (!headers.has("cache-control"))
+                        headers.set("cache-control", "no-store");
+                    if (setsCookie)
+                        privateCache(headers);
+                    // Single flight: an enhanced form submit that succeeded gets the page's fresh loader data
+                    // (the client revalidates from it). Failures changed nothing; other JSON posts (field checks,
+                    // autosave drafts) do not ask for it.
+                    if (status < 400 && request.headers.has("x-rivet-revalidate")) {
+                        phase = "loader";
+                        const fresh = await Promise.all(modules.map((module, i) => module?.load?.(loaderEvent(i, false))));
+                        const head = await options.head?.(route, fresh, { params: found.params, url });
+                        return reply({ action: performed, data: fresh, ...(head ? { head } : {}), ...depsOf() }, status, headers, url.origin);
+                    }
+                    return reply({ action: performed }, status, headers, url.origin);
+                }
+            }
+            const skip = new Set();
+            if (kept) {
+                const ids = new Set(kept.split(","));
+                const allowed = await options.keepable?.(route);
+                route.keys?.forEach((id, i) => ids.has(id) && allowed?.[i] !== false && skip.add(i));
+                // `.`: the page's own loader (same-URL `invalidate(key)` of layout keys only).
+                if (ids.has(KEEP_PAGE) && allowed?.[route.layouts.length] !== false)
+                    skip.add(route.layouts.length);
+            }
+            // Layout loaders that read the URL (or request) cannot be kept across URL changes: the client learns which.
+            phase = "loader";
+            // Deferred loaders (`load(fn, { defer: true })`, document requests only; data requests await them like any loader):
+            // started now, not awaited; their slot is a `Deferred` handle (`deferred.ts`, imported on first use).
+            let lazy, promises, moved;
+            if (!data && modules.some((module) => module?.load && module.load[DEFER]))
+                lazy = await (deferredModule ??= import("./deferred.js"));
+            const loaded = await Promise.all(modules.map((module, i) => {
+                if (skip.has(i) || !module?.load)
+                    return (loads[i] = undefined);
+                if (lazy && module.load[DEFER]) {
+                    // Deferred loaders are the shell's holes: live on every request, never tracked.
+                    const view = lazy.lateEvent(loaderEvent(i, i < route.layouts.length));
+                    // Error pages await it like the other loaders (`errorLayouts`): they render after the failure, not streamed.
+                    const started = ((promises ??= [])[i] = loads[i] = lazy.startDeferred(() => module.load(view)));
+                    // A redirect after the head is out: a client redirect at the document's end (other origins need `external`).
+                    started.catch((failure) => {
+                        if (isHttpError(failure) &&
+                            isRedirect(failure) &&
+                            (failure.external || !ABSOLUTE.test(failure.location) || new URL(failure.location).origin === url.origin))
+                            moved ??= failure.location;
+                    });
+                    // The handle is a thenable: set after `Promise.all`, which would await it.
+                    return undefined;
+                }
+                // Shell hit: the stored shell's data (its loaders read no request input; the composed response is out).
+                if (shell?.data)
+                    return (loads[i] = undefined), shell.data[i];
+                const view = loaderEvent(i, i < route.layouts.length);
+                const load = Promise.resolve(module.load(shell?.event ? shell.event(view, i) : view));
+                // Dev: a layout loader used as access control is skipped for kept layouts (`_rivet_keep`).
+                return (loads[i] = dev && i < route.layouts.length ? load.catch((failure) => accessHint(route, i, failure)) : load);
+            }));
+            shell?.loaded?.(loaded.slice(), [...byURL], depsOf().deps);
+            if (promises)
+                promises.forEach((promise, i) => (loaded[i] = shell?.handle ? shell.handle(promise, dev) : lazy.deferredHandle(promise, dev)));
+            const head = await options.head?.(route, loaded, { params: found.params, url });
+            if (data) {
+                if (!headers.has("cache-control"))
+                    headers.set("cache-control", "private, no-store");
+                else if (setsCookie)
+                    privateCache(headers);
+                return reply({
+                    data: loaded,
+                    status,
+                    ...(head ? { head } : {}),
+                    ...(skip.size ? { keep: [...skip] } : {}),
+                    ...(byURL.size ? { byURL: [...byURL] } : {}),
+                    ...depsOf(),
+                }, status, headers, url.origin);
+            }
+            if (!headers.has("cache-control"))
+                headers.set("cache-control", "no-cache");
+            if (setsCookie)
+                privateCache(headers);
+            phase = "render";
+            return await render({
+                request,
+                url,
+                route,
+                params: found.params,
+                data: loaded,
+                status,
+                headers,
+                nonce,
+                action: performed,
+                locals: event.locals,
+                head,
+                byURL: shell?.byURL ?? (byURL.size ? [...byURL] : NO_LAYOUTS),
+                ...(shell?.data ? (shell.deps ? { deps: shell.deps } : {}) : depsOf()),
+                ...(promises ? { deferred: true, moved: () => moved } : {}),
+                ...(shell ? { shell } : {}),
+            });
+        }
+        catch (failure) {
+            return settle(failure);
+        }
+    };
+}
+function json(value, status, headers, builtins, origin) {
+    headers.set("content-type", "application/json; charset=utf-8");
+    headers.set("x-content-type-options", "nosniff");
+    return new Response(encodeData(value, builtins, origin), { status, headers });
+}

package/server/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./handler.js";
+export type { CSPDirectives, CSPOptions } from "../shared/csp.js";
+export type { TrailingSlash } from "../shared/slash.js";
+export { strictCSP } from "./strict-csp.js";
+export { createApp, mergeHeads, type AppConfig, type GeneratedEntry, type PageInput } from "./app.js";
+export { renderPage, renderDocument, failureMarker, headTags, type DocumentShell, type DocumentInput, type DocumentParts, type RenderPageOptions, } from "./render.js";
+export { serverExports, mergeServer, loadServer } from "./module.js";
+export type { CacheRule, RouteCacheOptions, RouteRule, RouteRules, ShellRule } from "./route-cache.js";
+export type { EarlyHintsOptions } from "./early-hints.js";