@uniflowed/router 0.0.0-alpha.9 → 0.2.0

package/middleware.js

@@ -2,13 +2,13 @@
 //
 // Middleware: what runs before a path answers, whatever answers it.
 //
-// `app/dashboard/_uf.middleware.js` guards `/dashboard` and everything under
+// `app/dashboard/$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
+//   // app/dashboard/$middleware.js
 //   // @flow
 //   import { cookies } from "@uniflowed/server";
 //
@@ -27,10 +27,64 @@
 // 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.
+// There is no `next()`. A third answer is `rewrite(destination)`: serve another
+// route of this application at the address the visitor asked for.
+//
+//   // app/$middleware.js
+//   import { rewrite } from "@uniflowed/router/middleware";
+//
+//   export default function middleware(request: Request) {
+//     if (cookies().get("beta") != null) return rewrite("/beta" + new URL(request.url).pathname);
+//   }
+//
+// A returned value rather than a returned `Request`, which was the other
+// spelling on the table. A `Request` could change the method and the headers
+// too, and `headers()` reads the request the host began — so a middleware that
+// added a header would have handed the page one set of headers and `headers()`
+// another. A rewrite changes the path, the query when it names one, and
+// nothing else.
+//
+// # A rewrite runs the destination's middleware
+//
+// The chain starts again from the root over the middleware that has not run
+// yet, against the new path. So a rewrite into `/admin` passes the guard on
+// `/admin` exactly as a request for it would, and is never an unguarded way to
+// a guarded page; a middleware that already ran for this request does not run
+// a second time, which is also what makes the loop finite.
+//
+// # A payload request is its document
+//
+// A browser navigating a React Server Components application asks for
+// `/pricing/__uf.flight` rather than `/pricing`. The chain is matched against,
+// and every middleware is handed, the document's URL — so the check a
+// middleware writes against `/pricing` holds for a client navigation too, and
+// a rewrite of the document becomes a rewrite of its payload.
+//
+// # A payload that renders over another page runs that page's guards too
+//
+// An intercepted navigation — a modal slot opening over the page it was clicked
+// from — asks for the payload of the URL it opens, and names the page it
+// renders over in `uf-intercepted-from`. The answer is *both* pages: the one
+// the URL names, in the slot, and the one the header names, underneath it,
+// with that page's loader run and its data in the payload.
+//
+// So the chain matched against the URL alone would be the wrong chain. A guard
+// on `/feed` holds for a request *for* `/feed`, and a payload for `/photo/1`
+// rendered over `/feed` is `/feed` as much as it is `/photo/1`. After the
+// ordinary chain has admitted the request, every middleware guarding the page
+// underneath runs as well — against a `GET` for that page, with its params and
+// query — including one that already ran for the URL, because a middleware
+// that decides by reading the pathname (one root `$middleware.js` guarding
+// several sections is a common shape) has only been asked about the other
+// path. If every one of them declines, the interception stands. If any
+// answers or rewrites, the page underneath is not this request's to render:
+// the header is taken off, and what renders is the page the URL names on its
+// own — exactly what a reader who could not open the page underneath would
+// see after a reload. The guard's own answer is not sent: the request was for
+// `/photo/1`, which that guard does not cover.
+//
+// The header is taken off whenever it is not a path on this origin, too, so
+// the renderer is never handed a value this module has not judged.
 //
 // # The request it runs inside
 //
@@ -38,9 +92,18 @@
 // `@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 guards are the same cookies, `draftMode().isEnabled` gives a guard and
+// the page under it the same answer, and every `after()` on the request is one
+// ordered list the host drains after the response has gone.
+//
+// *Changing* draft mode is not a guard's to do, and that is a separate rule
+// with a separate reason: `enable()` writes a cookie, a cookie is part of a
+// response, and a guard may decline — so a guard that turned draft mode on and
+// then let the request through would have made a decision with nowhere to be
+// written. `asResponder` marks the two calls that do own a response, a route
+// handler and a server action, and `draftMode().enable()` refuses anywhere
+// else by name. A guard that wants draft mode on answers with a redirect to
+// the handler that turns it on. See ubugeeei-prod/uf#282.
 //
 // 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
@@ -59,6 +122,7 @@
 // `routesModuleSource` keeps the middleware table in an export the client
 // never imports, for the same reason it does that with route handlers.
 
