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

package/server/early-hints.d.ts

@@ -0,0 +1,34 @@
+import type { Head } from "../shared/data.js";
+/** `createApp({ earlyHints })`. */
+export interface EarlyHintsOptions {
+    /** Also hint the resume runtime entry (`rel=modulepreload`): pages that start it early (visible preloads). Default false. */
+    readonly runtime?: boolean;
+    /** Extra `Link` values sent as given, e.g. `"<https://cdn.example>; rel=preconnect"`. */
+    readonly links?: readonly string[];
+}
+/** Registered symbol: a per-request `(links) => void` the node adapter puts on the Request it builds (one writer of 103s). */
+export declare const EARLY_HINTS: unique symbol;
+export type HintWriter = (links: readonly string[]) => void;
+/** Whether `url` is a build asset below `base` (hashed file name, served immutable). */
+export declare const isAsset: (url: string, base: string) => boolean;
+/** `<url>; rel=preload; as=style` per linked (not inlined) build-asset stylesheet. */
+export declare function styleLinks(urls: readonly string[], inline: Readonly<Record<string, string>> | undefined, base?: string): string[];
+/**
+ * Build-asset font preloads of a merged head: build files are the same for every visitor; anything else in a head may
+ * come from loader data (preconnects, images) and is left out.
+ */
+export declare function headLinks(head: Head | undefined, base?: string): string[];
+/** Per route id: its `Link` values, re-derived when the learned head links change. */
+export interface Hinter {
+    links(routeId: string): readonly string[];
+    /** A render's merged head: its build-asset font preloads become the route's from now on. */
+    learn(routeId: string, head: Head | undefined): void;
+}
+/** `createApp`'s hinter: `styles` + the route's `routeStyles` (not inlined), learned head links, `links`, the runtime. */
+export declare function createHinter(option: true | EarlyHintsOptions, app: {
+    readonly styles: readonly string[];
+    readonly routeStyles?: Readonly<Record<string, readonly string[]>> | ((routeId: string) => unknown);
+    readonly inlineFor?: (list: readonly string[]) => Readonly<Record<string, string>> | undefined;
+    readonly base: string;
+    readonly runtime?: string | undefined;
+}): Hinter;

package/server/early-hints.js

