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

package/internal/stream.js

@@ -667,6 +667,23 @@ export type RenderOptions = {|
    * [`interleaved`], which says where it may and may not go.
    */
   readonly payload?: ReadableStream<Uint8Array>,
+  /**
+   * This response's Content-Security-Policy nonce, or absent for none.
+   *
+   * Absent is what every render had before nonces existed and what every
+   * render still has in a project that has not asked for one, so a document
+   * written without it is byte-for-byte the document uf has always written.
+   *
+   * Present, it reaches three places, and it has to reach all three or the
+   * page is broken rather than merely unprotected: React's own option, which
+   * nonces every inline script React emits — the runtime that reveals a
+   * `<Suspense>` boundary, and the bootstrap; `shell.open`/`shell.body`, which
+   * carry the client entry; and the payload chunk elements, which
+   * [`interleaved`] writes as text.
+   *
+   * `prerenderDocument` is deliberately never given one. See its own paragraph.
+   */
+  readonly nonce?: string | null,
 |};
 
 /**
@@ -706,6 +723,7 @@ export function renderDocument(node: React.Node, options: RenderOptions): Promis
                 withPayload(
                   assembled(queue.chunks(), options.shell, options.transformHead),
                   options.payload,
+                  options.nonce,
                 ),
                 options.onStream,
               ),
@@ -717,6 +735,11 @@ export function renderDocument(node: React.Node, options: RenderOptions): Promis
           reject(error);
         },
         onError: options.onError,
+        // Every inline script React writes for this document, from one option:
+        // the streaming runtime that reveals a boundary and patches a segment,
+        // and the bootstrap. uf nonces the scripts it writes itself; these are
+        // React's, and there is no other way to reach them.
+        nonce: options.nonce ?? undefined,
       });
       return;
     }
@@ -744,6 +767,7 @@ type ReadableStreamRenderer = (
   settings: {|
     readonly onError: (error: mixed) => void,
     readonly signal: AbortSignal,
+    readonly nonce?: string,
   |},
 ) => Promise<ByteSource>;
 
@@ -769,20 +793,24 @@ export function renderWithReadableStream(
   options: RenderOptions,
 ): Promise<DocumentBody> {
   const controller = new AbortController();
-  return render(node, { onError: options.onError, signal: controller.signal }).then(
-    (stream: ByteSource) =>
-      bodyOf(
-        outgoing(
-          withPayload(
-            assembled(decoded(stream), options.shell, options.transformHead),
-            options.payload,
-          ),
-          options.onStream,
+  return render(node, {
+    onError: options.onError,
+    signal: controller.signal,
+    nonce: options.nonce ?? undefined,
+  }).then((stream: ByteSource) =>
+    bodyOf(
+      outgoing(
+        withPayload(
+          assembled(decoded(stream), options.shell, options.transformHead),
+          options.payload,
+          options.nonce,
         ),
-        () => {
-          controller.abort();
-        },
+        options.onStream,
       ),
+      () => {
+        controller.abort();
+      },
+    ),
   );
 }
 
@@ -843,15 +871,16 @@ export async function prerenderDocument(node: React.Node, options: RenderOptions
 function withPayload(
   chunks: AsyncGenerator<string, void, void>,
   payload: ?ReadableStream<Uint8Array>,
+  nonce?: string | null,
 ): AsyncGenerator<string, void, void> {
-  return payload == null ? chunks : interleaved(chunks, payload);
+  return payload == null ? chunks : interleaved(chunks, payload, nonce);
 }
 
 /**
  * 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.
+ * Four 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
@@ -862,9 +891,20 @@ function withPayload(
  * **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.
+ * behind the markup it hydrates. Each HTML chunk that ends between elements is
+ * followed by whatever payload is waiting, and a payload that arrives while the
+ * HTML is idle there is written then, without a chunk of HTML to follow.
+ *
+ * **Only between elements.** React hands its HTML on through a fixed-size
+ * buffer, so a chunk can end anywhere: inside a tag, an attribute's value, a
+ * comment, a character reference or an inline `<script>`. A payload element
+ * written after such a chunk is not an element. It is part of the attribute,
+ * the comment or the text it landed in, the browser never reads it, and React's
+ * client closes the payload with rows missing, which is the "Connection closed"
+ * a page reports instead of hydrating. So a waiting payload goes out only where
+ * the HTML written so far ends between elements, which [`advanced`] follows
+ * from chunk to chunk, and otherwise waits for the HTML that finishes what is
+ * open.
  *
  * **`</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
@@ -881,8 +921,9 @@ function withPayload(
 async function* interleaved(
   chunks: AsyncGenerator<string, void, void>,
   payload: ReadableStream<Uint8Array>,
+  nonce?: string | null,
 ): AsyncGenerator<string, void, void> {
-  const encoder = createChunkEncoder();
+  const encoder = createChunkEncoder(nonce);
   const reader = payload.getReader();
   let written = "";
   let ended = false;
@@ -917,12 +958,13 @@ async function* interleaved(
     }
   })();
 
-  let opened = false;
+  // Nothing written yet, and nothing may go before the head.
+  let boundary: Boundary = NOTHING_WRITTEN;
   let closing = "";
   try {
     let next = chunks.next();
     while (true) {
-      if (opened && written !== "") {
+      if (boundary.safe && written !== "") {
         const out = written;
         written = "";
         yield out;
@@ -945,8 +987,8 @@ async function* interleaved(
       }
       if (text !== "") {
         yield text;
+        boundary = advanced(boundary, text);
       }
-      opened = true;
       next = chunks.next();
     }
     while (!ended || written !== "") {
@@ -972,6 +1014,54 @@ async function* interleaved(
   }
 }
 
+/** Where the HTML written so far leaves the next payload element. */
+type Boundary = {|
+  /** Whether a payload element may be written now. */
+  readonly safe: boolean,
+  /** The `script` or `style` element the HTML is inside, if it is inside one. */
+  readonly rawText: string | null,
+  /** A tag, or a comment, the HTML has started and not yet finished. */
+  readonly open: string,
+|};
+
+const NOTHING_WRITTEN: Boundary = { safe: false, rawText: null, open: "" };
+
+/**
+ * `boundary`, once `html` has been written after it.
+ *
+ * A payload element may follow HTML that ends with a `>` outside a `<script>`
+ * and a `<style>`. The test can be that short because React wrote the HTML: it
+ * escapes `<` and `>` in text and in attribute values, so a `>` it wrote closes
+ * a tag or a comment, and HTML that ends any other way ends inside one, or
+ * inside a character reference or a run of text. What React does not escape is
+ * the content of an inline script or stylesheet, where a `>` is code, so an
+ * opening `<script>` or `<style>` is followed to its closing tag. A tag split
+ * across two chunks is carried in `open` and read whole with the next one.
+ */
+function advanced(boundary: Boundary, html: string): Boundary {
+  const text = boundary.open + html;
+  let rawText = boundary.rawText;
+  const tags = /<(\/?)(script|style)(?=[\s/>])[^>]*>/gi;
+  let tag = tags.exec(text);
+  while (tag != null) {
+    const name = tag[2].toLowerCase();
+    if (tag[1] === "/") {
+      if (rawText === name) {
+        rawText = null;
+      }
+    } else if (rawText == null) {
+      rawText = name;
+    }
+    tag = tags.exec(text);
+  }
+  const start = text.lastIndexOf("<");
+  return {
+    safe: rawText == null && text.endsWith(">"),
+    rawText,
+    open: start > text.lastIndexOf(">") ? text.slice(start) : "",
+  };
+}
+
 /**
  * The prelude of a static prerender, whichever stream this build produced.
  *

package/middleware.js

@@ -27,10 +27,38 @@
 // that could only observe would not be able to reject, and one that had to
 // answer could not be a logger.
 //
-// There is no `next()` and no way to rewrite the request. Rewriting needs a
-// spelling — a returned `Request`, or a `next(request)` argument — and picking
-// one badly is harder to undo than not having it, so it is not spelled here
-// yet. What exists answers or continues, and says so.
+// There is no `next()`. A third answer is `rewrite(destination)`: serve another
+// route of this application at the address the visitor asked for.
+//
+//   // app/$middleware.js
+//   import { rewrite } from "@uniflowed/router/middleware";
+//
+//   export default function middleware(request: Request) {
+//     if (cookies().get("beta") != null) return rewrite("/beta" + new URL(request.url).pathname);
+//   }
+//
+// A returned value rather than a returned `Request`, which was the other
+// spelling on the table. A `Request` could change the method and the headers
+// too, and `headers()` reads the request the host began — so a middleware that
+// added a header would have handed the page one set of headers and `headers()`
+// another. A rewrite changes the path, the query when it names one, and
+// nothing else.
+//
+// # A rewrite runs the destination's middleware
+//
+// The chain starts again from the root over the middleware that has not run
+// yet, against the new path. So a rewrite into `/admin` passes the guard on
+// `/admin` exactly as a request for it would, and is never an unguarded way to
+// a guarded page; a middleware that already ran for this request does not run
+// a second time, which is also what makes the loop finite.
+//
+// # A payload request is its document
+//
+// A browser navigating a React Server Components application asks for
+// `/pricing/__uf.flight` rather than `/pricing`. The chain is matched against,
+// and every middleware is handed, the document's URL — so the check a
+// middleware writes against `/pricing` holds for a client navigation too, and
+// a rewrite of the document becomes a rewrite of its payload.
 //
 // # The request it runs inside
 //
@@ -68,6 +96,7 @@
 // `routesModuleSource` keeps the middleware table in an export the client
 // never imports, for the same reason it does that with route handlers.
 
+import { documentPathOf, flightUrl } from "./internal/flight.js";
 import { requireRequest } from "./internal/request.js";
 import type { RouteParams } from "./internal/runtime.js";
 
@@ -79,11 +108,39 @@ export type MiddlewareContext = {|
   readonly searchParams: URLSearchParams,
 |};
 
+/**
+ * What a middleware returns to serve another route at the requested address.
+ *
+ * Built by [`rewrite`] and read by the runner; a class so that the runner can
+ * tell it from a `Response` without trusting the shape of an object.
+ */
+export class Rewrite {
+  readonly destination: string;
+
+  constructor(destination: string) {
+    this.destination = destination;
+  }
+}
+
+/**
+ * Serve `destination` — a path of this application — in place of the path the
+ * request named.
+ *
+ * Relative to the request, so `"/beta/pricing"` and `"../pricing"` both work.
+ * A destination that names no query keeps the request's; one that names a
+ * query replaces it. Another origin is refused when the middleware returns it:
+ * sending a visitor elsewhere is `Response.redirect`, and proxying to another
+ * server is a route handler that fetches.
+ */
+export function rewrite(destination: string | URL): Rewrite {
+  return new Rewrite(typeof destination === "string" ? destination : destination.href);
+}
+
 /** One middleware function. */
 export type Middleware = (
   request: Request,
   context: MiddlewareContext,
-) => Response | void | Promise<Response | void>;
+) => Response | Rewrite | void | Promise<Response | Rewrite | void>;
 
 /** A middleware module, as the generated table loads it. */
 export type MiddlewareModule = { readonly [name: string]: mixed };
