@uniflowed/router 0.0.0-alpha.7 → 0.0.0-alpha.8

package/middleware.js

@@ -0,0 +1,211 @@
+// @flow
+//
+// Middleware: what runs before a path answers, whatever answers it.
+//
+// `app/dashboard/_uf.middleware.js` guards `/dashboard` and everything under
+// it — the pages, the route handlers, and the paths under it that match
+// nothing at all. There is no `matcher` to write because the directory the
+// file sits in *is* the matcher, which is the same composition rule layouts
+// already use and the reason uf does not inherit Next's regular expressions.
+//
+//   // app/dashboard/_uf.middleware.js
+//   // @flow
+//   import { cookies } from "@uniflowed/server";
+//
+//   export default function middleware(request: Request): Response | void {
+//     if (cookies().get("session") == null) {
+//       return Response.redirect(new URL("/sign-in", request.url), 302);
+//     }
+//   }
+//
+// # The signature, and what it deliberately does not say
+//
+// `(request, context) => Response | void`. Returning a `Response` *is* the
+// answer: nothing after it runs, no page is resolved and no handler is called.
+// Returning nothing continues to the next middleware and then to whatever the
+// path would otherwise have done. Both halves are load-bearing — a middleware
+// 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.
+//
+// # The request it runs inside
+//
+// The runner does not establish one. The host does — `beginRequest` in
+// `@uniflowed/server/host`, once per request, around everything that answers
+// it — and the guard, the handler or page underneath it, and the render all
+// see that one context. So `cookies()` in a guard and `cookies()` in the page
+// it guards are the same cookies, `draftMode().enable()` in a guard is visible
+// to what it guards, and every `after()` on the request is one ordered list
+// the host drains after the response has gone.
+//
+// It used to be the other way, and it is worth saying why that was wrong
+// rather than merely different: this module built its own context and drained
+// it before returning, which is early in both outcomes. When the chain
+// answered, the caller was several lines from writing a byte; when it
+// declined, there was no response at all yet and the dispatcher below was
+// about to build a second context nothing here could see. `after()` says "once
+// the response has been sent". See ubugeeei-prod/uf#389.
+//
+// # Server only
+//
+// This module is imported by `virtual:uf/server` and by nothing the browser
+// loads. That is not decoration: a middleware is where an application puts the
+// check it does not want a user to be able to read, and the client entry
+// importing the table it lives in would ship every one of them to the page.
+// `routesModuleSource` keeps the middleware table in an export the client
+// never imports, for the same reason it does that with route handlers.
+
+import { requireRequest } from "./internal/request.js";
+import type { RouteParams } from "./internal/runtime.js";
+
+/** What a middleware is given besides the request. */
+export type MiddlewareContext = {|
+  /** The `[param]` segments of the *directory the middleware guards*. */
+  readonly params: RouteParams,
+  /** The parsed query string, for the common case of reading one value. */
+  readonly searchParams: URLSearchParams,
+|};
+
+/** One middleware function. */
+export type Middleware = (
+  request: Request,
+  context: MiddlewareContext,
+) => Response | void | Promise<Response | void>;
+
+/** A middleware module, as the generated table loads it. */
+export type MiddlewareModule = { readonly [name: string]: mixed };
+
+/** One entry of the generated middleware table. */
+export type MiddlewareRecord = {|
+  /** The route path of the directory this middleware guards, `/` at the root. */
+  readonly path: string,
+  readonly file: string,
+  readonly load: () => Promise<MiddlewareModule>,
+|};
+
+/**
+ * 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.
+ *
+ * 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
+ * `createDispatcher` and again inside `createRenderer` was the first shape and
+ * it is wrong twice over: a request that matches neither — `/dashboard/typo`,
+ * which is a 404 — would have run no middleware at all, and a path that is
+ * both a page and a handler would have run it twice. Middleware is a property
+ * of the request, so it belongs where the request arrives.
+ */
+export function createMiddlewareRunner(options: {|
+  readonly middleware: $ReadOnlyArray<MiddlewareRecord>,
+|}): (request: Request) => Promise<Response | 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.
+  const table = [...options.middleware].sort(
+    (a, b) => segmentsOf(a.path).length - segmentsOf(b.path).length,
+  );
+
+  return async function runMiddleware(request: Request): Promise<Response | 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
+    // about `entry.runMiddleware` itself — called rather than tested for, so a
+    // server bundle without it is a `TypeError` on the first request instead of
+    // an application whose auth check quietly stopped running. The same
+    // argument applies to the request this runs inside: without one, the first
+    // `cookies()` in somebody's guard would throw "called outside a request …
+    // a static prerender, a module's top level, or a client component", which
+    // is three wrong places to look, and an application with no `cookies()`
+    // anywhere would reach its render with no context at all and lose every
+    // `after()` to a different exception later.
+    requireRequest("runMiddleware");
+    if (table.length === 0) {
+      return null;
+    }
+
+    const url = new URL(request.url);
+
+    for (const record of table) {
+      const params = matchPrefix(record.path, url.pathname);
+      if (params == null) {
+        continue;
+      }
+
+      const middleware = pick(await record.load(), record.file);
+      // In the host's context, not one of this module's own. Two middleware on
+      // the same path see the same cookies, and so does the handler or the page
+      // underneath them: `draftMode().enable()` in a guard is visible to what
+      // it guards, 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;
+      }
+    }
+
+    return null;
+  };
+}
+
+/**
+ * The function a middleware module exports.
+ *
+ * `default` or `middleware`, the same two spellings a page offers for its
+ * component. Anything else is an authoring mistake and throws rather than
+ * being skipped: a file named `_uf.middleware.js` that the router quietly
+ * ignored is the bug this whole module exists to stop happening.
+ */
+function pick(module: MiddlewareModule, file: string): Middleware {
+  const exported = typeof module.default === "function" ? module.default : module.middleware;
+  if (typeof exported !== "function") {
+    throw new Error(
+      `${file} is a middleware but exports no middleware function: export it as \`default\` or as \`middleware\`.`,
+    );
+  }
+  return exported as $FlowFixMe;
+}
+
+/**
+ * Match a middleware's directory path against a pathname, as a *prefix*.
+ *
+ * The difference from the dispatcher's `matchPath` is the whole point:
+ * `/dashboard` matches `/dashboard`, `/dashboard/settings` and
+ * `/dashboard/a/b`, because a middleware guards a subtree rather than a path.
+ * `null` when it does not match, so a route with no parameters is still
+ * distinguishable from a miss.
+ */
+function matchPrefix(routePath: string, pathname: string): RouteParams | null {
+  const wanted = segmentsOf(routePath);
+  const given = segmentsOf(pathname);
+  const params: { [string]: string | Array<string> } = {};
+
+  for (let index = 0; index < wanted.length; index += 1) {
+    const segment = wanted[index];
+    if (segment.startsWith(":") && segment.endsWith("*")) {
+      params[segment.slice(1, -1)] = given.slice(index);
+      return params as $FlowFixMe;
+    }
+    if (index >= given.length) {
+      return null;
+    }
+    if (segment.startsWith(":")) {
+      params[segment.slice(1)] = given[index];
+      continue;
+    }
+    if (segment !== given[index]) {
+      return null;
+    }
+  }
+
+  return params as $FlowFixMe;
+}
+
+function segmentsOf(value: string): Array<string> {
+  return value.split("/").filter((segment) => segment !== "");
+}

