@uniflowed/router 0.0.0-alpha.8 → 0.1.0

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);
@@ -26,6 +26,41 @@
 // 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
@@ -34,6 +69,9 @@
 // `after()` promises. A handler that streams its body has not sent a byte at
 // that point. See ubugeeei-prod/uf#389.
 
+import { asResponder, noteRoute } from "@uniflowed/server/host";
+
+import { matchRoute } from "./internal/routing.js";
 import { requireRequest } from "./internal/request.js";
 import type { RouteParams } from "./internal/runtime.js";
 
@@ -66,8 +104,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.
@@ -79,55 +136,70 @@ const METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
 export function createDispatcher(options: {|
   readonly handlers: $ReadOnlyArray<HandlerRecord>,
 |}): (request: Request) => Promise<Response | null> {
-  // Longest path first, so `/api/users/new` wins over `/api/users/[id]` and a
-  // catch-all is the last thing tried.
-  const table = [...options.handlers].sort((a, b) => specificity(b.path) - specificity(a.path));
+  const table = [...options.handlers];
 
   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);
-      if (params == null) {
-        continue;
-      }
-
-      const module = await record.load();
-      const method = request.method.toUpperCase();
-      const handler = pick(module, method);
-      if (handler == null) {
-        return methodNotAllowed(module);
-      }
+    const match = matchRoute(table, url.pathname);
+    if (match == null) return null;
+    const { route: record, params } = match;
+
+    // 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);
+    if (handler == null) {
+      return methodNotAllowed(module);
+    }
 
-      // 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.
-      const response = await 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 }),
+    );
+
+    // 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
+    // `GET`, so asking it whether a `HEAD` exists always said yes and the
+    // body went out anyway.
+    if (method === "HEAD" && typeof module.HEAD !== "function") {
+      return new Response(null, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
       });
-
-      // 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
-      // `GET`, so asking it whether a `HEAD` exists always said yes and the
-      // body went out anyway.
-      if (method === "HEAD" && typeof module.HEAD !== "function") {
-        return new Response(null, {
-          status: response.status,
-          statusText: response.statusText,
-          headers: response.headers,
-        });
-      }
-      return response;
     }
-    return null;
+    return response;
   };
 }
 
-/** 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;
@@ -145,7 +217,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");
@@ -154,64 +226,6 @@ 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(", ") },
   });
 }
-
-/**
- * Match one route path against a pathname, returning its parameters.
- *
- * `null` rather than an empty object when it does not match, so a route with
- * no parameters is still distinguishable from a miss.
- */
-function matchPath(routePath: string, pathname: string): RouteParams | null {
-  const wanted = segmentsOf(routePath);
-  const given = segmentsOf(pathname);
-  const params: { [string]: string | Array<string> } = {};
-
-  for (let index = 0; index < wanted.length; index += 1) {
-    const segment = wanted[index];
-    if (segment.startsWith(":") && segment.endsWith("*")) {
-      // A catch-all takes the rest, and matches zero segments as well as many.
-      params[segment.slice(1, -1)] = given.slice(index);
-      return params as $FlowFixMe;
-    }
-    if (index >= given.length) {
-      return null;
-    }
-    if (segment.startsWith(":")) {
-      params[segment.slice(1)] = given[index];
-      continue;
-    }
-    if (segment !== given[index]) {
-      return null;
-    }
-  }
-
-  return wanted.length === given.length ? (params as $FlowFixMe) : null;
-}
-
-function segmentsOf(value: string): Array<string> {
-  return value.split("/").filter((segment) => segment !== "");
-}
-
-/**
- * How specific a path is, so the table can be tried in the right order.
- *
- * A literal segment is worth more than a parameter and a parameter more than a
- * catch-all, and a longer path outranks a shorter one — which is what makes
- * `/api/users/new` win over `/api/users/[id]`.
- */
-function specificity(routePath: string): number {
-  let score = 0;
-  for (const segment of segmentsOf(routePath)) {
-    if (segment.startsWith(":") && segment.endsWith("*")) {
-      score += 1;
-    } else if (segment.startsWith(":")) {
-      score += 10;
-    } else {
-      score += 100;
-    }
-  }
-  return score;
-}

package/http-client.js

