@uniflowed/router 0.0.0-alpha.4 → 0.0.0-alpha.40

package/handler.js

@@ -2,13 +2,13 @@
 //
 // Route handlers: a path that answers a request instead of rendering a page.
 //
-// `app/api/users/_uf.route.js` exporting `GET` and `POST` serves
+// `app/api/users/$route.js` exporting `GET` and `POST` serves
 // `/api/users`. A handler takes a `Request` and returns a `Response` — the
 // platform's own types, not a framework's wrapper — because that is what runs
 // unchanged on Node.js, Bun, Deno and a Cloudflare Worker, and uf's whole
 // position is that the host is a capability rather than a target.
 //
-//   // app/api/users/[id]/_uf.route.js
+//   // app/api/users/[id]/$route.js
 //   // @flow
 //   export async function GET(request: Request, context: HandlerContext) {
 //     const user = await find(context.params.id);
@@ -25,8 +25,53 @@
 // It does answer `405` itself when the path matches and the method does not,
 // with the `Allow` header the specification requires — that is not the
 // handler's business, and every handler would otherwise write it.
+//
+// # `QUERY`, and what refuses it
+//
+// `QUERY` is a `GET` with a body: safe, idempotent, cacheable, and the method
+// that a search with more parameters than a URL can hold has been faking with a
+// `POST` for twenty years. A handler exports it like any other verb, and this
+// dispatcher matches it like any other verb, because there is nothing special
+// about it *here*. What is special about it is the path between a client and
+// this function, and that is the part worth writing down rather than leaving to
+// be discovered in production.
+//
+// Three things refuse it, and they refuse it differently:
+//
+//   * **A client that cannot send it.** The Fetch standard forbids `CONNECT`,
+//     `TRACE` and `TRACK` and allows any other token, so every browser and
+//     every runtime uf targets can send a `QUERY` today. `XMLHttpRequest` and
+//     `EventSource` cannot, and neither can a `<form>`.
+//   * **An intermediary that will not forward it.** This is the real one. A
+//     proxy, a CDN or a WAF that has a list of methods answers `405` or `501`
+//     itself, and the request never arrives — so the failure looks exactly like
+//     a route that does not exist, from a server that never saw it.
+//     `@uniflowed/fetch` names that case in the error rather than passing the
+//     status through, which is the whole of what "stated rather than
+//     discovered" can mean from the other end of a wire.
+//   * **A cache that does not know it is safe.** `QUERY` is cacheable in
+//     principle and the key includes the body, which almost nothing implements.
+//     uf's own route cache is `GET`-only and stays that way; anything in front
+//     of the application should be told not to store a `QUERY` at all.
+//
+// What uf deliberately does not do about any of it is accept a method-override
+// header. `X-HTTP-Method-Override: QUERY` on a `POST` is the usual workaround
+// and it is the shape of CVE-2025-29927: an inbound header steering dispatch,
+// which `docs/security.md` forbids in the row about that CVE and in rule 3. A
+// route that must work through hostile infrastructure exports `POST` as well
+// and says so in its own file, where a reader can see it.
+//
+// It also does not establish the request a handler is inside. The host does,
+// around the whole of it, so a handler and the guard above it share one
+// context; see the same section in `./middleware.js`. This module used to
+// build its own and drain it the moment the handler returned, which the
+// comment there called "the response is in hand" — true, and not what
+// `after()` promises. A handler that streams its body has not sent a byte at
+// that point. See ubugeeei-prod/uf#389.
 
-import { contextFor, drainDeferred, runWithContext } from "@uniflowed/server/host";
+import { asResponder, noteRoute } from "@uniflowed/server/host";
+
+import { requireRequest } from "./internal/request.js";
 import type { RouteParams } from "./internal/runtime.js";
 
 /** What a handler is given besides the request. */
