@rangojs/router 0.0.0-experimental.e16b7c00 → 0.0.0-experimental.e9c0b2f2

package/src/rsc/helpers.ts

@@ -11,7 +11,31 @@ import {
 import type { RequestContext } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
 import { isRedirectResponse } from "../response-utils.js";
+import {
+  EXTERNAL_REDIRECT_MARKER,
+  isExternalRedirect,
+  markExternalRedirect,
+} from "../redirect-origin.js";
 import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
+import { formatCacheSignalHeader } from "../router/telemetry.js";
+import type { RscPayload } from "./types.js";
+
+/**
+ * DEVELOPMENT/TEST ONLY. When the debug cache signal gate is on,
+ * match/matchPartial populate ctx._cacheSignal. Emit it as the X-Rango-Cache
+ * header. When the gate is off, ctx._cacheSignal is undefined and NOTHING is
+ * attached — output is byte-identical to the default. Header mutation failures
+ * are swallowed so immutable Response headers (e.g. protocol-switch) are safe.
+ */
+function applyCacheSignalHeader(target: Headers, ctx: RequestContext): void {
+  const signal = ctx._cacheSignal;
+  if (!signal || signal.length === 0) return;
+  try {
+    target.set("X-Rango-Cache", formatCacheSignalHeader(signal));
+  } catch {
+    // Headers immutable — skip.
+  }
+}
 
 /**
  * Copy stub headers from the request context onto a target Headers instance:
@@ -22,6 +46,10 @@ import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
 function applyStubHeaders(target: Headers, stub: Headers): void {
   stub.forEach((value, name) => {
     try {
+      // The reserved external-redirect marker is internal and never a trust
+      // signal; never copy a stub value (e.g. a stray ctx.header() call) onto a
+      // browser-facing response. The opt-in is the out-of-band brand.
+      if (name.toLowerCase() === EXTERNAL_REDIRECT_MARKER) return;
       if (name.toLowerCase() === "set-cookie") {
         target.append(name, value);
       } else if (!target.has(name)) {
@@ -37,18 +65,33 @@ function applyStubHeaders(target: Headers, stub: Headers): void {
  * Drain ctx._onResponseCallbacks onto a response. Swapping the array before
  * iteration prevents re-entrant registrations from double-firing and matches
  * the contract that each callback runs at most once per request.
+ *
+ * Exported so the testing primitives' buildRunResponse can reuse the exact
+ * production drain (swap-before-iterate + external-redirect brand preservation)
+ * rather than maintain a hand-synced copy. This module is plugin-rsc-free on its
+ * eager graph (dispatch.ts already statically imports from here in the same
+ * testing barrel), so importing it adds nothing to the unit runner's graph.
  */
-function drainOnResponseCallbacks(
+export function drainOnResponseCallbacks(
   ctx: RequestContext,
   response: Response,
 ): Response {
   const callbacks = ctx._onResponseCallbacks;
   if (callbacks.length === 0) return response;
   ctx._onResponseCallbacks = [];
+  // An onResponse callback may return a NEW Response (e.g. to add a header),
+  // which drops the out-of-band external-redirect brand (brand is keyed on
+  // Response object identity). Preserve a redirect(url, { external: true })
+  // opt-in across that rebuild so a callback can't silently neutralize the
+  // off-host redirect at the guard chokepoint.
+  const wasExternal = isExternalRedirect(response);
   let result = response;
   for (const callback of callbacks) {
     result = callback(result) ?? result;
   }
+  if (wasExternal && !isExternalRedirect(result)) {
+    markExternalRedirect(result);
+  }
   return result;
 }
 
@@ -85,6 +128,7 @@ export function createResponseWithMergedHeaders(
   const mergedHeaders = new Headers(init.headers);
   applyStubHeaders(mergedHeaders, ctx.res.headers);
   ctx.res.headers.delete("set-cookie");
+  applyCacheSignalHeader(mergedHeaders, ctx);
 
   // ctx.res.status overrides init.status when explicitly set (e.g. 404 for
   // notFound, 500 for error). Default ctx.res.status is 200.
@@ -115,8 +159,20 @@ export function createSimpleRedirectResponse(redirectUrl: string): Response {
 
 /**
  * Carry over headers from a source redirect Response to a wrapper Response.
- * Skips Location and X-RSC-Redirect (intentionally replaced by the wrapper)
- * and appends Set-Cookie to avoid clobbering multiple cookie headers.
+ * Skips Location and X-RSC-Redirect (intentionally replaced by the wrapper) and
+ * appends Set-Cookie to avoid clobbering multiple cookie headers.
+ *
+ * This is a GENERIC copier used by every redirect-rebuild path (PE
+ * extractRedirectResponse, the SPA intercept below, the guard's neutralize
+ * rebuild), so it has two redirect-specific jobs:
+ *
+ * 1. NEVER copy the reserved external-redirect header: it is no longer a trust
+ *    signal (the opt-in is the out-of-band brand), and a forged value from a
+ *    proxied upstream must not ride a rebuilt response to the browser.
+ * 2. Transfer the out-of-band external brand: a rebuilt document-native redirect
+ *    has to carry the opt-in to the guard chokepoint, which reads and clears it.
+ *    Without this transfer, redirect(url, { external: true }) would be silently
+ *    neutralized on any rebuild path (fail-closed, but a feature regression).
  */
 export function carryOverRedirectHeaders(
   source: Response,
@@ -125,12 +181,16 @@ export function carryOverRedirectHeaders(
   source.headers.forEach((value, name) => {
     const lower = name.toLowerCase();
     if (lower === "location" || lower === "x-rsc-redirect") return;
+    if (lower === EXTERNAL_REDIRECT_MARKER) return;
     if (lower === "set-cookie") {
       target.headers.append(name, value);
     } else if (!target.headers.has(name)) {
       target.headers.set(name, value);
     }
   });
+  if (isExternalRedirect(source)) {
+    markExternalRedirect(target);
+  }
 }
 
 /**
@@ -144,28 +204,62 @@ export function interceptRedirectForPartial(
   createRedirectFlightResponse: (
     redirectUrl: string,
     locationState?: Record<string, unknown>,
+    external?: boolean,
   ) => Response,
 ): Response | null {
   if (!isRedirectResponse(response)) {
     return null;
   }
   const redirectUrl = response.headers.get("Location")!;
+  // redirect(url, { external: true }) marks an explicit off-host redirect via
+  // the out-of-band brand (not a wire header). On the SPA/action channel the
+  // intent must travel as a Flight payload (metadata.redirect.external) so the
+  // client does a scheme-validated hard navigation (location.assign) rather than
+  // a partial fetch. The client re-validates the scheme; see partial-update.ts.
+  const external = isExternalRedirect(response);
   const locationState = getLocationState();
   let intercepted: Response;
   if (locationState) {
     intercepted = createRedirectFlightResponse(
       redirectUrl,
       resolveLocationStateEntries(locationState),
+      external,
     );
+  } else if (external) {
+    intercepted = createRedirectFlightResponse(redirectUrl, undefined, true);
   } else {
     intercepted = createSimpleRedirectResponse(redirectUrl);
   }
 
   carryOverRedirectHeaders(response, intercepted);
+  // Defense-in-depth at the SPA browser-facing exit: carryOverRedirectHeaders
+  // already refuses to copy the reserved marker, but strip any value that might
+  // exist on `intercepted` so a forged header can never ride the 200/204 to the
+  // browser. The external intent travels in metadata.redirect.external (Flight),
+  // where the client re-validates the scheme.
+  try {
+    intercepted.headers.delete(EXTERNAL_REDIRECT_MARKER);
+  } catch {
+    // Immutable headers: the marker was never copied here, so this is inert.
+  }
 
   return intercepted;
 }
 
+/**
+ * Attach location state set during a request to a payload's metadata.
+ * No-op if no location state was set. Callers must ensure payload.metadata
+ * is populated (the non-null assertion holds for the partial/action payloads
+ * that reach this helper).
+ */
+export function attachLocationStateIfPresent(payload: RscPayload): void {
+  const locationState = getLocationState();
+  if (locationState) {
+    payload.metadata!.locationState =
+      resolveLocationStateEntries(locationState);
+  }
+}
+
 /**
  * Only cache successful responses. Non-200 statuses (errors, redirects) are
  * not cached -- notFound() produces 500 in response routes, and explicit
@@ -192,7 +286,6 @@ export function buildRouteMiddlewareEntries<TEnv>(
       regex: null,
       paramNames: [],
       handler: mw.handler,
-      mountPrefix: null,
     } as MiddlewareEntry<TEnv>,
     params: mw.params,
   }));

package/src/rsc/index.ts

@@ -30,7 +30,4 @@ export type {
 } from "./types.js";
 
 // Re-export request context utilities for server-side access to env/request/params
-export {
-  getRequestContext,
-  requireRequestContext,
-} from "../server/request-context.js";
+export { getRequestContext } from "../server/request-context.js";

package/src/rsc/json-route-result.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared serialization for `json()` response-route results.
+ *
+ * Kept in its own lightweight module (depends only on `errors.js`) so the
+ * `dispatch()` testing primitive can import it WITHOUT dragging in
+ * `response-route-handler.ts`'s heavy runtime graph, which transitively reaches
+ * a Vite virtual module and breaks a plain (non-Vite) vitest import.
+ */
+
+import { RouterError } from "../errors.js";
+
+/**
+ * Serialize a `json()` response-route result, rejecting a nested unresolved
+ * Promise (the forgotten-await footgun: `() => ({ data: fetchSomething() })`).
+ * `JSON.stringify` would silently emit `{}` for a Promise, shipping empty data;
+ * the RSC pipeline awaits nested promises but this path does not. Throwing
+ * `RESPONSE_NOT_SERIALIZABLE` makes the failure loud.
+ *
+ * Shared by the production response-route handler and the `dispatch()` testing
+ * primitive so a `dispatch` json test of a forgotten await fails exactly where
+ * production 500s, instead of going green.
+ */
+export function stringifyJsonRouteResult(result: unknown): string {
+  return JSON.stringify(result, (_key, value) => {
+    if (
+      value != null &&
+      typeof (value as { then?: unknown }).then === "function"
+    ) {
+      throw new RouterError(
+        "RESPONSE_NOT_SERIALIZABLE",
+        "A json() response route returned a Promise (likely a forgotten " +
+          "await). Await async values before returning so they serialize, " +
+          "instead of emitting an empty {}.",
+      );
+    }
+    return value;
+  });
+}

package/src/rsc/loader-fetch.ts

@@ -12,8 +12,10 @@
  */
 
 import { getLoaderLazy } from "../server/loader-registry.js";
+import { DataNotFoundError } from "../errors.js";
 import { executeLoaderMiddleware } from "../router/middleware.js";
-import { requireRequestContext } from "../server/request-context.js";
+import { getRequestContext } from "../server/request-context.js";
+import { observePhase, PHASES } from "../router/instrument.js";
 import {
   createReverseFunction,
   stripInternalParams,
@@ -30,6 +32,62 @@ import {
 } from "./helpers.js";
 import type { HandlerContext } from "./handler-context.js";
 
+/**
+ * Build the 500 RSC error Response for a failed fetchable loader. Shared by the
+ * module-load-error catch (the import itself threw) and the loader-execution
+ * error catch — both call onError("loader"), serialize the same dev-gated error
+ * payload via renderToReadableStream (reporting render failures through
+ * onError("rendering")), and return a 500 text/x-component Response. The only
+ * per-site difference is the console.error label, passed in.
+ */
+function buildLoaderErrorResponse<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  error: unknown,
+  meta: { request: Request; url: URL; env: TEnv; loaderId: string },
+  logLabel: string,
+): Response {
+  const { request, url, env, loaderId } = meta;
+  const isDev = process.env.NODE_ENV !== "production";
+
+  console.error(logLabel, error);
+
+  ctx.callOnError(error, "loader", {
+    request,
+    url,
+    env,
+    loaderName: loaderId,
+    handledByBoundary: false,
+  });
+
+  const err = error instanceof Error ? error : new Error(String(error));
+  const errorPayload = {
+    loaderResult: null,
+    loaderError: {
+      message: isDev ? err.message : "An error occurred",
+      // Gate err.name to dev. In production it leaks the consumer's error class
+      // name (e.g. AuthError, PrismaClientKnownRequestError) to the client; the
+      // client only ever reads `message`, so the field is dead data outside dev.
+      // Matches sanitizeError's dev-only name contract.
+      name: isDev ? err.name : "Error",
+    },
+  };
+  const rscStream = ctx.renderToReadableStream(errorPayload, {
+    onError: (renderError: unknown) => {
+      ctx.callOnError(renderError, "rendering", {
+        request,
+        url,
+        env,
+        loaderName: loaderId,
+      });
+    },
+  });
+
+  return createResponseWithMergedHeaders(rscStream, {
+    status: 500,
+    headers: { "content-type": "text/x-component;charset=utf-8" },
+  });
+}
+
 export async function handleLoaderFetch<TEnv>(
   ctx: HandlerContext<TEnv>,
   request: Request,
@@ -46,8 +104,22 @@ export async function handleLoaderFetch<TEnv>(
     });
   }
 
-  // Look up loader lazily
-  const registeredLoader = await getLoaderLazy(loaderId);
+  // Look up loader lazily. getLoaderLazy returns undefined only when the id was
+  // never registered (genuine 404). A thrown error means the loader module
+  // EXISTS but its import failed (broken transitive import, syntax error, throw
+  // in top-level code) — a real server breakage that must surface as a 500 and
+  // fire onError, not be collapsed into a misleading "not found".
+  let registeredLoader;
+  try {
+    registeredLoader = await getLoaderLazy(loaderId);
+  } catch (error) {
+    return buildLoaderErrorResponse(
+      ctx,
+      error,
+      { request, url, env, loaderId },
+      `[RSC] Loader module load failed for "${loaderId}":`,
+    );
+  }
   if (!registeredLoader) {
     return createResponseWithMergedHeaders(
       `Loader "${loaderId}" not found in registry`,
@@ -124,7 +196,7 @@ export async function handleLoaderFetch<TEnv>(
         loaderParams,
         variables,
         async () => {
-          const reqCtx = requireRequestContext();
+          const reqCtx = getRequestContext();
           // Merge route params (from previewMatch) with explicit loader params.
           // Explicit params take precedence over route-matched params.
           const resolvedRouteParams = routeParams ?? {};
@@ -162,7 +234,12 @@ export async function handleLoaderFetch<TEnv>(
             ...(loaderFormData ? { formData: loaderFormData } : {}),
           };
 
-          const result = await fn(loaderCtx);
+          // Meter the fetchable-loader execution via observePhase, the sole
+          // funnel for this path (fn is called directly, not via ctx.use).
+          // depth:1 — a fetchable request has no render-phase parent.
+          const result = await observePhase(PHASES.loader(loaderId, 1), () =>
+            fn(loaderCtx),
+          );
 
           interface LoaderPayload {
             loaderResult: unknown;
@@ -190,40 +267,39 @@ export async function handleLoaderFetch<TEnv>(
       ),
     );
   } catch (error) {
-    const err = error instanceof Error ? error : new Error(String(error));
-    const isDev = process.env.NODE_ENV !== "production";
-
-    console.error("[RSC] Loader error:", error);
-
-    ctx.callOnError(error, "loader", {
-      request,
-      url,
-      env,
-      loaderName: loaderId,
-      handledByBoundary: false,
-    });
+    // A thrown Response is control flow, not an error: `throw redirect('/x')`
+    // throws a real Response (a 3xx). The with-middleware path already converts
+    // this to a returned Response (middleware.ts: `if (error instanceof Response)
+    // result = error`), but a fetchable loader with NO middleware reaches this
+    // catch directly, where the generic Error coercion below would turn it into a
+    // 500. Honor it the same way: re-wrap through createResponseWithMergedHeaders
+    // so the request context's stub cookies/headers merge, exactly like the
+    // returned-Response path. Mirrors rsc/handler.ts's `error instanceof Response`
+    // special-case.
+    if (error instanceof Response) {
+      return finalizeResponse(
+        createResponseWithMergedHeaders(error.body, {
+          status: error.status,
+          headers: error.headers,
+        }),
+      );
+    }
 
-    const errorPayload = {
-      loaderResult: null,
-      loaderError: {
-        message: isDev ? err.message : "An error occurred",
-        name: err.name,
-      },
-    };
-    const rscStream = ctx.renderToReadableStream(errorPayload, {
-      onError: (error: unknown) => {
-        ctx.callOnError(error, "rendering", {
-          request,
-          url,
-          env,
-          loaderName: loaderId,
-        });
-      },
-    });
+    // notFound() throws a DataNotFoundError (an Error subclass, NOT a Response),
+    // so it does not match the branch above. Map it to a 404 before the generic
+    // 500 coercion so a no-middleware fetchable loader's notFound() is honored
+    // (the with-middleware path resolves it through the notFoundBoundary).
+    if (error instanceof DataNotFoundError) {
+      return finalizeResponse(
+        createResponseWithMergedHeaders(null, { status: 404 }),
+      );
+    }
 
-    return createResponseWithMergedHeaders(rscStream, {
-      status: 500,
-      headers: { "content-type": "text/x-component;charset=utf-8" },
-    });
+    return buildLoaderErrorResponse(
+      ctx,
+      error,
+      { request, url, env, loaderId },
+      "[RSC] Loader error:",
+    );
   }
 }

package/src/rsc/manifest-init.ts

@@ -13,6 +13,7 @@ import {
   setRouteTrie,
   setRouterManifest,
   setRouterTrie,
+  setRouterPrecomputedEntries,
 } from "../route-map-builder.js";
 
 /**
@@ -36,47 +37,13 @@ export async function buildRouterTrieFromUrlpatterns(
     undefined,
     router.basename ? { urlPrefix: router.basename } : undefined,
   );
-  if (
-    generated._routeAncestry &&
-    Object.keys(generated._routeAncestry).length > 0
-  ) {
-    const { buildRouteTrie } = await import("../build/route-trie.js");
-    // Map each route to its include() staticPrefix so the trie
-    // returns the correct sp for lazy entry lookup in findMatch.
-    const routeToStaticPrefix: Record<string, string> = {};
-    for (const name of Object.keys(generated.routeManifest)) {
-      routeToStaticPrefix[name] = "";
-    }
-    // Override with prefix from include() entries so the trie
-    // returns the correct sp for lazy entry lookup in findMatch.
-    // Walk recursively to include routes in nested includes.
-    if (generated.prefixTree) {
-      const visitPrefixNode = (node: any): void => {
-        const sp = node.staticPrefix || "";
-        for (const route of node.routes || []) {
-          routeToStaticPrefix[route] = sp;
-        }
-        for (const child of Object.values(node.children || {})) {
-          visitPrefixNode(child);
-        }
-      };
-      for (const node of Object.values(generated.prefixTree)) {
-        visitPrefixNode(node);
-      }
-    }
-    const trie = buildRouteTrie(
-      generated.routeManifest,
-      generated._routeAncestry,
-      routeToStaticPrefix,
-      generated.routeTrailingSlash,
-      generated.prerenderRoutes
-        ? new Set(generated.prerenderRoutes)
-        : undefined,
-      generated.passthroughRoutes
-        ? new Set(generated.passthroughRoutes)
-        : undefined,
-      generated.responseTypeRoutes,
-    );
+  // Build the trie through the SAME shared helper the production discovery uses
+  // (discover-routers.ts), so the dev runtime-rebuilt trie and the prod
+  // serialized trie cannot drift. buildPerRouterTrie returns null when there
+  // are no routes.
+  const { buildPerRouterTrie } = await import("../build/route-trie.js");
+  const trie = buildPerRouterTrie(generated);
+  if (trie) {
     setRouterTrie(router.id, trie);
     // Set global trie only if not already set by another router
     if (!getRouteTrie()) {
@@ -84,6 +51,26 @@ export async function buildRouterTrieFromUrlpatterns(
     }
   }
   setRouterManifest(router.id, generated.routeManifest);
+
+  // Match the production discovery path: precompute leaf-include entries so the
+  // match-time shortcut in evaluateLazyEntry applies in dev/Cloudflare too.
+  // Without this, dev re-runs each matched leaf include's handler at match time
+  // (evaluateLazyEntry) AND again at render time (loadManifest); with it, the
+  // match-time run is skipped and the handler runs once per first request.
+  // Identical route ownership to the handler path (the shortcut is guarded by
+  // the same prefixIsShared and #506 checks production uses).
+  const { flattenLeafEntries } = await import("../build/prefix-tree-utils.js");
+  const precomputed: Array<{
+    staticPrefix: string;
+    routes: Record<string, string>;
+  }> = [];
+  flattenLeafEntries(
+    generated.prefixTree,
+    generated.routeManifest,
+    precomputed,
+  );
+  setRouterPrecomputedEntries(router.id, precomputed);
+
   // Merge into global manifest (needed for reverse/href across routers)
   const existing = hasCachedManifest() ? getGlobalRouteMap() : {};
   setCachedManifest({ ...existing, ...generated.routeManifest });

package/src/rsc/origin-guard.ts

@@ -30,6 +30,8 @@ export const ORIGIN_CHECK_PHASE_BY_MODE: Record<
   response: null,
   redirect: null,
   "version-mismatch": null,
+  // Terminal: handled before the origin guard (emits X-RSC-Reload, no execution).
+  "app-switch": null,
 };
 
 /**
@@ -67,11 +69,8 @@ export type OriginCheckConfig<TEnv = any> =
  * Returns true to allow, false to reject.
  */
 export function defaultOriginCheck(request: Request, url: URL): boolean {
-  // 1. Read Origin header (present on all cross-origin requests and
-  //    same-origin POST/PUT/PATCH/DELETE in modern browsers)
   let requestOrigin = request.headers.get("origin");
 
-  // 2. Fallback to Referer if Origin is absent (some proxies strip it)
   if (!requestOrigin) {
     const referer = request.headers.get("referer");
     if (referer) {
@@ -83,23 +82,20 @@ export function defaultOriginCheck(request: Request, url: URL): boolean {
     }
   }
 
-  // 3. No Origin or Referer — allow (can't be browser-initiated CSRF)
   if (!requestOrigin) return true;
 
-  // "null" origin comes from privacy-sensitive contexts (data: URLs,
-  // sandboxed iframes, cross-origin redirects). Reject it.
   if (requestOrigin === "null") return false;
 
-  // 4. Determine expected host from Host header or URL.
-  // X-Forwarded-Host/Proto are NOT used — they are client-controllable
-  // unless a trusted proxy strips them. On standard deployments (Cloudflare
-  // Workers, Node behind nginx/caddy) the Host header is already correct.
-  // For non-standard setups, use the custom function escape hatch.
-  const expectedHost = request.headers.get("host") || url.host;
-  const expectedProtocol = url.protocol;
+  // An Origin/Referer is present, so this is a browser request worth checking.
+  // Establish the expected origin from the Host header only -- browsers always
+  // send Host alongside Origin (runtimes synthesize it from the HTTP/2
+  // :authority), so a missing Host here is anomalous. Fail closed rather than
+  // fall back to url.host (derived from the request line) when the trusted Host
+  // cannot be established.
+  const expectedHost = request.headers.get("host");
+  if (!expectedHost) return false;
 
-  // 5. Build expected origin and compare (case-insensitive)
-  const expectedOrigin = `${expectedProtocol}//${expectedHost}`;
+  const expectedOrigin = `${url.protocol}//${expectedHost}`;
 
   return requestOrigin.toLowerCase() === expectedOrigin.toLowerCase();
 }