@@ -0,0 +1,63 @@
+/** Registered symbol: a per-request `(links) => void` the node adapter puts on the Request it builds (one writer of 103s). */
+export const EARLY_HINTS = Symbol.for("rivet.earlyHints");
+// A URL written into a header value: no whitespace / controls, nothing that ends the `<…>` or splits the list.
+const SAFE = /^[^\s\0-\x1f\x7f<>"',;\\]+$/;
+const TOKEN = /^[\w./+-]+$/;
+/** Whether `url` is a build asset below `base` (hashed file name, served immutable). */
+export const isAsset = (url, base) => url.startsWith(base + "/assets/");
+/** `<url>; rel=preload; as=style` per linked (not inlined) build-asset stylesheet. */
+export function styleLinks(urls, inline, base = "") {
+    const out = [];
+    for (const url of urls)
+        if (!(inline && Object.hasOwn(inline, url)) && SAFE.test(url) && isAsset(url, base))
+            out.push(`<${url}>; rel=preload; as=style`);
+    return out;
+}
+/**
+ * Build-asset font preloads of a merged head: build files are the same for every visitor; anything else in a head may
+ * come from loader data (preconnects, images) and is left out.
+ */
+export function headLinks(head, base = "") {
+    const out = [];
+    for (const link of head?.links ?? []) {
+        const value = linkValue(link, base);
+        if (value)
+            out.push(value);
+    }
+    return out;
+}
+function linkValue(link, base) {
+    if (!SAFE.test(link.href))
+        return undefined;
+    const rel = link.rel.toLowerCase();
+    const cors = link.crossorigin === "use-credentials" ? "; crossorigin=use-credentials" : link.crossorigin ? "; crossorigin" : "";
+    if (rel === "preload" && link.as === "font" && isAsset(link.href, base))
+        return `<${link.href}>; rel=preload; as=font${link.type && TOKEN.test(link.type) ? "; type=" + link.type : ""}${cors}`;
+    return undefined;
+}
+/** `createApp`'s hinter: `styles` + the route's `routeStyles` (not inlined), learned head links, `links`, the runtime. */
+export function createHinter(option, app) {
+    const extra = option === true
+        ? []
+        : [...(option.links ?? []), ...(option.runtime && app.runtime && SAFE.test(app.runtime) ? [`<${app.runtime}>; rel=modulepreload`] : [])];
+    const learned = new Map();
+    const memo = new Map();
+    return {
+        links(routeId) {
+            let links = memo.get(routeId);
+            if (links)
+                return links;
+            const own = app.routeStyles && typeof app.routeStyles !== "function" ? app.routeStyles[routeId] : undefined;
+            const list = own?.length ? [...app.styles, ...own] : app.styles;
+            const head = learned.get(routeId);
+            links = [...styleLinks(list, app.inlineFor?.(list), app.base), ...(head ? head.split("\n") : []), ...extra];
+            memo.set(routeId, links);
+            return links;
+        },
+        learn(routeId, head) {
+            const value = headLinks(head, app.base).join("\n");
+            if (value !== (learned.get(routeId) ?? ""))
+                (value ? learned.set(routeId, value) : learned.delete(routeId), memo.delete(routeId));
+        },
+    };
+}

package/server/handler.d.ts

@@ -0,0 +1,196 @@
+import { type ActionResult, type Head, type LoaderDeps } from "../shared/data.js";
+export { DATA_PARAM, type ActionResult } from "../shared/data.js";
+import { type BodyLimit } from "./security.js";
+export type { BodyLimit } from "./security.js";
+import type { RouteId, RouteParams } from "../index.js";
+/** Cookie access for one request; `set`/`delete` append `Set-Cookie` to the response. */
+export interface Cookies {
+    get(name: string): string | undefined;
+    /** Every request cookie (with this request's `set`/`delete` applied), in header order. */
+    getAll(): {
+        name: string;
+        value: string;
+    }[];
+    set(name: string, value: string, options?: CookieOptions): void;
+    delete(name: string, options?: Pick<CookieOptions, "path" | "domain">): void;
+}
+/** Cookie attributes of `cookies.set()`. */
+export interface CookieOptions {
+    path?: string;
+    domain?: string;
+    maxAge?: number;
+    expires?: Date;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "lax" | "strict" | "none";
+}
+/** What guards, loaders, actions and endpoints receive. `locals` is shared along one request's chain. */
+/** `RequestEvent<"items/[id]">`: params of a file route id (`RouteParams`, generated). */
+export interface RequestEvent<P extends Record<string, string> | RouteId = Record<string, string>> {
+    readonly request: Request;
+    readonly url: URL;
+    readonly params: Readonly<P extends RouteId ? RouteParams[P] : P>;
+    readonly locals: Record<string, unknown>;
+    readonly signal: AbortSignal;
+    readonly cookies: Cookies;
+    /** The handler runs in development (`dev` option); undefined when unknown (treat as production). */
+    readonly dev?: boolean;
+    /** Set a response header (HTML, data and action responses alike). */
+    setHeader(name: string, value: string): void;
+    /** Set several response headers; `set-cookie` is rejected (use `cookies.set`). */
+    setHeaders(headers: Readonly<Record<string, string>>): void;
+    /** The matched route (`id`: file route id, e.g. `blog/[slug]`); `null` for unmatched URLs. */
+    readonly route: {
+        readonly id: string | null;
+    };
+    /** A client-navigation data request (`?_rivet=data`, answered with JSON), not a document request. */
+    readonly isDataRequest: boolean;
+    /** What the adapter knows about the connection (node: `clientAddress`). */
+    readonly platform: Platform;
+    /**
+     * Loaders: name what this loader's data depends on (strings; a `URL` counts as its `href`), so
+     * `invalidate(key)` in the browser reruns only the loaders that depend on `key`. Any time during
+     * the loader; repeats are ignored. Elsewhere (guards, actions, handlers) it does nothing.
+     */
+    depends(...keys: readonly (string | URL)[]): void;
+}
+/** Adapter-provided request facts (`event.platform`). */
+export interface Platform {
+    /** Client IP address (node adapter: the socket's, or `X-Forwarded-For`'s first with `trustProxy`). */
+    readonly clientAddress?: string;
+    readonly [key: string]: unknown;
+}
+type Result = unknown;
+type Handler = (event: RequestEvent) => Response | undefined | void | Promise<Response | undefined | void>;
+/**
+ * A route's or layout's server exports, normalized: in-file `serverLoad`… arrive here as `load`…
+ * (sibling `*.server.ts` modules may still use the old names). `onRequest` and `on<Method>` request
+ * handlers run outermost first before guards; a returned `Response` ends the request.
+ */
+export interface ServerModule {
+    onRequest?: Handler;
+    onGet?: Handler;
+    onPost?: Handler;
+    onPut?: Handler;
+    onPatch?: Handler;
+    onDelete?: Handler;
+    /** OPTIONS (CORS preflight): after `onRequest`, outer → inner, the route's own module included; void → 204 + `Allow`. */
+    onOptions?: Handler;
+    guard?(event: RequestEvent): Result | Promise<Result>;
+    load?(event: RequestEvent): Result | Promise<Result>;
+    entries?(): Iterable<Record<string, string>> | Promise<Iterable<Record<string, string>>>;
+    prerender?: boolean;
+    /** `false` (route module only): skip the cross-site check for this route's unsafe methods (webhooks). */
+    csrf?: boolean;
+    actions?: Record<string, (event: RequestEvent) => Result | Promise<Result>>;
+    headers?(event: RequestEvent): HeadersInit | undefined;
+    GET?(event: RequestEvent): Response | Promise<Response>;
+    POST?(event: RequestEvent): Response | Promise<Response>;
+    PUT?(event: RequestEvent): Response | Promise<Response>;
+    PATCH?(event: RequestEvent): Response | Promise<Response>;
+    DELETE?(event: RequestEvent): Response | Promise<Response>;
+}
+type Load<T> = () => Promise<T>;
+/** One generated route-table entry. */
+export interface AppRoute {
+    readonly id: string;
+    readonly pattern: string;
+    /** Server modules of the enclosing layouts, outermost first (undefined: layout has none). */
+    readonly layouts: readonly (Load<ServerModule> | undefined)[];
+    readonly server?: Load<ServerModule>;
+    /** False for endpoint-only routes (a `.server.ts` without a page). */
+    readonly page: boolean;
+    /** Layout ids (`/` + folder path: `/`, `/shop`), parallel to `layouts`: data requests may skip the loaders of kept ones. */
+    readonly keys?: readonly string[];
+}
+/** Everything a renderer needs for one page. `data` holds layout data then page data. */
+export interface RenderInput {
+    readonly request: Request;
+    readonly url: URL;
+    readonly route: AppRoute;
+    readonly params: Readonly<Record<string, string>>;
+    readonly data: readonly unknown[];
+    readonly status: number;
+    readonly headers: Headers;
+    readonly nonce: string | undefined;
+    readonly action: ActionResult | undefined;
+    readonly locals: Record<string, unknown>;
+    /** Merged head (layouts → page) from `head` exports. */
+    readonly head: Head | undefined;
+    /** Layouts (indices into `data`) whose loader read the request URL: their data follows every URL change. */
+    readonly byURL?: readonly number[];
+    /** Keys the loaders passed to `event.depends()` (index into `data`); absent when none called it. */
+    readonly deps?: LoaderDeps;
+}
+/** What the error renderer receives: request, matched route, status and a user-safe message. */
+export interface ErrorInput {
+    readonly request: Request;
+    readonly url: URL;
+    /** Matched route (undefined for unmatched URLs). */
+    readonly route: AppRoute | undefined;
+    readonly status: number;
+    /** User-safe message: the HttpError's for 4xx, generic for 5xx outside dev. */
+    readonly message: string;
+    readonly headers: Headers;
+    readonly nonce: string | undefined;
+    /** The request's `locals` as guards/loaders left them (empty when no guard ran, e.g. unmatched URLs). */
+    readonly locals: Record<string, unknown>;
+    /**
+     * Data of the outermost layouts the error page renders inside (route data order): those whose guards
+     * passed and whose loaders succeeded, up to the first that did not. Unmatched URLs: the root layout's.
+     */
+    readonly layouts?: readonly unknown[];
+}
+/** Options of the app handler: routes, renderers, head and dev flags. */
+export interface AppOptions {
+    readonly routes: readonly AppRoute[];
+    render(input: RenderInput): Response | Promise<Response>;
+    renderError?(input: ErrorInput): Response | Promise<Response>;
+    /** Merged head for a route from its universal modules' `head` exports. */
+    head?(route: AppRoute, data: readonly unknown[], match: {
+        params: Readonly<Record<string, string>>;
+        url: URL;
+    }): Head | undefined | Promise<Head | undefined>;
+    /** Show 5xx messages (never in production). */
+    readonly dev?: boolean;
+    /** Server failures; `digest` is also in the (otherwise generic) 5xx message the client sees. */
+    onError?(error: unknown, request: Request, info?: ErrorInfo): void;
+    /** Request body limit in bytes for unsafe methods (413 past it). Default 1 MiB, multipart 10 MiB. */
+    readonly maxBody?: BodyLimit;
+    /**
+     * URL of the resume manifest's `builtins` chunk (RegExp / URLSearchParams / binary / error decoders): data and action
+     * answers holding such values name it (`x`), the client imports it before decoding. Without it they fail to decode.
+     */
+    builtins?(): string | undefined;
+    /** Data requests: per layout of `route`, whether its loader may be skipped when the client keeps its data (default all). */
+    keepable?(route: AppRoute): readonly boolean[] | undefined | Promise<readonly boolean[] | undefined>;
+    /**
+     * Called once per HTML page GET / HEAD (no data request, no action) after the request handlers and before the guards
+     * and loaders: the moment a server can send `103 Early Hints` while it is still busy (`createApp({ earlyHints })`).
+     */
+    earlyHints?(route: AppRoute, request: Request): void;
+}
+/** Where a server failure happened: request handler (`onRequest`/`on<Method>`/endpoint, module load), guard, loader, action or page render. */
+export type ErrorPhase = "handler" | "guard" | "loader" | "action" | "render";
+/** `onError` details of a reported (5xx) failure. */
+export interface ErrorInfo {
+    readonly digest: string;
+    readonly phase?: ErrorPhase;
+    /** Matched route id. */
+    readonly route?: string;
+}
+/** @internal Short random id tying a hidden 5xx message to its server log entry. */
+export declare const _digest: () => string;
+/** The app's web-standard request handler. */
+export type AppHandler = (request: Request, context?: {
+    nonce?: string;
+    address?: string;
+    platform?: Platform;
+}) => Promise<Response>;
+/**
+ * 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 declare function encodeData(value: unknown, builtins?: string, origin?: string): string;
+/** Create the app's request handler. */
+export declare function createHandler(options: AppOptions): AppHandler;