@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/src/rsc/helpers.ts

@@ -7,10 +7,41 @@
 import {
   _getRequestContext,
   getLocationState,
+  setRequestContextParams,
 } from "../server/request-context.js";
 import type { RequestContext } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
+import {
+  isRedirectResponse,
+  isWebSocketUpgradeResponse,
+} from "../response-utils.js";
+import {
+  EXTERNAL_REDIRECT_MARKER,
+  isExternalRedirect,
+  markExternalRedirect,
+  resolveSoftRedirectUrl,
+} from "../redirect-origin.js";
 import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
+import { formatCacheSignalHeader } from "../router/telemetry.js";
+import type { RscPayload } from "./types.js";
+import type { HandlerContext } from "./handler-context.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:
@@ -21,6 +52,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)) {
@@ -36,18 +71,41 @@ 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.
+  return applyOnResponseCallbacks(callbacks, response);
+}
+
+/** Apply a saved callback batch while preserving an external-redirect brand. */
+export function applyOnResponseCallbacks(
+  callbacks: Array<(response: Response) => Response>,
+  response: Response,
+): Response {
+  const wasExternal = isExternalRedirect(response);
   let result = response;
   for (const callback of callbacks) {
     result = callback(result) ?? result;
   }
+  if (wasExternal && !isExternalRedirect(result)) {
+    markExternalRedirect(result);
+  }
   return result;
 }
 
@@ -84,6 +142,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.
@@ -98,24 +157,82 @@ export function createResponseWithMergedHeaders(
   return drainOnResponseCallbacks(ctx, response);
 }
 
+/**
+ * Rebuild a Response returned or thrown by a response-route handler so request
+ * effects merge consistently in production and the public dispatch primitive.
+ */
+export function rewrapResponseRouteResponse(result: Response): Response {
+  if (isWebSocketUpgradeResponse(result)) {
+    return mergeStubHeadersAndFinalize(result);
+  }
+  const headers = new Headers();
+  result.headers.forEach((value, key) => {
+    if (key.toLowerCase() === EXTERNAL_REDIRECT_MARKER) return;
+    if (key.toLowerCase() === "set-cookie") {
+      headers.append(key, value);
+    } else {
+      headers.set(key, value);
+    }
+  });
+  const rewrapped = createResponseWithMergedHeaders(result.body, {
+    status: result.status,
+    headers,
+  });
+  if (isExternalRedirect(result)) {
+    markExternalRedirect(rewrapped);
+  }
+  return rewrapped;
+}
+
+/** Origin/basename needed to resolve soft redirect targets server-side. */
+export type SoftRedirectResolveOpts = {
+  requestOrigin: string;
+  basename?: string;
+};
+
 /**
  * Create a 204 response with X-RSC-Redirect header for stateless redirects.
  * Used during partial/action requests where fetch would auto-follow a raw
  * 3xx to a URL that renders full HTML instead of Flight data. The 204 status
  * prevents auto-follow; the client reads the header and re-navigates via
  * the router.
+ *
+ * The header value is resolved with {@link resolveSoftRedirectUrl} so a
+ * cross-origin / unsafe-scheme target is neutralized before it leaves the
+ * server (defense-in-depth; client validators still run).
  */
-export function createSimpleRedirectResponse(redirectUrl: string): Response {
+export function createSimpleRedirectResponse(
+  redirectUrl: string,
+  opts: SoftRedirectResolveOpts & { external?: boolean },
+): Response {
+  const resolved = resolveSoftRedirectUrl(
+    redirectUrl,
+    opts.requestOrigin,
+    opts.basename,
+    opts.external,
+  );
   return createResponseWithMergedHeaders(null, {
     status: 204,
-    headers: { "X-RSC-Redirect": redirectUrl },
+    headers: { "X-RSC-Redirect": resolved },
   });
 }
 
 /**
  * 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,
@@ -124,12 +241,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);
+  }
 }
 
 /**
@@ -137,34 +258,73 @@ export function carryOverRedirectHeaders(
  * intercept it and return a Flight-compatible redirect instead.
  * fetch() auto-follows 3xx which would hit a URL that renders full HTML
  * the client can't parse. Returns null if the response is not a redirect.
+ *
+ * Soft redirect targets are resolved server-side (same-origin / external
+ * scheme rules) via `opts` before they are written into X-RSC-Redirect or
+ * handed to the Flight factory.
  */
 export function interceptRedirectForPartial(
   response: Response,
   createRedirectFlightResponse: (
     redirectUrl: string,
     locationState?: Record<string, unknown>,
+    external?: boolean,
   ) => Response,
+  opts: SoftRedirectResolveOpts,
 ): Response | null {
-  const redirectUrl = response.headers.get("Location");
-  if (!(response.status >= 300 && response.status < 400 && redirectUrl)) {
+  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);
+    intercepted = createSimpleRedirectResponse(redirectUrl, opts);
   }
 
   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
@@ -191,7 +351,6 @@ export function buildRouteMiddlewareEntries<TEnv>(
       regex: null,
       paramNames: [],
       handler: mw.handler,
-      mountPrefix: null,
     } as MiddlewareEntry<TEnv>,
     params: mw.params,
   }));
@@ -224,3 +383,14 @@ export function finalizeResponse(response: Response): Response {
   if (!ctx) return response;
   return drainOnResponseCallbacks(ctx, response);
 }
+
+/** Match and stamp params/routeName on the request context as one operation. */
+export async function matchAndRecordParams<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+): Promise<Awaited<ReturnType<HandlerContext<TEnv>["router"]["match"]>>> {
+  const match = await ctx.router.match(request, { env });
+  setRequestContextParams(match.params, match.routeName);
+  return match;
+}

package/src/rsc/index.ts

@@ -1,5 +1,5 @@
 /**
- * RSC Router - RSC Entry Point
+ * Rango - RSC Entry Point
  *
  * This module provides RSC utilities for server-side rendering,
  * server actions, loader fetching, and progressive enhancement.
@@ -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 { isDataNotFoundError } 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 ?? {};
@@ -137,7 +209,7 @@ export async function handleLoaderFetch<TEnv>(
           const cleanUrl = stripInternalParams(url);
           const cleanSearchParams = cleanUrl.searchParams;
           const searchSchema = reqCtx._routeName
-            ? getSearchSchema(reqCtx._routeName)
+            ? getSearchSchema(reqCtx._routeName, reqCtx._routerId)
             : undefined;
           const loaderCtx: any = {
             ...reqCtx,
@@ -156,13 +228,18 @@ export async function handleLoaderFetch<TEnv>(
               reqCtx._routeName,
               mergedParams,
               reqCtx._routeName
-                ? isRouteRootScoped(reqCtx._routeName)
+                ? isRouteRootScoped(reqCtx._routeName, reqCtx._routerId)
                 : undefined,
             ),
             ...(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 (isDataNotFoundError(error)) {
+      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:",
+    );
   }
 }