@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/src/testing/dispatch.ts

@@ -7,25 +7,62 @@
  * and middleware short-circuits behave exactly as in production. It deliberately
  * does NOT render React Server Components: there is no Flight stream, no SSR,
  * and no DOM. Hit an RSC (component) route and dispatch throws a clear error
- * directing you to renderServer()/renderToFlightString or an e2e test.
+ * directing you to renderToFlightString/renderServerTree/renderHandler or an e2e test.
  *
  * What dispatch DOES support:
  * - Trailing-slash and other findMatch() redirects   -> 308 with Location
  * - Unmatched paths                                  -> 404 Response
+ *   Both the 308 and the 404 are produced INSIDE the global middleware chain
+ *   (mirroring production, where coreHandler runs wrapped by executeMiddleware),
+ *   so a global auth middleware can 401/redirect them and middleware-set
+ *   cookies/headers merge onto the 308/404 the way createResponseWithMergedHeaders
+ *   merges them in production.
  * - Response routes (non-RSC)                         -> serialized Response
- *   - json:           JSON.stringify({ data }) with application/json
+ *   - json:           JSON.stringify(result) (bare value) with application/json
  *   - text/html/xml/md: String(result) with the mapped MIME type
- *   - handler returning a Response:                     passed through
+ *   - handler returning a Response:                     re-wrapped like
+ *     handleResponseRoute (stub headers/cookies merged, Set-Cookie preserved,
+ *     WebSocket upgrade passed through without reconstruction)
  *   - handler throwing an error:                        typed 500 / RouterError
- *     status, matching handleResponseRoute (JSON error envelope for json
- *     routes, text/plain message otherwise)
+ *     status, matching handleResponseRoute (RFC 9457 problem+json body with
+ *     application/problem+json for json routes, text/plain message otherwise)
  *   - content-negotiated route:                         Vary: Accept appended
+ *   - cached response route (cache({...})):             getResponse/putResponse
+ *     hit/SWR/tag write, resolved from the matched entry tree exactly as
+ *     handleResponseRoute does. The write is scheduled via ctx.waitUntil
+ *     (a microtask without an executionContext), so a HIT-asserting test must
+ *     flush microtasks between the seeding dispatch and the asserting one.
  * - Global middleware (router.use(...)) AND route-level middleware, with full
  *   next()/short-circuit/throw-Response/header+cookie-merge fidelity.
  * - Partial (client-navigation) requests to a RESPONSE route (?_rsc_partial):
  *   global middleware runs first (so an auth gate can still 401/redirect),
  *   then — if it passes through — an X-RSC-Reload is returned. Route-level
  *   middleware is skipped on a partial, exactly as production skips it.
+ * - A middleware redirect (3xx + Location) on a partial/action request
+ *   (?_rsc_partial / ?_rsc_action): converted to a 204 + X-RSC-Redirect via the
+ *   real interceptRedirectForPartial, so fetch() does not auto-follow the 3xx —
+ *   identical to production's no-location-state path.
+ * - The open-redirect guard (rsc/redirect-guard.ts) on full (browser-followed)
+ *   redirects: a cross-origin Location is rewritten to the basename root unless
+ *   redirect(url, { external: true }) opted out, mirroring production's single
+ *   handler chokepoint. Soft partial/action redirects are 204 and pass through.
+ * - createRouter({ onError }) for CACHE / background-error degradation. dispatch
+ *   wires the request context's _reportBackgroundError to the router's onError the
+ *   same way the production RSC handler does, so a cache-read/cache-write/
+ *   stale-revalidation failure on a cached response route (a throwing route
+ *   cache({ key })/cache({ tags }), or a custom store whose keyGenerator/
+ *   getResponse/putResponse throws) fires onError with phase "cache" and
+ *   metadata.category, while the request still degrades-to-miss exactly as before.
+ *   (A thrown response-route HANDLER error is the one onError path NOT covered —
+ *   see "DOES NOT support" below.)
+ * - createRouter({ telemetry }) match-transaction lifecycle: request.start opens
+ *   the transaction before the global middleware chain, request.end closes it
+ *   after finalizeResponse (segmentCount 0 / cacheHit false — dispatch renders no
+ *   RSC segments and holds no match-cache state), and a thrown non-Response error
+ *   emits request.error with phase "routing". All three carry the same requestId
+ *   (getRequestId). Emission is gated entirely on a configured sink; with none,
+ *   dispatch does zero new work and stays byte-identical for existing callers.
+ *   Lets a consumer unit-test their sink wiring in-process instead of only at e2e.
  *
  * What dispatch DOES NOT support (and why):
  * - RSC component routes — rendering requires the Flight serializer + React
@@ -33,10 +70,27 @@
  *   This includes partial requests that resolve to a component route.
  * - Server actions (?_rsc_action) — RSC protocol concerns handled by
  *   router.fetch().
