@uniflowed/router 0.0.0-alpha.9 → 0.1.0

package/server.js

@@ -18,23 +18,26 @@
 //
 // They were one function with `renderToString` behind it, which answered the
 // first question by giving up on it: nothing streamed, so nothing could
-// usefully suspend, so `_uf.loading.js` had nothing to be. Making the split
+// usefully suspend, so `$loading.js` had nothing to be. Making the split
 // explicit is the point of ubugeeei-prod/uf#254 rather than a side effect —
 // `internal/stream.js` holds the mechanics and says which React renderer serves
 // which.
 
-import { DATA_ID, ROOT_ID } from "./internal/document.js";
+import { currentNonce, noteRoute } from "@uniflowed/server/host";
+import { traceLoader } from "./internal/server-instrumentation.js";
+
 import * as React from "react";
 
 import {
   type DocumentBody,
-  type DocumentShell,
+  type PrerenderedShell,
   type WritableLike,
-  bodyOfText,
   prerenderDocument,
   renderDocument,
 } from "./internal/stream.js";
 
+export type { PrerenderedShell } from "./internal/stream.js";
+
 import {
   type AppProps,
   type ResolvedRoute,
@@ -45,11 +48,21 @@ import {
   resolveMatch,
 } from "./internal/runtime.js";
 
+import { type StreamDiagnostic, streamReporter } from "./internal/inspector.js";
+
+import { redirectDocument, redirectResult, shellFor } from "./internal/shell.js";
+
 /** Asset URLs to reference from the document. */
 export type RenderAssets = {|
   readonly scripts: $ReadOnlyArray<string>,
   readonly styles: $ReadOnlyArray<string>,
   readonly preloads: $ReadOnlyArray<string>,
+  /**
+   * The build the document belongs to, written into its head as
+   * `<meta name="uf:deployment">`. Absent under `uf dev`, where there is no
+   * other build to be skewed against. See `./internal/deployment.js`.
+   */
+  readonly deployment?: string,
 |};
 
 /**
@@ -98,6 +111,42 @@ export type PrerenderResult = {|
   readonly headers?: { readonly [string]: string },
   /** The exception this render fell back to its error boundary for; see [`RenderResult`]. */
   readonly error?: mixed,
+  /**
+   * The Flight payload the document was rendered from, for a document React
+   * Server Components rendered.
+   *
+   * `uf build` writes it beside the document as the route's payload file, so a
+   * browser that navigates to a prerendered route fetches a file rather than
+   * asking a server — which is what makes a static host able to serve client
+   * navigation at all. Absent for a document rendered from its modules.
+   */
+  readonly payload?: Uint8Array,
+  /**
+   * The page's static shell, when the prerender was partial and the page read
+   * the request inside a `<Suspense>` boundary.
+   *
+   * `html` is then the shell's markup and not a document to write at the
+   * page's URL: a server answers the page by sending the shell and rendering
+   * the holes per request, through [`Renderer`]'s `resume`. No payload comes
+   * with it, because the browser hydrates from the request's. Only a renderer
+   * for React Server Components writes one.
+   */
+  readonly shell?: PrerenderedShell,
+|};
+
+/**
+ * A route's payload, as a browser navigating to it is answered.
+ *
+ * `stream` is `null` for a redirect, whose `location` is already the target's
+ * payload URL when the target is on this origin: `fetch` follows it and lands
+ * on a payload.
+ */
+export type FlightResponse = {|
+  readonly status: number,
+  readonly headers: { readonly [string]: string },
+  readonly stream: ReadableStream<Uint8Array> | null,
+  /** The exception the route resolved to its error boundary for; see [`RenderResult`]. */
+  readonly error?: mixed,
 |};
 
 /** What a host may tell the renderer about one request. */
