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

package/server-components.js

@@ -0,0 +1,155 @@
+// @flow
+//
+// `@uniflowed/router`, as a React Server Component imports it.
+//
+// The package root has two entries and an export condition picks between them:
+// a module graph resolved under `react-server` — the one uf renders server
+// components in (ubugeeei-prod/uf#519) — gets this file, and every other graph
+// gets `./index.js`. Both export the same names, which is the point. A layout
+// imports `Link` and `useRoute` from `@uniflowed/router` and means the same
+// thing wherever it is rendered; what differs is what the names *are* here.
+//
+// * `Link`, `RouterProvider`, `RouteView` and `routerView` come from
+//   `./internal/runtime.js`, a `"use client"` module, so in this graph each one
+//   is a client reference: rendered as markup on the server and hydrated in
+//   the browser, with its code shipped for the browser's half only.
+// * `useRoute`, `useLoaderData` and `useSeo` are server implementations. A
+//   server component has no context to read, so they read the route the
+//   Flight renderer is rendering — `./internal/server-route.js` — which is the
+//   same route the browser's hooks read back out of the payload. This
+//   repository's documentation site highlights the section a reader is in
+//   from a server layout, and would otherwise have needed a client component to
+//   find out where it was.
+// * `useRouter` refuses, by name. Navigation happens in the browser, and a
+//   router a server component could hold would be methods that can never do
+//   anything.
+// * `useIsServer` answers `true`, which is what it has always answered while a
+//   server renders.
+//
+// Everything else — matching, the router's control errors, resolution — is
+// React-free and is the same code `./index.js` exports.
+
+import * as React from "react";
+import { use } from "react";
+
+import { Head } from "./internal/head.js";
+import type { Metadata } from "./internal/resolve.js";
+import type { RouteInfo, Router } from "./internal/runtime.js";
+import { serverRoute } from "./internal/server-route.js";
+
+export type { ErrorProps, LayoutProps, PageProps } from "./index.js";
+
+export type {
+  AppProps,
+  ErrorBoundary,
+  ErrorModule,
+  Interception,
+  JsonLd,
+  LayoutModule,
+  LinkPrefetch,
+  LoaderArgs,
+  Metadata,
+  MetadataArgs,
+  NavigateOptions,
+  NotFoundBoundary,
+  PageModule,
+  ResolvedRoute,
+  Robots,
+  RouteError,
+  RouteInfo,
+  RouteMatch,
+  RouteParamSpec,
+  RouteParams,
+  RouteRecord,
+  RouteTable,
+  Router,
+  ResolvedSlot,
+  SearchParams,
+  SlotRecord,
+  SlotRouteRecord,
+  TemplateModule,
+  TwitterCard,
+} from "./internal/runtime.js";
+
+export { Link, RouteView, RouterProvider, routerView } from "./internal/runtime.js";
+
+export {
+  ForbiddenError,
+  NotFoundError,
+  RedirectError,
+  UnauthorizedError,
+  buildRoute,
+  forbidden,
+  hasClientPage,
+  matchRoute,
+  notFound,
+  parseSearch,
+  permanentRedirect,
+  redirect,
+  routeErrorStatus,
+  splitUrl,
+  unauthorized,
+} from "./internal/routing.js";
+
+export { resolveFailure, resolveMatch } from "./internal/resolve.js";
+
+/**
+ * The route this server component is rendering in.
+ *
+ * `pending` is always `false`: a pending navigation is a fact about a browser
+ * that has asked for the next route and not received it, and a server renders
+ * the route it was asked for. `data` waits for a loader the router deferred,
+ * which is what the browser's `useRoute` does too, so a component that reads
+ * the data suspends at the same boundary on both sides.
+ */
+export hook useRoute(): RouteInfo {
+  const route = serverRoute("useRoute");
+  return {
+    path: route.path,
+    pathname: route.pathname,
+    params: route.params,
+    searchParams: route.searchParams,
+    data: route.deferred == null ? route.data : use(route.deferred),
+    pending: false,
+  };
+}
+
+/** The current page's loader data; see `useRoute` for what a deferred loader does. */
+export hook useLoaderData(): mixed {
+  const route = serverRoute("useLoaderData");
+  return route.deferred == null ? route.data : use(route.deferred);
+}
+
+/**
+ * A refusal: navigation is the browser's.
+ *
+ * Thrown rather than handed back as methods that do nothing, because a server
+ * component that called `router.push` in response to something would be
+ * waiting for a navigation that cannot happen, and nothing would say so.
+ */
+export hook useRouter(): Router {
+  throw new Error(
+    "@uniflowed/router: useRouter() was called in a Server Component, and navigation happens " +
+      "in the browser. Call it from a client component — a module that opens with the use " +
+      "client directive — or render a <Link>, which is one, and which a Server Component can " +
+      "render.",
+  );
+}
+
+/**
+ * Head elements a server component contributes, with the route's
+ * `metadataBase` applied to the relative URLs it names.
+ *
+ * The same component the browser's `useSeo` renders, and the same base: the one
+ * the root layout declared, read from the route rather than from context.
+ */
+export hook useSeo(seo: Metadata): React.Node {
+  const route = serverRoute("useSeo");
+  const base = seo.metadataBase ?? route.metadata.metadataBase;
+  return <Head metadata={base == null ? seo : { ...seo, metadataBase: base }} />;
+}
+
+/** Whether the app is being rendered on the server: here, always. */
+export hook useIsServer(): boolean {
+  return true;
+}

package/server.js

@@ -46,7 +46,15 @@ import {
   resolveMatch,
 } from "./internal/runtime.js";
 
-import { type StreamDiagnostic, streamReporter } from "./internal/inspector.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";
 
 /** Asset URLs to reference from the document. */
 export type RenderAssets = {|
@@ -101,6 +109,31 @@ 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,
+|};
+
+/**
+ * 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. */
@@ -258,6 +291,14 @@ 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 |},
+  ) => Promise<FlightResponse>,
 |};
 
 export function createRenderer(options: {|
@@ -430,6 +471,392 @@ 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) {