- * - ctx.onError() callbacks on a thrown response-route handler error: the
+ * - createRouter({ onError }) on a thrown response-route HANDLER error: the
  *   error is serialized into the same typed 500 / RouterError Response as
- *   production, but registered onError handlers are NOT invoked here. Cover
- *   onError side effects with an e2e test.
+ *   production, but onError is NOT invoked for that path here. Cover handler-error
+ *   onError side effects with an e2e test. (This is the unchanged boundary; cache
+ *   and other background errors DO route through onError — see below.)
+ * - Location-state-carrying redirects on a partial/action request: production
+ *   embeds a Flight payload (createRedirectFlightResponse) so the client can
+ *   restore location state across the redirect. dispatch is RSC-free, so it
+ *   cannot emit that Flight stream. It falls back to the no-state behavior — a
+ *   204 + X-RSC-Redirect via createSimpleRedirectResponse — dropping the
+ *   embedded location state. The 204 status, the X-RSC-Redirect header, and the
+ *   merged cookies/headers all match production; only the Flight-embedded
+ *   location-state entries are absent. Cover location-state restoration across a
+ *   partial redirect with an e2e test.
+ * - Telemetry cache.decision / loader.* / handler.error events: these fire from
+ *   the real match()/matchPartial() + RSC render + loader pipeline (match-
+ *   handlers.ts, loader-resolution.ts, segment-resolution), none of which
+ *   dispatch runs. Synthesizing them here would be faking (the events would not
+ *   reflect a real cache lookup or loader run), so dispatch emits only the
+ *   request.start/end/error lifecycle above; cover cache/loader telemetry with an
+ *   e2e test driving a real RSC request.
  *
  * dispatch reuses router.previewMatch(), which itself runs content negotiation
  * and resolves route middleware from the matched entry tree, so dispatch's
