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

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 {
+  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: {|
   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

@@ -25,8 +25,16 @@
 // 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.
-
-import { contextFor, drainDeferred, runWithContext } from "@uniflowed/server/host";
+//
+// 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. */
@@ -76,6 +84,9 @@ export function createDispatcher(options: {|
   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);
@@ -90,17 +101,13 @@ export function createDispatcher(options: {|
         return methodNotAllowed(module);
       }
 
-      // Inside the request, so a handler that calls `headers()`, `cookies()`
-      // or `after()` has something to answer about. `drainDeferred` runs after
-      // the response is in hand, which is what `after()` means.
-      const context = contextFor(request);
-      const response = await runWithContext(context, () =>
-        handler(request, {
-          params,
-          searchParams: url.searchParams,
-        }),
-      );
-      await drainDeferred(context);
+      // 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

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,
@@ -28,19 +40,26 @@ export type {
 } 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,
@@ -57,10 +76,16 @@ export type PageProps<
   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 extends { readonly [string]: string | $ReadOnlyArray<string> } = {},
 > = {|
   readonly params: TParams,
-  readonly children: React$Node,
+  readonly children: React.Node,
 |};

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.",
+  );
+}