@@ -111,6 +160,76 @@ export type RenderOptions = {|
    * bytes. `uf dev` reports them in the terminal; a production host logs them.
    */
   readonly onError?: (error: mixed) => void,
+  /**
+   * Rewrite the document opening — the head and, when present, the body start
+   * tag — before it goes out.
+   *
+   * For `uf dev` and nothing else. Vite's `transformIndexHtml` injects
+   * `/@vite/client` and the refresh preamble and rewrites asset URLs, and it
+   * is a *whole document* hook, so the development server used to collect the
+   * page and transform it at the end. That made the one place a developer
+   * would notice streaming the one place it did not happen: a slow page showed
+   * nothing until it was finished, and `$loading.js` looked broken.
+   * See ubugeeei-prod/uf#374.
+   *
+   * A production host passes nothing here and streams as it always did.
+   *
+   * # What a plugin that injects into the body gets
+   *
+   * `transformIndexHtml` is a whole-document hook and this hands it only the
+   * parseable opening of the document. Measured against Vite 8.2.2, injecting
+   * all four positions into a whole document and into the streamed opening:
+   *
+   * | `injectTo`     | whole document      | streamed |
+   * | -------------- | ------------------- | -------- |
+   * | `head-prepend` | after `<head>`      | same     |
+   * | `head`         | before `</head>`    | same     |
+   * | `body-prepend` | after `<body>`      | same     |
+   * | `body`         | before `</body>`    | after `<body>`     |
+   *
+   * Nothing is dropped — every tag still reaches the document — but a `body`
+   * tag lands at the top of the body rather than after the content, because
+   * the content is deliberately not passed to the hook. That keeps Vite's
+   * parser away from chunk boundaries that may sit inside an attribute.
+   *
+   * uf's own injections are `head` and `head-prepend`, and Vite's client is
+   * head-injected, so this is about a third-party plugin.
+   * `packages/vite/dev-head-transform.test.js` pins the table above, so the day
+   * it changes is a failing test rather than a surprise.
+   */
+  readonly transformHead?: (html: string) => Promise<string>,
+  /**
+   * Told, in words, when a document streamed differently than it did last time.
+   *
+   * For `uf dev` and nothing else, like `transformHead` above. It answers the
+   * half of ubugeeei-prod/uf#520 that is about the wire — what arrived, in what
+   * order, and which part of the tree each chunk built — for the stream uf has
+   * today, which is a document whose Suspense boundaries resolve independently.
+   * `internal/inspector.js` is what it is and what it deliberately is not.
+   *
+   * A host that passes nothing here records nothing: no recorder is
+   * constructed, and the chunks a production stream yields are untouched.
+   *
+   * It is handed a message and its detail lines rather than the record they
+   * came from, because the caller is `@uniflowed/vite` — plain JavaScript, run
+   * by Vite before any Flow transform exists, which is why `DEVTOOLS_HOOK` and
+   * `DIAGNOSTIC_ENDPOINT` are spelled twice rather than imported. The
+   * vocabulary of the report belongs on this side of that line.
+   */
+  readonly onStream?: (diagnostic: StreamDiagnostic) => void,
+  /**
+   * For `prerender` only: whether a read of the request may be left for the
+   * request rather than fail the page.
+   *
+   * `uf build` passes it when `app.rendering.modes` allows `ppr` and the build
+   * leaves a server behind. A page that reads `cookies()`, `headers()` or
+   * `draftMode()` inside a `<Suspense>` boundary is then written as a static
+   * shell with that boundary as a hole — [`PrerenderResult`]'s `shell` — and a
+   * read outside every boundary still fails the page, naming what it read.
+   * The renderer for React Server Components honours it; a route rendered from
+   * its modules (`app.rsc: false`) is prerendered whole or not at all.
+   */
+  readonly partial?: boolean,
 |};
 
 /** The two ids the server writes and the client reads. */
@@ -121,13 +240,13 @@ export { DATA_ID, ROOT_ID } from "./internal/document.js";
  *
  * Re-exported rather than left to the host to import, and the reason is the
  * one thing about `@uniflowed/server` that is easy to get wrong: the request