@@ -58,8 +103,27 @@ export type HandlerRecord = {|
  * — and a module that exports a helper would then answer requests with it.
  * `HEAD` falls back to `GET` with the body dropped, which is what a client
  * asking for headers expects and what nobody remembers to write.
+ *
+ * It was closed in name only until `QUERY` was added. `pick` looked the method
+ * up on the module and this list decided nothing but the order of the `Allow`
+ * header, so a module exporting `PURGE` answered `PURGE` — the exact behaviour
+ * the paragraph above says is refused. Adding a verb was the moment to make the
+ * sentence true, because the alternative was adding one to a list nothing read.
+ *
+ * `QUERY` is here and `CONNECT` and `TRACE` are not, and the difference is not
+ * taste: the `fetch` specification forbids the last two outright, so a handler
+ * exporting either could never be reached by a browser.
  */
-const METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+export const HANDLER_METHODS: $ReadOnlyArray<string> = Object.freeze([
+  "GET",
+  "HEAD",
+  "QUERY",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "OPTIONS",
+]);
 
 /**
  * Match a request against the handler table and run it.
@@ -76,6 +140,9 @@ export function createDispatcher(options: {|
   const table = [...options.handlers].sort((a, b) => specificity(b.path) - specificity(a.path));
 
   return async function dispatch(request: Request): Promise<Response | null> {
+    // The host's half of the contract, checked rather than assumed; see
+    // `./internal/request.js`.
+    requireRequest("dispatch");
     const url = new URL(request.url);
     for (const record of table) {
       const params = matchPath(record.path, url.pathname);
@@ -83,6 +150,12 @@ export function createDispatcher(options: {|
         continue;
       }
 
+      // Before the module is loaded and before the method is checked, because
+      // this is the answer to "what was this request" and a `405` is as much
+      // this route's answer as a `200` is. A log of `/api/users/:id 405` is
+      // actionable; the same line with the path in it is a million lines.
+      noteRoute(record.path);
+
       const module = await record.load();
       const method = request.method.toUpperCase();
       const handler = pick(module, method);
@@ -90,17 +163,18 @@ export function createDispatcher(options: {|
         return methodNotAllowed(module);
       }
 
-      // Inside the request, so a handler that calls `headers()`, `cookies()`
-      // or `after()` has something to answer about. `drainDeferred` runs after
-      // the response is in hand, which is what `after()` means.
-      const context = contextFor(request);
-      const response = await runWithContext(context, () =>
-        handler(request, {
-          params,
-          searchParams: url.searchParams,
-        }),
+      // In the host's request, so a handler that calls `headers()`,
+      // `cookies()` or `after()` answers about the same one its guard did, and
+      // what it defers is drained once, by the host, after the bytes are out.
+      //
+      // And inside `asResponder`, which is the other half: a route handler is
+      // one of the two things that owns a response, so it is one of the two
+      // places `draftMode().enable()` is allowed — and the `Set-Cookie` it
+      // decided on is written onto the response below rather than left on an
+      // object the host is about to discard. See ubugeeei-prod/uf#282.
+      const response = await asResponder("a route handler", async () =>
+        handler(request, { params, searchParams: url.searchParams }),
       );
-      await drainDeferred(context);
 
       // A `HEAD` answered by `GET` must not carry the body. The test is
       // against the module's own `HEAD`, not `pick`'s — `pick` falls back to
@@ -119,8 +193,18 @@ export function createDispatcher(options: {|
   };
 }
 
-/** The function for a method, falling back to `GET` for `HEAD`. */
+/**
+ * The function for a method, falling back to `GET` for `HEAD`.
+ *
+ * The method is checked against `METHODS` first, which is what makes that list
+ * closed rather than decorative: without it a request could name any export,
+ * and a module's `PURGE` — or its `DEFAULT`, or a name a bundler added — would
+ * answer one.
+ */
 function pick(module: HandlerModule, method: string): Handler | null {
+  if (!HANDLER_METHODS.includes(method)) {
+    return null;
+  }
   const own = module[method];
   if (typeof own === "function") {
     return own as $FlowFixMe;
@@ -138,7 +222,7 @@ function pick(module: HandlerModule, method: string): Handler | null {
  * do that here" from "there is nothing here".
  */
 function methodNotAllowed(module: HandlerModule): Response {
-  const own = new Set(METHODS.filter((method) => typeof module[method] === "function"));
+  const own = new Set(HANDLER_METHODS.filter((method) => typeof module[method] === "function"));
   // A module exporting `GET` also answers `HEAD`, so `Allow` has to say so.
   if (own.has("GET")) {
     own.add("HEAD");
@@ -147,7 +231,7 @@ function methodNotAllowed(module: HandlerModule): Response {
   // header reads in the conventional order however the module was written.
   return new Response(null, {
     status: 405,
-    headers: { allow: METHODS.filter((method) => own.has(method)).join(", ") },
+    headers: { allow: HANDLER_METHODS.filter((method) => own.has(method)).join(", ") },
   });
 }
 

package/index.js

@@ -2,21 +2,54 @@
 //
 // `@uniflowed/router`: the file-system router.
 //
-// Pages live in `app/` as `_uf.page.js` (or `.mdx`), layouts as
-// `_uf.layout.js`, and `app.js` exports `routerView("./app")`. The route table
+// Pages live in `app/` as `$page.js` (or `.mdx`), layouts as
+// `$layout.js`, and `app.js` exports `routerView("./app")`. The route table
 // is generated from the directory at build time; this module is the runtime
 // that matches, loads, navigates and renders it.
+//
+// `$not-found.js` and `$error.js` are the two boundaries: the page for a
+// path that matched nothing, and what renders in place of a subtree that threw.
+// Both are segment files, resolved by the nearest one above the path — and the
+// router root always has one of each, so a project that declares neither still
+// answers a 404 inside its own layouts rather than beside them.
+//
+// `$template.js` is a layout that remounts on every navigation, for the
+// cases where a layout's persistence is the wrong default.
+//
+// A directory named `@team` is a parallel-route slot: it contributes no URL
+// segment, and the layout of the segment that holds it receives the slot as a
+// `team` prop beside `children`. The slot's pages are matched against the same
+// URL the page is, so one URL renders two subtrees at once, and
+// `$default.js` is what a slot renders when the URL matched none of its
+// routes. See ubugeeei-prod/uf#267.
+//
+// A directory named `(.)photo` inside a slot is an intercepting route: a client
+// navigation that starts on a page the slot is on, and reaches the URL the
+// directory stands in for, renders it in the slot and leaves the page
+// underneath where it was. A document request for that URL — a reload, a
+// shared link, a prerender — renders the ordinary page.
+
+import * as React from "react";
+
+import type { RouteError } from "./internal/runtime.js";
 
 export type {
   AppProps,
+  ErrorBoundary,
+  ErrorModule,
+  Interception,
+  JsonLd,
   LayoutModule,
   LinkPrefetch,
   LoaderArgs,
   Metadata,
   MetadataArgs,
   NavigateOptions,
+  NotFoundBoundary,
   PageModule,
   ResolvedRoute,
+  Robots,
+  RouteError,
   RouteInfo,
   RouteMatch,
   RouteParamSpec,
@@ -24,27 +57,42 @@ export type {
   RouteRecord,
   RouteTable,
   Router,
+  ResolvedSlot,
   SearchParams,
+  SlotRecord,
+  SlotRouteRecord,
+  TemplateModule,
+  TwitterCard,
 } from "./internal/runtime.js";
 
 export {
+  ForbiddenError,
   Link,
   NotFoundError,
   RedirectError,
   RouteView,
   RouterProvider,
+  UnauthorizedError,
+  basePath,
+  buildRoute,
+  forbidden,
+  hasClientPage,
   matchRoute,
   notFound,
   parseSearch,
   permanentRedirect,
   redirect,
+  resolveFailure,
   resolveMatch,
+  routeErrorStatus,
   routerView,
   splitUrl,
+  unauthorized,
   useIsServer,
   useLoaderData,
   useRoute,
   useRouter,
+  useSeo,
 } from "./internal/runtime.js";
 
 /** Props a page receives. */
@@ -57,10 +105,29 @@ export type PageProps<
   readonly data: TData,
 |};
 
-/** Props a layout receives. */
+/** Props an `$error.js` component receives. */
+export type ErrorProps = {|
+  readonly error: RouteError,
+  readonly reset: () => void,
+|};
+
+/**
+ * Props a layout receives.
+ *
+ * A layout on a segment that declares parallel-route slots receives one more
+ * prop per slot, named after the directory without its `@`, and this exact
+ * type does not describe those — the names are the project's. Declare them: a
+ * layout beside `@team` and `@analytics` is
+ *
+ *     component Dashboard(children: React.Node, team: React.Node, analytics: React.Node)
+ *
+ * and the router passes `null` for a slot the URL addressed by neither a route
+ * of its own nor a `$default.js`, so `{team ?? <Empty />}` is a thing that
+ * can be written and relied on.
+ */
 export type LayoutProps<
   TParams extends { readonly [string]: string | $ReadOnlyArray<string> } = {},
 > = {|
   readonly params: TParams,
-  readonly children: React$Node,
+  readonly children: React.Node,
 |};