@@ -0,0 +1,104 @@
+// @flow
+import {
+  ACTION_CONTENT_TYPE,
+  ACTION_HEADER,
+  decodeActionResult,
+  encodeActionArguments,
+  isActionId,
+  type ActionValue,
+} from "./internal/action-wire.js";
+
+export type RouteClientOptions = {|
+  readonly origin: string,
+  readonly getToken?: () => Promise<string>,
+  readonly fetch?: (url: string, options: RequestOptions) => Promise<Response>,
+  readonly allowInsecureDevelopment?: boolean,
+|};
+
+export type RouteRequest = {|
+  readonly method?: string,
+  readonly headers?: { readonly [string]: string },
+  readonly body?: string,
+  readonly signal?: AbortSignal,
+|};
+
+type RequestOptions = {|
+  ...RouteRequest,
+  readonly credentials: "omit",
+  readonly redirect: "error",
+|};
+
+/** Fetch transport shared by generated typed route clients and native actions. */
+export function createRouteClient(
+  options: RouteClientOptions,
+): (path: string, request?: RouteRequest) => Promise<Response> {
+  const origin = new URL(options.origin);
+  if (
+    origin.username ||
+    origin.password ||
+    origin.pathname !== "/" ||
+    origin.search ||
+    origin.hash
+  ) {
+    throw new TypeError("createRouteClient origin must contain only a scheme and host");
+  }
+  const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(origin.hostname);
+  if (
+    origin.protocol !== "https:" &&
+    !(origin.protocol === "http:" && (loopback || options.allowInsecureDevelopment === true))
+  ) {
+    throw new TypeError(
+      "createRouteClient requires HTTPS outside explicit development connections",
+    );
+  }
+  const send = options.fetch ?? globalThis.fetch;
+  return async (path, request = {}) => {
+    if (!path.startsWith("/") || path.startsWith("//") || path.includes("\\")) {
+      throw new TypeError("route client needs a same-origin absolute path");
+    }
+    const url = new URL(path, origin);
+    if (url.origin !== origin.origin) throw new TypeError("route client cannot change origin");
+    const headers: { [string]: string } = {};
+    for (const [name, value] of Object.entries(request.headers ?? {})) {
+      const lower = name.toLowerCase();
+      if (
+        ["cookie", "authorization", "origin", "host"].includes(lower) ||
+        lower.startsWith("sec-fetch-")
+      ) {
+        throw new TypeError(`route client does not accept the ${name} header`);
+      }
+      if (typeof value !== "string") throw new TypeError(`route header ${name} must be a string`);
+      headers[name] = value;
+    }
+    if (options.getToken != null) {
+      const token = await options.getToken();
+      if (!/^[A-Za-z0-9\-._~+/]+=*$/.test(token) || token.length > 8192) {
+        throw new TypeError("route client received an invalid bearer credential");
+      }
+      headers.authorization = `Bearer ${token}`;
+    }
+    return send(url.href, { ...request, headers, credentials: "omit", redirect: "error" });
+  };
+}
+
+/** Explicit action channel for clients holding application-issued bearer tokens. */
+export function createNativeActionClient(options: {|
+  ...RouteClientOptions,
+  readonly getToken: () => Promise<string>,
+|}): (id: string, args: $ReadOnlyArray<mixed>, path?: string) => Promise<ActionValue | void> {
+  const send = createRouteClient(options);
+  return async (id, args, path = "/") => {
+    if (!isActionId(id)) throw new TypeError("native action needs an ID from the current build");
+    const response = await send(path, {
+      method: "POST",
+      headers: {
+        [ACTION_HEADER]: id,
+        "uf-native-action": "bearer-v1",
+        "content-type": ACTION_CONTENT_TYPE,
+      },
+      body: encodeActionArguments(args),
+    });
+    if (!response.ok) throw new Error(`Native action failed with status ${response.status}`);
+    return decodeActionResult(await response.text());
+  };
+}

package/index.js

@@ -2,14 +2,32 @@
 //
 // `@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.
 //
-// `_uf.not-found.js` and `_uf.error.js` are the two boundaries: the page for a
+// `$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.
+// 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";
 
