@uniflowed/router 0.0.0-alpha.12 → 0.0.0-alpha.14

package/action.js

@@ -0,0 +1,198 @@
+// @flow
+//
+// `@uniflowed/router/action`: a server action, as the browser holds it.
+//
+// A `"use client"` module writes an ordinary import and an ordinary call:
+//
+//   // app/counter/_components/Counter.js
+//   "use client";
+//   import { recordClick } from "../_actions/clicks.js";
+//   …
+//   <button onClick={() => { void recordClick(count); }}>
+//
+// On the server that import is the function. In the browser it is a reference
+// built here: `@uniflowed/vite` replaces the `"use server"` module, in the
+// client graph only, with one `createServerReference` per callable export, so
+// what crosses the import is an id and a `fetch` — and the module's body, its
+// imports and every secret they reached stay where they were written.
+//
+// # Why this module is where it is
+//
+// It is the browser's half, so it may not live in `@uniflowed/server`: that
+// package is in `SERVER_ONLY_PACKAGES` and importing it from a client
+// component is the error the RSC graph exists to produce. It holds no
+// platform API beyond `fetch` and `location`, and it imports one internal
+// module, which is the grammar the server applies to the same bytes.
+//
+// # The call
+//
+// `POST` to the page's own URL, `uf-action: <id>`, `application/json`, and
+// `{"args":[…]}`. The URL is the page rather than a path uf reserves so that
+// the middleware guarding that path runs above the call exactly as it does
+// above the page — and it is not a substitute for the action authorizing
+// itself; `internal/action-endpoint.js` says why in the paragraph that matters.
+//
+// # What Flow checks, and where
+//
+// Flow reads `app/_actions/clicks.js`, not the reference the bundler
+// substitutes for it, so `recordClick("nine")` against
+// `recordClick(count: number)` is a `uf check` error rather than a `400`. That
+// is the half that needs nothing from this module.
+//
+// What a declaration alone does not say is whether those arguments and that
+// result can cross a wire at all, and `ActionArguments` and `ActionResult` are
+// that half: `uf prepare` writes one instantiation of each into
+// `server-actions.js`, over every action in the project at once, so an action
+// taking a callback or returning a `Map` is a `uf check` error naming the
+// offending type. Without them the same mistake is a request that arrives with
+// `{}` where an object was passed — the kind of bug found in production by a
+// column that stopped being written.
+
+import {
+  ACTION_CONTENT_TYPE,
+  ACTION_HEADER,
+  type ActionValue,
+  decodeActionResult,
+  encodeActionArguments,
+} from "./internal/action-wire.js";
+
+export type { ActionValue } from "./internal/action-wire.js";
+export {
+  ACTION_CONTENT_TYPE,
+  ACTION_HEADER,
+  ActionValueError,
+  MAX_ACTION_ARGUMENTS,
+  MAX_ACTION_BODY_BYTES,
+  MAX_ACTION_DEPTH,
+  MAX_ACTION_VALUES,
+} from "./internal/action-wire.js";
+
+/**
+ * A function that can be a server action.
+ *
+ * Both halves of the signature are the wire grammar: an action is called with
+ * values that can cross and answers with one that can. `void` is a result and
+ * not an argument, because JSON has no `undefined` and an action declared to
+ * take one would be taking something the caller cannot send.
+ */
+export type ServerActionFunction = (...args: Array<ActionValue>) => Promise<ActionValue | void>;
+
+/**
+ * An action's arguments, held against what a wire can carry.
+ *
+ * A bound on a tuple rather than a bound on the function, and the difference
+ * is the whole reason this is two types instead of one. A function type puts
+ * its parameters in a contravariant position: `F extends (…args:
+ * Array<ActionValue>) => …` asks whether `F` accepts *every* `ActionValue`,
+ * which `createUser(name: string)` does not and should not. `Parameters<F>` is
+ * the same list read covariantly, where the question is the one worth asking —
+ * is each argument something that can cross?
+ *
+ * `uf prepare` writes one instantiation over the whole project:
+ *
+ *   export type ServerActionArgsFitTheWire =
+ *     ActionArguments<ServerActionArgs<ServerActionName>>;
+ *
+ * `ServerActionName` is every action's name, so `ServerActionArgs` of it is
+ * every action's argument list, and one line checks all of them.
+ */
+export type ActionArguments<TArgs extends $ReadOnlyArray<ActionValue>> = TArgs;
+
+/**
+ * An action's result, held against the same grammar.
+ *
+ * A promise, because a server action is always async — the RSC graph rejects
+ * one that is not — and `void` is allowed because an action that returns
+ * nothing is ordinary. `Promise` is covariant in Flow, so the bound reaches
+ * the resolved type without any of the contortion the arguments needed.
+ */
+export type ActionResult<TResult extends Promise<ActionValue | void>> = TResult;
+
+/**
+ * A server action that did not answer.
+ *
+ * Carries the status and the action's build-time name and nothing else,
+ * because nothing else came back: the endpoint answers every refusal with a
+ * fixed body, so there is no message from the server to relay. What went wrong
+ * is in the server's log, which is where an application's internals belong.
+ */
+export class ServerActionError extends Error {
+  /** The HTTP status the endpoint answered with. */
+  status: number;
+  /** `module#export` of the action that was called. */
+  action: string;
+
+  constructor(action: string, status: number) {
+    super(
+      `@uniflowed/router: the server action \`${action}\` answered ${String(status)}. ` +
+        "The endpoint reports every failure the same way; the reason is in the server's log.",
+    );
+    this.name = "ServerActionError";
+    this.status = status;
+    this.action = action;
+  }
+}
+
+/**
+ * The reference the client bundle holds in place of one server action.
+ *
+ * Generated, never written by hand: `@uniflowed/vite` emits one call per
+ * callable export of a `"use server"` module, with the id
+ * `crates/uf_rsc/src/action.rs` derived for it and the `module#export` name
+ * that only ever appears in an error.
+ *
+ * The returned function is `async` and refuses before it sends: an argument
+ * outside the wire grammar throws an `ActionValueError` naming the argument's
+ * position, at the call site, rather than becoming a `400` with nothing in it.
+ */
+export function createServerReference(id: string, name: string): ServerActionFunction {
+  return async function callServerAction(...args: Array<ActionValue>): Promise<ActionValue | void> {
+    const body = encodeActionArguments(args);
+    // Built rather than written as a literal, because the header's name is a
+    // constant and a computed key in an object literal is a shape Flow
+    // declines to track.
+    const headers: { [string]: string } = { "content-type": ACTION_CONTENT_TYPE };
+    headers[ACTION_HEADER] = id;
+    const response = await fetch(currentUrl(), {
+      method: "POST",
+      // Stated rather than left to the default, because the default is what a
+      // reader has to look up and because this one is load-bearing: the
+      // endpoint's `Origin` check is only meaningful for a request that
+      // carries the visitor's cookies in the first place.
+      credentials: "same-origin",
+      // Never a cached answer, and never one written to a cache: an action is
+      // a side effect, and `POST` responses are outside HTTP caching by
+      // default only until something decides otherwise.
+      cache: "no-store",
+      headers,
+      body,
+    });
+    if (!response.ok) {
+      throw new ServerActionError(name, response.status);
+    }
+    return decodeActionResult(await response.text());
+  };
+}
+
+/**
+ * The URL an action call is sent to: the page the browser is on.
+ *
+ * Path and query, not the whole URL, so the request is same-origin by
+ * construction rather than by a comparison somebody could get wrong. The hash
+ * is left off because it never reaches a server.
+ *
+ * A reference only exists in the client bundle — the server imports the real
+ * module — so there is no `location` here only if something has imported the
+ * browser's half into a server, and saying so is better than posting to a
+ * relative path that means nothing there.
+ */
+function currentUrl(): string {
+  const location = globalThis.location;
+  if (location == null) {
+    throw new Error(
+      "@uniflowed/router: a server action reference was called where there is no `location`. " +
+        "A reference is the browser's half of an action; the server imports the module itself.",
+    );
+  }
+  return `${location.pathname}${location.search}`;
+}

