@uniflowed/router 0.0.0-alpha.34 → 0.0.0-alpha.35

package/internal/server-route.js

@@ -0,0 +1,52 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: the route a server component is rendering in.
+//
+// `useRoute()` in the browser reads the router's context, and a server
+// component has no context to read. The graph it renders in resolves `react`
+// under the `react-server` condition, which is the build with no `useContext`
+// in it (ubugeeei-prod/uf#519), and a layout that highlights the section it is
+// in — this repository's own documentation site has two — would otherwise have
+// to become a client component to find out where it is.
+//
+// So the Flight renderer runs each render inside a store holding the route it
+// resolved, and the server half of the hooks reads it back. `AsyncLocalStorage`
+// and not React's `cache`: `cache` finds its render through React's own request
+// storage, which the build React ships for Deno does not have, so after the
+// first `await` in an async server component it would stop finding the render
+// at all. A store of this module's own follows every continuation of the
+// render on every host `@uniflowed/server` already runs on, and it is one value
+// per render, so two requests in flight cannot read each other's route.
+//
+// Server-only by construction: nothing in the browser's graph imports this.
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+import type { RouteState } from "./flight.js";
+
+const storage: AsyncLocalStorage<RouteState> = new AsyncLocalStorage();
+
+/** Run `body` as a render of `route`. Everything it starts sees the route. */
+export function withServerRoute<T>(route: RouteState, body: () => T): T {
+  return storage.run(route, body);
+}
+
+/**
+ * The route being rendered, or a refusal naming the caller.
+ *
+ * A refusal rather than `null`, because the only way to arrive here without a
+ * route is to call a router hook from a server module that is not being
+ * rendered by the router — a script, a route handler, a module evaluated at
+ * import time — and each of those is a mistake worth a sentence.
+ */
+export function serverRoute(caller: string): RouteState {
+  const route = storage.getStore();
+  if (route == null) {
+    throw new Error(
+      `@uniflowed/router: ${caller}() was called in a server module outside a route the router ` +
+        "is rendering. Server Components read the route they render in; a route handler reads " +
+        "the request it was given, and a module evaluated at import time has no route at all.",
+    );
+  }
+  return route;
+}

package/internal/stream.js

@@ -43,6 +43,7 @@ import * as React from "react";
 import * as ReactDOMServer from "react-dom/server";
 import * as ReactDOMStatic from "react-dom/static";
 
+import { createChunkEncoder } from "./flight-chunks.js";
 import { type StreamRecord, inspected } from "./inspector.js";
 
 /**
@@ -656,6 +657,16 @@ export type RenderOptions = {|
    * everything before it writes a byte, so there is no order to report.
    */
   readonly onStream?: (record: StreamRecord) => void,
