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

package/server/handler.d.ts

@@ -0,0 +1,240 @@
+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 by tag (`server/module.ts`): each key is the kind of
+ * the wrapper that made the export (`export const loader = load(…)` arrives as `load`). `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;
+}
+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;
+    /** Set when a `data` slot is a deferred loader's `Deferred` handle (`load(fn, { defer: true })`): the page streams. */
+    readonly deferred?: true;
+    /**
+     * A deferred loader's `redirect()` (same origin, or `{ external: true }`): its first target, read when the document
+     * ends — the status is long sent, so the page navigates there in the browser (`location.replace`).
+     */
+    readonly moved?: () => string | undefined;
+    /** @internal Route rule `shell` (`shell-cache.ts`): this render fills or replays a stored shell (always streams). */
+    readonly shell?: ShellPhase;
+    /** 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;
+}
+/**
+ * @internal Route rule `shell` (`server/shell-cache.ts`): the route rules wrapper sets it on a document GET's Request
+ * (`SHELL`). After the guards and `headers()` the handler asks it how to load: a hit's stored shell data (the composed
+ * response already went out with the stored shell), a fill's read tracking, or nothing (render as usual).
+ */
+export interface ShellRequest {
+    begin(route: AppRoute, event: RequestEvent, headers: Headers): ShellPhase | undefined;
+}
+/** @internal One shell render (fill or hit replay). */
+export interface ShellPhase {
+    /** Hit: the fill's non-deferred loader results (those loaders are skipped) and URL / depends facts. */
+    readonly data?: readonly unknown[];
+    readonly byURL?: readonly number[];
+    readonly deps?: LoaderDeps;
+    /** Fill: a non-deferred loader's event view that records its request reads. */
+    event?(view: RequestEvent, index: number): RequestEvent;
+    /** Fill: the non-deferred loaders' results (deferred slots undefined), stored with the shell. */
+    loaded?(data: readonly unknown[], byURL: readonly number[], deps: LoaderDeps | undefined): void;
+    /** Fill: a deferred slot's handle (delivers only after the shell is out: in-order use is detected). */
+    handle?(promise: Promise<unknown>, dev: boolean): object;
+    /** Fill: the page's URL for the render (named query reads outside the key recorded). */
+    readonly url?: URL;
+    /** Set by `app.ts`: this render does not stream (dev `devResume` check mode), deferred data waits in place. */
+    plain?: boolean;
+}
+/** @internal Request property carrying a `ShellRequest` (`Symbol.for("rivet.shell")`). */
+export declare const SHELL: unique symbol;
+/** 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 (only the handler's seed, `context.locals`, 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;
+/** What the caller of the app handler passes with a request (adapters: `nonce`, `address`, `platform`). */
+export interface AppHandlerContext {
+    /** CSP nonce of this response (node adapter: fresh per request). */
+    nonce?: string;
+    /** Client address (`event.platform.clientAddress`). */
+    address?: string;
+    /** Adapter-provided request facts (`event.platform`). */
+    platform?: Platform;
+    /**
+     * Seeds `event.locals`: each request starts with a shallow copy, before any request handler, guard, loader or action
+     * runs (the caller's object is never changed). Only from the code that calls the handler (no adapter fills it from the
+     * request), e.g. a view model another server computed. Never sent to the browser unless a loader returns it. Requests
+     * that pass it bypass the route rules' page cache (their page depends on more than the URL). Client-navigation data
+     * requests (`?_rivet=data`) need the same seed.
+     */
+    locals?: Readonly<Record<string, unknown>>;
+}
+/** The app's web-standard request handler. */
+export type AppHandler = (request: Request, context?: AppHandlerContext) => 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;