package/package.json

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

package/server.js

@@ -3,13 +3,37 @@
 // Rendering one URL to an HTML document.
 //
 // `virtual:uf/server` calls `createRenderer` with the app root and the route
-// table, and `uf dev` renders every document request through the result while
-// `uf build` renders every static route through it once. Both produce the
+// table, and `uf dev` streams every document request through `render` while
+// `uf build` writes every static route through `prerender`. Both produce the
 // same markup from the same code, which is the point.
+//
+// # Two entry points, because there are two questions
+//
+// `render` streams and `prerender` waits, and which one a host wants is not a
+// detail of how it was called — it is what the host is *for*. A server has a
+// browser on the other end and a reason to send the layouts and the fallbacks
+// now; a build writes a file that something may later serve to a crawler, and a
+// file whose content is a `<template>` waiting for a script to move it is a
+// file that is blank to everything but a browser.
+//
+// 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
+// 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 * as React from "react";
-import { renderToString } from "react-dom/server";
+
+import {
+  type DocumentBody,
+  type DocumentShell,
+  type WritableLike,
+  bodyOfText,
+  prerenderDocument,
+  renderDocument,
+} from "./internal/stream.js";
 
 import {
   type AppProps,
@@ -28,11 +52,24 @@ export type RenderAssets = {|
   readonly preloads: $ReadOnlyArray<string>,
 |};
 
-/** A rendered document. */
+/**
+ * A document that has begun.
+ *
+ * `status` and `headers` are known once the shell is ready, which is the moment
+ * this resolves and is why a streaming renderer can still answer with a status
+ * line. The body arrives afterwards, through exactly one of `pipe`, `stream`
+ * and `text` — they are three views of one pass over the same chunks, not three
+ * copies of the document.
+ */
 export type RenderResult = {|
   readonly status: number,
-  readonly html: string,
   readonly headers?: { readonly [string]: string },
+  /** Write the document into a Node response. */
+  readonly pipe: (destination: WritableLike) => Promise<void>,
+  /** The document as a web stream, for `new Response(…)`. */
+  readonly stream: () => ReadableStream,
+  /** The whole document, once it has finished streaming. */
+  readonly text: () => Promise<string>,
   /**
    * The exception this render fell back to its error boundary for.
    *
@@ -44,24 +81,114 @@ export type RenderResult = {|
    *
    * `forbidden()` and `unauthorized()` do not set it: those are answers an
    * application chose, and a build that prerendered one has not failed.
+   *
+   * Only the failures known before the first byte: a loader that threw, or a
+   * shell that did. An exception inside a `<Suspense>` boundary happens after
+   * this has been read, so it is reported through `render`'s `onError` instead
+   * — a streaming renderer cannot put a late failure in a value the caller
+   * already has.
    */
   readonly error?: mixed,
 |};
 
+/** A document that is finished: every boundary resolved, nothing left to wait for. */
+export type PrerenderResult = {|
+  readonly status: number,
+  readonly html: string,
+  readonly headers?: { readonly [string]: string },
+  /** The exception this render fell back to its error boundary for; see [`RenderResult`]. */
+  readonly error?: mixed,
+|};
+
+/** What a host may tell the renderer about one request. */
+export type RenderOptions = {|
+  /**
+   * Every exception React recovered from, including the ones it answered by
+   * streaming a boundary's fallback after the response had begun.
+   *
+   * A callback rather than a field on the result, because that is the shape of
+   * the truth: by the time one of these happens the caller is already writing
+   * bytes. `uf dev` reports them in the terminal; a production host logs them.
+   */
+  readonly onError?: (error: mixed) => void,
+|};
+
+/** The two ids the server writes and the client reads. */
+export { DATA_ID, ROOT_ID } from "./internal/document.js";
+
 /**
- * Build a `render(url, assets)` for one app.
+ * How a host begins the request everything below runs inside.
+ *
+ * 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.
+ *
+ * `run` wraps everything that decides the response; `settle` is called once
+ * the response has been *written*, which is a different line in every host.
+ * `createMiddlewareRunner` and `createDispatcher` refuse to run outside it.
+ * See ubugeeei-prod/uf#389.
  */
-export { DATA_ID, ROOT_ID } from "./internal/document.js";
+export type { RequestLifecycle } from "@uniflowed/server/host";
+export { beginRequest } from "@uniflowed/server/host";
 
 export type { Handler, HandlerContext, HandlerModule, HandlerRecord } from "./handler.js";
 export { createDispatcher } from "./handler.js";
 
+export type {
+  Middleware,
+  MiddlewareContext,
+  MiddlewareModule,
+  MiddlewareRecord,
+} from "./middleware.js";
+export { createMiddlewareRunner } from "./middleware.js";
+
+/**
+ * What a URL turned out to be: a route to render, or a redirect to answer with.
+ *
+ * Tagged, and returned rather than thrown, because both entry points need the
+ * same answer and a redirect is the one thing `resolveMatch` lets out. Without
+ * the tag this would be a union of two exact objects and reading either field
+ * would be a type error on the branch that does not have it.
+ */
+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: (
+    url: string,
+    assets: RenderAssets,
+    options?: RenderOptions,
+  ) => Promise<RenderResult>,
+  readonly prerender: (
+    url: string,
+    assets: RenderAssets,
+    options?: RenderOptions,
+  ) => Promise<PrerenderResult>,
+|};
+
 export function createRenderer(options: {|
   readonly App: React.ComponentType<AppProps>,
   readonly routes: RouteTable["routes"],
   readonly notFound: RouteTable["notFound"],
   readonly errors: RouteTable["errors"],
-|}): (url: string, assets: RenderAssets) => Promise<RenderResult> {
+|}): Renderer {
   const table: RouteTable = {
     routes: options.routes,
     notFound: options.notFound,
@@ -70,43 +197,133 @@ export function createRenderer(options: {|
   installRoutes(table);
   const { App } = options;
 
-  return async function render(url: string, assets: RenderAssets): Promise<RenderResult> {
-    let resolved: ResolvedRoute;
+  /**
+   * 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.
+   */
+  async function resolve(url: string): Promise<Resolution> {
     try {
-      resolved = await resolveMatch(table, url);
+      return { kind: "route", route: await resolveMatch(table, url) };
     } catch (error) {
-      // A redirect is the only thing `resolveMatch` lets out, because a
-      // redirect is a response rather than a page.
       if (error instanceof RedirectError) {
-        return redirectDocument(error);
+        return { kind: "redirect", error };
       }
       throw error;
     }
+  }
+
+  async function render(
+    url: string,
+    assets: RenderAssets,
+    settings?: RenderOptions,
+  ): Promise<RenderResult> {
+    const resolution = await resolve(url);
+    if (resolution.kind === "redirect") {
+      return redirectDocument(resolution.error);
+    }
+    let resolved: ResolvedRoute = resolution.route;
+    const report = settings?.onError ?? (() => {});
+
+    // 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
+    // twice, once through `onError` and once as `result.error` after this
+    // re-renders. Errors are held until the shell is known to have survived;
+    // if it did not, they are the failure the caller is about to be handed, and
+    // the render they came from is being thrown away with them.
+    let streaming = false;
+    let held: Array<mixed> = [];
+    const onError = (error: mixed) => {
+      if (streaming) {
+        report(error);
+        return;
+      }
+      held.push(error);
+    };
 
-    let markup: string;
+    let body: DocumentBody;
     try {
-      markup = renderToString(<App url={url} initial={resolved} />);
+      body = await renderDocument(<App url={url} initial={resolved} />, {
+        shell: shellFor(resolved, assets),
+        onError,
+      });
+      streaming = true;
+      // Recovered before the shell was ready: a `<Suspense>` boundary whose
+      // content threw while the shell was still rendering. The response is
+      // fine and the host still has to hear about it.
+      for (const error of held) {
+        report(error);
+      }
+      held = [];
     } catch (error) {
-      // The server's half of the error boundary. React does not run class
-      // boundaries in `renderToString` — Fizz has no `getDerivedStateFromError`
-      // step outside a Suspense boundary — so `RouteView`'s boundary is the
-      // browser's containment and this is the server's. Without it one
-      // component that throws is the whole response, and during `uf build` the
-      // whole build. See ubugeeei-prod/uf#257.
+      // The server's half of the error boundary. React runs a class boundary
+      // inside a `<Suspense>` and not outside one, so a throw in the shell —
+      // the layouts, or a page with no boundary above it — still reaches here
+      // rather than `RouteView`'s. Nothing has been written yet, which is what
+      // makes answering with a different document possible at all: `onShellError`
+      // fires before the first byte, and once it has not, this is unreachable.
+      // See ubugeeei-prod/uf#257.
       if (error instanceof RedirectError) {
         return redirectDocument(error);
       }
+      held = [];
       resolved = await resolveFailure(table, url, error);
       // Deliberately not caught again: this render is the boundary's own
       // component, 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.
-      markup = renderToString(<App url={url} initial={resolved} />);
+      streaming = true;
+      body = await renderDocument(<App url={url} initial={resolved} />, {
+        shell: shellFor(resolved, assets),
+        onError,
+      });
+    }
+
+    return {
+      status: resolved.status,
+      pipe: body.pipe,
+      stream: body.stream,
+      text: body.text,
+      error: renderFailure(resolved),
+    };
+  }
+
+  async function prerender(
+    url: string,
+    assets: RenderAssets,
+    settings?: RenderOptions,
+  ): Promise<PrerenderResult> {
+    const resolution = await resolve(url);
+    if (resolution.kind === "redirect") {
+      return redirectResult(redirectDocument(resolution.error));
+    }
+    let resolved: ResolvedRoute = resolution.route;
+    const report = settings?.onError ?? (() => {});
+
+    let html: string;
+    try {
+      html = await prerenderDocument(<App url={url} initial={resolved} />, {
+        shell: shellFor(resolved, assets),
+        onError: report,
+      });
+    } catch (error) {
+      if (error instanceof RedirectError) {
+        return redirectResult(redirectDocument(error));
+      }
+      resolved = await resolveFailure(table, url, error);
+      html = await prerenderDocument(<App url={url} initial={resolved} />, {
+        shell: shellFor(resolved, assets),
+        onError: report,
+      });
     }
 
-    const html = assemble(markup, resolved, assets);
     return { status: resolved.status, html, error: renderFailure(resolved) };
-  };
+  }
+
+  return { render, prerender };
 }
 
 /** The exception a resolved route fell back to its error boundary for. */
@@ -123,32 +340,45 @@ 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 },
-    html: `<!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`,
+    pipe: body.pipe,
+    stream: body.stream,
+    text: body.text,
   };
 }
 
 /**
- * Turn the app's markup into a complete document.
+ * The document uf writes around the app's markup.
  *
- * An app whose root layout renders `<html>` owns the whole document, and the
- * client hydrates `document`; the scripts and stylesheets are inserted before
+ * 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.
  */
-function assemble(markup: string, resolved: ResolvedRoute, assets: RenderAssets): string {
+function shellFor(resolved: ResolvedRoute, assets: RenderAssets): DocumentShell {
   const head = headTags(assets) + dataScript(resolved.data);
-  if (/^\s*<html[\s>]/i.test(markup)) {
-    const document = markup.includes("</head>")
-      ? markup.replace("</head>", `${head}</head>`)
-      : markup.replace(/<html([^>]*)>/i, `<html$1><head>${head}</head>`);
-    return `<!doctype html>\n${document}\n`;
-  }
   const title =
     resolved.metadata.title != null ? `<title>${escapeText(resolved.metadata.title)}</title>` : "";
-  return `<!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}">${markup}</div></body></html>\n`;
+  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 {