- * lives in an `AsyncLocalStorage` belonging to *that module instance*. A host
- * that resolved `@uniflowed/server/host` for itself — from its own
- * `node_modules`, or from outside the bundle a build produced — would begin a
- * request in a second storage, and every `cookies()` in the application would
- * still be outside one, silently. Handing it out from here makes the copy the
- * host begins with the copy this module dispatches and renders with, because
- * it is the same import.
+ * store is shared by every copy of one *release* of that package, and no more.
+ * A host that resolved `@uniflowed/server/host` for itself — from its own
+ * `node_modules`, or from outside the bundle a build produced — may hold a
+ * different release, and would begin a request in a store the application
+ * never reads, so every `cookies()` in it would still be outside one, silently.
+ * Handing it out from here makes the copy the host begins with the copy this
+ * module dispatches and renders with, because it is the same import.
  *
  * `run` wraps everything that decides the response; `settle` is called once
  * the response has been *written*, which is a different line in every host.
@@ -148,6 +267,31 @@ export type {
 } from "./middleware.js";
 export { createMiddlewareRunner } from "./middleware.js";
 
+/**
+ * `app.router.basePath` and `trailingSlash`, for `virtual:uf/server` to install
+ * before the first render, and `basePath()` for a middleware or a route handler
+ * that builds an address itself. See `./internal/base-path.js`.
+ */
+export type { RoutingSettings, TrailingSlash } from "./internal/base-path.js";
+export { basePath, installRouting } from "./internal/base-path.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.
  *
@@ -160,15 +304,6 @@ type Resolution =
   | {| readonly kind: "route", readonly route: ResolvedRoute |}
   | {| readonly kind: "redirect", readonly error: RedirectError |};
 
-/** A redirect, as the finished document `prerender` answers with. */
-async function redirectResult(document: RenderResult): Promise<PrerenderResult> {
-  return {
-    status: document.status,
-    headers: document.headers,
-    html: await document.text(),
-  };
-}
-
 /** The two ways one app answers for a URL. */
 export type Renderer = {|
   readonly render: (
@@ -181,6 +316,28 @@ export type Renderer = {|
     assets: RenderAssets,
     options?: RenderOptions,
   ) => Promise<PrerenderResult>,
+  /**
+   * A route's payload, for a browser that is navigating rather than loading a
+   * document. Only a renderer for React Server Components has one.
+   */
+  readonly flight?: (
+    url: string,
+    options?: {|
+      readonly onError?: (error: mixed) => void,
+      readonly interceptedFrom?: string,
+    |},
+  ) => Promise<FlightResponse>,
+  /**
+   * A page `prerender` wrote as a static shell: the shell first, then its holes
+   * as this request renders them. Only a renderer for React Server Components
+   * has one, because only it writes a shell.
+   */
+  readonly resume?: (
+    url: string,
+    assets: RenderAssets,
+    shell: PrerenderedShell,
+    options?: RenderOptions,
+  ) => Promise<RenderResult>,
 |};
 
 export function createRenderer(options: {|
@@ -201,13 +358,35 @@ 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,
+          runLoader: traceLoader,
+        }),
+      };
     } catch (error) {
       if (error instanceof RedirectError) {
         return { kind: "redirect", error };
@@ -221,12 +400,22 @@ 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);
     }
     let resolved: ResolvedRoute = resolution.route;
     const report = settings?.onError ?? (() => {});
+    // Built once and shared by both renders below, so a page that threw its
+    // shell away and rendered its error boundary instead reports the stream the
+    // browser was actually sent rather than the one that was abandoned.
+    const send = settings?.onStream;
+    const onStream = send == null ? undefined : streamReporter(url, send);
+    // Read rather than minted: a project that has not asked for a nonce gets
+    // `null` and the document it has always had. Read once for both renders
+    // below, so the error document a failed shell falls back to carries the
+    // same nonce as the policy already on the response.
+    const nonce = currentNonce();
 
     // React reports an exception to `onError` *and*, if it was in the shell, to
     // `onShellError` — so forwarding both would tell the host about one failure
