@uniflowed/router 0.2.0 → 0.3.0

package/action.js

@@ -109,6 +109,7 @@
 import {
   ACTION_CONTENT_TYPE,
   ACTION_HEADER,
+  ACTION_OUTCOME_HEADER,
   type ActionArgument,
   type ActionValue,
   decodeActionResult,
@@ -117,6 +118,7 @@ import {
 import { loadDocument, refusedAsAnotherDeployment, withDeployment } from "./internal/deployment.js";
 import { withFormAction } from "./internal/form-action.js";
 import { clearNavigationCache } from "./internal/navigation-cache.js";
+import { ForbiddenError, NotFoundError, UnauthorizedError } from "./internal/routing.js";
 
 export type { ActionArgument, ActionValue } from "./internal/action-wire.js";
 export {
@@ -277,6 +279,9 @@ function callServerActionFor(id: string, name: string): ServerActionFunction {
     ...args: Array<ActionArgument>
   ): Promise<ActionValue | void> {
     const body = encodeActionArguments(args);
+    // The page the call is made from, kept for the answer: a relative redirect
+    // means relative to this page, whatever the visitor has done since.
+    const from = currentUrl();
     // 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.
@@ -285,7 +290,7 @@ function callServerActionFor(id: string, name: string): ServerActionFunction {
     // Which build this page is, so a server on another build refuses the call
     // rather than looking this id up in a table it was never in.
     withDeployment(headers);
-    const response = await fetch(currentUrl(), {
+    const response = await fetch(from, {
       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
@@ -313,6 +318,14 @@ function callServerActionFor(id: string, name: string): ServerActionFunction {
       loadDocument(currentUrl());
       return new Promise<ActionValue | void>(() => {});
     }
+    // The action called `redirect()`, `notFound()`, `unauthorized()` or
+    // `forbidden()`. Checked before the status, because three of the four are
+    // not `ok` and none of them is a failure.
+    const outcome = response.headers.get(ACTION_OUTCOME_HEADER);
+    if (outcome != null) {
+      void response.body?.cancel();
+      return followOutcome(name, outcome, response, from);
+    }
     if (!response.ok) {
       throw new ServerActionError(name, response.status);
     }
@@ -320,6 +333,50 @@ function callServerActionFor(id: string, name: string): ServerActionFunction {
   };
 }
 
+/**
+ * Do in the browser what the action's routing call asked for.
+ *
+ * - `redirect`: go to the answer's `Location` the way `router.push` would. The
+ *   call then resolves with `undefined`, because the action returned nothing;
+ *   it threw. It resolves only once the navigation has settled, so a
+ *   `useActionState` on a page that is still on screen afterwards (a redirect
+ *   to the same page) is not left pending.
+ * - `not-found`, `unauthorized`, `forbidden`: throw the same error the server
+ *   caught. React hands an error thrown by an action to the nearest error
+ *   boundary, and uf's route boundary already tells `unauthorized()` and
+ *   `forbidden()` apart. `notFound()` arrives as a `NotFoundError`, which an
+ *   `$error.js` can test for.
+ *
+ * Any other value is a server this reference does not understand, and it is
+ * the same `ServerActionError` as any other failure.
+ *
+ * The router is imported when a redirect happens, not at module scope. This
+ * module is also imported by the server graphs (`registerServerAction`), and
+ * the router's runtime is client-rendering code that has no place there.
+ */
+async function followOutcome(
+  name: string,
+  outcome: string,
+  response: Response,
+  from: string,
+): Promise<ActionValue | void> {
+  switch (outcome) {
+    case "redirect": {
+      const { followActionRedirect } = await import("./internal/runtime.js");
+      await followActionRedirect(response.headers.get("location") ?? from, from);
+      return undefined;
+    }
+    case "not-found":
+      throw new NotFoundError();
+    case "unauthorized":
+      throw new UnauthorizedError();
+    case "forbidden":
+      throw new ForbiddenError();
+    default:
+      throw new ServerActionError(name, response.status);
+  }
+}
+
 /**
  * The URL an action call is sent to: the page the browser is on.
  *

package/client.js

@@ -122,12 +122,26 @@ import { type TrailingSlash, addressOf, applicationPathOf } from "./internal/bas
 import { hydrationOptions } from "./internal/hydrate-options.js";
 import { readFormState } from "./internal/form-action.js";
 
+/**
+ * The React root `hydrate` and `render` mounted, as far as a caller needs it:
+ * a way to take the application down again. See `hydrate` for who needs that.
+ */
+export type ApplicationRoot = { readonly unmount: () => void, ... };
+
 /**
  * Hydrate the current document.
  *
  * Resolves without mounting anything when the current route ships no client
  * page — see the header. The promise settling is not a claim that React is on
  * the document.
+ *
+ * Resolves with the React root it created, or `null` when it mounted nothing.
+ * A page never needs it: its root lives as long as the document. It is for
+ * whoever has to take the application down again — a test that hydrates one
+ * page and then another in the same process, where an application left
+ * mounted keeps its router, its `popstate` listener and its effects running
+ * under the next one. `root.unmount()` runs every cleanup, including the one
+ * that stops a server action from navigating a router that is gone.
  */
 export async function hydrate(options: {|
   readonly App: React.ComponentType<AppProps>,
@@ -139,7 +153,7 @@ export async function hydrate(options: {|
   readonly basePath?: string,
   readonly trailingSlash?: TrailingSlash,
   readonly staleTime?: number,
-|}): Promise<void> {
+|}): Promise<ApplicationRoot | null> {
   const table: RouteTable = {
     routes: options.routes,
     notFound: options.notFound,
@@ -160,7 +174,7 @@ export async function hydrate(options: {|
   // would go looking for a page module that is not in this bundle.
   const matched = matchRoute(table.routes, applicationPath);
   if (matched != null && !hasClientPage(matched.route)) {
-    return;
+    return null;
   }
 
   const url = applicationPath + window.location.search;
@@ -213,8 +227,9 @@ export async function hydrate(options: {|
   // be a development-only difference without being a hydration difference.
   const tree = <App url={url} initial={resolved} />;
 
+  let root: ApplicationRoot | null = null;
   startTransition(() => {
-    hydrateRoot(
+    root = hydrateRoot(
       container,
       options.strictMode === true ? <StrictMode>{tree}</StrictMode> : tree,
       hydrationOptions(recovery, readFormState(document)),
@@ -235,6 +250,7 @@ export async function hydrate(options: {|
     const { reportDevtools } = await import("./internal/devtools.js");
     reportDevtools(window);
   }
+  return root;
 }
 
 /**
@@ -265,6 +281,9 @@ export async function hydrate(options: {|
  *   * **A redirect is the browser's.** `redirect()` from a loader throws before
  *     anything is rendered; on a server that becomes a 307 and here it becomes
  *     `location.replace`, which is the same instruction to the same browser.
+ *
+ * Resolves with the React root, or `null` when a loader redirected and nothing
+ * was mounted — for the reason `hydrate` gives.
  */
 export async function render(options: {|
   readonly App: React.ComponentType<AppProps>,
@@ -276,7 +295,7 @@ export async function render(options: {|
   readonly basePath?: string,
   readonly trailingSlash?: TrailingSlash,
   readonly staleTime?: number,
-|}): Promise<void> {
+|}): Promise<ApplicationRoot | null> {
   const table: RouteTable = {
     routes: options.routes,
     notFound: options.notFound,
@@ -296,7 +315,7 @@ export async function render(options: {|
   } catch (error) {
     if (error instanceof RedirectError) {
       window.location.replace(addressOf(error.to));
-      return;
+      return null;
     }
     // The error boundary, chosen the same way the server chooses it. A throw
     // from a loader is a page that cannot render, and rendering the boundary is
@@ -321,7 +340,7 @@ export async function render(options: {|
     );
   }
   const tree = <App url={url} initial={resolved} />;
-  createRoot(container).render(
-    options.strictMode === true ? <StrictMode>{tree}</StrictMode> : tree,
-  );
+  const root = createRoot(container);
+  root.render(options.strictMode === true ? <StrictMode>{tree}</StrictMode> : tree);
+  return root;
 }

package/internal/action-endpoint.js

@@ -125,6 +125,7 @@ import { asResponder, nativeActionAllowed } from "@uniflowed/server/host";
 import {
   ACTION_CONTENT_TYPE,
   ACTION_HEADER,
+  ACTION_OUTCOME_HEADER,
   type ActionArgument,
   ActionValueError,
   MAX_ACTION_BODY_BYTES,
@@ -140,7 +141,7 @@ import {
   readFormPost,
 } from "./form-action.js";
 import { requireRequest } from "./request.js";
-import { RedirectError } from "./routing.js";
+import { ForbiddenError, NotFoundError, RedirectError, UnauthorizedError } from "./routing.js";
 
 export type { FormState } from "./form-action.js";
 
@@ -294,6 +295,13 @@ export function createActionDispatcher(options: {|
         const call = action as $FlowFixMe;
         result = await traceRequestPhase("action", () => call(...args));
       } catch (error) {
+        // `redirect()` and its three siblings are where the visitor goes next,
+        // not something that went wrong: answered as themselves, and never
+        // reported. See `ACTION_OUTCOME_HEADER`.
+        const outcome = routingOutcome(error);
+        if (outcome != null) {
+          return outcome;
+        }
         report(record, error);
         return refusal(500);
       }
@@ -390,13 +398,23 @@ async function nativeFormPost(
       if (error instanceof RedirectError) {
         return seeOther(addressOf(error.to));
       }
+      // A person is looking at this answer and there is no page to render the
+      // boundary into, so it is the status with a fixed line of text — the same
+      // three statuses the JSON door answers, and nothing of the exception.
+      const status = routingStatus(error);
+      if (status != null) {
+        return new Response(`${status.text}\n`, {
+          status: status.code,
+          headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" },
+        });
+      }
       report(record, error);
       return refusal(500);
     }
     if (stateKey == null || postback == null) {
       // Post/redirect/get: the page again, by a `GET`, so a reload does not
       // submit the form a second time.
-      return seeOther(addressOf(url.pathname + url.search));
+      return seeOther(addressOf(withOneLeadingSlash(url.pathname) + url.search));
     }
     try {
       // Held to the grammar for the reason the JSON door holds a result to it:
@@ -451,6 +469,88 @@ function sameSiteFetch(request: Request): boolean {
   return site == null || site === "same-origin";
 }
 
+/** The kind, status and text of a routing error other than a redirect. */
+type RoutingStatus = {|
+  readonly kind: "not-found" | "unauthorized" | "forbidden",
+  readonly code: 404 | 401 | 403,
+  readonly text: string,
+|};
+
+/**
+ * What `notFound()`, `unauthorized()` or `forbidden()` answers with, or `null`
+ * for anything else.
+ *
+ * The statuses are the ones a page gets for the same call (`routeErrorStatus`
+ * and the not-found page), so a client that reads only the status reads the
+ * same thing a document request would have told it.
+ */
+function routingStatus(error: mixed): RoutingStatus | null {
+  if (error instanceof NotFoundError) {
+    return { kind: "not-found", code: 404, text: "not found" };
+  }
+  if (error instanceof UnauthorizedError) {
+    return { kind: "unauthorized", code: 401, text: "unauthorized" };
+  }
+  if (error instanceof ForbiddenError) {
+    return { kind: "forbidden", code: 403, text: "forbidden" };
+  }
+  return null;
+}
+
+/**
+ * The JSON door's answer for a routing error, or `null` for any other throw.
+ *
+ * A redirect is a `204` carrying `Location`, the address `addressOf` makes of
+ * it (under the base path for a path on this application). It is not a `3xx`,
+ * because `fetch` would follow that itself and fetch the page's HTML for
+ * nothing, and the reference could not read where it pointed. The other three
+ * are their page statuses. Each one carries `ACTION_OUTCOME_HEADER`, so a `404`
+ * from `notFound()` is not mistaken for the `404` of an unknown id. The body
+ * names the kind and nothing else.
+ */
+function routingOutcome(error: mixed): Response | null {
+  if (error instanceof RedirectError) {
+    const headers: { [string]: string } = {
+      "cache-control": "no-store",
+      location: addressOf(error.to),
+    };
+    headers[ACTION_OUTCOME_HEADER] = "redirect";
+    return new Response(null, { status: 204, headers });
+  }
+  const status = routingStatus(error);
+  if (status == null) {
+    return null;
+  }
+  const headers: { [string]: string } = { ...ANSWER_HEADERS };
+  headers[ACTION_OUTCOME_HEADER] = status.kind;
+  return new Response(JSON.stringify({ outcome: status.kind }), {
+    status: status.code,
+    headers,
+  });
+}
+
+/**
+ * `path` with a leading run of `/` counted down to one.
+ *
+ * The post/redirect/get above answers with the path the form was posted to,
+ * and that path is the request's: `https://app.example//evil.example/notes` is
+ * a link anybody can write, its page posts its forms back to the same address,
+ * and a URL parser reads `/\evil.example` as the same two slashes. Written
+ * into `Location` as it stands, `//evil.example/notes` is a network-path
+ * reference and the browser follows it to another host — after the person
+ * submitted a form on this one. `@uniflowed/server` makes the same repair to
+ * the trailing-slash redirect (`withOneLeadingSlash` in its `routing.js`); the
+ * router cannot import it, so it is spelled here as a counted loop, never a
+ * pattern (`docs/security.md`, rule 5).
+ */
+function withOneLeadingSlash(path: string): string {
+  let start = 0;
+  while (start + 1 < path.length && path.charCodeAt(start + 1) === 47) {
+    start += 1;
+  }
+  return path.charCodeAt(0) === 47 ? path.slice(start) : path;
+}
+
 /** A `303 See Other`, which a browser follows with a `GET`. */
 function seeOther(location: string): Response {
   return new Response(null, {

package/internal/action-wire.js

@@ -93,6 +93,24 @@
 // Pure: no imports, no platform APIs beyond `JSON`, so the browser half of
 // `@uniflowed/router` can reach it without reaching anything server-only.
 
+/**
+ * The response header that says a server action ended in a routing outcome
+ * rather than a result: `redirect`, `not-found`, `unauthorized` or
+ * `forbidden`.
+ *
+ * `redirect()`, `notFound()`, `unauthorized()` and `forbidden()` are how a
+ * page's code says where the visitor goes next, and an action is page code:
+ * `redirect("/notes")` at the end of a mutation is the common way to finish
+ * one. They are control flow, not failures, so the endpoint does not report
+ * them or answer `500`. It answers with this header, the matching status and,
+ * for a redirect, `Location`. The reference in the browser reads the header
+ * and navigates or throws the same error for the route's boundary. Only the
+ * kind crosses, plus the address for a redirect. The exception's message and
+ * stack never do, which is the fixed-`500` rule applied to the one failure
+ * that is not a failure.
+ */
+export const ACTION_OUTCOME_HEADER: string = "uf-action-outcome";
+
 /** The request header carrying the action id. */
 export const ACTION_HEADER: string = "uf-action";
 
@@ -248,6 +266,21 @@ function asFormData(value: mixed): FormData | null {
 /** One entry of the explicit walk stack. */
 type Pending = {| readonly value: mixed, readonly path: string, readonly depth: number |};
 
+/**
+ * How many more values a walk may visit before `MAX_ACTION_VALUES` is spent.
+ *
+ * An object rather than a number so that one budget can be handed to the walk
+ * of every argument of a call: the ceiling `docs/security.md` states is on the
+ * *call* — "at most 10,000 values in total" — and a budget per argument would
+ * be `MAX_ACTION_ARGUMENTS` times that.
+ */
+export type ValueBudget = { remaining: number };
+
+/** A fresh budget of `MAX_ACTION_VALUES`, for one call or one result. */
+export function valueBudget(): ValueBudget {
+  return { remaining: MAX_ACTION_VALUES };
+}
+
 /**
  * Refuse a value that cannot cross the wire, naming where it was.
  *
@@ -257,11 +290,27 @@ type Pending = {| readonly value: mixed, readonly path: string, readonly depth:
  * hand on the depth. Every bound is checked as the walk runs rather than
  * afterwards, so a payload that busts one is refused before the rest of it is
  * visited.
+ *
+ * That includes the count, which is checked *before* an array's or an
+ * object's members are queued rather than as each is visited. One array of
+ * half a million zeros fits in a 1 MiB body, and queueing every element — each
+ * with a path string of its own — before the counter reached any of them
+ * spent tens of megabytes of heap on a payload that was always going to be
+ * refused.
+ *
+ * `budget` is spent by this walk and may be shared: `decodeActionArguments`
+ * and `encodeActionArguments` hand every argument the same one, so the ceiling
+ * is on the call. Without one, the value has a budget of its own.
  */
-export function checkActionValue(root: mixed, label: string): void {
+export function checkActionValue(
+  root: mixed,
+  label: string,
+  budget?: ValueBudget = valueBudget(),
+): void {
   const stack: Array<Pending> = [{ value: root, path: label, depth: 0 }];
   const seen = new Set<mixed>();
-  let remaining = MAX_ACTION_VALUES;
+  const overBudget = () =>
+    new ActionValueError(label, `holds more than ${String(MAX_ACTION_VALUES)} values`);
 
   while (stack.length > 0) {
     const pending = stack.pop();
@@ -270,9 +319,9 @@ export function checkActionValue(root: mixed, label: string): void {
     }
     const { value, path, depth } = pending;
 
-    remaining -= 1;
-    if (remaining < 0) {
-      throw new ActionValueError(label, `holds more than ${String(MAX_ACTION_VALUES)} values`);
+    budget.remaining -= 1;
+    if (budget.remaining < 0) {
+      throw overBudget();
     }
     if (depth > MAX_ACTION_DEPTH) {
       throw new ActionValueError(path, `is nested deeper than ${String(MAX_ACTION_DEPTH)}`);
@@ -309,6 +358,11 @@ export function checkActionValue(root: mixed, label: string): void {
 
     if (Array.isArray(object)) {
       const items: $ReadOnlyArray<mixed> = object as $FlowFixMe;
+      // Every queued value will be visited and spent, so a queue longer than
+      // what is left is a refusal now rather than after the push.
+      if (stack.length + items.length > budget.remaining) {
+        throw overBudget();
+      }
       for (let index = 0; index < items.length; index += 1) {
         stack.push({ value: items[index], path: `${path}[${String(index)}]`, depth: depth + 1 });
       }
@@ -342,7 +396,11 @@ export function checkActionValue(root: mixed, label: string): void {
     }
 
     const record: { readonly [string]: mixed } = object as $FlowFixMe;
-    for (const key of Object.getOwnPropertyNames(object)) {
+    const keys = Object.getOwnPropertyNames(object);
+    if (stack.length + keys.length > budget.remaining) {
+      throw overBudget();
+    }
+    for (const key of keys) {
       if (FORBIDDEN_KEYS.includes(key)) {
         throw new ActionValueError(`${path}.${key}`, "is a key this grammar never carries");
       }
@@ -407,6 +465,8 @@ export function encodeActionArguments(args: $ReadOnlyArray<mixed>): string {
     );
   }
   const values: Array<mixed> = [];
+  // One budget for the whole call; see `ValueBudget`.
+  const budget = valueBudget();
   let form: {| readonly at: number, readonly entries: Array<Array<string>> |} | null = null;
   for (let index = 0; index < args.length; index += 1) {
     const argument = args[index];
@@ -420,7 +480,7 @@ export function encodeActionArguments(args: $ReadOnlyArray<mixed>): string {
       values.push(null);
       continue;
     }
-    checkActionValue(argument, label);
+    checkActionValue(argument, label, budget);
     values.push(argument);
   }
   return form == null ? JSON.stringify({ args: values }) : JSON.stringify({ args: values, form });
@@ -460,8 +520,10 @@ export function decodeActionArguments(text: string): Array<ActionArgument> {
       `passes more than ${String(MAX_ACTION_ARGUMENTS)} arguments`,
     );
   }
+  // One budget for the whole call; see `ValueBudget`.
+  const budget = valueBudget();
   for (let index = 0; index < args.length; index += 1) {
-    checkActionValue(args[index], `argument ${String(index + 1)}`);
+    checkActionValue(args[index], `argument ${String(index + 1)}`, budget);
   }
   const decoded: Array<ActionArgument> = args as $FlowFixMe;
   if (keys.length === 2) {

package/internal/compose.js

@@ -58,7 +58,7 @@ export type ComposeOptions = {|
 |};
 
 /** The route a slot renders inside, as much of it as a slot reads. */
-type SlotRoute = { +pathname: string, +searchParams: SearchParams, ... };
+type SlotRoute = { readonly pathname: string, readonly searchParams: SearchParams, ... };
 
 /**
  * Whether this bundle marks the boundaries it renders.
@@ -356,11 +356,11 @@ export function slotsAt(
   slots: $ReadOnlyArray<ResolvedSlot>,
   depth: number,
   route: SlotRoute,
-): { readonly [string]: React.Node } {
+): SlotProps {
   if (slots.length === 0) {
     return EMPTY_SLOTS;
   }
-  const props: { [string]: React.Node } = {};
+  const props: { key?: empty, [string]: React.Node } = {};
   for (const slot of slots) {
     if (slot.above === depth) {
       // `null` rather than an element that renders nothing, and the difference
@@ -376,8 +376,18 @@ export function slotsAt(
   return props;
 }
 
+/**
+ * A layout's slots, as the props they are spread into.
+ *
+ * `key` is named out of the indexer, the way `@uniflowed/ui`'s `Rest` names it:
+ * the object is spread onto an element, and a `React.Node` is not a key. No
+ * slot is called `key` — a slot is a prop the layout declares, and React
+ * never hands a component its key.
+ */
+export type SlotProps = { readonly key?: empty, readonly [string]: React.Node };
+
 /** One object for every layout on a project that declares no slot. */
-const EMPTY_SLOTS: { readonly [string]: React.Node } = Object.freeze({});
+const EMPTY_SLOTS: SlotProps = Object.freeze({});
 
 /**
  * One slot's tree: its page, inside the layouts declared under the slot, with

package/internal/deployment.js

@@ -52,8 +52,9 @@ let remembered: string | null | void;
 
 /** The parts of a `Document` read here. */
 type HeadLike = interface {
-  readonly querySelector: (selector: string) => ?interface {
-    readonly getAttribute: (name: string) => ?string,
+  // Methods, as a `Document`'s are: a method cannot be read off as a property.
+  querySelector(selector: string): ?interface {
+    getAttribute(name: string): ?string,
   },
 };
 

package/internal/devtools.js

@@ -92,7 +92,7 @@ export function devtoolsProblem(win: HookWindow): {|
   // handed back. Anything else there is a hook uf did not install and DevTools
   // did not either, and guessing at its shape would report a problem that is
   // really this module not recognising one.
-  const renderers = (hook: $FlowFixMe).renderers;
+  const renderers = (hook as $FlowFixMe).renderers;
   const count = renderers instanceof Map ? renderers.size : null;
   if (count != null && count > 1) {
     return {

package/internal/error-view.js

@@ -34,7 +34,7 @@ component DefaultRouteError(error: RouteError, reset: () => void) {
   const detail = match (error) {
     {kind: "unauthorized"} => "This page needs you to be signed in.",
     {kind: "forbidden"} => "You do not have access to this page.",
-    {kind: "thrown"} => "This page could not be rendered.",
+    {kind: "thrown", ...} => "This page could not be rendered.",
   };
   return (
     <main>