@uniflowed/router 0.0.0-alpha.4 → 0.0.0-alpha.41

package/internal/flight-browser.js

@@ -0,0 +1,238 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: React Server Components, in the browser.
+//
+// A route's tree reaches the browser as React's Flight payload
+// (ubugeeei-prod/uf#519), by one of two doors. The first page arrives inside
+// its document, as the chunks `./flight-chunks.js` describes, and is read here
+// while the document is still streaming so that `hydrateRoot` can start before
+// the slowest boundary has resolved. Every page after that is a `fetch` of the
+// route's payload URL (`./flight.js`), read the same way by React's own client.
+//
+// # The one hook React's Parcel client asks for
+//
+// `react-server-dom-parcel` resolves a client reference through a global
+// `parcelRequire`: `load(url)` for each chunk a reference names, then
+// `parcelRequire(id)` for the module, synchronously, once they have loaded. uf
+// has no Parcel; this module is that hook. A reference's id *is* its chunk's
+// URL — `@uniflowed/vite` writes it that way — so loading a chunk and
+// remembering its namespace under the same string is the whole of it.
+//
+// It imports same-origin URLs and nothing else. The payload comes from the
+// page's own origin, so a URL that points somewhere else is not a URL uf wrote,
+// and turning it into an `import()` would be letting bytes decide which script
+// runs.
+
+import { createFromFetch, createFromReadableStream } from "react-server-dom-parcel/client.browser";
+
+import { FLIGHT_CHUNK_ATTRIBUTE, flightChunkBytes } from "./flight-chunks.js";
+import {
+  FLIGHT_CONTENT_TYPE,
+  INTERCEPTED_FROM_HEADER,
+  type FetchedFlight,
+  type FlightFetchOptions,
+  type FlightRoot,
+  documentPathOf,
+  flightUrl,
+} from "./flight.js";
+import { requireServerComponentsReact } from "./react-version.js";
+
+/** A module namespace, as far as the loader looks into one. */
+type ModuleNamespace = { +[string]: mixed };
+
+/** The entry a refusal names: the one an application reaches this module through. */
+const ENTRY = "@uniflowed/router/rsc/client";
+
+/**
+ * Install the module hook React's Flight client resolves references through.
+ *
+ * Once per page. Defined rather than assigned, for the reason
+ * `./boundaries.js` gives about its own global: a name a page already defined
+ * as an accessor cannot be assigned to, and hydration must not throw over it.
+ */
+export function installBrowserModules(): void {
+  requireServerComponentsReact(ENTRY);
+  const loaded: Map<string, ModuleNamespace> = new Map();
+  // A function with three properties, which is the shape React's Parcel client
+  // calls: `parcelRequire(id)` for a module, `parcelRequire.load(url)` for the
+  // chunk it lives in. Declared and then given its properties, so the hook is
+  // built rather than merged into something that already existed.
+  function parcelRequire(id: string): ModuleNamespace {
+    const namespace = loaded.get(id);
+    if (namespace == null) {
+      throw new Error(
+        `@uniflowed/router: the client module ${id} was required before it loaded. React's ` +
+          "Flight client loads every chunk a reference names before it asks for the module.",
+      );
+    }
+    return namespace;
+  }
+  parcelRequire.load = (url: string): Promise<void> => {
+    const target = new URL(url, window.location.href);
+    if (target.origin !== window.location.origin) {
+      return Promise.reject(
+        new Error(
+          `@uniflowed/router: a payload named the client module ${url}, which is not on this ` +
+            "page's origin. uf writes same-origin chunk URLs only, so it is not loaded.",
+        ),
+      );
+    }
+    return import(target.href).then((namespace: ModuleNamespace) => {
+      loaded.set(url, namespace);
+    });
+  };
+  parcelRequire.extendImportMap = (): 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", {
+    value: parcelRequire,
+    writable: true,
+    configurable: true,
+  });
+}
+
+/** The parts of a `Document` the reader uses. */
+type DocumentLike = interface {
+  readonly querySelectorAll: (selector: string) => Iterable<ElementLike>,
+  readonly documentElement: mixed,
+};
+
+/** The parts of an `Element` the reader uses. */
+type ElementLike = interface {
+  readonly textContent: string | null,
+};
+
+/**
+ * The payload a document carries, as the byte stream React's client reads.
+ *
+ * Every chunk element already in the document is read at once, in document
+ * order, and a `MutationObserver` reads the ones the server has not written
+ * yet. The stream ends at the end marker and the observer is disconnected with
+ * it, so a prerendered document — every chunk already there — never installs
+ * one.
+ *
+ * `observe` is passed in rather than reached for, so the reader can be driven
+ * by a test with a document it mutates by hand; `domObserver` in
+ * `./payload-rows.js` is the browser's.
+ */
+export function documentPayload(
+  document: DocumentLike,
+  observe: ?(callback: () => void) => (() => void) | null,
+): ReadableStream<Uint8Array> {
+  const seen: WeakSet<ElementLike> = new WeakSet();
+  let stop: (() => void) | null = null;
+  let done = false;
+  return new ReadableStream({
+    start(controller) {
+      const sweep = () => {
+        if (done) {
+          return;
+        }
+        for (const element of document.querySelectorAll(`script[${FLIGHT_CHUNK_ATTRIBUTE}]`)) {
+          if (seen.has(element)) {
+            continue;
+          }
+          seen.add(element);
+          let bytes;
+          try {
+            bytes = flightChunkBytes(element.textContent ?? "null");
+          } catch (error) {
+            done = true;
+            stop?.();
+            controller.error(error);
+            return;
+          }
+          if (bytes == null) {
+            done = true;
+            stop?.();
+            controller.close();
+            return;
+          }
+          controller.enqueue(bytes);
+        }
+      };
+      sweep();
+      if (!done && observe != null) {
+        stop = observe(sweep);
+      }
+    },
+    cancel() {
+      done = true;
+      stop?.();
+    },
+  });
+}
+
+/** Read the payload a document carries into its root value. */
+export function readDocumentPayload(
+  document: DocumentLike,
+  observe: ?(callback: () => void) => (() => void) | null,
+): Promise<FlightRoot> {
+  requireServerComponentsReact(ENTRY);
+  return createFromReadableStream(documentPayload(document, observe));
+}
+
+/**
+ * Fetch `url`'s payload.
+ *
+ * A redirect is followed by `fetch`, and the route the payload is for is read
+ * back off the URL the answer came from — so a loader's `redirect()` during a
+ * navigation lands the history entry on the target, as a document request
+ * would have. Anything that is not a payload is handed back as a document to
+ * load instead of being fed to React's client.
+ *
+ * The status is not what decides, the content type is. A route that resolved
+ * to its not-found or error boundary is answered with a 404 or a 500 *and a
+ * payload*, and that payload is the page to show; what is not a payload — a
+ * static host's `404.html` for a file it does not have, a middleware's own
+ * refusal — is a document, whatever its status.
+ */
+export async function fetchFlight(
+  url: string,
+  options?: FlightFetchOptions,
+): Promise<FetchedFlight> {
+  // Outside the `try` below, which answers every failure to fetch with a
+  // document load: too old a React is not a network failure, and a navigation
+  // that quietly reloaded the page would hide it.
+  requireServerComponentsReact(ENTRY);
+  const headers = new Headers({ accept: FLIGHT_CONTENT_TYPE });
+  const interceptedFrom = options?.interceptedFrom;
+  if (interceptedFrom != null) {
+    headers.set(INTERCEPTED_FROM_HEADER, interceptedFrom);
+  }
+  let response: Response;
+  try {
+    response = await fetch(flightUrl(url), {
+      credentials: "same-origin",
+      headers,
+    });
+  } catch {
+    // A request that could not be made or followed: a dropped connection, or a
+    // redirect to another origin — a sign-in page — which `fetch` may not
+    // follow without CORS. The browser can still load the document, and a
+    // top-level navigation follows any redirect, so that is what the router
+    // does rather than leave the click doing nothing.
+    return { kind: "document", url };
+  }
+  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();
+    // 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
+    // URL lets it see the document and name that instead.
+    return { kind: "document", url: document == null ? url : `${document}${landed.search}` };
+  }
+  return {
+    kind: "flight",
+    url: `${document}${landed.search}`,
+    root: createFromFetch(Promise.resolve(response)),
+  };
+}

