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

package/client.js

@@ -6,25 +6,58 @@
 // The current route's chunks are loaded and its embedded loader data read
 // *before* `hydrateRoot`, so the first client render is synchronous and
 // matches the server's markup exactly.
+//
+// # A route can decline to be hydrated
+//
+// uf's server-component analysis decides which routes have a `"use client"`
+// boundary anywhere in them, and `@uniflowed/vite` leaves the page out of the
+// client route table for the ones that have none. Such a route has nothing in
+// the browser to attach: the document the server wrote is the whole of it. So
+// this returns without calling `hydrateRoot`, and the `<a>` elements a `Link`
+// rendered stay what the server made them — real links the browser follows.
+// See ubugeeei-prod/uf#350.
 
 import * as React from "react";
 import { startTransition } from "react";
 import { hydrateRoot } from "react-dom/client";
 
-import { type AppProps, type RouteTable, installRoutes, resolveMatch } from "./internal/runtime.js";
-import { DATA_ID, ROOT_ID } from "./server.js";
+import {
+  type AppProps,
+  type RouteTable,
+  hasClientPage,
+  installRoutes,
+  matchRoute,
+  resolveMatch,
+} from "./internal/runtime.js";
+import { DATA_ID, ROOT_ID } from "./internal/document.js";
 
 /**
  * Hydrate the current document.
+ *
+ * Resolves without mounting anything when the current route ships no client
+ * page — see the header. The promise settling is not a claim that React is on
+ * the document.
  */
 export async function hydrate(options: {|
-  +App: React.ComponentType<AppProps>,
-  +routes: RouteTable["routes"],
-  +notFound: RouteTable["notFound"],
+  readonly App: React.ComponentType<AppProps>,
+  readonly routes: RouteTable["routes"],
+  readonly notFound: RouteTable["notFound"],
+  readonly errors: RouteTable["errors"],
 |}): Promise<void> {
-  const table: RouteTable = { routes: options.routes, notFound: options.notFound };
+  const table: RouteTable = {
+    routes: options.routes,
+    notFound: options.notFound,
+    errors: options.errors,
+  };
   installRoutes(table);
 
+  // Before the loader data is read and before `resolveMatch` is called: both
+  // would go looking for a page module that is not in this bundle.
+  const matched = matchRoute(table.routes, window.location.pathname);
+  if (matched != null && !hasClientPage(matched.route)) {
+    return;
+  }
+
   const url = window.location.pathname + window.location.search;
   const embedded = document.getElementById(DATA_ID);
   const data = embedded != null ? JSON.parse(embedded.textContent ?? "null") : undefined;

package/handler.js

@@ -0,0 +1,217 @@
+// @flow
+//
+// Route handlers: a path that answers a request instead of rendering a page.
+//
+// `app/api/users/_uf.route.js` exporting `GET` and `POST` serves
+// `/api/users`. A handler takes a `Request` and returns a `Response` — the
+// platform's own types, not a framework's wrapper — because that is what runs
+// unchanged on Node.js, Bun, Deno and a Cloudflare Worker, and uf's whole
+// position is that the host is a capability rather than a target.
+//
+//   // app/api/users/[id]/_uf.route.js
+//   // @flow
+//   export async function GET(request: Request, context: HandlerContext) {
+//     const user = await find(context.params.id);
+//     return user == null
+//       ? new Response("not found", { status: 404 })
+//       : Response.json(user);
+//   }
+//
+// # What the dispatcher decides, and what it does not
+//
+// It matches a path and a method and calls a function. It does not catch the
+// handler's errors, because a handler that throws is a bug the host's own
+// error reporting should see, and swallowing it into a 500 here would hide it.
+// It does answer `405` itself when the path matches and the method does not,
+// with the `Allow` header the specification requires — that is not the
+// handler's business, and every handler would otherwise write it.
+//
+// It also does not establish the request a handler is inside. The host does,
+// around the whole of it, so a handler and the guard above it share one
+// context; see the same section in `./middleware.js`. This module used to
+// build its own and drain it the moment the handler returned, which the
+// comment there called "the response is in hand" — true, and not what
+// `after()` promises. A handler that streams its body has not sent a byte at
+// that point. See ubugeeei-prod/uf#389.
+
+import { requireRequest } from "./internal/request.js";
+import type { RouteParams } from "./internal/runtime.js";
+
+/** What a handler is given besides the request. */
+export type HandlerContext = {|
+  /** The `[param]` and `[...rest]` segments of the matched path. */
+  readonly params: RouteParams,
+  /** The parsed query string, for the common case of reading one value. */
+  readonly searchParams: URLSearchParams,
+|};
+
+/** One exported method of a handler module. */
+export type Handler = (request: Request, context: HandlerContext) => Response | Promise<Response>;
+
+/** A handler module, as the generated table loads it. */
+export type HandlerModule = { readonly [method: string]: mixed };
+
+/** One entry of the generated handler table. */
+export type HandlerRecord = {|
+  readonly path: string,
+  readonly params: $ReadOnlyArray<{| readonly name: string, readonly catchAll: boolean |}>,
+  readonly file: string,
+  readonly load: () => Promise<HandlerModule>,
+|};
+
+/**
+ * The methods a handler may export.
+ *
+ * A closed list, because the alternative is treating every export as a method
+ * — and a module that exports a helper would then answer requests with it.
+ * `HEAD` falls back to `GET` with the body dropped, which is what a client
+ * asking for headers expects and what nobody remembers to write.
+ */
+const METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+
+/**
+ * Match a request against the handler table and run it.
+ *
+ * Returns `null` when no path matches, which is the caller's signal to carry
+ * on — a request for `/about` is a page, and the dispatcher declining is how
+ * it says so.
+ */
+export function createDispatcher(options: {|
+  readonly handlers: $ReadOnlyArray<HandlerRecord>,
+|}): (request: Request) => Promise<Response | null> {
+  // Longest path first, so `/api/users/new` wins over `/api/users/[id]` and a
+  // catch-all is the last thing tried.
+  const table = [...options.handlers].sort((a, b) => specificity(b.path) - specificity(a.path));
+
+  return async function dispatch(request: Request): Promise<Response | null> {
+    // The host's half of the contract, checked rather than assumed; see
+    // `./internal/request.js`.
+    requireRequest("dispatch");
+    const url = new URL(request.url);
+    for (const record of table) {
+      const params = matchPath(record.path, url.pathname);
+      if (params == null) {
+        continue;
+      }
+
+      const module = await record.load();
+      const method = request.method.toUpperCase();
+      const handler = pick(module, method);
+      if (handler == null) {
+        return methodNotAllowed(module);
+      }
+
+      // In the host's request, so a handler that calls `headers()`,
+      // `cookies()` or `after()` answers about the same one its guard did, and
+      // what it defers is drained once, by the host, after the bytes are out.
+      const response = await handler(request, {
+        params,
+        searchParams: url.searchParams,
+      });
+
+      // A `HEAD` answered by `GET` must not carry the body. The test is
+      // against the module's own `HEAD`, not `pick`'s — `pick` falls back to
+      // `GET`, so asking it whether a `HEAD` exists always said yes and the
+      // body went out anyway.
+      if (method === "HEAD" && typeof module.HEAD !== "function") {
+        return new Response(null, {
+          status: response.status,
+          statusText: response.statusText,
+          headers: response.headers,
+        });
+      }
+      return response;
+    }
+    return null;
+  };
+}
+
+/** The function for a method, falling back to `GET` for `HEAD`. */
+function pick(module: HandlerModule, method: string): Handler | null {
+  const own = module[method];
+  if (typeof own === "function") {
+    return own as $FlowFixMe;
+  }
+  if (method === "HEAD" && typeof module.GET === "function") {
+    return module.GET as $FlowFixMe;
+  }
+  return null;
+}
+
+/**
+ * `405`, with the `Allow` header naming what the path does accept.
+ *
+ * Required by the specification, and the reason a client can tell "you may not
+ * do that here" from "there is nothing here".
+ */
+function methodNotAllowed(module: HandlerModule): Response {
+  const own = new Set(METHODS.filter((method) => typeof module[method] === "function"));
+  // A module exporting `GET` also answers `HEAD`, so `Allow` has to say so.
+  if (own.has("GET")) {
+    own.add("HEAD");
+  }
+  // Filtered through `METHODS` rather than listed in insertion order, so the
+  // header reads in the conventional order however the module was written.
+  return new Response(null, {
+    status: 405,
+    headers: { allow: METHODS.filter((method) => own.has(method)).join(", ") },
+  });
+}
+
+/**
+ * Match one route path against a pathname, returning its parameters.
+ *
+ * `null` rather than an empty object when it does not match, so a route with
+ * no parameters is still distinguishable from a miss.
+ */
+function matchPath(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("*")) {
+      // A catch-all takes the rest, and matches zero segments as well as many.
+      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 wanted.length === given.length ? (params as $FlowFixMe) : null;
+}
+
+function segmentsOf(value: string): Array<string> {
+  return value.split("/").filter((segment) => segment !== "");
+}
+
+/**
+ * How specific a path is, so the table can be tried in the right order.
+ *
+ * A literal segment is worth more than a parameter and a parameter more than a
+ * catch-all, and a longer path outranks a shorter one — which is what makes
+ * `/api/users/new` win over `/api/users/[id]`.
+ */
+function specificity(routePath: string): number {
+  let score = 0;
+  for (const segment of segmentsOf(routePath)) {
+    if (segment.startsWith(":") && segment.endsWith("*")) {
+      score += 1;
+    } else if (segment.startsWith(":")) {
+      score += 10;
+    } else {
+      score += 100;
+    }
+  }
+  return score;
+}

package/index.js

@@ -6,17 +6,29 @@
 // `_uf.layout.js`, and `app.js` exports `routerView("./app")`. The route table
 // is generated from the directory at build time; this module is the runtime
 // that matches, loads, navigates and renders it.
+//
+// `_uf.not-found.js` and `_uf.error.js` are the two boundaries: the page for a
+// path that matched nothing, and what renders in place of a subtree that threw.
+// Both are segment files, resolved by the nearest one above the path.
+
+import * as React from "react";
+
+import type { RouteError } from "./internal/runtime.js";
 
 export type {
   AppProps,
+  ErrorBoundary,
+  ErrorModule,
   LayoutModule,
   LinkPrefetch,
   LoaderArgs,
   Metadata,
   MetadataArgs,
   NavigateOptions,
+  NotFoundBoundary,
   PageModule,
   ResolvedRoute,
+  RouteError,
   RouteInfo,
   RouteMatch,
   RouteParamSpec,
@@ -25,22 +37,30 @@ export type {
   RouteTable,
   Router,
   SearchParams,
+  TwitterCard,
 } from "./internal/runtime.js";
 
 export {
+  ForbiddenError,
   Link,
   NotFoundError,
   RedirectError,
   RouteView,
   RouterProvider,
+  UnauthorizedError,
+  forbidden,
+  hasClientPage,
   matchRoute,
   notFound,
   parseSearch,
   permanentRedirect,
   redirect,
+  resolveFailure,
   resolveMatch,
+  routeErrorStatus,
   routerView,
   splitUrl,
+  unauthorized,
   useIsServer,
   useLoaderData,
   useRoute,
@@ -49,16 +69,24 @@ export {
 
 /** Props a page receives. */
 export type PageProps<
-  TParams: { +[string]: string | $ReadOnlyArray<string> } = {},
+  TParams extends { readonly [string]: string | $ReadOnlyArray<string> } = {},
   TData = void,
 > = {|
-  +params: TParams,
-  +searchParams: { +[string]: string },
-  +data: TData,
+  readonly params: TParams,
+  readonly searchParams: { readonly [string]: string },
+  readonly data: TData,
+|};
+
+/** Props an `_uf.error.js` component receives. */
+export type ErrorProps = {|
+  readonly error: RouteError,
+  readonly reset: () => void,
 |};
 
 /** Props a layout receives. */
-export type LayoutProps<TParams: { +[string]: string | $ReadOnlyArray<string> } = {}> = {|
-  +params: TParams,
-  +children: React$Node,
+export type LayoutProps<
+  TParams extends { readonly [string]: string | $ReadOnlyArray<string> } = {},
+> = {|
+  readonly params: TParams,
+  readonly children: React.Node,
 |};

package/internal/document.js

@@ -0,0 +1,24 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: the two ids the server writes and the
+// client reads.
+//
+// Their own module because both halves need them and neither should import the
+// other. The client used to take them from `./server.js`, which meant a client
+// bundle reached the request dispatcher — and through it `node:async_hooks`,
+// by way of `@uniflowed/server`. Nothing was *called*, so a bundler dropped the
+// code, but the import of a Node builtin survived into a browser bundle and
+// Vite said so on every build.
+//
+// Two string constants are not worth a boundary violation.
+
+/**
+ * The element the client hydrates when the app does not render `<html>`.
+ *
+ * An app whose root layout renders the whole document owns it and hydrates
+ * `document` instead; this is the wrapper for the ones that render content.
+ */
+export const ROOT_ID = "uf-root";
+
+/** The script element the server's resolved route data is written into. */
+export const DATA_ID = "__uf_data";

package/internal/request.js

@@ -0,0 +1,43 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: the request the server half runs inside.
+//
+// One function, and it exists because two modules need the same refusal.
+// `createMiddlewareRunner` and `createDispatcher` both used to build a request
+// context of their own — `contextFor`, then `runWithContext`, then
+// `drainDeferred` — which gave one request up to two contexts and ran what
+// `after()` deferred before the response was written, and in the middleware's
+// case before there was a response at all. See ubugeeei-prod/uf#389.
+//
+// Both now run inside whatever request the host established, which means both
+// depend on the host having established one. That dependency is checked rather
+// than assumed, for the reason `createApplicationHandler` gives about
+// `entry.runMiddleware` itself: a missing half of the contract should be a
+// failure on the first request, not an application that answers strangely.
+//
+// Server-only, like the two modules that import it. Nothing the browser loads
+// reaches this.
+
+import { insideRequest } from "@uniflowed/server/host";
+
+/**
+ * Refuse to run outside a request, naming what has to establish one.
+ *
+ * The message is addressed to whoever wired the host, because that is who can
+ * fix it. Left to fail on its own, a mis-wired host would surface as the first
+ * `cookies()` in somebody's guard throwing "called outside a request … a
+ * static prerender, a module's top level, or a client component" — three
+ * places to look, none of them this one — and an application that calls no
+ * server function at all would sail past that and lose every `after()` instead.
+ */
+export function requireRequest(entry: string): void {
+  if (insideRequest()) {
+    return;
+  }
+  throw new Error(
+    `@uniflowed/router: ${entry}() was called outside a request. A host owns the request: ` +
+      "begin it with `beginRequest` from `@uniflowed/server/host` (a bundled application " +
+      "re-exports it from `virtual:uf/server`), run the whole request inside `run`, and call " +
+      "`settle` once the response has been sent. See ubugeeei-prod/uf#389.",
+  );
+}