@uniflowed/router 0.0.0-alpha.40 → 0.0.0-alpha.41

package/handler.js

@@ -71,6 +71,7 @@
 
 import { asResponder, noteRoute } from "@uniflowed/server/host";
 
+import { matchRoute } from "./internal/routing.js";
 import { requireRequest } from "./internal/request.js";
 import type { RouteParams } from "./internal/runtime.js";
 
@@ -135,61 +136,55 @@ export const HANDLER_METHODS: $ReadOnlyArray<string> = Object.freeze([
 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));
+  const table = [...options.handlers];
 
   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;
-      }
-
-      // Before the module is loaded and before the method is checked, because
-      // this is the answer to "what was this request" and a `405` is as much
-      // this route's answer as a `200` is. A log of `/api/users/:id 405` is
-      // actionable; the same line with the path in it is a million lines.
-      noteRoute(record.path);
-
-      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.
-      //
-      // And inside `asResponder`, which is the other half: a route handler is
-      // one of the two things that owns a response, so it is one of the two
-      // places `draftMode().enable()` is allowed — and the `Set-Cookie` it
-      // decided on is written onto the response below rather than left on an
-      // object the host is about to discard. See ubugeeei-prod/uf#282.
-      const response = await asResponder("a route handler", async () =>
-        handler(request, { params, searchParams: url.searchParams }),
-      );
+    const match = matchRoute(table, url.pathname);
+    if (match == null) return null;
+    const { route: record, params } = match;
+
+    // Before the module is loaded and before the method is checked, because
+    // this is the answer to "what was this request" and a `405` is as much
+    // this route's answer as a `200` is. A log of `/api/users/:id 405` is
+    // actionable; the same line with the path in it is a million lines.
+    noteRoute(record.path);
+
+    const module = await record.load();
+    const method = request.method.toUpperCase();
+    const handler = pick(module, method);
+    if (handler == null) {
+      return methodNotAllowed(module);
+    }
 
-      // 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;
+    // 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.
+    //
+    // And inside `asResponder`, which is the other half: a route handler is
+    // one of the two things that owns a response, so it is one of the two
+    // places `draftMode().enable()` is allowed — and the `Set-Cookie` it
+    // decided on is written onto the response below rather than left on an
+    // object the host is about to discard. See ubugeeei-prod/uf#282.
+    const response = await asResponder("a route handler", async () =>
+      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 null;
+    return response;
   };
 }
 
