@uniflowed/router 0.1.0 → 0.3.0

package/internal/flight-browser.js

@@ -39,7 +39,7 @@ import {
 import { requireServerComponentsReact } from "./react-version.js";
 
 /** A module namespace, as far as the loader looks into one. */
-type ModuleNamespace = { +[string]: mixed };
+type ModuleNamespace = { readonly [string]: mixed };
 
 /** The entry a refusal names: the one an application reaches this module through. */
 const ENTRY = "@uniflowed/router/rsc/client";
@@ -86,16 +86,24 @@ export function installBrowserModules(): void {
     throw new Error("@uniflowed/router: a payload asked for an import map, which uf never writes");
   };
   parcelRequire.meta = { publicUrl: "", devServer: null };
-  Object.defineProperty(globalThis, "parcelRequire", {
+  // `Reflect`, because Flow reads a property name given to
+  // `Object.defineProperty` as one the target must already declare, and
+  // `parcelRequire` is exactly the global nothing declares. `Object`'s throws
+  // where this answers `false`, so the throw is kept.
+  const defined = Reflect.defineProperty(globalThis, "parcelRequire", {
     value: parcelRequire,
     writable: true,
     configurable: true,
   });
+  if (!defined) {
+    throw new TypeError("@uniflowed/router: could not install parcelRequire on the global object");
+  }
 }
 
 /** The parts of a `Document` the reader uses. */
 type DocumentLike = interface {
-  readonly querySelectorAll: (selector: string) => Iterable<ElementLike>,
+  // A method, as a `Document`'s is: a method cannot be read off as a property.
+  querySelectorAll(selector: string): Iterable<ElementLike>,
   readonly documentElement: mixed,
 };
 
@@ -222,12 +230,16 @@ export async function fetchFlight(
   const landed = new URL(response.url, window.location.href);
   const document = documentPathOf(landed.pathname);
   const type = response.headers.get("content-type") ?? "";
-  if (
-    landed.origin !== window.location.origin ||
-    document == null ||
-    !type.startsWith(FLIGHT_CONTENT_TYPE)
-  ) {
-    void response.body?.cancel();
+  // A payload file a static host could not type (#1495) is taken for what it
+  // is only after its first bytes say so; see [`untypedPayload`].
+  const payload =
+    landed.origin === window.location.origin && document != null
+      ? type.startsWith(FLIGHT_CONTENT_TYPE)
+        ? response
+        : await untypedPayload(response, type)
+      : null;
+  if (payload == null || document == null) {
+    void response.body?.cancel().catch(() => {});
     // The URL the reader asked for when the redirect did not end on a payload,
     // rather than the one it ended on. A middleware that answered with its
     // sign-in page wrote a `next=` naming the payload URL; loading the document
@@ -237,6 +249,70 @@ export async function fetchFlight(
   return {
     kind: "flight",
     url: `${document}${landed.search}`,
-    root: createFromFetch(Promise.resolve(response)),
+    root: createFromFetch(Promise.resolve(payload)),
   };
 }
+
+/** The types a host sends for a file it does not know, or no type at all. */
+const UNTYPED: $ReadOnlyArray<string> = Object.freeze([
+  "",
+  "application/octet-stream",
+  "binary/octet-stream",
+]);
+
+/** How far into a body to look for the first row before giving up. */
+const SNIFF_LIMIT = 256;
+
+/**
+ * `response` as a payload, when a host served one without saying so.
+ *
+ * A prerendered page's payload is a file, `<route>/__uf.flight`, and a static
+ * host that does not know the extension sends it with no `Content-Type` (the
+ * Workers asset server, Pages) or as `application/octet-stream`. Refusing it
+ * made every client navigation on such a host a full page load. The type
+ * check is not dropped for it, it is replaced by one that cannot be fooled the
+ * same way: the answer has to be a `200` for the payload URL itself (no
+ * redirect — a sign-in page reached by one is what the type check is for),
+ * untyped rather than typed as something else (`text/html` is a document,
+ * whatever its bytes), and its first line has to be a Flight row, `<hex id>:`.
+ * Anything else answers `null` and the router loads the document, as before.
+ *
+ * The bytes read to decide are put back in front of the rest, so React reads
+ * the whole payload.
+ */
+async function untypedPayload(response: Response, type: string): Promise<Response | null> {
+  const media = type.split(";")[0].trim().toLowerCase();
+  if (!UNTYPED.includes(media) || response.status !== 200 || response.redirected) return null;
+  const body = response.body;
+  if (body == null) return null;
+  const reader = body.getReader();
+  const read: Array<Uint8Array> = [];
+  let seen = "";
+  const decoder = new TextDecoder();
+  while (!seen.includes("\n") && seen.length < SNIFF_LIMIT) {
+    const step = await reader.read();
+    if (step.done === true) break;
+    read.push(step.value);
+    seen += decoder.decode(step.value, { stream: true });
+  }
+  if (!/^[0-9a-f]+:/i.test(seen)) {
+    void reader.cancel().catch(() => {});
+    return null;
+  }
+  const replayed = new ReadableStream({
+    start(controller) {
+      for (const chunk of read) controller.enqueue(chunk);
+    },
+    async pull(controller) {
+      const step = await reader.read();
+      if (step.done === true) controller.close();
+      else controller.enqueue(step.value);
+    },
+    cancel(reason) {
+      return reader.cancel(reason);
+    },
+  });
+  const headers = new Headers(response.headers);
+  headers.set("content-type", FLIGHT_CONTENT_TYPE);
+  return new Response(replayed, { status: 200, headers });
+}

package/internal/flight-chunks.js

@@ -142,13 +142,13 @@ export function flightChunkBytes(text: string): Uint8Array | null {
   if (typeof value === "string") {
     return new TextEncoder().encode(value);
   }
-  if (
-    typeof value === "object" &&
-    !Array.isArray(value) &&
-    typeof value.bytes === "string" &&
-    Object.keys(value).length === 1
-  ) {
-    return fromBase64(value.bytes);
+  if (typeof value === "object" && !Array.isArray(value)) {
+    // Read once into a local: a refinement of `value.bytes` does not survive
+    // to the call, a `const` does.
+    const bytes = value.bytes;
+    if (typeof bytes === "string" && Object.keys(value).length === 1) {
+      return fromBase64(bytes);
+    }
   }
   throw new Error(`@uniflowed/router: a ${FLIGHT_CHUNK_ATTRIBUTE} element holds no payload chunk`);
 }

package/internal/flight-rows.js

@@ -39,7 +39,12 @@ const NEWLINE = 0x0a;
 const ERROR_TAG = "E".charCodeAt(0);
 
 /** One row's place in the payload. */
-type Row = {| +start: number, +end: number, +tag: number, +body: number |};
+type Row = {|
+  readonly start: number,
+  readonly end: number,
+  readonly tag: number,
+  readonly body: number,
+|};
 
 /**
  * Every row of a finished payload, in order.
@@ -92,7 +97,7 @@ function rowsOf(bytes: Uint8Array): Array<Row> {
 export function withoutErrorRows(
   payload: Uint8Array,
   left: (digest: string) => boolean,
-): {| +payload: Uint8Array, +removed: number |} {
+): {| readonly payload: Uint8Array, readonly removed: number |} {
   const decoder = new TextDecoder();
   const kept: Array<Uint8Array> = [];
   let removed = 0;

package/internal/flight-ssr.js

@@ -28,7 +28,7 @@ import type { FlightRoot } from "./flight.js";
 import { requireServerComponentsReact } from "./react-version.js";
 
 /** A module namespace, as far as the hook looks into one. */
-type ModuleNamespace = { +[string]: mixed };
+type ModuleNamespace = { readonly [string]: mixed };
 
 /** The server copy of the client module at a browser chunk URL. */
 export type ClientModuleLoader = (url: string) => Promise<ModuleNamespace>;
@@ -64,11 +64,18 @@ export function installServerModules(load: ClientModuleLoader): void {
     throw new Error("@uniflowed/router: a payload asked for an import map, which uf never writes");
   };
   parcelRequire.meta = { publicUrl: "", devServer: null };
-  Object.defineProperty(globalThis, "parcelRequire", {
+  // `Reflect`, because Flow reads a property name given to
+  // `Object.defineProperty` as one the target must already declare, and
+  // `parcelRequire` is exactly the global nothing declares. `Object`'s throws
+  // where this answers `false`, so the throw is kept.
+  const defined = Reflect.defineProperty(globalThis, "parcelRequire", {
     value: parcelRequire,
     writable: true,
     configurable: true,
   });
+  if (!defined) {
+    throw new TypeError("@uniflowed/router: could not install parcelRequire on the global object");
+  }
 }
 
 /**
@@ -82,7 +89,7 @@ export function installServerModules(load: ClientModuleLoader): void {
  */
 export function readPayload(
   stream: ReadableStream<Uint8Array>,
-  options?: {| +partial?: boolean |},
+  options?: {| readonly partial?: boolean |},
 ): Promise<FlightRoot> {
   requireServerComponentsReact(ENTRY);
   return options?.partial === true

package/internal/flight.js

@@ -108,6 +108,38 @@ export type FetchedFlight =
       readonly url: string,
     |};
 
+/**
+ * `error` as it may cross into a Flight payload: a thrown value that is not an
+ * `Error` becomes one.
+ *
+ * The route's error travels to the browser as a prop of the error page and as
+ * part of the route state, and React serialises it the way it serialises any
+ * prop. For an `Error` that is safe by React's own rule: a production payload
+ * carries the digest and none of the message or the stack. A thrown value
+ * that is *not* an `Error` gets no such rule. A string, or a plain object
+ * such as an API client's `{ message, details, hint }`, would be serialised
+ * as the data it is, and a query, a table name or a token in it would be
+ * published to whoever asked for the page.
+ *
+ * So it is wrapped. The message is the value's `String()`, which `uf dev`
+ * shows and which a production payload drops along with every other `Error`
+ * message. The original value is still what the server reported: this is
+ * applied only to the copy that crosses. `unauthorized` and `forbidden` carry
+ * nothing and pass through as they are.
+ */
+export function crossableRouteError(error: ?RouteError): ?RouteError {
+  if (error == null || error.kind !== "thrown" || error.error instanceof Error) {
+    return error;
+  }
+  let text = "a value that is not an Error was thrown";
+  try {
+    text = String(error.error);
+  } catch {
+    // A value whose `toString` throws: the sentence above is all it gets.
+  }
+  return { kind: "thrown", error: new Error(text) };
+}
+
 /** The part of a resolved route that crosses to the browser. */
 export function routeState(resolved: ResolvedRoute): RouteState {
   const interception = resolved.interception;

package/internal/form-action.js

@@ -0,0 +1,243 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: a server action as a form the browser can
+// submit before any JavaScript has run.
+//
+// React 19's contract for `<form action={serverFunction}>` is progressive
+// enhancement. While rendering to HTML, React asks the function for
+// `$$FORM_ACTION(prefix)` and writes what it answers into the markup — a
+// `method`, an `encType`, a hidden field named `name`, and one hidden field per
+// entry of `data` — so the form is a real form that posts to the page it is on.
+// A function without the property gets `action="javascript:throw …"` instead,
+// which is what every uf form got before ubugeeei-prod/uf#1358.
+//
+// Two functions carry the property: the reference the browser holds
+// (`createServerReference` in `../action.js`) and the real function the server
+// renders with (`registerServerAction`, which `@uniflowed/vite` calls on every
+// callable export of a `"use server"` module in the server graph). Both answer
+// with the same fields, from the code below, so the markup the server writes and
+// what a hydrated page would have written agree.
+//
+// # The fields
+//
+// React hands `$$FORM_ACTION` a prefix unique to the form in its render, and
+// the prefix is in every field name so that two forms — or a `<form>` and a
+// `<button formAction>` inside it — never read each other's fields:
+//
+// | Field | Value |
+// | --- | --- |
+// | `$uf_ref_<prefix>` | empty. The field that says *which* action this submit is for; on a `<button formAction>` it is the button's own name, so only the button that was pressed sends it |
+// | `$uf_id_<prefix>` | the action's id, the same 64 hexadecimal characters the JSON call carries in `uf-action` |
+// | `$uf_bound_<prefix>` | the bound arguments, as the JSON envelope `encodeActionArguments` writes, when there are any |
+//
+// `useActionState` adds React's own `$ACTION_KEY`, which names the hook that
+// submitted, so the answer can put the action's result back into the same hook.
+//
+// Every field is a string and every bound argument goes through the same
+// grammar as a JSON call: nothing new is allowed to cross by arriving as a form.
+// `./action-endpoint.js` is the other half, and its header says what a native
+// post is refused for.
+
+import { encodeActionArguments } from "./action-wire.js";
+
+/** The name of the field that says which action a submit is for. */
+export const FORM_REF_FIELD = "$uf_ref_";
+/** The action id, beside it. */
+export const FORM_ID_FIELD = "$uf_id_";
+/** The bound arguments, beside it. */
+export const FORM_BOUND_FIELD = "$uf_bound_";
+/** React's own: which `useActionState` submitted. */
+export const FORM_STATE_KEY_FIELD = "$ACTION_KEY";
+
+/**
+ * The only content type a native action post may have.
+ *
+ * `application/x-www-form-urlencoded` rather than `multipart/form-data`,
+ * because a server action refuses a file anyway and multipart parsing is a
+ * surface uf does not open for one (`docs/security.md`). `$$FORM_ACTION` says
+ * it explicitly, so React writes it on the form and on a submit button.
+ */
+export const FORM_ACTION_CONTENT_TYPE = "application/x-www-form-urlencoded";
+
+/** What `$$FORM_ACTION` answers, in the shape React reads. */
+export type FormActionFields = {|
+  readonly name: string,
+  readonly method: "POST",
+  readonly encType: string,
+  readonly data: FormData,
+|};
+
+/**
+ * What a `useActionState` postback leaves for the page it renders.
+ *
+ * React's `ReactFormState`: the action's result, the hook's key, the action's
+ * id, and how many bound arguments it had *besides* the state
+ * `useActionState` bound itself.
+ */
+export type FormState = [mixed, string, string, number];
+
+/**
+ * Make `fn` a server action a form can post to without JavaScript.
+ *
+ * Defines three non-enumerable properties on `fn` and returns it:
+ *
+ * - `$$FORM_ACTION(prefix)`, the fields above;
+ * - `$$IS_SIGNATURE_EQUAL(id, bound)`, which React asks while rendering a
+ *   postback's answer to decide whether a `useActionState` is the one that
+ *   submitted — the same action, bound the same number of times;
+ * - `bind`, which keeps both of those on the function it returns, with the
+ *   bound arguments recorded so they travel in the form.
+ *
+ * `call` is what the bound function runs: `fn` itself on the server, the
+ * network call in the browser.
+ */
+export function withFormAction<T extends (...args: $ReadOnlyArray<empty>) => mixed>(
+  fn: T,
+  id: string,
+  bound: $ReadOnlyArray<mixed>,
+): T {
+  const define = (name: string, value: mixed) => {
+    Object.defineProperty(fn, name, { value, configurable: true, writable: true });
+  };
+  define("$$FORM_ACTION", (prefix: string): FormActionFields => formFields(id, bound, prefix));
+  define(
+    "$$IS_SIGNATURE_EQUAL",
+    (referenceId: string, boundCount: number): boolean =>
+      referenceId === id && boundCount === bound.length,
+  );
+  // `Function.prototype.bind` itself, reached through a cast: Flow types
+  // `bind` per call site and has no type for the method taken off the
+  // prototype and applied to an arbitrary function.
+  const nativeBind: $FlowFixMe = Function.prototype.bind;
+  define("bind", function bindAction(thisArg: mixed, ...more: Array<mixed>) {
+    const next: T = nativeBind.call(fn, thisArg, ...more);
+    return withFormAction(next, id, [...bound, ...more]);
+  });
+  return fn;
+}
+
+/**
+ * The fields a form bound to this action is written with.
+ *
+ * Throws `ActionValueError` when a bound argument cannot cross, which React
+ * catches and reports as "Failed to serialize an action for progressive
+ * enhancement" before writing the form it would have written without this —
+ * so an unencodable state costs the pre-hydration submit and nothing else.
+ */
+export function formFields(
+  id: string,
+  bound: $ReadOnlyArray<mixed>,
+  prefix: string,
+): FormActionFields {
+  const data = new FormData();
+  data.append(`${FORM_ID_FIELD}${prefix}`, id);
+  if (bound.length > 0) {
+    data.append(`${FORM_BOUND_FIELD}${prefix}`, encodeActionArguments(bound));
+  }
+  return {
+    name: `${FORM_REF_FIELD}${prefix}`,
+    method: "POST",
+    encType: FORM_ACTION_CONTENT_TYPE,
+    data,
+  };
+}
+
+/** What a native post names, read off its fields. */
+export type FormPost = {|
+  /** The action id, as sent; checked by the caller. */
+  readonly id: string | null,
+  /** The bound-argument envelope, as sent, or `null` when there is none. */
+  readonly bound: string | null,
+  /** `$ACTION_KEY`, or `null` when no `useActionState` submitted. */
+  readonly stateKey: string | null,
+  /** Every other field, in order: what the action is handed as its form. */
+  readonly entries: Array<[string, string]>,
+|};
+
+/**
+ * Read a native post's fields, or `null` when it names no action at all.
+ *
+ * `null` is the caller's signal to decline, exactly as a JSON request with no
+ * `uf-action` header is: an ordinary form posted to a route handler must reach
+ * that handler. The last `$uf_ref_` field wins, because the browser writes a
+ * pressed button's name after the fields of the form around it, and a button's
+ * `formAction` is meant to override the form's `action`.
+ *
+ * Every field whose name uf or React owns is kept out of `entries`, including
+ * another prefix's, so the action receives the form the person filled in and
+ * nothing that says how it was wired.
+ */
+export function readFormPost(fields: URLSearchParams): FormPost | null {
+  let prefix: string | null = null;
+  for (const [name] of fields) {
+    if (name.startsWith(FORM_REF_FIELD)) {
+      prefix = name.slice(FORM_REF_FIELD.length);
+    }
+  }
+  if (prefix == null) {
+    return null;
+  }
+  const entries: Array<[string, string]> = [];
+  for (const [name, value] of fields) {
+    if (!isWiring(name)) {
+      entries.push([name, value]);
+    }
+  }
+  return {
+    id: fields.get(`${FORM_ID_FIELD}${prefix}`),
+    bound: fields.get(`${FORM_BOUND_FIELD}${prefix}`),
+    stateKey: fields.get(FORM_STATE_KEY_FIELD),
+    entries,
+  };
+}
+
+/** Whether a field is uf's or React's rather than the form's own. */
+function isWiring(name: string): boolean {
+  return name.startsWith("$uf_") || name.startsWith("$ACTION_");
+}
+
+/** The element a postback's form state is written into the document as. */
+export const FORM_STATE_ELEMENT_ID = "uf:form-state";
+
+/**
+ * The `<script>` that carries a postback's form state to `hydrateRoot`.
+ *
+ * `application/json`, so it is data and never executed — no nonce, and nothing
+ * a Content Security Policy has to admit. The result was already held to the
+ * wire grammar before it got here, so it is plain JSON; `<` is escaped so
+ * that no string in it can close the element.
+ */
+export function formStateScript(state: FormState): string {
+  const json = JSON.stringify(state).replace(/</g, "\\u003c");
+  return `<script type="application/json" id="${FORM_STATE_ELEMENT_ID}">${json}</script>`;
+}
+
+/**
+ * The form state a document carries, or `undefined`.
+ *
+ * Read by both hydrating entries before `hydrateRoot`. Anything malformed is
+ * `undefined` rather than an exception: the page still hydrates, and the
+ * `useActionState` that submitted starts from its initial state, which is what
+ * it would have done with JavaScript from the start.
+ */
+export function readFormState(document: Document): FormState | void {
+  const element = document.getElementById(FORM_STATE_ELEMENT_ID);
+  if (element == null) {
+    return undefined;
+  }
+  try {
+    const parsed: mixed = JSON.parse(element.textContent);
+    if (
+      Array.isArray(parsed) &&
+      parsed.length === 4 &&
+      typeof parsed[1] === "string" &&
+      typeof parsed[2] === "string" &&
+      typeof parsed[3] === "number"
+    ) {
+      return [parsed[0], parsed[1], parsed[2], parsed[3]];
+    }
+  } catch {
+    // Fall through: see above.
+  }
+  return undefined;
+}

package/internal/hydrate-options.js

@@ -0,0 +1,38 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: what both hydrating entries hand
+// `hydrateRoot` besides the tree.
+
+import type { FormState } from "./form-action.js";
+
+/** React's `onRecoverableError`, as the development report builds one. */
+type Recovery = (error: mixed, info: { componentStack?: ?string, ... }) => void;
+
+/** What this hands `hydrateRoot`. */
+type HydrationOptions = {| onRecoverableError?: Recovery, formState?: FormState |};
+
+/**
+ * `hydrateRoot`'s options: the development recovery handler, and a postback's
+ * form state.
+ *
+ * `formState` is React's own option. A page rendered in answer to a form posted
+ * before hydration was rendered with it, React marked the `useActionState` that
+ * submitted, and passing the same value here is how the browser's copy of that
+ * hook starts from the action's result instead of its initial state.
+ */
+export function hydrationOptions(
+  recovery: ?Recovery,
+  formState: FormState | void,
+): HydrationOptions | void {
+  if (recovery == null && formState == null) {
+    return undefined;
+  }
+  const options: HydrationOptions = {};
+  if (recovery != null) {
+    options.onRecoverableError = recovery;
+  }
+  if (formState != null) {
+    options.formState = formState;
+  }
+  return options;
+}

package/internal/hydration.js

@@ -195,21 +195,26 @@ type DetachedHeadStyle = {|
  * puts them back in the same order.
  */
 export function prepareDevHeadForHydration(document: Document): () => void {
-  for (const script of document.head.querySelectorAll("script")) {
+  // A document without a head has nothing of uf's in it to hide.
+  const head = document.head;
+  if (head == null) {
+    return () => {};
+  }
+  for (const script of head.querySelectorAll("script")) {
     if (isDevHeadScript(script)) {
       script.remove();
     }
   }
-  for (const child of Array.from(document.head.childNodes)) {
+  for (const child of Array.from(head.childNodes)) {
     if (isIgnorableHeadWhitespace(child)) {
-      child.remove();
+      head.removeChild(child);
     }
   }
   const detached = [];
-  for (const style of document.head.querySelectorAll("style")) {
+  for (const style of head.querySelectorAll("style")) {
     if (isViteDevStyle(style)) {
       const anchor = document.createComment("uf dev style");
-      document.head.insertBefore(anchor, style);
+      head.insertBefore(anchor, style);
       style.remove();
       detached.push({ anchor, style });
     }
@@ -243,7 +248,7 @@ function restoreDevHeadStyles(
       parent.insertBefore(style, anchor);
       parent.removeChild(anchor);
     } else {
-      document.head.appendChild(style);
+      document.head?.appendChild(style);
     }
   }
 }

package/internal/navigation-cache.js

@@ -62,7 +62,7 @@ let staleTimeMs: number = 0;
 export function installStaleTime(seconds: number): void {
   staleTimeMs = Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : 0;
   if (import.meta.hot != null) {
-    Object.defineProperty((globalThis: $FlowFixMe), "__UF_NAVIGATION_CACHE__", {
+    Object.defineProperty(globalThis as $FlowFixMe, "__UF_NAVIGATION_CACHE__", {
       configurable: true,
       value: inspectNavigationCache,
     });

package/internal/payload-rows.js

@@ -81,13 +81,15 @@ export type PayloadReader = {|
 
 /** The parts of a `Document` this module uses, so it needs no DOM lib. */
 type DocumentLike = interface {
-  readonly querySelectorAll: (selector: string) => Iterable<ElementLike>,
-  readonly documentElement: mixed,
+  // Methods rather than function-valued properties: a `Document`'s are
+  // methods, and a method cannot be read off its object as a property.
+  querySelectorAll(selector: string): Iterable<ElementLike>,
+  readonly documentElement: ?Node,
 };
 
 /** The parts of an `Element` this module uses. */
 type ElementLike = interface {
-  readonly getAttribute: (name: string) => string | null,
+  getAttribute(name: string): ?string,
   readonly textContent: string | null,
 };
 
@@ -261,7 +263,6 @@ export function domObserver(
     const observer = new MutationObserver(() => {
       callback();
     });
-    // $FlowFixMe[incompatible-call] `documentElement` is a `Node`; the interface above says only what is read.
     observer.observe(root, { childList: true, subtree: true });
     return () => {
       observer.disconnect();