+  /**
+   * The Flight payload this document's tree was read from, to write into the
+   * document for the browser to hydrate from.
+   *
+   * Absent for a document rendered from the route's modules, which is what
+   * every document was before ubugeeei-prod/uf#519 and what `app.rsc: false`
+   * still asks for. Present, it is copied into the document as it arrives, by
+   * [`interleaved`], which says where it may and may not go.
+   */
+  readonly payload?: ReadableStream<Uint8Array>,
 |};
 
 /**
@@ -692,7 +703,10 @@ export function renderDocument(node: React.Node, options: RenderOptions): Promis
           resolve(
             bodyOf(
               outgoing(
-                assembled(queue.chunks(), options.shell, options.transformHead),
+                withPayload(
+                  assembled(queue.chunks(), options.shell, options.transformHead),
+                  options.payload,
+                ),
                 options.onStream,
               ),
               () => abort(),
@@ -759,7 +773,10 @@ export function renderWithReadableStream(
     (stream: ByteSource) =>
       bodyOf(
         outgoing(
-          assembled(decoded(stream), options.shell, options.transformHead),
+          withPayload(
+            assembled(decoded(stream), options.shell, options.transformHead),
+            options.payload,
+          ),
           options.onStream,
         ),
         () => {
@@ -815,10 +832,146 @@ export async function prerenderDocument(node: React.Node, options: RenderOptions
       ? await ReactDOMStatic.prerenderToNodeStream(node, settings)
       : await ReactDOMStatic.prerender(node, settings);
   return bodyOf(
-    assembled(preludeChunks(result.prelude), options.shell, options.transformHead),
+    withPayload(
+      assembled(preludeChunks(result.prelude), options.shell, options.transformHead),
+      options.payload,
+    ),
   ).text();
 }
 
+/** `chunks` unchanged when there is no payload, and [`interleaved`] with one. */
+function withPayload(
+  chunks: AsyncGenerator<string, void, void>,
+  payload: ?ReadableStream<Uint8Array>,
+): AsyncGenerator<string, void, void> {
+  return payload == null ? chunks : interleaved(chunks, payload);
+}
+
+/**
+ * A document's chunks, with the Flight payload it was rendered from written
+ * into it as it arrives.
+ *
+ * Three rules, and each is the answer to a way the obvious version is wrong.
+ *
+ * **Nothing before the head.** The first chunk this is handed is the whole
+ * opening of the document — `assembled` does not let one go until the head is
+ * complete — and a payload element written in front of it would sit before
+ * `<head>`, where the parser would open a body for it and every tag after it
+ * would land in the wrong element.
+ *
+ * **Written as soon as it exists.** A payload row usually exists before the
+ * HTML rendered from it — React's client reads the row, then the boundary
+ * renders — so waiting for the next HTML chunk would put the browser's copy
+ * behind the markup it hydrates. Each HTML chunk is followed by whatever
+ * payload is waiting, and a payload that arrives while the HTML is idle is
+ * written then, without a chunk of HTML to follow.
+ *
+ * **`</body></html>` waits for the end of the payload.** The HTML can finish
+ * first — the last boundary's markup is rendered from rows that are already
+ * written — and a payload element after `</html>` is one the parser moves
+ * rather than one React expects. So the closing tags are held back, the rest of
+ * the payload and its end marker are written, and the tags go last. For a
+ * document uf wraps, the closing run is `</div></body></html>`, and only the
+ * part from `</body>` is held: the root element React hydrates must hold
+ * nothing React did not render.
+ *
+ * A consumer that stops early stops the payload too: the reader is cancelled
+ * in the `finally`, which is where `return()` on this generator lands.
+ */
+async function* interleaved(
+  chunks: AsyncGenerator<string, void, void>,
+  payload: ReadableStream<Uint8Array>,
+): AsyncGenerator<string, void, void> {
+  const encoder = createChunkEncoder();
+  const reader = payload.getReader();
+  let written = "";
+  let ended = false;
+  let wake: ?() => void = null;
+  const ring = () => {
+    const resume = wake;
+    wake = null;
+    if (resume != null) {
+      resume();
+    }
+  };
+  const pumping = (async () => {
+    try {
+      while (true) {
+        const step = await reader.read();
+        if (step.done === true) {
+          break;
+        }
+        if (step.value != null) {
+          written += encoder.encode(step.value);
+          ring();
+        }
+      }
+    } catch {
+      // A payload that failed partway is still ended, with the end marker, so
+      // the browser's reader closes and React reports the rows it never got
+      // rather than waiting for them for as long as the page is open.
+    } finally {
+      written += encoder.end();
+      ended = true;
+      ring();
+    }
+  })();
+
+  let opened = false;
+  let closing = "";
+  try {
+    let next = chunks.next();
+    while (true) {
+      if (opened && written !== "") {
+        const out = written;
+        written = "";
+        yield out;
+      }
+      const idle = new Promise<null>((resolve) => {
+        wake = () => resolve(null);
+      });
+      const outcome = await Promise.race([next, idle]);
+      if (outcome == null) {
+        continue;
+      }
+      if (outcome.done === true) {
+        break;
+      }
+      let text = outcome.value;
+      const close = text.search(/<\/body>\s*<\/html>\s*$/i);
+      if (close !== -1) {
+        closing = text.slice(close);
+        text = text.slice(0, close);
+      }
+      if (text !== "") {
+        yield text;
+      }
+      opened = true;
+      next = chunks.next();
+    }
+    while (!ended || written !== "") {
+      if (written !== "") {
+        const out = written;
+        written = "";
+        yield out;
+        continue;
+      }
+      await new Promise<void>((resolve) => {
+        wake = resolve;
+        if (ended || written !== "") {
+          ring();
+        }
+      });
+    }
+    await pumping;
+    yield closing;
+  } finally {
+    if (!ended) {
+      void reader.cancel();
+    }
+  }
+}
+
 /**
  * The prelude of a static prerender, whichever stream this build produced.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/router",
-  "version": "0.0.0-alpha.34",
+  "version": "0.0.0-alpha.35",
   "description": "The file-system router for Flow React applications: matching, layouts, loaders, navigation, server rendering and hydration.",
   "type": "module",
   "license": "MIT",
@@ -11,10 +11,14 @@
     "directory": "packages/router"
   },
   "exports": {
-    ".": "./index.js",
+    ".": {
+      "react-server": "./server-components.js",
+      "default": "./index.js"
+    },
     "./action": "./action.js",
     "./client": "./client.js",
     "./native": "./native.js",
+    "./rsc": "./rsc.js",
     "./server": "./server.js",
     "./routing": "./routing.js",
     "./package.json": "./package.json",
@@ -30,15 +34,23 @@
     "middleware.js",
     "native.js",
     "routing.js",
+    "rsc.js",
+    "server-components.js",
     "server.js",
     "!*.test.js"
   ],
   "peerDependencies": {
-    "react": ">=19",
-    "react-dom": ">=19"
+    "react": ">=19.3.0",
+    "react-dom": ">=19.3.0",
+    "react-server-dom-parcel": ">=19.3.0"
+  },
+  "peerDependenciesMeta": {
+    "react-dom": {
+      "optional": true
+    }
   },
   "dependencies": {
-    "@uniflowed/hooks": "0.0.0-alpha.34",
-    "@uniflowed/server": "0.0.0-alpha.34"
+    "@uniflowed/hooks": "0.0.0-alpha.35",
+    "@uniflowed/server": "0.0.0-alpha.35"
   }
 }

package/rsc.js

@@ -0,0 +1,323 @@
+// @flow
+//
+// `@uniflowed/router/rsc`: a route, rendered as React Server Components.
+//
+// This module runs in the module graph uf resolves under the `react-server`
+// export condition, which is the graph where `react` is the build with no
+// `useState` in it and where React's Flight renderer is allowed to load
+// (ubugeeei-prod/uf#519). It does three things, and each is a piece that
+// already existed somewhere else:
+//
+//   1. **Resolve the URL** — `resolveMatch`, the same resolution a single-page
+//      application runs in the browser: the match, the modules, the loader, the
+//      metadata, the boundaries.
+//   2. **Compose the tree** — `composeRoute`, the same walk `RouteView` makes,
+//      so a layout, a fallback, a template and a slot land where they would in
+//      any other render.
+//   3. **Render it as a Flight payload** — `renderToReadableStream` from
+//      `react-server-dom-parcel`, which is React's own renderer and React's own
+//      wire format. uf writes no serialiser here and no decoder anywhere.
+//
+// The payload's root value is a [`FlightRoot`]: the route, as the part of it a
+// hook reads, and the tree. The HTML renderer (`./server.js`) reads it to write
+// the document, and the browser (`./client.js`) reads the same bytes to hydrate
+// and, after that, to navigate — so what the browser renders is exactly what
+// the server rendered, and no page, layout or loader module is ever the
+// browser's to evaluate. A `"use client"` module is the one thing that crosses,
+// as a reference to a chunk the browser loads.
+//
+// # What leaves before the payload does
+//
+// A redirect, and the status. Both are decided while the route resolves, which
+// is before anything renders, so `renderFlight` answers a redirect instead of a
+// stream and a route with the status it resolved to. That is the head-before-
+// the-first-byte property `./internal/stream.js` depends on, kept from the
+// other side: nothing the renderer learns while streaming can change the
+// response line.
+//
+// # Error boundaries have to be client modules
+//
+// An `$error.js` catches a throw while the *browser* renders, so its component
+// is the browser's, and a server component cannot be passed to a client one —
+// Flight refuses a function where a reference was expected. So each boundary's
+// component crosses as the client reference its `"use client"` directive made it
+// in this graph, and a boundary module without the directive is refused here,
+// with its file named, rather than by React with a sentence about functions.
+
+import * as React from "react";
+import { use } from "react";
+// React's Flight server. Only this graph can load it: it refuses to evaluate
+// unless `react` resolved under the `react-server` condition.
+import { renderToReadableStream } from "react-server-dom-parcel/server";
+
+import { noteRoute } from "@uniflowed/server/host";
+
+import { BoundaryReporter } from "./internal/boundaries.js";
+import { routeBoundaries } from "./internal/boundary-data.js";
+import { composeRoute, pageComponent } from "./internal/compose.js";
+import { ErrorRoutePage } from "./internal/error-view.js";
+import { type FlightRoot, routeState } from "./internal/flight.js";
+import type { ErrorModule, PageModule, ResolvedRoute, ResolvedSlot } from "./internal/resolve.js";
+import { resolveFailure, resolveMatch } from "./internal/resolve.js";
+import type { RouteParams, RouteTable, SearchParams } from "./internal/routing.js";
+import { RedirectError, nearestBoundary } from "./internal/routing.js";
+import { withServerRoute } from "./internal/server-route.js";
+
+export type { FlightRoot, RouteState } from "./internal/flight.js";
+
+/** What a host may tell the renderer about one render. */
+export type FlightOptions = {|
+  /**
+   * Whether a loader may be left running into a `$loading.js` boundary.
+   *
+   * On by default: a payload streams, so a slow loader is a fallback now and
+   * its answer later. A prerender turns it off, because a file has no "later".
+   */
+  readonly defer?: boolean,
+  /**
+   * Every exception the render recovered from, including the late ones.
+   *
+   * What it returns becomes the exception's digest. React writes the digest
+   * into the row that stands in for the part of the tree that failed, and sets
+   * it on the error its Flight client rebuilds from that row — which is how
+   * `./server.js` recognises, in the HTML renderer, the copy of an exception
+   * this renderer has already reported.
+   */
+  readonly onError?: (error: mixed) => ?string,
+  /**
+   * Render the error boundary for this exception instead of resolving the URL.
+   *
+   * What the HTML renderer asks for when the shell it was streaming from the
+   * payload threw before its first byte: the route resolved, and rendering it
+   * did not.
+   */
+  readonly failure?: {| readonly error: mixed |},
+  /** Stops the render, for a reader that went away. */
+  readonly signal?: AbortSignal,
+|};
+
+/** A render: a redirect to answer with, or a route and its payload. */
+export type FlightRender =
+  | {| readonly kind: "redirect", readonly status: 307 | 308, readonly location: string |}
+  | {|
+      readonly kind: "route",
+      readonly status: 200 | 401 | 403 | 404 | 500,
+      /** The payload, as React writes it. Read exactly once. */
+      readonly stream: ReadableStream<Uint8Array>,
+      /**
+       * The exception this route resolved to its error boundary for, when it did.
+       *
+       * The same field `./server.js` has always carried as `error`: `uf build`
+       * fails a route that set it and `uf dev` reports it. `forbidden()` and
+       * `unauthorized()` do not set it.
+       */
+      readonly failure: mixed,
+    |};
+
+/** Render one URL. */
+export type FlightRenderer = (url: string, options?: FlightOptions) => Promise<FlightRender>;
+
+/**
+ * Whether this bundle marks the boundaries it renders.
+ *
+ * `BOUNDARY_MARKS` in `./internal/runtime.js` has the argument; a build replaces
+ * `import.meta.hot` with `undefined` and every use below folds away.
+ */
+const BOUNDARY_MARKS: boolean = import.meta.hot != null;
+
+/** How a client reference says what it is. React's symbol, not uf's. */
+const CLIENT_REFERENCE: symbol = Symbol.for("react.client.reference");
+
+/**
+ * The renderer for one route table.
+ *
+ * The table is the server's whole one — every page, layout and boundary module
+ * — and it is `virtual:uf/routes` as this graph generates it.
+ */
+export function createFlightRenderer(options: {|
+  readonly routes: RouteTable["routes"],
+  readonly notFound: RouteTable["notFound"],
+  readonly errors: RouteTable["errors"],
+|}): FlightRenderer {
+  const table: RouteTable = {
+    routes: options.routes,
+    notFound: options.notFound,
+    errors: options.errors,
+  };
+
+  return async function renderFlight(url: string, settings?: FlightOptions): Promise<FlightRender> {
+    let resolved: ResolvedRoute;
+    try {
+      const failure = settings?.failure;
+      resolved =
+        failure == null
+          ? // `onMatch` records the route pattern on the request before the
+            // loader runs, so every line the loader logs names its route.
+            await resolveMatch(table, url, { defer: settings?.defer !== false, onMatch: noteRoute })
+          : await resolveFailure(table, url, failure.error);
+    } catch (error) {
+      if (error instanceof RedirectError) {
+        return { kind: "redirect", status: error.permanent ? 308 : 307, location: error.to };
+      }
+      throw error;
+    }
+
+    const errorFile = nearestBoundary(table.errors, resolved.pathname)?.file ?? null;
+    const route = forTheBrowser(resolved, errorFile);
+    const state = routeState(route);
+    const marks = BOUNDARY_MARKS ? routeBoundaries(route, errorFile) : null;
+    const tree = (
+      <>
+        {composeRoute(route, { page: pageElement(route), marks })}
+        {BOUNDARY_MARKS && marks != null ? (
+          <BoundaryReporter path={route.path} boundaries={marks} />
+        ) : null}
+      </>
+    );
+    const root: FlightRoot = { route: state, tree };
+    const report = settings?.onError;
+    // Inside the route's store, so a server component's `useRoute()` finds the
+    // route however many `await`s into the render it asks.
+    const stream = withServerRoute(state, () =>
+      renderToReadableStream(root, {
+        // Handed over as it is, so that the digest it returns reaches the row.
+        // Absent, React logs the exception to the console itself.
+        onError: report,
+        signal: settings?.signal,
+      }),
+    );
+    return { kind: "route", status: route.status, stream, failure: renderFailure(route) };
+  };
+}
+
+/**
+ * The page element: the route's page with its data, the deferred page that
+ * waits for its loader, or the error route's page.
+ *
+ * An element for a component rather than a call, so that a page module with no
+ * component in it throws while React renders — inside the boundaries the
+ * composition placed — rather than before the render has begun.
+ */
+function pageElement(route: ResolvedRoute): React.Node {
+  const error = route.error;
+  if (error != null) {
+    return <ErrorRoutePage module={route.errorBoundary.module} error={error} />;
+  }
+  const deferred = route.deferred;
+  if (deferred != null) {
+    return (
+      <DeferredPage
+        page={route.page}
+        params={route.params}
+        searchParams={route.searchParams}
+        loader={deferred}
+      />
+    );
+  }
+  return (
+    <RoutePage
+      page={route.page}
+      params={route.params}
+      searchParams={route.searchParams}
+      data={route.data}
+    />
+  );
+}
+
+/** A route's page, with its loader's answer. */
+component RoutePage(
+  page: PageModule,
+  params: RouteParams,
+  searchParams: SearchParams,
+  data: mixed,
+) {
+  const Page = pageComponent(page);
+  return <Page params={params} searchParams={searchParams} data={data} />;
+}
+
+/**
+ * The same page, once the loader the router deferred has answered.
+ *
+ * `use` rather than an `async` component: it suspends at the same point, inside
+ * the innermost `$loading.js` boundary, and it is the one spelling the
+ * browser's `AwaitedPage` already uses for the same wait.
+ */
+component DeferredPage(
+  page: PageModule,
+  params: RouteParams,
+  searchParams: SearchParams,
+  loader: Promise<mixed>,
+) {
+  return <RoutePage page={page} params={params} searchParams={searchParams} data={use(loader)} />;
+}
+
+/**
+ * The resolved route with every error boundary as the browser receives it.
+ *
+ * An error module is the server's module; what the browser needs is its
+ * component, and in this graph a `"use client"` component *is* a client
+ * reference. So each boundary becomes `{ default: <reference> }` — a plain
+ * object Flight can carry — and a boundary whose component is not a reference
+ * is refused with its file named.
+ */
+function forTheBrowser(resolved: ResolvedRoute, file: string | null): ResolvedRoute {
+  const boundary = resolved.errorBoundary;
+  return {
+    ...resolved,
+    errorBoundary: { above: boundary.above, module: clientErrorModule(boundary.module, file) },
+    slots: resolved.slots.map(slotForTheBrowser),
+  };
+}
+
+function slotForTheBrowser(slot: ResolvedSlot): ResolvedSlot {
+  const boundary = slot.errorBoundary;
+  return {
+    ...slot,
+    errorBoundary:
+      boundary == null
+        ? null
+        : { above: boundary.above, module: clientErrorModule(boundary.module, null) },
+    slots: slot.slots.map(slotForTheBrowser),
+  };
+}
+
+function clientErrorModule(module: ?ErrorModule, file: string | null): ?ErrorModule {
+  if (module == null) {
+    return null;
+  }
+  const component = module.default ?? module.Error;
+  if (component == null) {
+    throw new Error(
+      "@uniflowed/router: an error module must export a component as `default` or `Error`",
+    );
+  }
+  if (!isClientReference(component)) {
+    throw new Error(
+      `@uniflowed/router: ${file ?? "an `$error.js` inside a slot"} is an error boundary, and an ` +
+        "error boundary catches a throw while the browser renders — so its component runs in " +
+        "the browser, and the module has to open with the use client directive, as its first " +
+        "statement.",
+    );
+  }
+  return { default: component };
+}
+
+function isClientReference(value: mixed): boolean {
+  if (value == null || (typeof value !== "object" && typeof value !== "function")) {
+    return false;
+  }
+  const tagged: { +$$typeof?: mixed, ... } = (value: $FlowFixMe);
+  return tagged.$$typeof === CLIENT_REFERENCE;
+}
+
+/** The exception a resolved route fell back to its error boundary for. */
+function renderFailure(resolved: ResolvedRoute): mixed {
+  if (resolved.error == null) {
+    return undefined;
+  }
+  return match (resolved.error) {
+    {kind: "thrown", error: const error} => error,
+    {kind: "unauthorized"} => undefined,
+    {kind: "forbidden"} => undefined,
+  };
+}