@@ -60,13 +114,36 @@ import {
 import { NOCACHE_SYMBOL } from "../cache/taint.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { CacheProfile } from "../cache/profile-registry.js";
+// cache-scope is loaded LAZILY inside the response-route cache path (below):
+// its module graph pulls @vitejs/plugin-rsc/rsc (via segment-codec), which the
+// non-Vite unit-test runner cannot resolve. A static import here would drag that
+// onto the whole testing barrel's eager graph and break every consumer suite
+// that imports `@rangojs/router/testing` without mocking plugin-rsc.
+import type { EntryData } from "../server/context.js";
 import { setRouterManifest } from "../route-map-builder.js";
 import { RESPONSE_TYPE_MIME } from "../router/content-negotiation.js";
 import { RouterError } from "../errors.js";
-import { createResponseErrorPayload } from "../rsc/response-error.js";
-import { createResponseWithMergedHeaders } from "../rsc/helpers.js";
+import { createProblemDetails } from "../rsc/response-error.js";
+import {
+  createResponseWithMergedHeaders,
+  createSimpleRedirectResponse,
+  finalizeResponse,
+  interceptRedirectForPartial,
+  mergeStubHeadersAndFinalize,
+} from "../rsc/helpers.js";
+import { guardOutgoingRedirect } from "../rsc/redirect-guard.js";
+import { stringifyJsonRouteResult } from "../rsc/json-route-result.js";
+import {
+  EXTERNAL_REDIRECT_MARKER,
+  isExternalRedirect,
+  markExternalRedirect,
+} from "../redirect-origin.js";
 import { isWebSocketUpgradeResponse } from "../response-utils.js";
+import { invokeOnError } from "../router/error-handling.js";
+import type { OnErrorCallback } from "../types/error-types.js";
 import type { Rango } from "../router/router-interfaces.js";
+import { getRequestId, resolveSink, safeEmit } from "../router/telemetry.js";
+import type { TelemetrySink } from "../router/telemetry.js";
 
 /**
  * The internal subset of the router surface dispatch depends on. The public
@@ -79,11 +156,19 @@ interface DispatchableRouter<TEnv> {
   routerId?: string;
   routeMap: Record<string, unknown>;
   middleware: MiddlewareEntry<TEnv>[];
-  findMatch(pathname: string): {
+  onError?: OnErrorCallback<TEnv>;
+  /**
+   * Optional telemetry sink from createRouter({ telemetry }) (RangoInternal
+   * field). dispatch emits the match-transaction lifecycle events onto it so a
+   * consumer can unit-test their sink wiring in-process; undefined keeps dispatch
+   * byte-identical for every existing caller.
+   */
+  telemetry?: TelemetrySink;
+  findMatch(pathname: string): Promise<{
     redirectTo?: string;
     routeKey?: string;
     params?: Record<string, string>;
-  } | null;
+  } | null>;
   previewMatch(
     request: Request,
     input?: { env?: TEnv },
@@ -97,6 +182,7 @@ interface DispatchableRouter<TEnv> {
     params?: Record<string, string>;
     routeKey?: string;
     negotiated?: boolean;
+    manifestEntry?: EntryData;
   } | null>;
   basename?: string;
   cache?:
@@ -112,6 +198,8 @@ interface DispatchableRouter<TEnv> {
  * Options for dispatch.
  */
 export interface DispatchOptions<TEnv = any> {
+  /** The request to dispatch: a `Request`, or a URL string (absolute or path). */
+  request: Request | string;
   /** Environment bindings forwarded to matching and middleware. */
   env?: TEnv;
 }
@@ -124,20 +212,28 @@ function toRequest(request: Request | string): Request {
 }
 
 /**
- * Serialize a response-route handler result, mirroring the router's
- * handleResponseRoute() contract:
- * - a returned Response is passed through unchanged,
- * - "json" wraps the value as JSON.stringify({ data }) with application/json,
+ * Serialize a NON-Response response-route handler result, mirroring the
+ * router's handleResponseRoute() contract:
+ * - "json" serializes the value (bare) with application/json, rejecting a nested
+ *   unresolved Promise via the shared stringifyJsonRouteResult guard,
  * - text/html/xml/md stringify with the mapped MIME type.
+ *
+ * A handler-returned Response is NOT routed here — callHandler re-wraps it via
+ * rewrapHandlerResponse (mirroring handleResponseRoute's rewrapResponse) so the
+ * WebSocket-upgrade bypass and Set-Cookie-preserving header merge match
+ * production.
  */
 function serializeResponseRouteResult(
   result: unknown,
   responseType: string,
 ): Response {
-  if (result instanceof Response) return result;
-
   if (responseType === "json") {
-    return new Response(JSON.stringify({ data: result }), {
+    // Serialize through the SAME guard production uses: a nested unresolved
+    // Promise (forgotten await) throws RESPONSE_NOT_SERIALIZABLE here, caught by
+    // callHandler's catch and mapped to the identical typed 500 production
+    // returns -- so a dispatch json test fails exactly where production would,
+    // instead of silently emitting {} and passing.
+    return new Response(stringifyJsonRouteResult(result), {
       status: 200,
       headers: { "content-type": "application/json;charset=utf-8" },
     });
@@ -162,27 +258,28 @@ function serializeResponseRouteResult(
 /**
  * Serialize a thrown handler error into the same typed Response the router's
  * handleResponseRoute() catch block produces:
- * - status is the RouterError.status, else 500,
- * - "json" routes return { error: <createResponseErrorPayload> } as JSON,
+ * - "json" routes return an RFC 9457 problem+json body (application/problem+json),
  * - all other types return a text/plain body (the RouterError message verbatim,
  *   the Error message in dev, else "Internal Server Error").
  *
- * Reuses the production createResponseErrorPayload so the JSON error envelope
- * is byte-identical rather than re-derived.
+ * `status` is the effective HTTP status resolved by the caller (RouterError.status
+ * or 500, overridden by ctx.setStatus()); it governs both the HTTP status and the
+ * problem body's `status`/`title` members. Reuses the production
+ * createProblemDetails so the error body is byte-identical rather than re-derived.
  */
 function serializeResponseRouteError(
   error: unknown,
   responseType: string,
+  status: number,
 ): Response {
   const isDev = process.env.NODE_ENV !== "production";
-  const status = error instanceof RouterError ? error.status : 500;
 
   if (responseType === "json") {
     return new Response(
-      JSON.stringify({ error: createResponseErrorPayload(error, isDev) }),
+      JSON.stringify(createProblemDetails(error, status, isDev)),
       {
         status,
-        headers: { "content-type": "application/json;charset=utf-8" },
+        headers: { "content-type": "application/problem+json;charset=utf-8" },
       },
     );
   }
@@ -199,6 +296,51 @@ function serializeResponseRouteError(
   });
 }
 
+/**
+ * Re-wrap a handler-returned Response, byte-identical to handleResponseRoute's
+ * rewrapResponse:
+ * - A WebSocket upgrade (status 101 or a `webSocket` property) is returned via
+ *   mergeStubHeadersAndFinalize WITHOUT reconstruction — the Response
+ *   constructor rejects status 101, and an upgrade response's headers/socket
+ *   must not be rebuilt.
+ * - Otherwise headers are copied into a fresh Headers (Set-Cookie appended to
+ *   preserve duplicates, others set) and the Response is rebuilt through
+ *   createResponseWithMergedHeaders so stub headers/cookies, the ctx.setStatus
+ *   override, and onResponse callbacks merge exactly as in production. statusText
+ *   is intentionally dropped (production does not carry it across the re-wrap).
+ *
+ * Must run inside runWithRequestContext (reads the ambient request context via
+ * the helpers), which callHandler guarantees.
+ */
+function rewrapHandlerResponse(result: Response): Response {
+  if (isWebSocketUpgradeResponse(result)) {
+    return mergeStubHeadersAndFinalize(result);
+  }
+  const headers = new Headers();
+  result.headers.forEach((value, key) => {
+    // Mirror production: never copy the reserved external-redirect marker off a
+    // handler result (it is not a trust signal; the opt-in is the out-of-band
+    // brand transferred below).
+    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,
+  });
+  // Mirror production's rewrapResponse: transfer the out-of-band external brand
+  // only from a genuinely branded result (a real redirect(url, { external:
+  // true })), never from a proxied upstream's forged header.
+  if (isExternalRedirect(result)) {
+    markExternalRedirect(rewrapped);
+  }
+  return rewrapped;
+}
+
 /**
  * Run a request through the router in-process and return the Response.
  *
@@ -208,21 +350,20 @@ function serializeResponseRouteError(
  *   path.json("/api/health", () => ({ ok: true }), { name: "health" }),
  * ]));
  *
- * const res = await dispatch(router, "/api/health");
+ * const res = await dispatch(router, { request: "/api/health" });
  * expect(res.status).toBe(200);
- * expect(await res.json()).toEqual({ data: { ok: true } });
+ * expect(await res.json()).toEqual({ ok: true });
  * ```
  */
 export async function dispatch<TEnv = any>(
   publicRouter: Rango<TEnv, any>,
-  request: Request | string,
-  opts: DispatchOptions<TEnv> = {},
+  opts: DispatchOptions<TEnv>,
 ): Promise<Response> {
   // The public Rango type intentionally hides the matching internals; read them
   // through the dispatchable shape (present at runtime). Consumers pass their
   // real router with no cast.
   const router = publicRouter as unknown as DispatchableRouter<TEnv>;
-  const req = toRequest(request);
+  const req = toRequest(opts.request);
   const url = new URL(req.url);
   const env = (opts.env ?? {}) as TEnv;
 
@@ -234,39 +375,35 @@ export async function dispatch<TEnv = any>(
 
   // findMatch carries trailing-slash/redirect targets and null on no match.
   // previewMatch swallows redirects, so detect them here first.
-  const match = router.findMatch(url.pathname);
-
-  if (match?.redirectTo) {
-    return new Response(null, {
-      status: 308,
-      headers: { Location: match.redirectTo + url.search },
-    });
-  }
-
-  if (!match) {
-    return new Response("Not Found", {
-      status: 404,
-      headers: { "content-type": "text/plain;charset=utf-8" },
-    });
-  }
+  const match = await router.findMatch(url.pathname);
+  const redirectTo = match?.redirectTo;
+  const isUnmatched = !match;
 
   // previewMatch resolves responseType, the response-route handler, and the
   // route middleware from the matched entry tree (with content negotiation).
-  const preview = await router.previewMatch(req, { env });
-
-  // No preview (e.g. resolved to a redirect inside previewMatch) — fall back to
-  // the findMatch result. A bare match with no responseType is an RSC route.
+  // Skip it for a redirect/unmatched path — there is no response route to
+  // resolve, and previewMatch would return null / a redirect marker anyway.
+  const preview =
+    redirectTo || isUnmatched ? null : await router.previewMatch(req, { env });
+
+  // A bare match with no responseType is an RSC route. The RSC-route throw is a
+  // hard boundary of this primitive (no Flight runtime), distinct from the
+  // 308/404 outcomes below, so it stays a pre-middleware guard.
   const responseType = preview?.responseType;
   const handler = preview?.handler;
-  const params = preview?.params ?? match.params ?? {};
-  const routeKey = preview?.routeKey ?? match.routeKey;
-
-  if (!responseType || typeof handler !== "function") {
+  const params = preview?.params ?? match?.params ?? {};
+  const routeKey = preview?.routeKey ?? match?.routeKey;
+
+  if (
+    !redirectTo &&
+    !isUnmatched &&
+    (!responseType || typeof handler !== "function")
+  ) {
     throw new Error(
       `dispatch() does not render RSC routes — the route matched at ` +
         `"${url.pathname}" is a React Server Component route, not a response ` +
-        `route. Use renderServer()/renderToFlightString or an e2e test to ` +
-        `exercise component rendering.`,
+        `route. Use renderHandler/renderServerTree/renderToFlightString or an ` +
+        `e2e test to exercise component rendering.`,
     );
   }
 
@@ -293,6 +430,22 @@ export async function dispatch<TEnv = any>(
     cacheStore,
     cacheProfiles: router.cacheProfiles,
   });
+  // Wire background error reporting so cache degradation (reportCacheError ->
+  // _reportBackgroundError) reaches the router's onError, mirroring the production
+  // RSC handler (rsc/handler.ts). Without this, dispatch could not observe onError.
+  requestContext._reportBackgroundError = (error, category) => {
+    if (error != null && typeof error === "object") {
+      if (requestContext._reportedErrors.has(error)) return;
+      requestContext._reportedErrors.add(error);
+    }
+    invokeOnError(
+      router.onError,
+      error,
+      "cache",
+      { request: req, url, metadata: { category } },
+      "RSC",
+    );
+  };
   // Match production: the RSC handler stores the router's basename on the
   // request context (handler.ts), and redirect() prefixes root-relative URLs
   // with it. Mirror it so basename-redirect tests behave as they do in a real
@@ -312,129 +465,349 @@ export async function dispatch<TEnv = any>(
     search?: Record<string, unknown>,
   ) => string;
 
+  const isPartial = url.searchParams.has("_rsc_partial");
+  const isAction = url.searchParams.has("_rsc_action");
+
+  // Telemetry: mirror the router's match-transaction lifecycle onto the
+  // configured sink so a consumer can unit-test createRouter({ telemetry })
+  // wiring in-process (the dogfood gap the RSC-free dispatch left — see
+  // tests/cloudflare-basic/test/cache-status.test.ts). Every emit is gated on
+  // `sink` truthiness: with no sink configured dispatch does zero new work and
+  // stays byte-identical for existing callers. Only request.start/end/error are
+  // reachable here — cache.decision and loader.* originate in the real match()/
+  // matchPartial() + RSC render pipeline dispatch deliberately does not run
+  // (module header), so fabricating them would violate the no-fake rule.
+  const sink = router.telemetry;
+  const telemetryRequestId = sink ? getRequestId(req) : undefined;
+  const telemetryStart = sink ? performance.now() : 0;
+
   return runWithRequestContext(requestContext, async () => {
     // Set params before middleware/handler run, so global middleware sees
     // ctx.params (production sets them during matching, before middleware).
+    // On a redirect/unmatched path there are no route params.
     if (routeKey !== undefined) {
       setRequestContextParams(params, routeKey);
     } else {
       requestContext.params = params;
     }
 
-    // Match production: a partial (client-navigation) request to a response
-    // route is short-circuited to X-RSC-Reload, but ONLY after GLOBAL
-    // (app-level) middleware has run. In production the partial check lives
-    // inside coreHandler (handler.ts wraps it with executeMiddleware) and,
-    // within handleResponseRoute, precedes the route-level middleware
-    // (response-route-handler.ts). So global middleware (e.g. an auth gate)
-    // can still 401/redirect a partial request; only when it calls next()
-    // through does the reload get emitted. Route-level middleware is skipped
-    // on a partial, exactly as production skips it.
-    const isPartial = url.searchParams.has("_rsc_partial");
-    const partialFinalHandler = async (): Promise<Response> =>
-      createResponseWithMergedHeaders(null, {
-        status: 200,
-        headers: {
-          "X-RSC-Reload": stripInternalParams(url).toString(),
-          "content-type": "text/x-component;charset=utf-8",
-        },
-      });
+    // The response-route handler (with its own route middleware) lives inside
+    // coreHandler below, mirroring production where handleResponseRoute is
+    // nested inside coreHandler. Built lazily so a redirect/404 path never
+    // touches it.
+    const callResponseRoute = async (): Promise<Response> => {
+      // Match production: a partial (client-navigation) request to a response
+      // route is short-circuited to X-RSC-Reload (handleResponseRoute), BEFORE
+      // route-level middleware runs. Route-level middleware is skipped on a
+      // partial, exactly as production skips it.
+      const partialFinalHandler = async (): Promise<Response> =>
+        createResponseWithMergedHeaders(null, {
+          status: 200,
+          headers: {
+            "X-RSC-Reload": stripInternalParams(url).toString(),
+            "content-type": "text/x-component;charset=utf-8",
+          },
+        });
+
+      const cleanUrl = new URL(req.url);
+      for (const key of [...cleanUrl.searchParams.keys()]) {
+        if (key.startsWith("_rsc")) cleanUrl.searchParams.delete(key);
+      }
 
-    const cleanUrl = new URL(req.url);
-    for (const key of [...cleanUrl.searchParams.keys()]) {
-      if (key.startsWith("_rsc")) cleanUrl.searchParams.delete(key);
-    }
+      // Lightweight response-handler context mirroring handleResponseRoute.
+      const responseHandlerCtx = {
+        request: req,
+        params,
+        env,
+        searchParams: cleanUrl.searchParams,
+        url: cleanUrl,
+        originalUrl: requestContext.originalUrl,
+        pathname: url.pathname,
+        reverse,
+        get: requestContext.get,
+        header: (name: string, value: string) =>
+          requestContext.header(name, value),
+        waitUntil: requestContext.waitUntil.bind(requestContext),
+        executionContext: requestContext.executionContext,
+        _responseType: responseType,
+      };
+      // Brand as request-scoped so a "use cache" inside a response-route handler
+      // is detected as a request-scope violation here exactly as in production
+      // (response-route-handler.ts brands the same shape).
+      (responseHandlerCtx as Record<symbol, unknown>)[NOCACHE_SYMBOL] = true;
+
+      const callHandler = async (): Promise<Response> => {
+        let merged: Response;
+        try {
+          const result = await (handler as Function)(responseHandlerCtx);
+          if (result instanceof Response) {
+            // Handler returned a Response: mirror handleResponseRoute's
+            // rewrapResponse (WebSocket-upgrade bypass + Set-Cookie-preserving
+            // header rebuild, statusText dropped) rather than the generic
+            // createResponseWithMergedHeaders re-wrap below.
+            merged = rewrapHandlerResponse(result);
+          } else {
+            // Route the serialized (json/text/...) body through the SAME
+            // production finalizer the RSC handler uses, so ctx.onResponse()
+            // callbacks fire and stub headers/cookies + the ctx.setStatus
+            // override merge identically to production. Runs inside
+            // runWithRequestContext, so _getRequestContext() resolves here.
+            const serialized = serializeResponseRouteResult(
+              result,
+              responseType as string,
+            );
+            merged = createResponseWithMergedHeaders(serialized.body, {
+              status: serialized.status,
+              headers: serialized.headers,
+            });
+          }
+        } catch (error) {
+          // Mirror handleResponseRoute's catch: a genuine handler error becomes
+          // the router's typed 500 / RouterError-status Response (NOT a rejected
+          // promise). Middleware short-circuit via thrown Response is handled by
+          // executeMiddleware and never reaches here.
+          const derivedStatus =
+            error instanceof RouterError ? error.status : 500;
+          // Resolve the effective status the way createResponseWithMergedHeaders
+          // (below) will (ctx.res.status override) BEFORE building the problem
+          // body, so the body's status/title match the actual HTTP status when a
+          // handler called ctx.setStatus() before throwing — exactly as
+          // handleResponseRoute resolves it.
+          const status =
+            requestContext.res.status !== 200
+              ? requestContext.res.status
+              : derivedStatus;
+          const serialized = serializeResponseRouteError(
+            error,
+            responseType as string,
+            status,
+          );
+          merged = createResponseWithMergedHeaders(serialized.body, {
+            status: serialized.status,
+            headers: serialized.headers,
+          });
+        }
+
+        // Append Vary: Accept on content-negotiated responses, matching
+        // handleResponseRoute's callHandlerWithVary. Skipped on WebSocket
+        // upgrade responses (immutable headers, Vary meaningless for a 101).
+        if (preview?.negotiated && !isWebSocketUpgradeResponse(merged)) {
+          merged.headers.append("Vary", "Accept");
+        }
+
+        return merged;
+      };
+
+      // On a partial request the reload IS the terminal handler and route
+      // middleware is skipped; otherwise the response-route handler is wrapped
+      // by route-level middleware (production order: route middleware runs
+      // inside handleResponseRoute, after the global chain).
+      if (isPartial) {
+        return partialFinalHandler();
+      }
 
-    // Lightweight response-handler context mirroring handleResponseRoute.
-    const responseHandlerCtx = {
-      request: req,
-      params,
-      env,
-      searchParams: cleanUrl.searchParams,
-      url: cleanUrl,
-      originalUrl: requestContext.originalUrl,
-      pathname: url.pathname,
-      reverse,
-      get: requestContext.get,
-      header: (name: string, value: string) =>
-        requestContext.header(name, value),
-      waitUntil: requestContext.waitUntil.bind(requestContext),
-      executionContext: requestContext.executionContext,
-      _responseType: responseType,
+      // executeHandler = callHandler wrapped by route-level middleware, exactly
+      // the unit the production response cache wraps (response-route-handler.ts).
+      const executeHandler = (): Promise<Response> => {
+        const routeMiddlewareEntries = (preview?.routeMiddleware ?? []).map(
+          (mw) => ({
+            entry: {
+              pattern: null,
+              regex: null,
+              paramNames: [],
+              handler: mw.handler,
+            } as MiddlewareEntry<TEnv>,
+            params: mw.params,
+          }),
+        );
+        if (routeMiddlewareEntries.length === 0) {
+          return callHandler();
+        }
+        return executeMiddleware<TEnv>(
+          routeMiddlewareEntries,
+          req,
+          env,
+          variables,
+          callHandler,
+          reverse,
+        );
+      };
+
+      // Response-route cache path: resolved through the SAME shared serve leaf
+      // (rsc/response-cache-serve.ts) production uses, so a cached
+      // path.json/path.text route hits/SWRs/writes tags through dispatch exactly
+      // as in production — and the two can never drift. Resolved from the matched
+      // entry tree (preview.manifestEntry), which previewMatch surfaces for
+      // response routes.
+      const manifestEntry = preview?.manifestEntry;
+      if (manifestEntry) {
+        // Lazy so the testing barrel's eager graph stays plugin-rsc-free (see the
+        // import note above): the leaf takes createCacheScope/resolveCacheTags as
+        // INJECTED deps so it never imports plugin-rsc; we hand it the lazily
+        // imported pair here, only once a response route actually matched.
+        const cacheScopeMod = await import("../cache/cache-scope.js");
+        const { serveResponseRouteWithCache } =
+          await import("../rsc/response-cache-serve.js");
+        // requestContext is RequestContext<TEnv>; the leaf is typed against the
+        // default-env RequestContext (it reads only env-agnostic config).
+        // Assignable in the router's own tsc but not when a consumer pins a
+        // concrete Env — cast to the leaf's param type.
+        const cached = await serveResponseRouteWithCache({
+          reqCtx: requestContext as Parameters<
+            typeof serveResponseRouteWithCache
+          >[0]["reqCtx"],
+          manifestEntry,
+          responseType: responseType as string,
+          url,
+          executeHandler,
+          deps: {
+            createCacheScope: cacheScopeMod.createCacheScope,
+            resolveCacheTags: cacheScopeMod.resolveCacheTags,
+          },
+        });
+        if (cached !== undefined) return cached;
+      }
+
+      return executeHandler().then(finalizeResponse);
     };
-    // Brand as request-scoped so a "use cache" inside a response-route handler
-    // is detected as a request-scope violation here exactly as in production
-    // (response-route-handler.ts brands the same shape).
-    (responseHandlerCtx as Record<symbol, unknown>)[NOCACHE_SYMBOL] = true;
-
-    const callHandler = async (): Promise<Response> => {
-      let serialized: Response;
-      try {
-        const result = await (handler as Function)(responseHandlerCtx);
-        serialized = serializeResponseRouteResult(result, responseType);
-      } catch (error) {
-        // Mirror handleResponseRoute's catch: a genuine handler error becomes
-        // the router's typed 500 / RouterError-status Response (NOT a rejected
-        // promise). Middleware short-circuit via thrown Response is handled by
-        // executeMiddleware and never reaches here.
-        serialized = serializeResponseRouteError(error, responseType);
+
+    // coreHandler is the single terminal the global middleware chain wraps,
+    // mirroring production's coreHandler (handler.ts): a trailing-slash/redirect
+    // 308, an unmatched-path 404, or the response route. Both the 308 and the
+    // 404 are produced via createResponseWithMergedHeaders so middleware-set
+    // cookies/headers merge onto them, identical to production's
+    // rsc-rendering.ts redirect path — and because they sit inside the chain, a
+    // global middleware that short-circuits (e.g. an auth 401) runs first and
+    // wins, never reaching the 308/404.
+    const coreHandler = async (): Promise<Response> => {
+      if (redirectTo) {
+        return createResponseWithMergedHeaders(null, {
+          status: 308,
+          headers: { Location: redirectTo + url.search },
+        });
+      }
+      if (isUnmatched) {
+        return createResponseWithMergedHeaders("Not Found", {
+          status: 404,
+          headers: { "content-type": "text/plain;charset=utf-8" },
+        });
       }
+      return callResponseRoute();
+    };
 
-      // Route through the SAME production finalizer the RSC handler uses, so
-      // ctx.onResponse() callbacks fire and stub headers/cookies + ctx.setStatus
-      // merge identically to production (handleResponseRoute also goes through
-      // createResponseWithMergedHeaders). Runs inside runWithRequestContext, so
-      // _getRequestContext() resolves to this request's context.
-      const merged = createResponseWithMergedHeaders(serialized.body, {
-        status: serialized.status,
-        statusText: serialized.statusText,
-        headers: serialized.headers,
+    // request.start opens the match transaction, mirroring match-handlers.ts.
+    // transaction is always "match" (dispatch has no matchPartial split);
+    // isPartial carries the ?_rsc_partial signal the same way production does.
+    if (sink) {
+      safeEmit(resolveSink(sink), {
+        type: "request.start",
+        timestamp: telemetryStart,
+        requestId: telemetryRequestId,
+        method: req.method,
+        pathname: url.pathname,
+        transaction: "match",
+        isPartial,
       });
+    }
 
-      // Append Vary: Accept on content-negotiated responses, matching
-      // handleResponseRoute's callHandlerWithVary. Skipped on WebSocket upgrade
-      // responses (immutable headers, Vary meaningless for a 101).
-      if (preview?.negotiated && !isWebSocketUpgradeResponse(merged)) {
-        merged.headers.append("Vary", "Accept");
+    try {
+      // Global (pattern-matched) middleware wraps coreHandler, exactly as
+      // production wraps coreHandler with executeMiddleware (handler.ts).
+      const globalMatches = matchMiddleware(url.pathname, router.middleware);
+      const mwResponse =
+        globalMatches.length === 0
+          ? await coreHandler()
+          : await executeMiddleware<TEnv>(
+              globalMatches,
+              req,
+              env,
+              variables,
+              coreHandler,
+              reverse,
+            );
+
+      // Match production's global-chain exit (handler.ts): on a partial/action
+      // request a middleware 3xx redirect is converted to a Flight-safe response
+      // so fetch() does not auto-follow it; every path then drains onResponse
+      // callbacks via finalizeResponse. dispatch is RSC-free, so the
+      // createRedirectFlightResponse stand-in falls back to the no-state
+      // 204 + X-RSC-Redirect (see the location-state divergence in the header).
+      let finalResponse: Response;
+      if (isPartial || isAction) {
+        const intercepted = interceptRedirectForPartial(
+          mwResponse,
+          (redirectUrl) => createSimpleRedirectResponse(redirectUrl),
+        );
+        finalResponse = finalizeResponse(intercepted ?? mwResponse);
+      } else {
+        finalResponse = finalizeResponse(mwResponse);
       }
 
-      return merged;
-    };
+      // request.end closes the transaction. dispatch produces no RSC segments and
+      // holds no match-cache state, so segmentCount/cacheHit are 0/false — the
+      // same shape production emits for its own redirect (segment-less) result.
+      if (sink) {
+        safeEmit(resolveSink(sink), {
+          type: "request.end",
+          timestamp: performance.now(),
+          requestId: telemetryRequestId,
+          method: req.method,
+          pathname: url.pathname,
+          transaction: "match",
+          durationMs: performance.now() - telemetryStart,
+          segmentCount: 0,
+          cacheHit: false,
+          // dispatch's final response IS built before request.end (unlike
+          // match()/matchPartial(), whose Response is built after), so stamp its
+          // status — the same field a thrown-Response short-circuit carries.
+          status: finalResponse.status,
+        });
+      }
 
-    // On a partial request the reload IS the terminal handler; otherwise the
-    // response-route handler is. Either way global middleware wraps it.
-    const finalHandler = isPartial ? partialFinalHandler : callHandler;
-
-    // Combine global (pattern-matched) middleware with route middleware,
-    // preserving the router's order: global runs before route-level. Route
-    // middleware is skipped on a partial request (production returns the
-    // reload before handleResponseRoute reaches its route middleware).
-    const globalMatches = matchMiddleware(url.pathname, router.middleware);
-    const routeMiddlewareEntries = isPartial
-      ? []
-      : (preview?.routeMiddleware ?? []).map((mw) => ({
-          entry: {
-            pattern: null,
-            regex: null,
-            paramNames: [],
-            handler: mw.handler,
-            mountPrefix: null,
-          } as MiddlewareEntry<TEnv>,
-          params: mw.params,
-        }));
-    const allMiddleware = [...globalMatches, ...routeMiddlewareEntries];
-
-    if (allMiddleware.length === 0) {
-      return finalHandler();
+      // Mirror production's single open-redirect chokepoint (handler.ts): every
+      // browser-followed (3xx + Location) redirect is same-origin guarded before
+      // it leaves -- a cross-origin Location is rewritten to the basename root
+      // unless redirect(url, { external: true }) opted out. Soft partial/action
+      // redirects are 204 + X-RSC-Redirect and pass through untouched (the client
+      // validates them), so this is a no-op for them.
+      return guardOutgoingRedirect(finalResponse, url.origin, router.basename);
+    } catch (error) {
+      if (sink) {
+        if (error instanceof Response) {
+          // executeMiddleware absorbs a middleware-thrown Response and returns it
+          // (middleware.ts:566), so a thrown Response never actually reaches this
+          // level in dispatch. Defensive: if one ever does it is a completed
+          // request from the consumer's seat (a short-circuit redirect), so mirror
+          // plan 002 / match-handlers.ts and emit request.end, not request.error.
+          safeEmit(resolveSink(sink), {
+            type: "request.end",
+            timestamp: performance.now(),
+            requestId: telemetryRequestId,
+            method: req.method,
+            pathname: url.pathname,
+            transaction: "match",
+            durationMs: performance.now() - telemetryStart,
+            segmentCount: 0,
+            cacheHit: false,
+            // Carry the short-circuit Response's status (parity with
+            // match-handlers.ts's thrown-Response request.end).
+            status: error.status,
+          });
+        } else {
+          safeEmit(resolveSink(sink), {
+            type: "request.error",
+            timestamp: performance.now(),
+            requestId: telemetryRequestId,
+            method: req.method,
+            pathname: url.pathname,
+            transaction: "match",
+            error: error instanceof Error ? error : new Error(String(error)),
+            phase: "routing",
+            durationMs: performance.now() - telemetryStart,
+          });
+        }
+      }
+      throw error;
     }
-
-    return executeMiddleware<TEnv>(
-      allMiddleware,
-      req,
-      env,
-      variables,
-      finalHandler,
-      reverse,
-    );
   });
 }