@@ -19,6 +37,8 @@ export type {
   AppProps,
   ErrorBoundary,
   ErrorModule,
+  Interception,
+  JsonLd,
   LayoutModule,
   LinkPrefetch,
   LoaderArgs,
@@ -28,6 +48,7 @@ export type {
   NotFoundBoundary,
   PageModule,
   ResolvedRoute,
+  Robots,
   RouteError,
   RouteInfo,
   RouteMatch,
@@ -36,7 +57,12 @@ export type {
   RouteRecord,
   RouteTable,
   Router,
+  ResolvedSlot,
   SearchParams,
+  SlotRecord,
+  SlotRouteRecord,
+  TemplateModule,
+  TwitterCard,
 } from "./internal/runtime.js";
 
 export {
@@ -47,6 +73,8 @@ export {
   RouteView,
   RouterProvider,
   UnauthorizedError,
+  basePath,
+  buildRoute,
   forbidden,
   hasClientPage,
   matchRoute,
@@ -61,9 +89,11 @@ export {
   splitUrl,
   unauthorized,
   useIsServer,
+  useLinkStatus,
   useLoaderData,
   useRoute,
   useRouter,
+  useSeo,
 } from "./internal/runtime.js";
 
 /** Props a page receives. */
@@ -76,13 +106,26 @@ export type PageProps<
   readonly data: TData,
 |};
 
-/** Props an `_uf.error.js` component receives. */
+/** Props an `$error.js` component receives. */
 export type ErrorProps = {|
   readonly error: RouteError,
   readonly reset: () => void,
 |};
 
-/** Props a layout receives. */
+/**
+ * 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> } = {},
 > = {|

package/instrumentation.js

@@ -0,0 +1,92 @@
+// @flow
+
+export type NavigationTiming = {|
+  readonly kind: "document" | "router",
+  readonly pathname: string,
+  readonly duration: number,
+  readonly status: "complete" | "error",
+|};
+
+export type ClientInstrumentation = {|
+  readonly register?: () => void | Promise<void>,
+  readonly onError?: (
+    error: mixed,
+    context: {| readonly source: "error" | "unhandledrejection" | "navigation" | "startup" |},
+  ) => void | Promise<void>,
+  readonly onNavigation?: (timing: NavigationTiming) => void | Promise<void>,
+|};
+
+const observers: Set<ClientInstrumentation> = new Set();
+
+function notify(body: () => mixed): void {
+  Promise.resolve()
+    .then(body)
+    .catch((error) => console.error("uf client instrumentation failed", error));
+}
+
+/** Installed by the client entry before hydration, with disposal during HMR. */
+export async function installClientInstrumentation(
+  hooks: ClientInstrumentation,
+): Promise<() => void> {
+  const error = (event: ErrorEvent) =>
+    notify(() => hooks.onError?.(event.error ?? event.message, { source: "error" }));
+  const rejection = (event: PromiseRejectionEvent) =>
+    notify(() => hooks.onError?.(event.reason, { source: "unhandledrejection" }));
+  window.addEventListener("error", error);
+  window.addEventListener("unhandledrejection", rejection);
+  observers.add(hooks);
+  let performanceObserver = null;
+  if (
+    typeof PerformanceObserver === "function" &&
+    PerformanceObserver.supportedEntryTypes.includes("navigation")
+  ) {
+    performanceObserver = new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        const timing: NavigationTiming = {
+          kind: "document",
+          pathname: new URL(entry.name).pathname,
+          duration: entry.duration,
+          status: "complete",
+        };
+        notify(() => hooks.onNavigation?.(timing));
+      }
+    });
+    performanceObserver.observe({ type: "navigation", buffered: true });
+  }
+  const dispose = () => {
+    window.removeEventListener("error", error);
+    window.removeEventListener("unhandledrejection", rejection);
+    observers.delete(hooks);
+    performanceObserver?.disconnect();
+  };
+  try {
+    await hooks.register?.();
+  } catch (failure) {
+    notify(() => hooks.onError?.(failure, { source: "startup" }));
+    dispose();
+  }
+  return dispose;
+}
+
+/** The router's asynchronous navigation work; a hard navigation has browser timing entries. */
+export async function observeNavigation<T>(to: string, body: () => Promise<T>): Promise<T> {
+  if (observers.size === 0) return body();
+  const started = performance.now();
+  const pathname = new URL(to, window.location.href).pathname;
+  let status: NavigationTiming["status"] = "complete";
+  try {
+    return await body();
+  } catch (error) {
+    status = "error";
+    for (const hooks of observers) notify(() => hooks.onError?.(error, { source: "navigation" }));
+    throw error;
+  } finally {
+    const timing: NavigationTiming = {
+      kind: "router",
+      pathname,
+      duration: performance.now() - started,
+      status,
+    };
+    for (const hooks of observers) notify(() => hooks.onNavigation?.(timing));
+  }
+}