@@ -100,7 +157,10 @@ export type MiddlewareRecord = {|
  * Build the middleware runner for one application.
  *
  * Returns `null` when every middleware on the path declined, which is the
- * caller's signal to carry on to the handler or the page.
+ * caller's signal to carry on to the handler or the page. Returns a `Request`
+ * when one of them rewrote: the same request at the destination, which the
+ * caller carries on with instead — and which has already been past the
+ * destination's middleware.
  *
  * The runner is called once per request, above both the dispatcher and the
  * renderer, rather than from inside each of them. Putting the call inside
@@ -112,7 +172,7 @@ export type MiddlewareRecord = {|
  */
 export function createMiddlewareRunner(options: {|
   readonly middleware: $ReadOnlyArray<MiddlewareRecord>,
-|}): (request: Request) => Promise<Response | null> {
+|}): (request: Request) => Promise<Response | Request | null> {
   // Root first, so an application-wide check runs before the one that guards a
   // section of it. A shorter path is always an ancestor of a longer one that
   // also matched, so segment count is the whole of the ordering.
@@ -120,7 +180,7 @@ export function createMiddlewareRunner(options: {|
     (a, b) => segmentsOf(a.path).length - segmentsOf(b.path).length,
   );
 
-  return async function runMiddleware(request: Request): Promise<Response | null> {
+  return async function runMiddleware(request: Request): Promise<Response | Request | null> {
     // Checked rather than assumed, and checked before the table so that a host
     // is caught on its first request whether or not this project happens to
     // have a middleware. `createApplicationHandler` makes the same argument
@@ -138,13 +198,26 @@ export function createMiddlewareRunner(options: {|
       return null;
     }
 
-    const url = new URL(request.url);
+    const arrived = new URL(request.url);
+    const document = documentPathOf(arrived.pathname);
+    // The URL the chain is matched against and every middleware is handed: the
+    // document's, for a payload request. See "A payload request is its
+    // document" above.
+    let url = document == null ? arrived : withPathname(arrived, document);
+    let seen = document == null ? request : requestAt(request, url);
+    let rewritten = false;
+    const ran: Set<MiddlewareRecord> = new Set();
 
-    for (const record of table) {
+    for (let index = 0; index < table.length; index += 1) {
+      const record = table[index];
+      if (ran.has(record)) {
+        continue;
+      }
       const params = matchPrefix(record.path, url.pathname);
       if (params == null) {
         continue;
       }
+      ran.add(record);
 
       const middleware = pick(await record.load(), record.file);
       // In the host's context, not one of this module's own. Two middleware on
@@ -152,16 +225,71 @@ export function createMiddlewareRunner(options: {|
       // underneath them: `draftMode().isEnabled` is one answer for the whole
       // request, and every `after()` on the request lands in one ordered list
       // that the host drains once, after the response has gone.
-      const result = await middleware(request, { params, searchParams: url.searchParams });
-      if (result != null) {
-        return result;
+      const result = await middleware(seen, { params, searchParams: url.searchParams });
+      if (result == null) {
+        continue;
+      }
+      if (result instanceof Rewrite) {
+        url = destinationOf(result.destination, url, record.file);
+        seen = requestAt(seen, url);
+        rewritten = true;
+        // From the root again, over what has not run: the destination's guards
+        // are owed their say, and the ones that already had it are not asked
+        // twice.
+        index = -1;
+        continue;
       }
+      return result;
     }
 
-    return null;
+    if (!rewritten) {
+      return null;
+    }
+    return document == null
+      ? seen
+      : requestAt(seen, new URL(flightUrl(url.pathname + url.search), url));
   };
 }
 
+/**
+ * Where a rewrite goes, resolved against the URL the middleware was handed.
+ *
+ * Refused by name when it leaves the origin, because the one thing a rewrite
+ * promises is that this application answers.
+ */
+function destinationOf(destination: string, base: URL, file: string): URL {
+  const next = new URL(destination, base);
+  if (next.origin !== base.origin) {
+    throw new Error(
+      `${file} rewrote ${base.pathname} to ${destination}, which is another origin. A rewrite ` +
+        "serves another route of this application: answer with `Response.redirect` to send the " +
+        "visitor elsewhere, or fetch the other server from a route handler.",
+    );
+  }
+  if (!destination.includes("?")) {
+    next.search = base.search;
+  }
+  next.hash = "";
+  return next;
+}
+
+function withPathname(url: URL, pathname: string): URL {
+  const next = new URL(url.href);
+  next.pathname = pathname;
+  return next;
+}
+
+/**
+ * `request` at another URL: same method, headers, signal and body.
+ *
+ * A `Request` is a valid `RequestInit`, so a streamed body is handed on rather
+ * than read.
+ */
+function requestAt(request: Request, url: URL): Request {
+  // $FlowFixMe[incompatible-call] - a `Request` is read as the `RequestInit` it satisfies.
+  return new Request(url.href, request);
+}
+
 /**
  * The function a middleware module exports.
  *
@@ -171,6 +299,8 @@ export function createMiddlewareRunner(options: {|
  * ignored is the bug this whole module exists to stop happening.
  */
 function pick(module: MiddlewareModule, file: string): Middleware {
+  // `rewrite` is an export a middleware module may well import, and is never
+  // the middleware itself.
   const exported = typeof module.default === "function" ? module.default : module.middleware;
   if (typeof exported !== "function") {
     throw new Error(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/router",
-  "version": "0.0.0-alpha.35",
+  "version": "0.0.0-alpha.39",
   "description": "The file-system router for Flow React applications: matching, layouts, loaders, navigation, server rendering and hydration.",
   "type": "module",
   "license": "MIT",
@@ -19,6 +19,8 @@
     "./client": "./client.js",
     "./native": "./native.js",
     "./rsc": "./rsc.js",
+    "./rsc/client": "./rsc-client.js",
+    "./rsc/ssr": "./rsc-ssr.js",
     "./server": "./server.js",
     "./routing": "./routing.js",
     "./package.json": "./package.json",
@@ -34,23 +36,28 @@
     "middleware.js",
     "native.js",
     "routing.js",
+    "rsc-client.js",
+    "rsc-ssr.js",
     "rsc.js",
     "server-components.js",
     "server.js",
     "!*.test.js"
   ],
   "peerDependencies": {
-    "react": ">=19.3.0",
-    "react-dom": ">=19.3.0",
+    "react": ">=19.2.3",
+    "react-dom": ">=19.2.3",
     "react-server-dom-parcel": ">=19.3.0"
   },
   "peerDependenciesMeta": {
     "react-dom": {
       "optional": true
+    },
+    "react-server-dom-parcel": {
+      "optional": true
     }
   },
   "dependencies": {
-    "@uniflowed/hooks": "0.0.0-alpha.35",
-    "@uniflowed/server": "0.0.0-alpha.35"
+    "@uniflowed/hooks": "0.0.0-alpha.39",
+    "@uniflowed/server": "0.0.0-alpha.39"
   }
 }

package/rsc-client.js

@@ -0,0 +1,120 @@
+// @flow
+//
+// `@uniflowed/router/rsc/client`: starting, in the browser, an application that
+// React Server Components rendered.
+//
+// `virtual:uf/client` imports this entry when routes render as Server
+// Components, which is the default. It imports `@uniflowed/router/client` when
+// they render from their modules (`app.rsc: false`) or into an empty shell
+// (`app.rendering.modes: ["csr"]`). This is an entry of its own because it loads
+// React's Flight client, `react-server-dom-parcel`. That package is an optional
+// peer and needs React 19.3, while the rest of the router runs on the React
+// 19.2.3 that Expo SDK 57 and React Native 0.87 ship (ubugeeei-prod/uf#992). A
+// bundler resolves every import in the graph it is given, whether or not
+// anything calls it, so a browser bundle that renders no Server Component
+// leaves the package out only if nothing it imports names it.
+// `crates/uf_lib/tests/package_surface.rs` holds the router to that.
+//
+// The same reason keeps the payload fetch out of `./internal/runtime.js`.
+// Navigation there serves every application, so `hydrateFlight` hands it the
+// fetch before the first render.
+
+import * as React from "react";
+import { StrictMode, startTransition } from "react";
+import { hydrateRoot } from "react-dom/client";
+
+import { type TrailingSlash, applicationPathOf } from "./internal/base-path.js";
+import { ROOT_ID } from "./internal/document.js";
+import {
+  fetchFlight,
+  installBrowserModules,
+  readDocumentPayload,
+} from "./internal/flight-browser.js";
+import { domObserver } from "./internal/payload-rows.js";
+import { prepareDocumentForHydration } from "./internal/prepare-document.js";
+import { requireServerComponentsReact } from "./internal/react-version.js";
+import {
+  type AppProps,
+  type Navigation,
+  installFlightFetch,
+  installNavigation,
+  installRouting,
+  installStaleTime,
+} from "./internal/runtime.js";
+
+/**
+ * Hydrate a document React Server Components rendered.
+ *
+ * `hydrate` in `./client.js` resolves the route from its modules and renders it
+ * again over the server's markup. This one resolves nothing and imports no route
+ * module: the document carries the Flight payload its tree was rendered from,
+ * React's own client reads it, and the tree the browser hydrates is the tree the
+ * server rendered — a Server Component is markup and a reference, and a client
+ * component is the one kind of module this page loads. See
+ * ubugeeei-prod/uf#519.
+ *
+ * The payload is read while the document is still arriving. Row 0 is in the
+ * shell, so hydration starts as soon as the module script runs, and every row
+ * after it lands in a later chunk that the reader picks up as it is parsed — so
+ * a boundary the server completes after hydration began resolves then, with no
+ * second request.
+ *
+ * Everything else is `hydrate`'s, for the reasons written there: the navigation
+ * mode is installed before the first render, the development hydration report
+ * captures the server's markup before React repairs it, and Strict Mode wraps
+ * the root.
+ *
+ * On a React older than 19.3 it refuses before it touches the page, naming the
+ * version it found; see `./internal/react-version.js`.
+ */
+export async function hydrateFlight(options: {|
+  readonly App: React.ComponentType<AppProps>,
+  readonly strictMode?: boolean,
+  readonly navigation?: Navigation,
+  readonly basePath?: string,
+  readonly trailingSlash?: TrailingSlash,
+  readonly staleTime?: number,
+|}): Promise<void> {
+  requireServerComponentsReact("@uniflowed/router/rsc/client");
+  installNavigation(options.navigation ?? "client");
+  installRouting({ basePath: options.basePath, trailingSlash: options.trailingSlash });
+  installStaleTime(options.staleTime ?? 0);
+  installFlightFetch(fetchFlight);
+  installBrowserModules();
+  const flight = readDocumentPayload(document, domObserver(document));
+
+  // The route table has no base path in it, and the address bar does.
+  const url =
+    (applicationPathOf(window.location.pathname) ?? window.location.pathname) +
+    window.location.search;
+  const { App } = options;
+  const container = document.getElementById(ROOT_ID) ?? document;
+  prepareDocumentForHydration(document);
+
+  let recovery = null;
+  let restoreDevHead = null;
+  if (import.meta.hot != null) {
+    const { captureServerMarkup, hydrationErrorHandler, prepareDevHeadForHydration } =
+      await import("./internal/hydration.js");
+    restoreDevHead = prepareDevHeadForHydration(document);
+    recovery = hydrationErrorHandler(container, captureServerMarkup(container), document);
+  }
+
+  const tree = <App url={url} flight={flight} />;
+
+  startTransition(() => {
+    hydrateRoot(
+      container,
+      options.strictMode === true ? <StrictMode>{tree}</StrictMode> : tree,
+      recovery == null ? undefined : { onRecoverableError: recovery },
+    );
+    if (restoreDevHead != null) {
+      setTimeout(restoreDevHead, 250);
+    }
+  });
+
+  if (import.meta.hot != null) {
+    const { reportDevtools } = await import("./internal/devtools.js");
+    reportDevtools(window);
+  }
+}