@uniflowed/router 0.1.0 → 0.3.0

package/action.js

@@ -66,26 +66,19 @@
 // still reads `submitNote`'s own declaration, so a form action whose first
 // parameter is not the state it was given `null` for is a `uf check` error.
 //
-// **This needs the page to be hydrated.** React's progressive enhancement —
-// the form that submits before its JavaScript has arrived — works through a
-// `$$FORM_ACTION` property that turns the submit into a *native* form post,
-// and a native form post is `multipart/form-data`: the content type this
-// endpoint refuses, deliberately, as one of the three things standing between
-// it and a cross-site call. Supporting the pre-hydration submit would mean
-// accepting that content type, so a reference carries no `$$FORM_ACTION`, and
-// React writes the form it writes for any client action —
-// `action="javascript:throw new Error('React form unexpectedly submitted.')"`
-// — so a submit before hydration throws in the page rather than posting
-// anywhere. Nothing reaches a server that was not meant to; what is missing is
-// the submit working at all. See ubugeeei-prod/uf#252.
-//
-// The refusal is why the property is withheld, not what would stop it: no
-// request is made, so nothing is refused. Nor would a native form post aimed
-// at a page by hand be refused as multipart — `createActionDispatcher` reads
-// the `uf-action` header before it looks at the method or the content type and
-// returns `null` when it is absent, so the request is not an action call at
-// all and falls through to the route handlers. The `415` answers a request
-// that claims to be an action, which is the only kind that reaches it.
+// **It works before the page has hydrated, too.** React's progressive
+// enhancement — the form that submits before its JavaScript has arrived — asks
+// the function for `$$FORM_ACTION` while rendering to HTML, and a reference
+// has one: `method="POST"`, `application/x-www-form-urlencoded`, and hidden
+// fields naming the action and carrying its bound arguments. The server
+// renders with the real function, which `@uniflowed/vite` gives the same
+// property through `registerServerAction` below, so the markup is the same
+// whichever side wrote it. A native post is not the JSON call: it is a
+// separate door in `./internal/action-endpoint.js`, which accepts only that
+// content type, only from the page's own origin, and only with the fields
+// `./internal/form-action.js` writes. `useActionState` works there as well
+// — the answer is the page rendered with the action's result as the hook's
+// state. See ubugeeei-prod/uf#1358.
 //
 // # After a deploy
 //
@@ -116,13 +109,16 @@
 import {
   ACTION_CONTENT_TYPE,
   ACTION_HEADER,
+  ACTION_OUTCOME_HEADER,
   type ActionArgument,
   type ActionValue,
   decodeActionResult,
   encodeActionArguments,
 } from "./internal/action-wire.js";
 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 {
@@ -248,15 +244,44 @@ export class ServerActionError extends Error {
  * 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.
  *
- * It carries no `$$FORM_ACTION`, which is deliberate and is the header's last
- * section: React uses that property to make a form submit *natively* before
- * hydration, and a native submit is a content type this endpoint refuses.
+ * It carries `$$FORM_ACTION`, so a form bound to it is a real form before the
+ * page hydrates; see the header and `./internal/form-action.js`.
  */
 export function createServerReference(id: string, name: string): ServerActionFunction {
+  return withFormAction(callServerActionFor(id, name), id, []);
+}
+
+/**
+ * Give a server action, on the server, what its reference has in the browser.
+ *
+ * `@uniflowed/vite` calls this on every callable export of a `"use server"`
+ * module in the server graphs, with the id the build derived for it, so that a
+ * client component rendered to HTML writes a form that posts without
+ * JavaScript. It changes nothing about calling the function: the properties it
+ * defines are ones only React reads, and `bind` still binds. Anything that is
+ * not a function is returned untouched, because the RSC graph has already
+ * refused a `"use server"` export that is not one and this is not the place to
+ * say it twice.
+ */
+export function registerServerAction<T>(fn: T, id: string): T {
+  if (typeof fn !== "function") {
+    return fn;
+  }
+  // `typeof` refines `T` to a function whose parameters Flow cannot name, and
+  // `withFormAction` changes nothing about calling it; the cast says that.
+  withFormAction(fn as $FlowFixMe, id, []);
+  return fn;
+}
+
+/** The network call one reference makes. */
+function callServerActionFor(id: string, name: string): ServerActionFunction {
   return async function callServerAction(
     ...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.
@@ -265,7 +290,7 @@ export function createServerReference(id: string, name: string): ServerActionFun
     // 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
@@ -293,6 +318,14 @@ export function createServerReference(id: string, name: string): ServerActionFun
       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);
     }
@@ -300,6 +333,50 @@ export function createServerReference(id: string, name: string): ServerActionFun
   };
 }
 
+/**
+ * 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

@@ -119,6 +119,14 @@ import { decodePayload } from "./internal/payload.js";
 import { createPayloadReader, domObserver } from "./internal/payload-rows.js";
 import { prepareDocumentForHydration } from "./internal/prepare-document.js";
 import { type TrailingSlash, addressOf, applicationPathOf } from "./internal/base-path.js";
+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.
@@ -126,6 +134,14 @@ import { type TrailingSlash, addressOf, applicationPathOf } from "./internal/bas
  * 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>,
@@ -137,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,
@@ -158,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;
@@ -211,11 +227,12 @@ 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,
-      recovery == null ? undefined : { onRecoverableError: recovery },
+      hydrationOptions(recovery, readFormState(document)),
     );
     if (restoreDevHead != null) {
       setTimeout(restoreDevHead, 250);
@@ -233,6 +250,7 @@ export async function hydrate(options: {|
     const { reportDevtools } = await import("./internal/devtools.js");
     reportDevtools(window);
   }
+  return root;
 }
 
 /**
@@ -263,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>,
@@ -274,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,
@@ -294,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
@@ -319,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;
 }