+import { INTERCEPTED_FROM_HEADER, documentPathOf, flightUrl } from "./internal/flight.js";
 import { requireRequest } from "./internal/request.js";
 import type { RouteParams } from "./internal/runtime.js";
 
@@ -70,11 +134,39 @@ export type MiddlewareContext = {|
   readonly searchParams: URLSearchParams,
 |};
 
+/**
+ * What a middleware returns to serve another route at the requested address.
+ *
+ * Built by [`rewrite`] and read by the runner; a class so that the runner can
+ * tell it from a `Response` without trusting the shape of an object.
+ */
+export class Rewrite {
+  readonly destination: string;
+
+  constructor(destination: string) {
+    this.destination = destination;
+  }
+}
+
+/**
+ * Serve `destination` — a path of this application — in place of the path the
+ * request named.
+ *
+ * Relative to the request, so `"/beta/pricing"` and `"../pricing"` both work.
+ * A destination that names no query keeps the request's; one that names a
+ * query replaces it. Another origin is refused when the middleware returns it:
+ * sending a visitor elsewhere is `Response.redirect`, and proxying to another
+ * server is a route handler that fetches.
+ */
+export function rewrite(destination: string | URL): Rewrite {
+  return new Rewrite(typeof destination === "string" ? destination : destination.href);
+}
+
 /** One middleware function. */
 export type Middleware = (
   request: Request,
   context: MiddlewareContext,
-) => Response | void | Promise<Response | void>;
+) => Response | Rewrite | void | Promise<Response | Rewrite | void>;
 
 /** A middleware module, as the generated table loads it. */
 export type MiddlewareModule = { readonly [name: string]: mixed };