@@ -234,61 +229,3 @@ function methodNotAllowed(module: HandlerModule): Response {
     headers: { allow: HANDLER_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/http-client.js

@@ -0,0 +1,104 @@
+// @flow
+import {
+  ACTION_CONTENT_TYPE,
+  ACTION_HEADER,
+  decodeActionResult,
+  encodeActionArguments,
+  isActionId,
+  type ActionValue,
+} from "./internal/action-wire.js";
+
+export type RouteClientOptions = {|
+  readonly origin: string,
+  readonly getToken?: () => Promise<string>,
+  readonly fetch?: (url: string, options: RequestOptions) => Promise<Response>,
+  readonly allowInsecureDevelopment?: boolean,
+|};
+
+export type RouteRequest = {|
+  readonly method?: string,
+  readonly headers?: { readonly [string]: string },
+  readonly body?: string,
+  readonly signal?: AbortSignal,
+|};
+
+type RequestOptions = {|
+  ...RouteRequest,
+  readonly credentials: "omit",
+  readonly redirect: "error",
+|};
+
+/** Fetch transport shared by generated typed route clients and native actions. */
+export function createRouteClient(
+  options: RouteClientOptions,
+): (path: string, request?: RouteRequest) => Promise<Response> {
+  const origin = new URL(options.origin);
+  if (
+    origin.username ||
+    origin.password ||
+    origin.pathname !== "/" ||
+    origin.search ||
+    origin.hash
+  ) {
+    throw new TypeError("createRouteClient origin must contain only a scheme and host");
+  }
+  const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(origin.hostname);
+  if (
+    origin.protocol !== "https:" &&
+    !(origin.protocol === "http:" && (loopback || options.allowInsecureDevelopment === true))
+  ) {
+    throw new TypeError(
+      "createRouteClient requires HTTPS outside explicit development connections",
+    );
+  }
+  const send = options.fetch ?? globalThis.fetch;
+  return async (path, request = {}) => {
+    if (!path.startsWith("/") || path.startsWith("//") || path.includes("\\")) {
+      throw new TypeError("route client needs a same-origin absolute path");
+    }
+    const url = new URL(path, origin);
+    if (url.origin !== origin.origin) throw new TypeError("route client cannot change origin");
+    const headers: { [string]: string } = {};
+    for (const [name, value] of Object.entries(request.headers ?? {})) {
+      const lower = name.toLowerCase();
+      if (
+        ["cookie", "authorization", "origin", "host"].includes(lower) ||
+        lower.startsWith("sec-fetch-")
+      ) {
+        throw new TypeError(`route client does not accept the ${name} header`);
+      }
+      if (typeof value !== "string") throw new TypeError(`route header ${name} must be a string`);
+      headers[name] = value;
+    }
+    if (options.getToken != null) {
+      const token = await options.getToken();
+      if (!/^[A-Za-z0-9\-._~+/]+=*$/.test(token) || token.length > 8192) {
+        throw new TypeError("route client received an invalid bearer credential");
+      }
+      headers.authorization = `Bearer ${token}`;
+    }
+    return send(url.href, { ...request, headers, credentials: "omit", redirect: "error" });
+  };
+}
+
+/** Explicit action channel for clients holding application-issued bearer tokens. */
+export function createNativeActionClient(options: {|
+  ...RouteClientOptions,
+  readonly getToken: () => Promise<string>,
+|}): (id: string, args: $ReadOnlyArray<mixed>, path?: string) => Promise<ActionValue | void> {
+  const send = createRouteClient(options);
+  return async (id, args, path = "/") => {
+    if (!isActionId(id)) throw new TypeError("native action needs an ID from the current build");
+    const response = await send(path, {
+      method: "POST",
+      headers: {
+        [ACTION_HEADER]: id,
+        "uf-native-action": "bearer-v1",
+        "content-type": ACTION_CONTENT_TYPE,
+      },
+      body: encodeActionArguments(args),
+    });
+    if (!response.ok) throw new Error(`Native action failed with status ${response.status}`);
+    return decodeActionResult(await response.text());
+  };
+}

package/index.js

@@ -89,6 +89,7 @@ export {
   splitUrl,
   unauthorized,
   useIsServer,
+  useLinkStatus,
   useLoaderData,
   useRoute,
   useRouter,

package/internal/action-endpoint.js

@@ -88,7 +88,7 @@
 // it. Written here because this is the file somebody reads before deciding
 // otherwise.
 
-import { asResponder } from "@uniflowed/server/host";
+import { asResponder, nativeActionAllowed } from "@uniflowed/server/host";
 
 import {
   ACTION_CONTENT_TYPE,
@@ -163,7 +163,8 @@ export function createActionDispatcher(options: {|
     if (request.method.toUpperCase() !== "POST") {
       return new Response(null, { status: 405, headers: { ...ANSWER_HEADERS, allow: "POST" } });
     }
-    if (!sameOrigin(request)) {
+    const native = request.headers.has("uf-native-action");
+    if (native ? !nativeActionAllowed(request) : !sameOrigin(request)) {
       return refusal(403);
     }
     if (!isJson(request.headers.get("content-type"))) {

package/internal/flight-browser.js

@@ -28,7 +28,9 @@ import { createFromFetch, createFromReadableStream } from "react-server-dom-parc
 import { FLIGHT_CHUNK_ATTRIBUTE, flightChunkBytes } from "./flight-chunks.js";
 import {
   FLIGHT_CONTENT_TYPE,
+  INTERCEPTED_FROM_HEADER,
   type FetchedFlight,
+  type FlightFetchOptions,
   type FlightRoot,
   documentPathOf,
   flightUrl,
@@ -186,16 +188,24 @@ export function readDocumentPayload(
  * static host's `404.html` for a file it does not have, a middleware's own
  * refusal — is a document, whatever its status.
  */
-export async function fetchFlight(url: string): Promise<FetchedFlight> {
+export async function fetchFlight(
+  url: string,
+  options?: FlightFetchOptions,
+): Promise<FetchedFlight> {
   // Outside the `try` below, which answers every failure to fetch with a
   // document load: too old a React is not a network failure, and a navigation
   // that quietly reloaded the page would hide it.
   requireServerComponentsReact(ENTRY);
+  const headers = new Headers({ accept: FLIGHT_CONTENT_TYPE });
+  const interceptedFrom = options?.interceptedFrom;
+  if (interceptedFrom != null) {
+    headers.set(INTERCEPTED_FROM_HEADER, interceptedFrom);
+  }
   let response: Response;
   try {
     response = await fetch(flightUrl(url), {
       credentials: "same-origin",
-      headers: { accept: FLIGHT_CONTENT_TYPE },
+      headers,
     });
   } catch {
     // A request that could not be made or followed: a dropped connection, or a

package/internal/flight.js

@@ -52,6 +52,7 @@ export type RouteState = {|
   readonly viewTransition: ?string,
   readonly status: 200 | 401 | 403 | 404 | 500,
   readonly error: ?RouteError,
+  readonly interception?: ?FlightInterception,
 |};
 
 /** Row 0 of a route's payload: the route, and the tree it rendered. */
@@ -60,6 +61,18 @@ export type FlightRoot = {|
   readonly tree: Node,
 |};
 
+/** The intercepted URL a Flight payload rendered, and the page it rendered over. */
+export type FlightInterception = {|
+  readonly pathname: string,
+  readonly search: string,
+  readonly from: string,
+|};
+
+/** What the browser may send with a payload request. */
+export type FlightFetchOptions = {|
+  readonly interceptedFrom?: string,
+|};
+
 /**
  * What fetching a route's payload turned into.
  *
@@ -88,6 +101,7 @@ export type FetchedFlight =
 
 /** The part of a resolved route that crosses to the browser. */
 export function routeState(resolved: ResolvedRoute): RouteState {
+  const interception = resolved.interception;
   return {
     pathname: resolved.pathname,
     search: resolved.search,
@@ -100,6 +114,14 @@ export function routeState(resolved: ResolvedRoute): RouteState {
     viewTransition: resolved.viewTransition,
     status: resolved.status,
     error: resolved.error,
+    interception:
+      interception == null
+        ? null
+        : {
+            pathname: interception.pathname,
+            search: interception.search,
+            from: interception.base.pathname + interception.base.search,
+          },
   };
 }
 
@@ -123,6 +145,9 @@ export const FLIGHT_SEGMENT: string = "__uf.flight";
 /** The content type a payload is answered with. */
 export const FLIGHT_CONTENT_TYPE: string = "text/x-component";
 
+/** The request header that carries the page an intercepted payload is rendered over. */
+export const INTERCEPTED_FROM_HEADER: string = "uf-intercepted-from";
+
 /**
  * The URL of `url`'s payload: its pathname with [`FLIGHT_SEGMENT`] appended,
  * and its query string unchanged.

package/internal/native-links.js

@@ -0,0 +1,67 @@
+// @flow
+import type { RouteTable } from "./routing.js";
+import { hasClientPage, matchRoute } from "./routing.js";
+
+type Table = RouteTable<mixed, mixed, mixed, mixed, mixed>;
+
+/** One parser for cold starts, warm deliveries and programmatic navigation. */
+export function nativeLinkHref(table: Table, to: string): string | null {
+  const links = table.nativeLinks;
+  if (links == null || !/^https:\/\//i.test(to) || /[\\\u0000-\u0020]/.test(to)) return null;
+  try {
+    const url = new URL(to);
+    if (url.username !== "" || url.password !== "" || url.hash !== "") return null;
+    // URL does not reject malformed percent escapes. Encoded separators must
+    // not change the route when another layer decodes the path a second time.
+    decodeURIComponent(url.pathname + url.search);
+    if (/%(?:2f|5c)/i.test(url.pathname)) return null;
+    if (!links.origins.some((origin) => new URL(origin).origin === url.origin)) return null;
+    const match = matchRoute(table.routes, url.pathname);
+    if (match == null || !hasClientPage(match.route) || !links.routes.includes(match.route.path))
+      return null;
+    return url.pathname + url.search;
+  } catch {
+    return null;
+  }
+}
+
+export type NativeLinkSource = {|
+  readonly getInitialURL: () => Promise<string | null>,
+  readonly addEventListener: (
+    event: "url",
+    listener: (event: {| url: string |}) => void,
+  ) => {| remove: () => void |},
+|};
+
+/** Pass React Native's Linking; rejected links stay with the OS/browser. */
+export function createNativeLinking(
+  table: Table,
+  source: NativeLinkSource,
+): {|
+  getInitialURL: () => Promise<string | null>,
+  subscribe: (listener: (href: string) => void) => () => void,
+|} {
+  let last: string | null = null;
+  let deliveredAt = -Infinity;
+  function receive(url: string): string | null {
+    const href = nativeLinkHref(table, url);
+    const now = Date.now();
+    if (href == null || (href === last && now - deliveredAt < 1000)) return null;
+    last = href;
+    deliveredAt = now;
+    return href;
+  }
+  return {
+    async getInitialURL() {
+      const url = await source.getInitialURL();
+      return url == null ? null : receive(url);
+    },
+    subscribe(listener) {
+      const subscription = source.addEventListener("url", ({ url }) => {
+        const href = receive(url);
+        if (href != null) listener(href);
+      });
+      return () => subscription.remove();
+    },
+  };
+}

package/internal/native-tree.js

@@ -0,0 +1,89 @@
+// @flow
+import type { RouteModule, RouteTable } from "./routing.js";
+
+export type NativeLayout = {
+  readonly segment: string,
+  readonly file: string,
+  readonly module: RouteModule<>,
+};
+export type NativeNode = {
+  name: string,
+  module: ?RouteModule<>,
+  layout: boolean,
+  children: Array<NativeNode>,
+};
+export type NativeTree = { root: NativeNode, paths: Map<string, $ReadOnlyArray<string>> };
+
+/** Module identity comes from the generated table; group names never become URLs. */
+export function nativeTree(table: RouteTable<>, layouts: $ReadOnlyArray<NativeLayout>): NativeTree {
+  const rootLayout = layouts.find((layout) => layout.segment === "/");
+  const root: NativeNode = { name: "root", module: rootLayout?.module, layout: true, children: [] };
+  const metadata = new Map(layouts.map((layout) => [layout.module, layout]));
+  const paths = new Map<string, $ReadOnlyArray<string>>();
+  for (const route of table.routes) {
+    if (route.page == null) continue;
+    let parent = root;
+    const path = [];
+    for (const load of route.layouts) {
+      if (load === rootLayout?.module) continue;
+      const layout = metadata.get(load);
+      if (layout == null)
+        throw new Error(`Native navigation: missing layout metadata for ${route.path}`);
+      const name = `layout:${layout.segment}`;
+      let child = parent.children.find((node) => node.name === name);
+      if (child == null) {
+        child = { name, module: load, layout: true, children: [] };
+        parent.children.push(child);
+      }
+      parent = child;
+      path.push(name);
+    }
+    parent.children.push({ name: route.path, module: route.page, layout: false, children: [] });
+    path.push(route.path);
+    paths.set(route.path, path);
+  }
+  return { root, paths };
+}
+
+export type NavigationPayload = {
+  readonly ufHref: string,
+  readonly ufParams: { readonly [string]: string | $ReadOnlyArray<string> },
+};
+export type NavigationState = {
+  readonly key?: string,
+  readonly type?: string,
+  readonly index?: number,
+  readonly routes: $ReadOnlyArray<{
+    readonly name: string,
+    readonly params?: NavigationPayload,
+    readonly state?: NavigationState,
+  }>,
+};
+
+export function stateForPath(
+  names: $ReadOnlyArray<string>,
+  payload: NavigationPayload,
+): NavigationState {
+  const [name, ...rest] = names;
+  if (name == null) throw new Error("Native navigation: an empty screen path cannot be opened");
+  return {
+    routes: [
+      {
+        name,
+        ...(rest.length === 0 ? { params: payload } : { state: stateForPath(rest, payload) }),
+      },
+    ],
+  };
+}
+
+export function hrefFromState(state: NavigationState): string | null {
+  const route = state.routes[state.index ?? state.routes.length - 1];
+  if (route == null) return null;
+  return route.state == null ? (route.params?.ufHref ?? null) : hrefFromState(route.state);
+}
+
+/** React Navigation's nested navigate payload, separate from user route params. */
+export function paramsForPath(names: $ReadOnlyArray<string>, payload: NavigationPayload): mixed {
+  const [screen, ...rest] = names;
+  return screen == null ? payload : { screen, params: paramsForPath(rest, payload) };
+}

package/internal/navigation-cache.js

@@ -61,6 +61,12 @@ let staleTimeMs: number = 0;
  */
 export function installStaleTime(seconds: number): void {
   staleTimeMs = Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : 0;
+  if (import.meta.hot != null) {
+    Object.defineProperty((globalThis: $FlowFixMe), "__UF_NAVIGATION_CACHE__", {
+      configurable: true,
+      value: inspectNavigationCache,
+    });
+  }
   if (staleTimeMs === 0) {
     clearNavigationCache();
   }
@@ -87,6 +93,15 @@ export type NavigationCache<T> = {|
   readonly clear: () => void,
   /** How many routes are kept, fresh or not. */
   readonly size: () => number,
+  readonly inspect: () => $ReadOnlyArray<NavigationCacheEntry>,
+|};
+
+/** Metadata only: inspecting the cache never exposes loader or Flight data. */
+export type NavigationCacheEntry = {|
+  readonly key: string,
+  readonly cachedAt: number,
+  readonly staleAt: number,
+  readonly fresh: boolean,
 |};
 
 function createNavigationCache<T>(): NavigationCache<T> {
@@ -128,6 +143,15 @@ function createNavigationCache<T>(): NavigationCache<T> {
     size() {
       return entries.size;
     },
+    inspect() {
+      const now = Date.now();
+      return Array.from(entries, ([key, entry]) => ({
+        key,
+        cachedAt: entry.at,
+        staleAt: entry.at + staleTimeMs,
+        fresh: now - entry.at < staleTimeMs,
+      }));
+    },
   };
 }
 
@@ -137,6 +161,19 @@ export const flightNavigations: NavigationCache<Promise<FetchedFlight>> = create
 /** Resolved routes, for an application rendered from its modules. */
 export const routeNavigations: NavigationCache<Promise<ResolvedRoute>> = createNavigationCache();
 
+/** A fresh snapshot for the development console, without reading an entry. */
+export function inspectNavigationCache(): {|
+  readonly staleTime: number,
+  readonly flight: $ReadOnlyArray<NavigationCacheEntry>,
+  readonly routes: $ReadOnlyArray<NavigationCacheEntry>,
+|} {
+  return {
+    staleTime: staleTimeMs / 1000,
+    flight: flightNavigations.inspect(),
+    routes: routeNavigations.inspect(),
+  };
+}
+
 /** Forget every kept route. `router.refresh()` and each server action call this. */
 export function clearNavigationCache(): void {
   flightNavigations.clear();

package/internal/resolve.js

@@ -1043,15 +1043,13 @@ export function interceptingRoutes(
  * something to show for one URL, the way two slots each match one URL by their
  * own routes.
  *
- * # Never on a server
+ * # Never for a document
  *
- * Nothing on the server calls this. A document request for an intercepted URL
- * resolves the ordinary page, because a request carries where it is going and
- * not what was on screen when it was made — which is what a reload, a shared
- * link and a crawler all are. That includes the Flight renderer, so a browser
- * holding a payload rather than a resolved route navigates to the page the URL
- * names: interception is a feature of the router that resolves routes from
- * their modules.
+ * A document request for an intercepted URL resolves the ordinary page,
+ * because a request carries where it is going and not what was on screen when
+ * it was made — which is what a reload, a shared link and a crawler all are.
+ * A Flight payload request may carry the page the browser is navigating from,
+ * and the React Server Components renderer calls this for that request only.
  *
  * # When the interception cannot render
  *

package/internal/routing.js

@@ -139,6 +139,10 @@ export type RouteTable<
   TError = mixed,
 > = {|
   readonly routes: $ReadOnlyArray<RouteRecord<TPage, TLayout, TTemplate, TLoading, TError>>,
+  readonly nativeLinks?: {|
+    readonly origins: $ReadOnlyArray<string>,
+    readonly routes: $ReadOnlyArray<string>,
+  |},
   readonly notFound: $ReadOnlyArray<NotFoundBoundary<TPage, TLayout>>,
   readonly errors: $ReadOnlyArray<ErrorBoundary<TError, TLayout>>,
 |};