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

package/server.js

@@ -24,14 +24,11 @@
 // which.
 
 import { noteRoute } from "@uniflowed/server/host";
-import { ROOT_ID } from "./internal/document.js";
 import * as React from "react";
 
 import {
   type DocumentBody,
-  type DocumentShell,
   type WritableLike,
-  bodyOfText,
   prerenderDocument,
   renderDocument,
 } from "./internal/stream.js";
@@ -46,15 +43,8 @@ import {
   resolveMatch,
 } from "./internal/runtime.js";
 
-import { type StreamDiagnostic, type StreamRecord, streamReporter } from "./internal/inspector.js";
-
-import {
-  type ClientModuleLoader,
-  installServerModules,
-  readPayload,
-} from "./internal/flight-ssr.js";
-import { FLIGHT_CONTENT_TYPE, flightUrl } from "./internal/flight.js";
-import type { FlightRenderer } from "./rsc.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 = {|
@@ -241,6 +231,14 @@ 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.
  *
@@ -270,15 +268,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: (
@@ -471,392 +460,6 @@ export function createRenderer(options: {|
   return { render, prerender };
 }
 
-/** What `virtual:uf/server` hands the renderer for React Server Components. */
-export type DocumentRendererOptions = {|
-  readonly App: React.ComponentType<AppProps>,
-  /** The Flight renderer, from the module graph resolved under `react-server`. */
-  readonly renderFlight: FlightRenderer,
-  /** The server copy of the client module at a browser chunk URL. */
-  readonly loadClientModule: ClientModuleLoader,
-|};
-
-/**
- * The renderer for an application rendered by React Server Components.
- *
- * [`createRenderer`] renders a route's modules into HTML. This one renders no
- * route module at all: the Flight renderer (`./rsc.js`), in the module graph
- * resolved under `react-server`, renders the route into a payload, and this
- * reads that payload with React's own Flight client and renders what comes
- * out. The same bytes are written into the document as they arrive, so the
- * browser hydrates the tree the server rendered rather than rendering the
- * route's modules a second time — which is what keeps a Server Component's
- * module out of the browser. See ubugeeei-prod/uf#519.
- *
- * The contract with a host is [`Renderer`]'s, unchanged: `render` resolves
- * when the shell is ready with a status and a body, `prerender` resolves with a
- * finished document, and `error` is the exception a route fell back to its
- * error boundary for. It adds `flight`, which answers a browser that is
- * navigating, and `prerender` adds the payload a static host serves for one.
- *
- * # When the shell throws
- *
- * The HTML renderer only ever sees React's serialisation of what a Server
- * Component threw — in a build, a sentence and a digest — and resolving the
- * error boundary needs the exception itself: `forbidden()` is a 403 and a
- * `RedirectError` is a redirect. So the first exception the Flight renderer
- * reports is kept, as thrown, and it is what the error route is resolved for.
- * An exception only the HTML renderer saw — a client component that threw
- * while it rendered on the server — is resolved for as it is.
- */
-export function createDocumentRenderer(options: DocumentRendererOptions): Renderer {
-  const { App, renderFlight } = options;
-  installServerModules(options.loadClientModule);
-
-  /**
-   * The document for one payload: React's Flight client reads one copy of the
-   * stream while the other copy is written into the document.
-   */
-  async function documentOf(
-    stream: ReadableStream<Uint8Array>,
-    url: string,
-    assets: RenderAssets,
-    settings: {|
-      readonly onError: (error: mixed) => void,
-      readonly transformHead?: (html: string) => Promise<string>,
-      readonly onStream?: (record: StreamRecord) => void,
-    |},
-  ): Promise<DocumentBody> {
-    const [forHtml, forBrowser] = stream.tee();
-    try {
-      return await renderDocument(<App url={url} flight={readPayload(forHtml)} />, {
-        shell: shellFor(assets),
-        onError: settings.onError,
-        transformHead: settings.transformHead,
-        onStream: settings.onStream,
-        payload: forBrowser,
-      });
-    } catch (error) {
-      void forBrowser.cancel();
-      throw error;
-    }
-  }
-
-  async function render(
-    url: string,
-    assets: RenderAssets,
-    settings?: RenderOptions,
-  ): Promise<RenderResult> {
-    const report = settings?.onError ?? (() => {});
-    const send = settings?.onStream;
-    const onStream = send == null ? undefined : streamReporter(url, send);
-    const transformHead = settings?.transformHead;
-    const ledger = createErrorLedger();
-
-    // Held until the shell is known to have survived, for the reason
-    // [`createRenderer`] holds them — and dropped rather than reported once the
-    // render they came from has been given up for the error boundary. That
-    // render goes on reporting while it stops, and nothing it says then is
-    // about the response.
-    let streaming = false;
-    let abandoned = false;
-    let held: Array<mixed> = [];
-    const onError = (error: mixed) => {
-      if (abandoned) {
-        return;
-      }
-      if (streaming) {
-        report(error);
-        return;
-      }
-      held.push(error);
-    };
-
-    const stop = new AbortController();
-    const rendered = await renderFlight(url, {
-      onError: (error: mixed) => {
-        onError(error);
-        return ledger.record(error);
-      },
-      signal: stop.signal,
-    });
-    if (rendered.kind === "redirect") {
-      return redirectDocument(new RedirectError(rendered.location, rendered.status === 308));
-    }
-    let status = rendered.status;
-    let failure = rendered.failure;
-    let body: DocumentBody;
-    try {
-      body = await documentOf(rendered.stream, url, assets, {
-        onError: (error: mixed) => {
-          if (!ledger.isCopy(error)) {
-            onError(error);
-          }
-        },
-        transformHead,
-        onStream,
-      });
-      streaming = true;
-      for (const error of held) {
-        report(error);
-      }
-      held = [];
-    } catch (error) {
-      abandoned = true;
-      held = [];
-      stop.abort();
-      const cause = ledger.originalOf(error);
-      if (cause instanceof RedirectError) {
-        return redirectDocument(cause);
-      }
-      // Deliberately not caught again: this render is the boundary's own, and a
-      // boundary that throws has nothing left to answer with. It reaches
-      // `uf dev`'s overlay and fails `uf build`'s route, which is where somebody
-      // can fix it.
-      const recovered = await renderFlight(url, {
-        failure: { error: cause },
-        onError: (late: mixed) => {
-          report(late);
-          return ledger.record(late);
-        },
-      });
-      if (recovered.kind === "redirect") {
-        return redirectDocument(new RedirectError(recovered.location, recovered.status === 308));
-      }
-      status = recovered.status;
-      failure = recovered.failure;
-      try {
-        body = await documentOf(recovered.stream, url, assets, {
-          onError: (late: mixed) => {
-            if (!ledger.isCopy(late)) {
-              report(late);
-            }
-          },
-          transformHead,
-          onStream,
-        });
-      } catch (thrown) {
-        // The boundary's own render threw; see `prerender` for why what leaves
-        // is the exception as thrown rather than React's copy of it.
-        throw ledger.originalOf(thrown);
-      }
-    }
-
-    return { status, pipe: body.pipe, stream: body.stream, text: body.text, error: failure };
-  }
-
-  async function prerender(
-    url: string,
-    assets: RenderAssets,
-    settings?: RenderOptions,
-  ): Promise<PrerenderResult> {
-    const report = settings?.onError ?? (() => {});
-    const ledger = createErrorLedger();
-    // The Flight renderer's copy of an exception is the one reported, because it
-    // is the exception as thrown; the HTML renderer's copy of the same one is
-    // recognised by its digest and dropped. See [`createErrorLedger`].
-    const onServerError = (error: mixed): string => {
-      report(error);
-      return ledger.record(error);
-    };
-    const onHtmlError = (error: mixed) => {
-      if (!ledger.isCopy(error)) {
-        report(error);
-      }
-    };
-
-    // `defer: false`, for the reason [`createRenderer`]'s prerender passes it:
-    // a file has no fallback to show first.
-    const rendered = await renderFlight(url, { defer: false, onError: onServerError });
-    if (rendered.kind === "redirect") {
-      return redirectResult(
-        redirectDocument(new RedirectError(rendered.location, rendered.status === 308)),
-      );
-    }
-    let status = rendered.status;
-    let failure = rendered.failure;
-    let payload: Uint8Array;
-    let html: string;
-    try {
-      // Inside the `try`, with the document: a payload the Flight renderer
-      // could not finish — a function handed to a client component, say —
-      // fails the stream itself, and that is this route's failure like any
-      // other.
-      payload = await bytesOf(rendered.stream);
-      html = await staticDocumentOf(payload, url, assets, onHtmlError);
-    } catch (error) {
-      const cause = ledger.originalOf(error);
-      if (cause instanceof RedirectError) {
-        return redirectResult(redirectDocument(cause));
-      }
-      const recovered = await renderFlight(url, {
-        defer: false,
-        failure: { error: cause },
-        onError: onServerError,
-      });
-      if (recovered.kind === "redirect") {
-        return redirectResult(
-          redirectDocument(new RedirectError(recovered.location, recovered.status === 308)),
-        );
-      }
-      status = recovered.status;
-      failure = recovered.failure;
-      try {
-        payload = await bytesOf(recovered.stream);
-        html = await staticDocumentOf(payload, url, assets, onHtmlError);
-      } catch (thrown) {
-        // The boundary's own render threw, and nothing is left to answer with.
-        // What leaves is the exception as thrown rather than the copy React's
-        // client rebuilt from its row, whose message in a build says only that
-        // the real one was omitted — which is all `uf build` would then print.
-        throw ledger.originalOf(thrown);
-      }
-    }
-    return { status, html, error: failure, payload };
-  }
-
-  /** A finished document for a finished payload, with the payload written into it. */
-  function staticDocumentOf(
-    payload: Uint8Array,
-    url: string,
-    assets: RenderAssets,
-    onError: (error: mixed) => void,
-  ): Promise<string> {
-    return prerenderDocument(<App url={url} flight={readPayload(streamOf(payload))} />, {
-      shell: shellFor(assets),
-      onError,
-      payload: streamOf(payload),
-    });
-  }
-
-  async function flight(
-    url: string,
-    settings?: {| readonly onError?: (error: mixed) => void |},
-  ): Promise<FlightResponse> {
-    const rendered = await renderFlight(url, { onError: settings?.onError });
-    if (rendered.kind === "redirect") {
-      const { location } = rendered;
-      // A redirect on this origin points at its target's payload, so the
-      // browser's `fetch` follows it and lands on one. A redirect elsewhere is
-      // left as written: what the browser finds there is not a payload, and it
-      // loads the URL as a document instead.
-      const onThisOrigin = location.startsWith("/") && !location.startsWith("//");
-      return {
-        status: rendered.status,
-        headers: { location: onThisOrigin ? flightUrl(location) : location },
-        stream: null,
-      };
-    }
-    return {
-      status: rendered.status,
-      headers: { "content-type": FLIGHT_CONTENT_TYPE },
-      stream: rendered.stream,
-      error: rendered.failure,
-    };
-  }
-
-  return { render, prerender, flight };
-}
-
-/**
- * Pairs each exception the Flight renderer reports with the copy of it the HTML
- * renderer sees.
- *
- * A Server Component that throws is seen twice. The Flight renderer catches the
- * exception as it was thrown and writes an error row where that part of the
- * tree would have been; React's Flight client reads the row and throws an error
- * rebuilt from it, which is what the HTML renderer sees at the same spot — and
- * in a build, that error's message is a sentence saying the real one was
- * omitted. Reporting both tells a host about one failure twice, once uselessly.
- * Resolving the error boundary for the rebuilt one is worse: `forbidden()`
- * would become a 500 and `redirect()` an error page, because neither survives
- * being rebuilt as a plain `Error`.
- *
- * The row carries a digest, and that is React's field for exactly this: what
- * the Flight renderer's `onError` returns is written into the row and set on the
- * rebuilt error as `digest`. So every exception is recorded here under a digest
- * of its own, and an error the HTML renderer reports with a recorded digest is a
- * copy — dropped from the report, and exchanged for the original when the
- * boundary is resolved.
- *
- * The digest reaches the browser inside the payload, and says nothing: it counts
- * the exceptions one render has recorded.
- */
-function createErrorLedger(): ErrorLedger {
-  const originals: Map<string, mixed> = new Map();
-  const recorded = (error: mixed): string | null => {
-    const digest = digestOf(error);
-    return digest != null && originals.has(digest) ? digest : null;
-  };
-  return {
-    record(error: mixed): string {
-      const digest = `uf:${originals.size + 1}`;
-      originals.set(digest, error);
-      return digest;
-    },
-    isCopy(error: mixed): boolean {
-      return recorded(error) != null;
-    },
-    originalOf(error: mixed): mixed {
-      const digest = recorded(error);
-      return digest == null ? error : originals.get(digest);
-    },
-  };
-}
-
-/** See [`createErrorLedger`]. */
-type ErrorLedger = {|
-  /** Keep an exception the Flight renderer reported, and return its digest. */
-  readonly record: (error: mixed) => string,
-  /** Whether an error the HTML renderer reported is the copy of a kept one. */
-  readonly isCopy: (error: mixed) => boolean,
-  /** The exception as thrown, for a copy; any other error, as it is. */
-  readonly originalOf: (error: mixed) => mixed,
-|};
-
-/** The digest React set on an error, when it set one. */
-function digestOf(error: mixed): string | null {
-  if (error == null || typeof error !== "object") {
-    return null;
-  }
-  const tagged: { +digest?: mixed, ... } = (error: $FlowFixMe);
-  return typeof tagged.digest === "string" ? tagged.digest : null;
-}
-
-/** Every byte of a stream, as one array. */
-async function bytesOf(stream: ReadableStream<Uint8Array>): Promise<Uint8Array> {
-  const reader = stream.getReader();
-  const chunks: Array<Uint8Array> = [];
-  let total = 0;
-  while (true) {
-    const step = await reader.read();
-    if (step.done === true) {
-      break;
-    }
-    const chunk = step.value;
-    if (chunk != null) {
-      chunks.push(chunk);
-      total += chunk.byteLength;
-    }
-  }
-  const bytes = new Uint8Array(total);
-  let at = 0;
-  for (const chunk of chunks) {
-    bytes.set(chunk, at);
-    at += chunk.byteLength;
-  }
-  return bytes;
-}
-
-/** A stream of one array, read as many times as a caller constructs one. */
-function streamOf(bytes: Uint8Array): ReadableStream<Uint8Array> {
-  return new ReadableStream({
-    start(controller) {
-      controller.enqueue(bytes);
-      controller.close();
-    },
-  });
-}
-
 /** The exception a resolved route fell back to its error boundary for. */
 function renderFailure(resolved: ResolvedRoute): mixed {
   if (resolved.error == null) {
@@ -869,54 +472,6 @@ 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 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.
- *
- * `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.
- */
 /**
  * The document a single-page build writes, and the only one it writes.
  *
@@ -946,31 +501,3 @@ export function shellDocument(assets: RenderAssets): string {
   const shell = shellFor(assets);
   return `${shell.open}${shell.body}${shell.close}`;
 }
-
-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">`,
-    body: `${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;
-}
-
-function escapeAttribute(value: string): string {
-  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
-}