@@ -91,7 +183,13 @@ export type MiddlewareRecord = {|
  * 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.
+ * caller's signal to carry on to the handler or the page. Returns a `Request`
+ * when one of them rewrote: the same request at the destination, which the
+ * caller carries on with instead — and which has already been past the
+ * destination's middleware. It also returns a `Request` when a payload request
+ * names a page to render over and that page's guards did not all admit it: the
+ * same request without `uf-intercepted-from`. The host must carry on with that
+ * request and read the header off nothing else, or the decision is undone.
  *
  * 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
@@ -103,7 +201,7 @@ export type MiddlewareRecord = {|
  */
 export function createMiddlewareRunner(options: {|
   readonly middleware: $ReadOnlyArray<MiddlewareRecord>,
-|}): (request: Request) => Promise<Response | null> {
+|}): (request: Request) => Promise<Response | Request | 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.
@@ -111,7 +209,7 @@ export function createMiddlewareRunner(options: {|
     (a, b) => segmentsOf(a.path).length - segmentsOf(b.path).length,
   );
 
-  return async function runMiddleware(request: Request): Promise<Response | null> {
+  return async function runMiddleware(request: Request): Promise<Response | Request | 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
@@ -129,39 +227,193 @@ export function createMiddlewareRunner(options: {|
       return null;
     }
 
-    const url = new URL(request.url);
+    const arrived = new URL(request.url);
+    const document = documentPathOf(arrived.pathname);
+    // The URL the chain is matched against and every middleware is handed: the
+    // document's, for a payload request. See "A payload request is its
+    // document" above.
+    let url = document == null ? arrived : withPathname(arrived, document);
+    let seen = document == null ? request : requestAt(request, url);
+    let rewritten = false;
+    const ran: Set<MiddlewareRecord> = new Set();
 
-    for (const record of table) {
+    for (let index = 0; index < table.length; index += 1) {
+      const record = table[index];
+      if (ran.has(record)) {
+        continue;
+      }
       const params = matchPrefix(record.path, url.pathname);
       if (params == null) {
         continue;
       }
+      ran.add(record);
 
       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
+      // underneath them: `draftMode().isEnabled` is one answer for the whole
+      // request, 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;
+      const result = await middleware(seen, { params, searchParams: url.searchParams });
+      if (result == null) {
+        continue;
+      }
+      if (result instanceof Rewrite) {
+        url = destinationOf(result.destination, url, record.file);
+        seen = requestAt(seen, url);
+        rewritten = true;
+        // From the root again, over what has not run: the destination's guards
+        // are owed their say, and the ones that already had it are not asked
+        // twice.
+        index = -1;
+        continue;
       }
+      return result;
     }
 
-    return null;
+    const admitted: Request | null = !rewritten
+      ? null
+      : document == null
+        ? seen
+        : requestAt(seen, new URL(flightUrl(url.pathname + url.search), url));
+
+    // A payload rendered over another page: that page's guards have their say
+    // too. See "A payload that renders over another page" above.
+    if (document != null && request.headers.has(INTERCEPTED_FROM_HEADER)) {
+      const carried = admitted ?? request;
+      const underneath = interceptionBase(request.headers.get(INTERCEPTED_FROM_HEADER), url);
+      if (underneath == null || !(await guardsAdmit(table, carried, underneath))) {
+        return withoutInterception(carried);
+      }
+    }
+    return admitted;
   };
 }
 
+/**
+ * The page an intercepted payload names in its header, as a URL on `base`'s
+ * origin, or `null` when the value is not a path on this origin.
+ *
+ * The same shape the renderer accepts (`usableInterceptionBase` in `./rsc.js`,
+ * `interceptedFrom` in `@uniflowed/server`): a path, not a network-path
+ * reference, with any fragment dropped. Parsed rather than compared as text,
+ * so the pathname the guards are matched against is the one the renderer's
+ * route matching will read.
+ */
+function interceptionBase(header: string | null, base: URL): URL | null {
+  if (header == null || !header.startsWith("/") || header.startsWith("//")) {
+    return null;
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(header, base);
+  } catch {
+    return null;
+  }
+  if (parsed.origin !== base.origin) {
+    return null;
+  }
+  parsed.hash = "";
+  return parsed;
+}
+
+/**
+ * Whether every middleware guarding `underneath` lets this request see it.
+ *
+ * Each one is asked exactly as it would be asked by a request for that page: a
+ * `GET` at its URL carrying this request's headers, with the params of the
+ * directory it guards and the page's query. All of them, root first, whether
+ * or not they already ran for the URL the request names — a guard that reads
+ * the pathname has so far only been asked about the other one.
+ *
+ * A `Response` is a refusal and so is a `rewrite()`: the page a guard would
+ * serve instead is not the page the header names, and the renderer has no way
+ * to render one under the other. Nothing either returns is sent; the caller
+ * only learns that the page underneath is not this request's to render.
+ */
+async function guardsAdmit(
+  table: $ReadOnlyArray<MiddlewareRecord>,
+  request: Request,
+  underneath: URL,
+): Promise<boolean> {
+  const asked = new Request(underneath.href, { method: "GET", headers: request.headers });
+  for (const record of table) {
+    const params = matchPrefix(record.path, underneath.pathname);
+    if (params == null) {
+      continue;
+    }
+    const middleware = pick(await record.load(), record.file);
+    const result = await middleware(asked, { params, searchParams: underneath.searchParams });
+    if (result != null) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * `request` with its `uf-intercepted-from` header taken off, so the renderer
+ * answers with the page its URL names and nothing underneath it.
+ *
+ * Only a payload request reaches here, and a payload is a `GET` or a `HEAD`,
+ * so there is no body to hand on.
+ */
+function withoutInterception(request: Request): Request {
+  const headers = new Headers(request.headers);
+  headers.delete(INTERCEPTED_FROM_HEADER);
+  return new Request(request.url, { method: request.method, headers, signal: request.signal });
+}
+
+/**
+ * Where a rewrite goes, resolved against the URL the middleware was handed.
+ *
+ * Refused by name when it leaves the origin, because the one thing a rewrite
+ * promises is that this application answers.
+ */
+function destinationOf(destination: string, base: URL, file: string): URL {
+  const next = new URL(destination, base);
+  if (next.origin !== base.origin) {
+    throw new Error(
+      `${file} rewrote ${base.pathname} to ${destination}, which is another origin. A rewrite ` +
+        "serves another route of this application: answer with `Response.redirect` to send the " +
+        "visitor elsewhere, or fetch the other server from a route handler.",
+    );
+  }
+  if (!destination.includes("?")) {
+    next.search = base.search;
+  }
+  next.hash = "";
+  return next;
+}
+
+function withPathname(url: URL, pathname: string): URL {
+  const next = new URL(url.href);
+  next.pathname = pathname;
+  return next;
+}
+
+/**
+ * `request` at another URL: same method, headers, signal and body.
+ *
+ * A `Request` is a valid `RequestInit`, so a streamed body is handed on rather
+ * than read.
+ */
+function requestAt(request: Request, url: URL): Request {
+  // $FlowFixMe[incompatible-call] - a `Request` is read as the `RequestInit` it satisfies.
+  return new Request(url.href, request);
+}
+
 /**
  * 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
+ * being skipped: a file named `$middleware.js` that the router quietly
  * ignored is the bug this whole module exists to stop happening.
  */
 function pick(module: MiddlewareModule, file: string): Middleware {
+  // `rewrite` is an export a middleware module may well import, and is never
+  // the middleware itself.
   const exported = typeof module.default === "function" ? module.default : module.middleware;
   if (typeof exported !== "function") {
     throw new Error(

package/native-navigation.js

@@ -0,0 +1,217 @@
+// @flow
+import * as React from "react";
+import { Pressable } from "react-native";
+import {
+  CommonActions,
+  NavigationContainer,
+  StackActions,
+  createNavigationContainerRef,
+  useRoute,
+} from "@react-navigation/native";
+import { resolveNativeNavigation, createNativeRouter, createNativeLinking } from "./native.js";
+import type { NativeLinkSource } from "./native.js";
+import type { RouteTable } from "./internal/routing.js";
+import type {
+  NativeLayout,
+  NativeNode,
+  NativeTree,
+  NavigationPayload,
+  NavigationState,
+} from "./internal/native-tree.js";
+import { nativeTree, stateForPath, hrefFromState, paramsForPath } from "./internal/native-tree.js";
+
+export interface NavigatorPair {
+  readonly Navigator: React.ComponentType<{ ... }>;
+  readonly Screen: React.ComponentType<{ ... }>;
+}
+export type FileRouter = {
+  readonly push: (href: string) => void,
+  readonly replace: (href: string) => void,
+  readonly back: () => void,
+  readonly prefetch: (href: string) => Promise<void>,
+};
+type Scope = {
+  tree: NativeTree,
+  node: NativeNode,
+  screens: Map<NativeNode, React.ComponentType<{ ... }>>,
+  stack: NavigatorPair,
+  tabs: ?NavigatorPair,
+  router: FileRouter,
+};
+const ScopeContext: React.Context<Scope | null> = React.createContext(null);
+
+function useScope(): Scope {
+  const scope = React.useContext(ScopeContext);
+  if (scope == null)
+    throw new Error(
+      "Native navigation: mount createNativeNavigation().Root before using its navigator or hooks",
+    );
+  return scope;
+}
+
+/** The application supplies its own React Navigation navigator factories. */
+export function createNativeNavigation(options: {
+  table: RouteTable<>,
+  layouts: $ReadOnlyArray<NativeLayout>,
+  stack: NavigatorPair,
+  tabs?: NavigatorPair,
+  initialHref?: string,
+  links?: NativeLinkSource,
+}): { Root: React.ComponentType<{ ... }>, router: FileRouter, linking: { ... } } {
+  const { table, layouts, stack, tabs } = options;
+  const tree = nativeTree(table, layouts);
+  const ref = createNavigationContainerRef();
+  const screens = new Map<NativeNode, React.ComponentType<{ ... }>>();
+  const resolve = (href: string): { names: $ReadOnlyArray<string>, payload: NavigationPayload } => {
+    const event = resolveNativeNavigation(table, href);
+    const names = tree.paths.get(event.route);
+    if (names == null) throw new Error(`Native navigation: no screen for ${event.route}`);
+    return { names, payload: { ufHref: event.href, ufParams: event.params } };
+  };
+  function actionFor(
+    names: $ReadOnlyArray<string>,
+    payload: NavigationPayload,
+    kind: "push" | "replace",
+  ): { readonly [string]: mixed } {
+    if (!ref.isReady()) throw new Error("Native navigation: NavigationContainer is not ready");
+    let state: NavigationState = ref.getRootState();
+    let depth = 0;
+    while (depth < names.length - 1) {
+      const active = state.routes[state.index ?? 0];
+      if (active?.name !== names[depth] || active?.state == null) break;
+      state = active.state;
+      depth += 1;
+    }
+    const name = names[depth];
+    const params = paramsForPath(names.slice(depth + 1), payload);
+    const action =
+      state.type === "stack"
+        ? StackActions[kind](name, params)
+        : CommonActions.navigate({ name, params });
+    return { ...action, target: state.key };
+  }
+  function navigate(href: string, kind: "push" | "replace"): void {
+    const { names, payload } = resolve(href);
+    ref.dispatch(actionFor(names, payload, kind));
+  }
+  const router: FileRouter = {
+    push: (href) => navigate(href, "push"),
+    replace: (href) => navigate(href, "replace"),
+    back: () => {
+      if (ref.canGoBack()) ref.goBack();
+    },
+    prefetch: createNativeRouter(table, {}).prefetch,
+  };
+  const source = options.links == null ? null : createNativeLinking(table, options.links);
+  const linking = {
+    prefixes: [""],
+    getInitialURL: source?.getInitialURL ?? (async () => null),
+    subscribe: source?.subscribe ?? (() => () => {}),
+    getStateFromPath: (href: string) => {
+      const { names, payload } = resolve(
+        href.startsWith("/") || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(href) ? href : `/${href}`,
+      );
+      return stateForPath(names, payload);
+    },
+    getPathFromState: (state: NavigationState) => hrefFromState(state) ?? "/",
+    getActionFromState: (state: NavigationState) => {
+      const href = hrefFromState(state);
+      if (href == null) return undefined;
+      const { names, payload } = resolve(href);
+      return actionFor(names, payload, "push");
+    },
+  };
+  function build(node: NativeNode): React.ComponentType<{ ... }> {
+    const load = node.module;
+    const Content =
+      load == null
+        ? Stack
+        : React.lazy(async () => {
+            const module: $FlowFixMe = await load();
+            const Component = module.default ?? (node.layout ? module.Layout : module.Page);
+            if (
+              typeof Component !== "function" &&
+              (Component == null || typeof Component !== "object")
+            ) {
+              throw new Error(
+                `Native navigation: ${node.name} must export ${node.layout ? "Layout" : "Page"} or default`,
+              );
+            }
+            return { default: Component };
+          });
+    function Screen(props: { ... }): React.Node {
+      return (
+        <ScopeContext value={{ tree, node, screens, stack, tabs, router }}>
+          <React.Suspense fallback={null}>
+            <Content {...props} />
+          </React.Suspense>
+        </ScopeContext>
+      );
+    }
+    screens.set(node, Screen);
+    for (const child of node.children) build(child);
+    return Screen;
+  }
+  const RootScreen = build(tree.root);
+  const initialState =
+    options.initialHref == null ? undefined : linking.getStateFromPath(options.initialHref);
+  function Root(props: { ... }): React.Node {
+    return (
+      <NavigationContainer {...props} ref={ref} linking={linking} initialState={initialState}>
+        <RootScreen />
+      </NavigationContainer>
+    );
+  }
+  return { Root, router, linking };
+}
+
+/** Any React Navigation navigator can consume this segment's direct children. */
+export component Navigator(navigator: NavigatorPair, ...props: { ... }) {
+  const scope = useScope();
+  const Container = navigator.Navigator;
+  const Screen = navigator.Screen;
+  return (
+    <Container {...props}>
+      {scope.node.children.map((node) => (
+        <Screen key={node.name} name={node.name} component={scope.screens.get(node)} />
+      ))}
+    </Container>
+  );
+}
+
+export component Stack(...props: { ... }) {
+  return <Navigator {...props} navigator={useScope().stack} />;
+}
+
+export component Tabs(...props: { ... }) {
+  const tabs = useScope().tabs;
+  if (tabs == null)
+    throw new Error("Native navigation: supply the app's tab navigator to createNativeNavigation");
+  return <Navigator {...props} navigator={tabs} />;
+}
+
+export function useNativeRouter(): FileRouter {
+  return useScope().router;
+}
+export function useParams(): { readonly [string]: string | $ReadOnlyArray<string> } {
+  const route = useRoute();
+  return route.params?.ufParams ?? {};
+}
+
+export component Link(
+  href: string,
+  children: React.Node,
+  replace: boolean = false,
+  ...props: { ... }
+) {
+  const router = useNativeRouter();
+  return (
+    <Pressable
+      {...props}
+      accessibilityRole="link"
+      onPress={() => (replace ? router.replace(href) : router.push(href))}
+    >
+      {children}
+    </Pressable>
+  );
+}