package/internal/flight-chunks.js

@@ -0,0 +1,205 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: a Flight payload, written into a document
+// and read back out of one.
+//
+// A document a server streams carries the payload the browser hydrates from,
+// beside the HTML rendered from it: every chunk React's Flight renderer wrote
+// is copied into a `<script type="application/json" data-uf-flight>` element
+// as the HTML streams, and the browser reads the elements back into the byte
+// stream React's Flight client consumes. This module is the encoding of one
+// chunk in each direction, and nothing else, so the writer (`./stream.js`) and
+// the reader (`./flight-browser.js`) cannot disagree about it.
+//
+// # `application/json`, and not a script that runs
+//
+// The obvious mechanism is an inline script that pushes each chunk into a
+// global. `./runtime.js` and `./payload-rows.js` have already made the case
+// against it for uf's documents: a script that runs is a script a content
+// security policy has to allow, and application data in a script element with
+// no type is application data handed to the JavaScript parser. A JSON script
+// runs nothing, and a `MutationObserver` notices each one as it lands.
+//
+// # Text, and bytes that are not text
+//
+// A payload is bytes. Almost all of it is UTF-8 text — rows of JSON — and it is
+// written as a JSON string, which is what makes it readable in a document. A
+// typed array a server component passed as a prop is a row of raw bytes that
+// need not be valid UTF-8, and a decoder that replaced them would hand React a
+// different array. So a run of bytes that does not decode strictly is written
+// as base64 instead, and the reader turns each element back into exactly the
+// bytes the writer was given.
+//
+// A chunk boundary can fall inside a multi-byte character, which is not an
+// invalid sequence and must not be treated as one: the writer keeps an
+// incomplete tail back and prepends it to the next chunk.
+
+/** The attribute every payload chunk element carries. */
+export const FLIGHT_CHUNK_ATTRIBUTE: string = "data-uf-flight";
+
+/** What one element holds: text, bytes that are not text, or the end. */
+export type FlightChunk = string | {| readonly bytes: string |} | null;
+
+/**
+ * An element's text: a JSON value with the three escapes an inline element
+ * needs.
+ *
+ * `<` so a payload holding `</script>` cannot close the element early, and
+ * U+2028 and U+2029 because JSON is sometimes read as JavaScript. The same
+ * escape `./payload.js` applies, for the same reasons.
+ */
+function elementJson(value: FlightChunk): string {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+/**
+ * The element for one chunk, or the end marker for `null`.
+ *
+ * `nonce` is this response's, and it is carried even though the element is
+ * `application/json` and therefore a data block the browser never executes.
+ * Two reasons, and neither is "in case the spec changes". A uf document's
+ * invariant is that every `<script>` in it carries the nonce — that is what
+ * `packages/router/streaming.test.js` pins, and an invariant with an exception
+ * in it is one a reader has to check every new script against. And these are
+ * written as text into a stream rather than rendered by React, so unlike the
+ * payload rows in `./runtime.js` there is no second render on the client to
+ * disagree with; the attribute costs a comparison nobody makes.
+ */
+export function flightChunkElement(chunk: FlightChunk, nonce?: string | null): string {
+  const carried = nonce == null ? "" : ` nonce="${escapeNonce(nonce)}"`;
+  return `<script type="application/json"${carried} ${FLIGHT_CHUNK_ATTRIBUTE}>${elementJson(chunk)}</script>`;
+}
+
+/**
+ * A nonce, as an attribute value.
+ *
+ * uf's own nonces are base64 and hold none of these, so this is about the one a
+ * project supplied: the value reaches a document that a browser parses as
+ * HTML, and a `"` in it would end the attribute and open whatever follows.
+ */
+function escapeNonce(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+
+/**
+ * A writer's state: the bytes of an incomplete character, carried to the next
+ * chunk.
+ *
+ * One per document, made by [`createChunkEncoder`], because the carry is a fact
+ * about the stream and two documents must never share one.
+ */
+export type ChunkEncoder = {|
+  /** The elements for one chunk of payload bytes; possibly none. */
+  readonly encode: (bytes: Uint8Array) => string,
+  /** The elements for whatever is carried, and the end marker. */
+  readonly end: () => string,
+|};
+
+export function createChunkEncoder(nonce?: string | null): ChunkEncoder {
+  const strict = new TextDecoder("utf-8", { fatal: true });
+  let carry: Uint8Array = new Uint8Array(0);
+
+  function encode(bytes: Uint8Array): string {
+    const joined = concat(carry, bytes);
+    const complete = completeLength(joined);
+    carry = joined.slice(complete);
+    if (complete === 0) {
+      return "";
+    }
+    const body = joined.subarray(0, complete);
+    try {
+      return flightChunkElement(strict.decode(body), nonce);
+    } catch {
+      return flightChunkElement({ bytes: base64(body) }, nonce);
+    }
+  }
+
+  function end(): string {
+    const rest = carry;
+    carry = new Uint8Array(0);
+    const tail = rest.length === 0 ? "" : flightChunkElement({ bytes: base64(rest) }, nonce);
+    return `${tail}${flightChunkElement(null, nonce)}`;
+  }
+
+  return { encode, end };
+}
+
+/**
+ * The bytes one element holds, or `null` for the end marker.
+ *
+ * Refuses anything that is not one of the three shapes the writer produces,
+ * rather than guessing: a document carrying some other value in an element
+ * with this attribute was not written by this module.
+ */
+export function flightChunkBytes(text: string): Uint8Array | null {
+  const value: mixed = JSON.parse(text);
+  if (value === null) {
+    return 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);
+  }
+  throw new Error(`@uniflowed/router: a ${FLIGHT_CHUNK_ATTRIBUTE} element holds no payload chunk`);
+}
+
+/**
+ * How many leading bytes of `bytes` end on a character boundary.
+ *
+ * Walks back over at most three continuation bytes to the lead byte of the last
+ * character and keeps it back when the character is not yet whole. A byte that
+ * is not a valid lead at all is left in — the strict decoder is what says so,
+ * and holding it back would carry it forever.
+ */
+function completeLength(bytes: Uint8Array): number {
+  const length = bytes.length;
+  let at = length - 1;
+  let continuation = 0;
+  while (at >= 0 && continuation < 3 && (bytes[at] & 0xc0) === 0x80) {
+    at -= 1;
+    continuation += 1;
+  }
+  if (at < 0) {
+    return length;
+  }
+  const lead = bytes[at];
+  const needed = lead >= 0xf0 ? 4 : lead >= 0xe0 ? 3 : lead >= 0xc0 ? 2 : 1;
+  return length - at >= needed ? length : at;
+}
+
+function concat(first: Uint8Array, second: Uint8Array): Uint8Array {
+  if (first.length === 0) {
+    return second;
+  }
+  const joined = new Uint8Array(first.length + second.length);
+  joined.set(first, 0);
+  joined.set(second, first.length);
+  return joined;
+}
+
+function base64(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+
+function fromBase64(text: string): Uint8Array {
+  const binary = atob(text);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}

package/internal/flight-ssr.js

@@ -0,0 +1,78 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: React Server Components, while HTML renders.
+//
+// The HTML renderer does not render a route's modules. It reads the payload
+// the Flight renderer wrote (`../rsc.js`) with React's own Flight client and
+// renders what comes out, so the document is the payload's tree and not a
+// second rendering of the same modules — which is what lets a Server Component
+// be a module that neither this graph nor the browser ever evaluates.
+//
+// # Where a client component's server copy comes from
+//
+// A client reference in a payload names a chunk URL, which is the browser's
+// module. HTML still has to be rendered from the component, on the server, so
+// `@uniflowed/vite` builds a server copy of every client module and hands the
+// renderer a table from the browser's URL to that copy. React's Parcel client
+// resolves references through a global `parcelRequire`, exactly as in the
+// browser (`./flight-browser.js`), and this module is that hook on a server.
+//
+// The same global serves one application per process, which is what a uf
+// server is. `meta.publicUrl` is empty because the URLs a reference names are
+// already absolute paths: React asks the document to preload each chunk while
+// it renders, and those tags are right exactly as the payload spells them.
+
+import { createFromReadableStream } from "react-server-dom-parcel/client.edge";
+
+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 };
+
+/** The server copy of the client module at a browser chunk URL. */
+export type ClientModuleLoader = (url: string) => Promise<ModuleNamespace>;
+
+/** The entry a refusal names: the one an application reaches this module through. */
+const ENTRY = "@uniflowed/router/rsc/ssr";
+
+/**
+ * Install the module hook React's Flight client resolves references through.
+ *
+ * Idempotent over the same loader and replaced by a different one, so a dev
+ * server that rebuilds its table installs the new table rather than keeping a
+ * stale one.
+ */
+export function installServerModules(load: ClientModuleLoader): void {
+  requireServerComponentsReact(ENTRY);
+  const loaded: Map<string, ModuleNamespace> = new Map();
+  // The browser's hook, on a server; `./flight-browser.js` has the shape.
+  function parcelRequire(id: string): ModuleNamespace {
+    const namespace = loaded.get(id);
+    if (namespace == null) {
+      throw new Error(
+        `@uniflowed/router: the client module ${id} was required before its server copy loaded`,
+      );
+    }
+    return namespace;
+  }
+  parcelRequire.load = (url: string): Promise<void> =>
+    load(url).then((namespace) => {
+      loaded.set(url, namespace);
+    });
+  parcelRequire.extendImportMap = (): 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", {
+    value: parcelRequire,
+    writable: true,
+    configurable: true,
+  });
+}
+
+/** Read a payload into its root value, as React's client does in the browser. */
+export function readPayload(stream: ReadableStream<Uint8Array>): Promise<FlightRoot> {
+  requireServerComponentsReact(ENTRY);
+  return createFromReadableStream(stream);
+}