package/client.js

@@ -7,6 +7,17 @@
 // *before* `hydrateRoot`, so the first client render is synchronous and
 // matches the server's markup exactly.
 //
+// # A hydration that fails says what differed
+//
+// React reports a mismatch with one sentence and a list of the six things that
+// usually cause it, and leaves the reader to find which node of the two
+// thousand on the page was the one. This module is the only place that can do
+// better, because it is the only place that runs between the parser finishing
+// and React starting: `internal/hydration.js` takes a copy of the server's
+// markup here, and compares it against the repaired tree when React reports.
+// Development only, and dynamically imported so a production bundle has no path
+// to it. See ubugeeei-prod/uf#508.
+//
 // # A route can decline to be hydrated
 //
 // uf's server-component analysis decides which routes have a `"use client"`
@@ -65,7 +76,30 @@ export async function hydrate(options: {|
 
   const { App } = options;
   const container = document.getElementById(ROOT_ID) ?? document;
+
+  // The server's markup, and the reporter that will read it, in development
+  // only. Both have to be in place *before* `hydrateRoot`: React repairs a
+  // mismatched subtree by rendering over it, so the bytes the server sent exist
+  // for exactly the moment between the parser finishing and this line.
+  //
+  // `import.meta.hot` is the gate because it is the one signal that is right in
+  // all three places this module is evaluated. Vite defines it while serving
+  // and replaces it with `undefined` in a build, so the branch is statically
+  // dead there; Node leaves it undefined, so `tests/library/rsc-split.test.js`
+  // imports this file without a bundler and gets the production path. The
+  // import is dynamic so that the overlay is not merely shaken out of a
+  // production bundle but never reachable from one.
+  let recovery = null;
+  if (import.meta.hot != null) {
+    const { captureServerMarkup, hydrationErrorHandler } = await import("./internal/hydration.js");
+    recovery = hydrationErrorHandler(container, captureServerMarkup(container), document);
+  }
+
   startTransition(() => {
-    hydrateRoot(container, <App url={url} initial={resolved} />);
+    hydrateRoot(
+      container,
+      <App url={url} initial={resolved} />,
+      recovery == null ? undefined : { onRecoverableError: recovery },
+    );
   });
 }

package/handler.js

@@ -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,8 @@
 // `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 { requireRequest } from "./internal/request.js";
 import type { RouteParams } from "./internal/runtime.js";
 
@@ -66,8 +103,18 @@ 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"];
+const METHODS = ["GET", "HEAD", "QUERY", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
 
 /**
  * Match a request against the handler table and run it.
@@ -94,6 +141,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);
@@ -104,10 +157,15 @@ export function createDispatcher(options: {|
       // 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,
-      });
+      //
+      // 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
@@ -126,8 +184,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 (!METHODS.includes(method)) {
+    return null;
+  }
   const own = module[method];
   if (typeof own === "function") {
     return own as $FlowFixMe;

package/index.js

@@ -9,7 +9,12 @@
 //
 // `_uf.not-found.js` and `_uf.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.
+//
+// `_uf.template.js` is a layout that remounts on every navigation, for the
+// cases where a layout's persistence is the wrong default.
 
 import * as React from "react";
 
@@ -19,6 +24,7 @@ export type {
   AppProps,
   ErrorBoundary,
   ErrorModule,
+  JsonLd,
   LayoutModule,
   LinkPrefetch,
   LoaderArgs,
@@ -28,6 +34,7 @@ export type {
   NotFoundBoundary,
   PageModule,
   ResolvedRoute,
+  Robots,
   RouteError,
   RouteInfo,
   RouteMatch,
@@ -37,6 +44,7 @@ export type {
   RouteTable,
   Router,
   SearchParams,
+  TemplateModule,
   TwitterCard,
 } from "./internal/runtime.js";
 
@@ -65,6 +73,7 @@ export {
   useLoaderData,
   useRoute,
   useRouter,
+  useSeo,
 } from "./internal/runtime.js";
 
 /** Props a page receives. */