@rangojs/router 0.0.0-experimental.ea6d5eec → 0.0.0-experimental.ea9f40f2

package/src/redirect-origin.ts

@@ -0,0 +1,114 @@
+/**
+ * Runtime-neutral same-origin redirect rule.
+ *
+ * Shared by the client redirect guard (`browser/validate-redirect-origin.ts`,
+ * which validates redirect targets the client JS is about to navigate to) and
+ * the server outgoing-redirect guard (`rsc/redirect-guard.ts`, which validates
+ * every browser-followed `Location` header before it leaves the handler). Kept
+ * at the `src/` root so both layers import the ONE rule and cannot drift -- a
+ * cross-origin target blocked on the JS/fetch path is blocked identically on the
+ * no-JS (PE) and full-page document paths.
+ */
+
+/**
+ * Resolve a redirect target against the current origin.
+ *
+ * Returns the canonical (normalized) same-origin href -- which also collapses
+ * protocol-relative (`//evil.com`) and other ambiguous forms -- or `null` when
+ * the target resolves to a different origin or is unparseable. Pure: no logging,
+ * no side effects.
+ */
+export function resolveSameOriginRedirect(
+  url: string,
+  currentOrigin: string,
+): string | null {
+  try {
+    const target = new URL(url, currentOrigin);
+    if (target.origin !== currentOrigin) {
+      return null;
+    }
+    return target.href;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validate an explicit off-origin redirect target (`redirect(url, { external:
+ * true })`).
+ *
+ * `external` opts out of the same-origin rule, but NOT out of scheme safety:
+ * only `http:`/`https:` targets are allowed. A redirect ultimately reaches the
+ * browser via `window.location.assign()` on the SPA/action client paths, so a
+ * forged or mistaken `redirect("javascript:...", { external: true })` would be a
+ * scriptable navigation if the scheme were not checked here. Returns the
+ * normalized href for an http(s) target (same- or cross-origin), or `null`
+ * otherwise. Pure: no logging, no side effects.
+ */
+export function resolveExternalRedirect(
+  url: string,
+  currentOrigin: string,
+): string | null {
+  try {
+    const target = new URL(url, currentOrigin);
+    if (target.protocol !== "http:" && target.protocol !== "https:") {
+      return null;
+    }
+    return target.href;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The safe same-origin landing for a blocked redirect.
+ *
+ * Every guard that neutralizes a cross-origin/unsafe redirect target sends the
+ * browser here instead: the app's basename root, or `"/"` when unset. Kept
+ * beside the resolvers so the "where does a blocked redirect go" answer lives
+ * in ONE place -- the server 3xx guard (`rsc/redirect-guard.ts`) and the
+ * shell-HIT degradation path (`rsc/rsc-rendering.ts`) must agree, or a blocked
+ * redirect lands differently depending on which exit it took.
+ */
+export function safeSameOriginLanding(basename: string | undefined): string {
+  return basename && basename !== "/" ? basename : "/";
+}
+
+/**
+ * Out-of-band brand for `redirect(url, { external: true })`.
+ *
+ * The external opt-in MUST be settable only by app code calling `redirect(...,
+ * { external: true })`, never by an attacker. An earlier design carried the
+ * opt-in as a wire header (`x-rango-redirect-external`), but a wire header is
+ * forgeable: a proxy-style response route that copies an attacker-controlled
+ * upstream response's headers would let `302 Location: https://evil` plus that
+ * header bypass the same-origin guard without app code ever opting in. So the
+ * opt-in is now an out-of-band brand on the Response object itself, tracked in a
+ * `WeakSet` that cannot cross the wire. `redirect()` brands the Response; the
+ * small set of internal redirect-rebuild paths (middleware `mergeResponse`,
+ * `carryOverRedirectHeaders`, the response-route rewrap) transfer the brand onto
+ * the rebuilt Response; the guard and the SPA intercept read it. An upstream
+ * Response an app proxies is never branded, so its forged header is inert.
+ *
+ * Fail-closed: if a rebuild path ever drops the brand, the redirect is
+ * neutralized to the app root rather than allowed off-host.
+ */
+const externalRedirects = new WeakSet<Response>();
+
+/** Brand a Response as an explicit `{ external: true }` redirect (out-of-band). */
+export function markExternalRedirect(response: Response): void {
+  externalRedirects.add(response);
+}
+
+/** Read the out-of-band `{ external: true }` brand off a Response. */
+export function isExternalRedirect(response: Response): boolean {
+  return externalRedirects.has(response);
+}
+
+/**
+ * Reserved internal header name. No longer a trust signal -- the external
+ * opt-in is the out-of-band brand above. It is kept only so the redirect-rebuild
+ * paths and the guard can defensively strip any value (e.g. one forged by a
+ * proxied upstream) and guarantee it never reaches the browser.
+ */
+export const EXTERNAL_REDIRECT_MARKER: string = "x-rango-redirect-external";

package/src/regex-escape.ts

@@ -0,0 +1,8 @@
+/**
+ * Escape a string for literal use inside a RegExp. Single source of truth for
+ * the router runtime (matching) and the vite build (transform/scan); a pure,
+ * dependency-free leaf so both environments can share it.
+ */
+export function escapeRegExp(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/render-error-thrower.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+interface RenderErrorThrowerProps {
+  error: unknown;
+}
+
+/**
+ * Client component that throws the given error during render, so the nearest
+ * error boundary catches it. Errors thrown during render are caught by error
+ * boundaries; async errors (rejected promises) are not -- which is why the
+ * navigation bridge funnels processing failures through this component instead
+ * of letting them surface as uncaught rejections.
+ */
+export function RenderErrorThrower({
+  error,
+}: RenderErrorThrowerProps): ReactNode {
+  throw error;
+}

package/src/response-utils.ts

@@ -0,0 +1,62 @@
+/**
+ * Runtime-neutral Response shape utilities.
+ *
+ * Kept at the src/ root so both `router/` and `rsc/` can depend on it
+ * without creating a cross-layer import cycle.
+ */
+
+/**
+ * True when a Response represents a WebSocket upgrade handoff and must not
+ * be reconstructed or mutated:
+ *
+ * - Status 101 (Switching Protocols) is outside the standard Response
+ *   constructor's 200–599 range, so `new Response(body, { status: 101 })`
+ *   throws RangeError on Node/undici and any spec-compliant runtime.
+ * - Cloudflare's workerd attaches a non-standard `webSocket` property on
+ *   the upgrade Response (e.g. from `acceptWebSocket`/`handleWebSocketUpgrade`
+ *   or the `agents` library's `routeAgentRequest`). That property is dropped
+ *   by a `new Response(...)` copy, breaking the upgrade even on workerd
+ *   where the status range is relaxed.
+ *
+ * Callers should short-circuit header/body merges for these responses.
+ */
+export function isWebSocketUpgradeResponse(response: Response): boolean {
+  return (
+    response.status === 101 ||
+    (response as unknown as { webSocket?: unknown }).webSocket != null
+  );
+}
+
+/**
+ * Append `Accept` to a response's `Vary` header without duplicating it.
+ *
+ * Content-negotiated responses already carry `Vary: Accept` from the
+ * upstream layer (response-route-handler's callHandlerWithVary, or
+ * handleRscRendering baking `accept` into its vary list). The negotiated
+ * post-append in the handler would otherwise emit `Vary: Accept, Accept`,
+ * a redundant token some proxies/CDNs treat as a distinct cache key.
+ * Token match is case-insensitive (HTTP field tokens are case-insensitive)
+ * and whitespace-tolerant.
+ */
+export function appendVaryAccept(response: Response): void {
+  const existing = response.headers.get("Vary");
+  if (!existing) {
+    response.headers.set("Vary", "Accept");
+    return;
+  }
+  const hasAccept = existing
+    .split(",")
+    .some((token) => token.trim().toLowerCase() === "accept");
+  if (!hasAccept) {
+    response.headers.append("Vary", "Accept");
+  }
+}
+
+// Location truthiness (not presence) so an empty `Location: ""` is not a redirect.
+export function isRedirectResponse(response: Response): boolean {
+  return (
+    response.status >= 300 &&
+    response.status < 400 &&
+    Boolean(response.headers.get("Location"))
+  );
+}

package/src/reverse.ts

@@ -1,6 +1,7 @@
 import type { ExtractParams } from "./types.js";
 import type { SearchSchema, ResolveSearchSchema } from "./search-params.js";
 import { serializeSearchParams } from "./search-params.js";
+import { substitutePatternParams } from "./router/substitute-pattern-params.js";
 
 /**
  * Sanitize prefix string by removing leading slash
@@ -218,6 +219,67 @@ export type ExtractLocalRoutes<TPatterns> = TPatterns extends {
     ? TPatterns
     : Record<string, string>;
 
+/**
+ * Params accepted by `useReverse(routes)`. The route's own params are
+ * required, and additional string keys are permitted so callers can
+ * override values that would otherwise be auto-filled from the matched
+ * route's `useParams()` (e.g. an enclosing `:tenantId` mount segment).
+ */
+export type LocalReverseParams<TPattern extends string> =
+  ExtractParams<TPattern> & {
+    readonly [extra: string]: string | undefined;
+  };
+
+/**
+ * Type-safe local reverse function.
+ *
+ * Returned by `useReverse(routes)` on the client. The route map is the
+ * exposure boundary (a generated `routes` from a `urls()` module) and the
+ * scope is implicit from that import. Names may be written with or without a
+ * leading dot — `reverse("post")` and `reverse(".post")` are identical. The dot
+ * is a cosmetic readability convention (and parity with `ctx.reverse(".name")`);
+ * there is no separate global namespace here, so it carries no meaning.
+ *
+ * @example
+ * ```typescript
+ * const reverse = useReverse(blogRoutes);
+ * reverse("index");                          // ✓ no params (dot optional)
+ * reverse(".index");                         // ✓ identical to the above
+ * reverse("post", { postId: "hello" });      // ✓ with params
+ * reverse("search", {}, { q: "hi" });        // ✓ with search schema
+ * reverse("typo");                           // ✗ compile error
+ * ```
+ */
+export type LocalReverseFunction<TLocalRoutes> = {
+  /**
+   * Route without params (leading dot optional)
+   */
+  <TName extends keyof TLocalRoutes & string>(
+    name: IsEmptyObject<
+      ExtractParams<RoutePatternFor<TLocalRoutes, TName>>
+    > extends true
+      ? TName | `.${TName}`
+      : never,
+  ): string;
+
+  /**
+   * Route with params (leading dot optional)
+   */
+  <TName extends keyof TLocalRoutes & string>(
+    name: TName | `.${TName}`,
+    params: LocalReverseParams<RoutePatternFor<TLocalRoutes, TName>>,
+  ): string;
+
+  /**
+   * Route with params and search (leading dot optional)
+   */
+  <TName extends keyof TLocalRoutes & string>(
+    name: TName | `.${TName}`,
+    params: LocalReverseParams<RoutePatternFor<TLocalRoutes, TName>>,
+    search: ResolveSearchSchema<ExtractSearchSchema<TLocalRoutes, TName>>,
+  ): string;
+};
+
 /**
  * Extract the response data type for a named route from a UrlPatterns instance.
  * Re-exported from urls.ts for consumer convenience.
@@ -301,21 +363,9 @@ export function createReverse<TRoutes extends Record<string, string>>(
       throw new Error(`Unknown route: ${name}`);
     }
 
-    let result = pattern;
-    if (params) {
-      // Replace :param placeholders with actual values
-      // Strip constraint syntax: :param(a|b) -> use "param" as key
-      result = result.replace(
-        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?\??/g,
-        (_, key) => {
-          const value = params[key];
-          if (value === undefined) {
-            throw new Error(`Missing param "${key}" for route "${name}"`);
-          }
-          return encodeURIComponent(value);
-        },
-      );
-    }
+    let result = params
+      ? substitutePatternParams(pattern, params, name)
+      : pattern;
 
     // Append search params as query string
     if (search) {

package/src/root-error-boundary.tsx

@@ -3,26 +3,17 @@
 import { Component, useState, type ReactNode } from "react";
 import type { ClientErrorBoundaryFallbackProps } from "./types.js";
 
-/**
- * Check if an error is a network-related error
- */
 function isNetworkError(error: Error): boolean {
   return error.name === "NetworkError";
 }
 
-/**
- * Network error fallback UI with retry functionality
- * Shows a connection-specific message and allows retrying via page refresh
- */
 function NetworkErrorFallback({
   error,
-  reset,
 }: ClientErrorBoundaryFallbackProps): ReactNode {
   const [isRetrying, setIsRetrying] = useState(false);
 
   const handleRetry = (): void => {
     setIsRetrying(true);
-    // Refresh the page to retry the request
     window.location.reload();
   };
 
@@ -42,7 +33,6 @@ function NetworkErrorFallback({
           marginBottom: "1rem",
         }}
       >
-        {/* Simple cloud with x icon using CSS */}
         <span style={{ color: "#9ca3af" }}>&#9729;</span>
       </div>
       <h1
@@ -101,10 +91,6 @@ function NetworkErrorFallback({
   );
 }
 
-/**
- * Default fallback UI for root error boundary
- * This is shown when an unhandled error bubbles up to the root
- */
 function RootErrorFallback({
   error,
   reset,
@@ -230,7 +216,6 @@ export class RootErrorBoundary extends Component<
   }
 
   componentDidMount(): void {
-    // Listen for popstate (back/forward navigation) to reset error state
     window.addEventListener("popstate", this.handlePopState);
   }
 
@@ -247,15 +232,13 @@ export class RootErrorBoundary extends Component<
   }
 
   componentDidUpdate(prevProps: { children: ReactNode }): void {
-    // Reset error state when children change (e.g., navigation)
-    // This allows the app to recover after navigation away from an errored route
+    // Reset error on children change (navigation).
     if (this.state.hasError && prevProps.children !== this.props.children) {
       this.setState({ hasError: false, error: null });
     }
   }
 
   handlePopState = (): void => {
-    // Reset error state on back/forward navigation
     if (this.state.hasError) {
       this.setState({ hasError: false, error: null });
     }
@@ -276,7 +259,6 @@ export class RootErrorBoundary extends Component<
         segmentType: "route" as const,
       };
 
-      // Use specialized fallback for network errors
       if (isNetworkError(this.state.error)) {
         return <NetworkErrorFallback error={errorInfo} reset={this.reset} />;
       }

package/src/route-content-wrapper.tsx

@@ -1,10 +1,9 @@
 "use client";
 import type { ReactNode } from "react";
-import { Suspense, use, useId } from "react";
-import { invariant } from "./errors";
+import { Suspense, use } from "react";
 import { OutletProvider } from "./outlet-provider.js";
 import type { ResolvedSegment } from "./types.js";
-import { isLoaderDataResult } from "./types.js";
+import { decodeLoaderResults } from "./decode-loader-results.js";
 
 /**
  * Stable async wrapper component for route content
@@ -22,14 +21,12 @@ export function RouteContentWrapper({
   fallback,
   segmentId,
 }: {
-  content: Promise<ReactNode>;
+  // Normally a pending promise (use() suspends -> fallback). forceAwait paths
+  // pass an already-resolved node so Suspender renders it without suspending.
+  content: Promise<ReactNode> | ReactNode;
   fallback?: ReactNode;
   segmentId?: string;
 }): ReactNode {
-  if (!content) {
-    // Already resolved
-    return content as ReactNode;
-  }
   return (
     <Suspense
       fallback={fallback ?? null}
@@ -40,57 +37,20 @@ export function RouteContentWrapper({
   );
 }
 
-export function RouteContentWrapperCallback<T>({
-  resolve,
-  fallback,
-  children,
-}: {
-  resolve: Promise<T> | T;
-  fallback?: ReactNode;
-  children: (data: T) => ReactNode;
-}): ReactNode {
-  const id = useId();
-  invariant(children, "RouteContentWrapperCallback requires children");
-  invariant(
-    typeof children === "function",
-    "RouteContentWrapperCallback requires children to be a function",
-  );
-  invariant(
-    resolve !== undefined,
-    "RouteContentWrapperCallback requires resolve",
-  );
-  return (
-    <Suspense
-      fallback={fallback ?? null}
-      key={"route-content-suspense-callback-" + id}
-    >
-      <SuspenderCallback resolve={resolve} key={id}>
-        {children}
-      </SuspenderCallback>
-    </Suspense>
-  );
-}
-
 const Suspender = ({
   content,
 }: {
   content: Promise<ReactNode> | ReactNode;
 }): ReactNode => {
-  invariant(content instanceof Promise, "Suspender expects a Promise content");
-
-  return use(content);
-};
-
-const SuspenderCallback = <T,>({
-  resolve,
-  children,
-}: {
-  resolve: Promise<T> | T;
-  children: (data: T) => ReactNode;
-}): ReactNode => {
-  return resolve instanceof Promise
-    ? children(use(resolve))
-    : children(resolve);
+  // Normally content is a pending promise -> use() suspends and the wrapping
+  // Suspense shows the loading() fallback. forceAwait paths (popstate,
+  // stale-revalidation, fully-prefetched nav) instead pass the ALREADY-RESOLVED
+  // node so first render does not suspend for a microtask and flash the loading()
+  // fallback on a NORMAL (non-transition) commit. The wrapper tree
+  // (RouteContentWrapper > Suspense > Suspender) is identical either way, so this
+  // preserves tree structure (see docs/tree-structure.md) — only whether use()
+  // suspends differs, exactly like LoaderResolver's resolved-data branch.
+  return content instanceof Promise ? use(content) : content;
 };
 
 /**
@@ -159,28 +119,10 @@ function LoaderResolver({
       ? use(loaderDataPromise)
       : loaderDataPromise;
 
-  // Build loaderData record from resolved values
-  const loaderData: Record<string, any> = {};
-  let loaderErrorFallback: ReactNode = null;
-
-  loaderIds.forEach((id, i) => {
-    const result = resolvedData[i];
-
-    if (isLoaderDataResult(result)) {
-      if (result.ok) {
-        loaderData[id] = result.data;
-      } else {
-        if (result.fallback) {
-          loaderErrorFallback = result.fallback;
-        } else {
-          throw new Error(result.error.message);
-        }
-      }
-    } else {
-      // Legacy format - direct data
-      loaderData[id] = result;
-    }
-  });
+  const { loaderData, errorFallback } = decodeLoaderResults(
+    resolvedData,
+    loaderIds,
+  );
 
   return (
     <OutletProvider
@@ -190,7 +132,7 @@ function LoaderResolver({
       parallel={parallel}
       loaderData={Object.keys(loaderData).length > 0 ? loaderData : undefined}
     >
-      {loaderErrorFallback ?? children}
+      {errorFallback ?? children}
     </OutletProvider>
   );
 }