@@ -247,8 +436,11 @@ export function createRenderer(options: {|
     let body: DocumentBody;
     try {
       body = await renderDocument(<App url={url} initial={resolved} />, {
-        shell: shellFor(resolved, assets),
+        shell: shellFor(assets, nonce),
         onError,
+        transformHead: settings?.transformHead,
+        onStream,
+        nonce,
       });
       streaming = true;
       // Recovered before the shell was ready: a `<Suspense>` boundary whose
@@ -277,8 +469,11 @@ 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, nonce),
         onError,
+        transformHead: settings?.transformHead,
+        onStream,
+        nonce,
       });
     }
 
@@ -296,7 +491,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 +501,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 +510,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,
       });
     }
@@ -338,85 +533,38 @@ function renderFailure(resolved: ResolvedRoute): mixed {
   };
 }
 
-function redirectDocument(error: RedirectError): RenderResult {
-  const target = escapeAttribute(error.to);
-  // A document rather than an empty body, because a redirect is still an answer
-  // a browser may be shown; it goes through the same three methods as a
-  // rendered one so that a host has one shape to write, not two.
-  const body = bodyOfText(
-    `<!doctype html><html><head><meta charset="utf-8"><meta http-equiv="refresh" content="0; url=${target}"><title>Redirecting</title></head><body><a href="${target}">Redirecting…</a></body></html>\n`,
-  );
-  return {
-    status: error.permanent ? 308 : 307,
-    headers: { Location: error.to },
-    pipe: body.pipe,
-    stream: body.stream,
-    text: body.text,
-  };
-}
-
 /**
- * The document uf writes around the app's markup.
+ * The document a single-page build writes, and the only one it writes.
  *
- * The same two shapes `assemble` chose between, decided from the same evidence
- * — whether the markup opens with `<html>` — but stated up front instead of
- * afterwards, because a stream has no "afterwards" in which to splice a head.
- * An app whose root layout renders `<html>` owns the whole document and the
- * client hydrates `document`, so uf contributes only the tags that go before
- * `</head>`. An app that renders only content is wrapped in a minimal shell
- * around `<div id="uf-root">`, which is what the client hydrates instead.
+ * `app.rendering.modes: ["csr"]` renders no route at build time: the client
+ * router resolves and renders every one of them in the browser, so what the
+ * build has to leave behind is the *chrome* — the stylesheets, the module
+ * script, and the empty root the client renders into. That is exactly
+ * [`shellFor`]'s three strings with nothing between them, which is why this is
+ * three concatenations rather than a fourth shape of document to keep in step
+ * with the other three.
  *
- * `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.
- */
-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>` : "";
-  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}">`,
-    close: `</div></body></html>\n`,
-  };
-}
-
-function headTags(assets: RenderAssets): string {
-  let tags = "";
-  for (const href of assets.styles) {
-    tags += `<link rel="stylesheet" href="${escapeAttribute(href)}">`;
-  }
-  for (const href of assets.preloads) {
-    tags += `<link rel="modulepreload" href="${escapeAttribute(href)}">`;
-  }
-  for (const src of assets.scripts) {
-    tags += `<script type="module" src="${escapeAttribute(src)}"></script>`;
-  }
-  return tags;
-}
-
-/**
- * The loader data, embedded for hydration.
+ * No React runs. There is nothing to render: no URL has been asked for, and
+ * whatever this document is served for is decided by the host rather than by
+ * this build.
+ *
+ * # What it costs, said here because it is not visible from the file
  *
- * `<` 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.
+ * The document has no `<title>`, no `<meta name="description">` and no content.
+ * A crawler that runs no JavaScript sees an empty page for **every** URL, and a
+ * reader sees nothing until the bundle has loaded and the route has resolved.
+ * That is what a single-page application is, and it is why `modes: ["csr"]` is
+ * a declaration a project makes rather than something a build falls back to.
+ * A project that wants a document per route has `ssg`, and one that wants a
+ * document per request has `ssr`.
  */
-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;");
+export function shellDocument(assets: RenderAssets): string {
+  const shell = shellFor(assets);
+  return `${shell.open}${shell.body}${shell.close}`;
 }
 
-function escapeText(value: string): string {
-  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-}
+export {
+  createInstrumentation,
+  instrumentRender,
+  traceRequestPhase,
+} from "@uniflowed/server/instrumentation";