npm - @uniflowed/router - Versions diffs - 0.0.0-alpha.11 → 0.0.0-alpha.13 - Mend

@uniflowed/router 0.0.0-alpha.11 → 0.0.0-alpha.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/action.js +198 -0
package/client.js +35 -1
package/handler.js +65 -2
package/index.js +10 -1
package/internal/action-endpoint.js +408 -0
package/internal/action-wire.js +382 -0
package/internal/hydration.js +861 -0
package/internal/runtime.js +1037 -70
package/internal/stream.js +122 -12
package/package.json +4 -2
package/server.js +68 -39

package/internal/stream.js CHANGED Viewed

@@ -125,8 +125,13 @@ export type DocumentShell = {|
    * `</head>` React writes.
    */
   readonly head: string,
-  /** Everything before the markup of an app that renders no document. */
+  /**
+   * For an app that renders no document: everything up to the point uf's own
+   * head can still take tags — so it ends *inside* an open `<head>`.
+   */
   readonly open: string,
+  /** The rest of that head, and everything up to the app's markup. */
+  readonly body: string,
   /** Everything after it. */
   readonly close: string,
 |};
@@ -293,6 +298,11 @@ function queueDestination(queue: ChunkQueue): NodeDestination {
  * React writes a document with no head at all — an app whose root layout is
  * `<html><body>` — the tags go in a head of uf's own, inserted after the
  * opening tag, which is what the browser would have synthesized anyway.
+ *
+ * The shell case waits for the end of the run of hoistable elements React
+ * opened with, because that is where *its* tags go — see [`hoisted`]. Both
+ * waits are bounded by the head, and both are the same idea: the head goes out
+ * once, and everything that belongs in it has to be in hand by then.
  */
 async function* assembled(
   chunks: AsyncGenerator<string, void, void>,
@@ -302,7 +312,7 @@ async function* assembled(
   let shape = "unknown";
   for await (const chunk of chunks) {
-    if (shape === "document-open" || shape === "shell") {
+    if (shape === "document-open" || shape === "shell-open") {
       yield chunk;
       continue;
     }
@@ -312,11 +322,16 @@ async function* assembled(
       if (shape === "unknown") {
         continue;
       }
-      if (shape === "shell") {
-        yield shell.open + held;
-        held = "";
+    }
+    if (shape === "shell") {
+      const split = hoisted(held);
+      if (!split.complete) {
         continue;
       }
+      shape = "shell-open";
+      yield shell.open + split.head + shell.body + split.rest;
+      held = "";
+      continue;
     }
     // A document, and the tags go where its head closes.
     const close = held.indexOf("</head>");
@@ -335,17 +350,21 @@ async function* assembled(
     }
   }
-  // The render ended before the decision could be made, or before the head it
-  // opened was closed: an empty document, or one with neither `</head>` nor
-  // `<body>` in it. There is nothing left to wait for either way.
+  // The render ended before the decision could be made, or before what was
+  // being waited for arrived: an empty document, one with neither `</head>` nor
+  // `<body>` in it, or a shell that is hoistable elements all the way down.
+  // There is nothing left to wait for in any of them.
   if (shape === "document") {
     yield ufDoctype(held + shell.head);
     shape = "document-open";
-  } else if (shape === "unknown") {
-    shape = "shell";
-    yield shell.open + held;
+  } else if (shape === "shell" || shape === "unknown") {
+    // `complete` is not consulted: nothing more is coming, so a run that was
+    // still open is over and whatever was left of it is markup like any other.
+    const split = hoisted(held);
+    shape = "shell-open";
+    yield shell.open + split.head + shell.body + split.rest;
   }
-  if (shape === "shell") {
+  if (shape === "shell-open") {
     yield shell.close;
   } else {
     // The newline `assemble` ended a document with, kept: `uf build` writes
@@ -355,6 +374,97 @@ async function* assembled(
   }
 }
+/**
+ * The head elements React opened the app's markup with, split from the rest.
+ *
+ * `complete` is false while the buffer might still be in the middle of one — a
+ * chunk that ends inside `<meta cont`, or after a `<link>` and before whatever
+ * follows it. Deciding on an incomplete buffer would be a classification that
+ * depends on where React split its output, which is the bug `documentShape`
+ * above is written the way it is to avoid. The split is filled in either way,
+ * because the caller that has run out of chunks has nothing left to wait for
+ * and wants it.
+ *
+ * # Why a leading run rather than the whole document
+ *
+ * React hoists a `<title>`, a `<meta>` and a `<link>` into the `<head>` of a
+ * document *it* rendered. uf's shell is not one — React is handed the app, not
+ * the document — so with the shell every one of those landed in the body, and
+ * `<link rel="canonical">` in a body is a canonical link Google does not read.
+ * The fix is for uf to do the hoisting into the head it wrote itself.
+ *
+ * A leading run is what can be hoisted without holding the document. `RouteView`
+ * renders the route's metadata first, before the layouts and the page, so the
+ * run is exactly that metadata and the wait ends at the first byte of the
+ * application's own markup. Scanning further would mean buffering an arbitrary
+ * amount of a document to find a `<meta>` that might be at the end of it, which
+ * is streaming in shape and buffering in fact — the same trade this module
+ * refuses in `ChunkQueue`. So a tag a component renders further in stays where
+ * it is, and on a client React will hoist it into `document.head` itself.
+ *
+ * # Reading React's markup with a regular expression
+ *
+ * Which is only safe because it is React's. React escapes `>` in an attribute
+ * value and `<` in text, so the first `>` after an opening tag ends it and the
+ * first `</title>` ends a title — neither can appear inside one. This function
+ * is not an HTML parser and must never be handed markup from anywhere else.
+ */
+function hoisted(held: string): HoistedHead {
+  let index = 0;
+  while (index < held.length) {
+    const rest = held.slice(index);
+    const split = { head: held.slice(0, index), rest, complete: false };
+    const open = rest.match(/^<(title|meta|link)(?=[\s/>])/i);
+    if (open == null) {
+      // Not a hoistable element, or not yet enough bytes to say it is not one.
+      return { ...split, complete: !couldOpenHoistable(rest) };
+    }
+    const close = held.indexOf(">", index);
+    if (close === -1) {
+      return split;
+    }
+    if (open[1].toLowerCase() !== "title") {
+      index = close + 1;
+      continue;
+    }
+    const end = held.indexOf("</title>", close);
+    if (end === -1) {
+      return split;
+    }
+    index = end + "</title>".length;
+  }
+  // Every byte so far is a complete hoistable element, and the next one may
+  // still be on its way — the case a document that is metadata and nothing else
+  // ends in, and the reason the loop is bounded by the buffer rather than by
+  // `true`: a `while (true)` here is a function the checker reads as returning
+  // `void` on a path it cannot see is unreachable.
+  return { head: held, rest: "", complete: false };
+}
+/** What [`hoisted`] found, and whether more bytes could still change it. */
+type HoistedHead = {|
+  /** The hoistable elements the markup opened with. */
+  readonly head: string,
+  /** Everything after them. */
+  readonly rest: string,
+  /** Whether the run is known to have ended. */
+  readonly complete: boolean,
+|};
+/**
+ * Whether `rest` could still turn into a hoistable element once more bytes
+ * arrive.
+ *
+ * True for `"<"` and for every proper prefix of `<title`, `<meta` and `<link` —
+ * the states a chunk boundary can leave the buffer in. False for `<main`, and
+ * false for `<titlebar>`, which is somebody's component and not a title however
+ * much of it has arrived.
+ */
+function couldOpenHoistable(rest: string): boolean {
+  const text = rest.toLowerCase();
+  return ["<title", "<meta", "<link"].some((tag) => tag.startsWith(text));
+}
 /**
  * uf's spelling of the doctype, in place of whichever one React wrote.
  *

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/router",
-  "version": "0.0.0-alpha.11",
+  "version": "0.0.0-alpha.13",
   "description": "The file-system router for Flow React applications: matching, layouts, loaders, navigation, server rendering and hydration.",
   "type": "module",
   "license": "MIT",
@@ -12,6 +12,7 @@
   },
   "exports": {
     ".": "./index.js",
+    "./action": "./action.js",
     "./client": "./client.js",
     "./server": "./server.js",
     "./package.json": "./package.json",
@@ -19,6 +20,7 @@
     "./middleware": "./middleware.js"
   },
   "files": [
+    "action.js",
     "client.js",
     "handler.js",
     "index.js",
@@ -31,6 +33,6 @@
     "react-dom": ">=19"
   },
   "dependencies": {
-    "@uniflowed/server": "0.0.0-alpha.11"
+    "@uniflowed/server": "0.0.0-alpha.13"
   }
 }

package/server.js CHANGED Viewed

@@ -23,7 +23,8 @@
 // `internal/stream.js` holds the mechanics and says which React renderer serves
 // which.
-import { DATA_ID, ROOT_ID } from "./internal/document.js";
+import { noteRoute } from "@uniflowed/server/host";
+import { ROOT_ID } from "./internal/document.js";
 import * as React from "react";
 import {
@@ -148,6 +149,23 @@ export type {
 } from "./middleware.js";
 export { createMiddlewareRunner } from "./middleware.js";
+/**
+ * The endpoint a `"use server"` export is dialled at.
+ *
+ * Here rather than beside `@uniflowed/router/action`, which is the browser's
+ * half of the same feature and must stay reachable from a client component:
+ * this one refuses outside a request, so it imports `internal/request.js` and
+ * through it `node:async_hooks`. The two halves share `internal/action-wire.js`
+ * and nothing else, which is what keeps one grammar rather than two.
+ *
+ * `virtual:uf/server` calls it with the table `virtual:uf/actions` built from
+ * the RSC manifest, and every host runs it between the middleware and the
+ * route handlers. See `internal/action-endpoint.js` for what the endpoint
+ * refuses and why.
+ */
+export type { ActionModule, ActionRecord } from "./internal/action-endpoint.js";
+export { createActionDispatcher } from "./internal/action-endpoint.js";
 /**
  * What a URL turned out to be: a route to render, or a redirect to answer with.
  *
@@ -201,13 +219,31 @@ export function createRenderer(options: {|
    * The route to render, or the redirect to answer with instead.
    *
    * Shared by both entry points, because *what* a URL resolves to has nothing
-   * to do with how the answer is delivered. Returning the redirect rather than
-   * throwing it keeps the two callers from each having to remember that a
-   * redirect is the one thing `resolveMatch` lets out.
+   * to do with how the answer is delivered — with one exception, which is
+   * `defer` and is the exception that proves it. Whether the router may hand
+   * the page a loader that has not answered yet *is* a question about delivery:
+   * only a renderer with a `<Suspense>` fallback to send first has anywhere to
+   * put the wait. `render` says yes and `prerender` says no; see
+   * `ResolveOptions.defer` and ubugeeei-prod/uf#373.
+   *
+   * Returning the redirect rather than throwing it keeps the two callers from
+   * each having to remember that a redirect is the one thing `resolveMatch`
+   * lets out.
+   *
+   * `onMatch` is what makes the request's log line say `/orders/:id` rather
+   * than `/orders/8813`. It is handed to `resolveMatch` rather than read off
+   * the route this returns, because a loader runs *inside* that call and a
+   * loader has things to log: recording the route afterwards would leave every
+   * line the loader wrote claiming to belong to no route at all. `noteRoute`
+   * does nothing outside a request, which is what lets `prerender` — a build,
+   * with no request anywhere — call the same function.
    */
-  async function resolve(url: string): Promise<Resolution> {
+  async function resolve(url: string, defer: boolean): Promise<Resolution> {
     try {
-      return { kind: "route", route: await resolveMatch(table, url) };
+      return {
+        kind: "route",
+        route: await resolveMatch(table, url, { defer, onMatch: noteRoute }),
+      };
     } catch (error) {
       if (error instanceof RedirectError) {
         return { kind: "redirect", error };
@@ -221,7 +257,7 @@ export function createRenderer(options: {|
     assets: RenderAssets,
     settings?: RenderOptions,
   ): Promise<RenderResult> {
-    const resolution = await resolve(url);
+    const resolution = await resolve(url, true);
     if (resolution.kind === "redirect") {
       return redirectDocument(resolution.error);
     }
@@ -247,7 +283,7 @@ export function createRenderer(options: {|
     let body: DocumentBody;
     try {
       body = await renderDocument(<App url={url} initial={resolved} />, {
-        shell: shellFor(resolved, assets),
+        shell: shellFor(assets),
         onError,
       });
       streaming = true;
@@ -277,7 +313,7 @@ export function createRenderer(options: {|
       // where somebody can fix it.
       streaming = true;
       body = await renderDocument(<App url={url} initial={resolved} />, {
-        shell: shellFor(resolved, assets),
+        shell: shellFor(assets),
         onError,
       });
     }
@@ -296,7 +332,7 @@ export function createRenderer(options: {|
     assets: RenderAssets,
     settings?: RenderOptions,
   ): Promise<PrerenderResult> {
-    const resolution = await resolve(url);
+    const resolution = await resolve(url, false);
     if (resolution.kind === "redirect") {
       return redirectResult(redirectDocument(resolution.error));
     }
@@ -306,7 +342,7 @@ export function createRenderer(options: {|
     let html: string;
     try {
       html = await prerenderDocument(<App url={url} initial={resolved} />, {
-        shell: shellFor(resolved, assets),
+        shell: shellFor(assets),
         onError: report,
       });
     } catch (error) {
@@ -315,7 +351,7 @@ export function createRenderer(options: {|
       }
       resolved = await resolveFailure(table, url, error);
       html = await prerenderDocument(<App url={url} initial={resolved} />, {
-        shell: shellFor(resolved, assets),
+        shell: shellFor(assets),
         onError: report,
       });
     }
@@ -369,14 +405,29 @@ function redirectDocument(error: RedirectError): RenderResult {
  * `internal/stream.js` picks between them on the opening bytes React writes;
  * everything either shape is made of is here, so what a uf document contains is
  * still readable in one place.
+ *
+ * # Why the shell is three strings and not one
+ *
+ * Because uf's own `<head>` has to still be open when React's head tags arrive.
+ * React hoists a `<title>`, a `<meta>` and a `<link>` into the head it wrote
+ * itself, and here it wrote none — so with one string this shell closed its
+ * head before the app had rendered a byte, and every `og:` tag and the
+ * `<link rel="canonical">` landed in the body, where a crawler ignores them.
+ * `open` is uf's head up to that point, `body` is the rest of it and the
+ * wrapper, and what goes between them is whatever `assembled` lifts out of the
+ * app's own markup. See ubugeeei-prod/uf#547.
+ *
+ * That is also why no `<title>` is written here any more. It was, from
+ * `resolved.metadata.title` — the same string `Head` renders — so a document
+ * carried two of them, one in each place, and only one was where a browser
+ * looks. Hoisting the rendered one leaves the metadata with a single source.
  */
-function shellFor(resolved: ResolvedRoute, assets: RenderAssets): DocumentShell {
-  const head = headTags(assets) + dataScript(resolved.data);
-  const title =
-    resolved.metadata.title != null ? `<title>${escapeText(resolved.metadata.title)}</title>` : "";
+function shellFor(assets: RenderAssets): DocumentShell {
+  const head = headTags(assets);
   return {
     head,
-    open: `<!doctype html>\n<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">${title}${head}</head><body><div id="${ROOT_ID}">`,
+    open: `<!doctype html>\n<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">`,
+    body: `${head}</head><body><div id="${ROOT_ID}">`,
     close: `</div></body></html>\n`,
   };
 }
@@ -395,28 +446,6 @@ function headTags(assets: RenderAssets): string {
   return tags;
 }
-/**
- * The loader data, embedded for hydration.
- *
- * `<` is escaped inside the JSON so a string holding `</script>` cannot end
- * the element early, and the script's type keeps the browser from executing
- * it.
- */
-function dataScript(data: mixed): string {
-  if (data === undefined) {
-    return "";
-  }
-  const json = JSON.stringify(data)
-    .replace(/</g, "\\u003c")
-    .replace(/\u2028/g, "\\u2028")
-    .replace(/\u2029/g, "\\u2029");
-  return `<script id="${DATA_ID}" type="application/json">${json}</script>`;
-}
 function escapeAttribute(value: string): string {
   return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
 }
-function escapeText(value: string): string {
-  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-}