@rangojs/router 0.27.0 → 0.28.0

package/src/rsc/handler.ts

@@ -6,19 +6,15 @@
  * and progressive enhancement (no-JS form submissions).
  */
 
-import { requestHeaders } from "../server/request-headers.js";
 import { isRouteNotFoundError } from "../errors.js";
 import { matchMiddleware, executeMiddleware } from "../router/middleware.js";
 import {
   runWithRequestContext,
-  setRequestContextParams,
   getRequestContext,
   _getRequestContext,
   createRequestContext,
   captureRequestEntryContext,
 } from "../server/request-context.js";
-import { REWRITE_HEADER, runRewritePasses } from "./rewrite-passes.js";
-import { rewriteTrail } from "../server/rewrite-trail.js";
 import { payloadLocation } from "./full-payload.js";
 import * as rscDeps from "@vitejs/plugin-rsc/rsc/server";
 import type {
@@ -36,7 +32,6 @@ import {
   buildRouteMiddlewareEntries,
 } from "./helpers.js";
 import { renderRscFlightStage, renderRscResponse } from "./render-pipeline.js";
-import { guardOutgoingRedirect } from "./redirect-guard.js";
 import {
   resolveSoftRedirectUrl,
   resolveExternalRedirect,
@@ -48,21 +43,13 @@ import {
   appendVaryAccept,
   trySetHeader,
 } from "../response-utils.js";
-import {
-  handleResponseRoute,
-  type ResponseRouteMatch,
-} from "./response-route-handler.js";
 import { nonce as nonceToken, resolveProviderNonce } from "./nonce.js";
 import {
   resolvePrerenderVersion,
   resolveRouterVersions,
 } from "../server/build-version-table.js";
-import type { ErrorPhase } from "../types.js";
 import type { RouterRequestInput } from "../router/router-interfaces.js";
-import {
-  invokeOnError,
-  resolveDefaultNotFound,
-} from "../router/error-handling.js";
+import { resolveDefaultNotFound } from "../router/error-handling.js";
 import {
   printServerError,
   wasServerErrorPrinted,
@@ -76,7 +63,6 @@ import {
   getRouterTrie,
 } from "../route-map-builder.js";
 import type { HandlerContext } from "./handler-context.js";
-import type { CacheErrorCategory } from "../cache/cache-error.js";
 import {
   compileSearchParamsFilter,
   type SearchParamsFilter,
@@ -91,7 +77,6 @@ import {
   type ActionContinuation,
 } from "./server-action.js";
 import { handleLoaderFetch, renderLoaderError } from "./loader-fetch.js";
-import { applyStreamIdleTimeout } from "./stream-idle.js";
 import {
   checkRequestOrigin,
   ORIGIN_CHECK_PHASE_BY_MODE,
@@ -100,14 +85,7 @@ import { handleRscRendering } from "./rsc-rendering.js";
 import { withoutShellMissMarker } from "./shell-serve.js";
 import { readWarmMark } from "../prerender/warm-request.js";
 import { defaultSSRModuleLoaderForTests } from "./ssr-module-loader.js";
-import {
-  withTimeout,
-  isTimeoutEnabled,
-  RouterTimeoutError,
-  createDefaultTimeoutResponse,
-  type TimeoutPhase,
-  type RenderTimeoutContext,
-} from "../router/timeout.js";
+import { withTimeout, isTimeoutEnabled } from "../router/timeout.js";
 import {
   createMetricsStore,
   appendMetric,
@@ -123,12 +101,21 @@ import {
   SSR_SETUP_VAR,
   type SSRSetup,
 } from "./ssr-setup.js";
+import type { ExecutableRequestPlan } from "../router/request-classification.js";
 import {
-  classifyRequest,
-  type RequestPlan,
-  type ExecutableRequestPlan,
-} from "../router/request-classification.js";
-import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
+  classify,
+  createErrorReporter,
+  finalizeRequestResponse,
+  originRejectedResponse,
+  recordPlanRoute,
+  reportBackgroundErrors,
+  responseRouteMatch,
+  runRequestPasses,
+  serveResponseRoute,
+  terminalPlanResponse,
+  timeoutResponse,
+} from "./request-stages.js";
+import { WIRE } from "../wire-params.js";
 
 /**
  * Create an RSC request handler.
@@ -218,27 +205,7 @@ export function createRSCHandler<
           }))
       : rawLoadSSRModule;
 
-  /**
-   * Per-request error reporter that deduplicates via the ALS request context.
-   *
-   * Uses the same _reportedErrors WeakSet as the router layer so errors
-   * that propagate across layers are only reported once per request.
-   */
-  function callOnError(
-    error: unknown,
-    phase: ErrorPhase,
-    context: Parameters<typeof invokeOnError<TEnv>>[3],
-  ): void {
-    // Guard: abort signal handlers fire asynchronously outside the ALS
-    // request scope, so the context may be gone. Skip dedup in that
-    // case — the error is from a cancelled stream, not a real failure.
-    const reqCtx = _getRequestContext();
-    if (error != null && typeof error === "object" && reqCtx) {
-      if (reqCtx._reportedErrors.has(error)) return;
-      reqCtx._reportedErrors.add(error);
-    }
-    invokeOnError(router.onError, error, phase, context, "RSC");
-  }
+  const callOnError = createErrorReporter<TEnv>(router);
 
   function getRequiredRouteMap(): Record<string, string> {
     const routeMap = getRouterManifest(router.id);
@@ -250,112 +217,6 @@ export function createRSCHandler<
     return routeMap;
   }
 
-  /**
-   * Handle a timeout by reporting the error, emitting telemetry,
-   * and returning either the custom onTimeout response or a default 504.
-   */
-  async function handleTimeoutResponse(
-    request: Request,
-    env: TEnv,
-    url: URL,
-    phase: TimeoutPhase,
-    durationMs: number,
-    routeKey?: string,
-    actionId?: string,
-  ): Promise<Response> {
-    const timeoutError = new RouterTimeoutError(phase, durationMs);
-    const requestContext = _getRequestContext<TEnv>();
-    const cursor = requestContext?._renderForeground;
-    const render: RenderTimeoutContext | undefined =
-      phase === "render-start" && cursor
-        ? {
-            mode: cursor.mode,
-            phase: cursor.phase,
-            state: cursor.state,
-            completed: cursor.completed,
-            total: cursor.total,
-            ...(cursor.phaseStartedAt !== undefined && {
-              phaseDurationMs: performance.now() - cursor.phaseStartedAt,
-            }),
-          }
-        : undefined;
-    const trace =
-      phase === "render-start" ? requestContext?._activeRoutine : undefined;
-    const activeEntries = trace?.active() ?? [];
-    const activeStep = activeEntries.at(-1);
-    const activeAt = performance.now();
-    const routineSnapshot =
-      trace && activeStep
-        ? {
-            name: trace.name,
-            path: activeEntries.map((entry) => entry.name),
-            durationMs: activeAt - activeStep.startedAt,
-          }
-        : undefined;
-
-    if (INTERNAL_RANGO_DEBUG && trace && activeStep) {
-      console.log(
-        `[routine] TIMEOUT ${request.method} ${url.pathname} (${trace.name})\n${trace.formatActive(activeEntries, activeAt)}`,
-      );
-    }
-
-    // Each surface gets its OWN shallow render snapshot. A consumer that mutates
-    // its copy must not corrupt what the other two observe. The internal-debug
-    // routine snapshot is bounded metadata sent only to onError.
-    callOnError(timeoutError, phase === "action" ? "action" : "handler", {
-      request,
-      url,
-      env,
-      routeKey,
-      actionId,
-      handledByBoundary: false,
-      metadata: {
-        timeout: true,
-        phase,
-        durationMs,
-        ...(render && { render: { ...render } }),
-        ...(routineSnapshot && { routine: routineSnapshot }),
-      },
-    });
-
-    if (router.telemetry) {
-      safeEmit(resolveSink(router.telemetry), {
-        type: "request.timeout",
-        timestamp: performance.now(),
-        requestId: getRequestId(request),
-        phase,
-        pathname: url.pathname,
-        routeKey,
-        actionId,
-        durationMs,
-        customHandler: !!router.onTimeout,
-        ...(render && { render: { ...render } }),
-      });
-    }
-
-    if (router.onTimeout) {
-      try {
-        return await router.onTimeout({
-          phase,
-          request,
-          url,
-          env,
-          routeKey,
-          actionId,
-          durationMs,
-          ...(render && { render: { ...render } }),
-        });
-      } catch (e) {
-        if (process.env.NODE_ENV !== "production") {
-          console.error("[RSC] onTimeout callback error:", e);
-        }
-        return createDefaultTimeoutResponse(phase);
-      }
-    }
-
-    return createDefaultTimeoutResponse(phase);
-  }
-
   /**
    * Build a 200 Flight response that carries a redirect URL and optional state.
    * Used when a partial/action request results in a redirect -- fetch
@@ -413,7 +274,7 @@ export function createRSCHandler<
           env: reqCtx.env,
           payload: redirectPayload,
           tracking: {
-            mode: reqCtx.url.searchParams.has("_rsc_action")
+            mode: reqCtx.url.searchParams.has(WIRE.action)
               ? "action-revalidation"
               : "partial",
             routeKey: reqCtx._routeName,
@@ -476,7 +337,7 @@ export function createRSCHandler<
     // Connection warmup: return 204 immediately before any processing
     if (router?.warmupEnabled && request.method === "HEAD") {
       const warmupUrl = new URL(request.url);
-      if (warmupUrl.searchParams.has("_rsc_warmup")) {
+      if (warmupUrl.searchParams.has(WIRE.warmup)) {
         return new Response(null, { status: 204 });
       }
     }
@@ -637,18 +498,7 @@ export function createRSCHandler<
       requestContext._debugPerformance = true;
       requestContext._metricsStore = earlyMetricsStore;
     }
-    // Wire background error reporting so "use cache" and other subsystems
-    // can surface non-fatal errors through the router's onError callback.
-    requestContext._reportBackgroundError = (
-      error: unknown,
-      category: CacheErrorCategory,
-    ) => {
-      callOnError(error, "cache", {
-        request,
-        url,
-        metadata: { category },
-      });
-    };
+    reportBackgroundErrors(requestContext, request, url, callOnError);
 
     const ctxCreateDur = performance.now() - ctxCreateStart;
 
@@ -660,9 +510,8 @@ export function createRSCHandler<
       `handler-ctx-create;dur=${ctxCreateDur.toFixed(2)}`,
     ];
 
-    // Store timing data in variables for downstream access
-    variables.__handlerTiming = handlerTiming;
-    variables.__handlerStart = handlerStart;
+    // The core handler adds its classify timing (coreRequestHandler).
+    requestContext._handlerTiming = handlerTiming;
 
     // Wrap entire request handling in request context
     // Makes context available via getRequestContext() throughout:
@@ -693,57 +542,29 @@ export function createRSCHandler<
         // latter is reserved for the low-cardinality template (OTel convention).
         span.setAttribute("url.path", url.pathname);
 
-        // One pass per URL: the global middleware chain matched on the pass's
-        // path, wrapping the core handler. A `throw rewrite()` from global or
-        // route middleware unwinds the pass, and the next one runs the same
-        // request as the target from the top, as a direct visit would
-        // (rsc/rewrite-passes.ts). The response is finalized below, inside the
-        // response span.
-        let passIndex = 0;
-        let hasMiddleware = false;
-        const { response: downstream, rewrittenTo } = await runRewritePasses({
+        // The global middleware passes (rsc/request-stages.ts). The response
+        // is finalized below, inside the response span.
+        const {
+          response: downstream,
+          rewrittenTo,
+          hasMiddleware,
+        } = await runRequestPasses({
+          ctx: handlerCtx,
           reqCtx: requestContext,
           request,
           url,
-          routeMap: getRequiredRouteMap,
-          basename: router.basename,
-          runPass: (passRequest, passUrl) => {
-            const passMiddleware =
-              passIndex++ === 0
-                ? matchedMiddleware
-                : matchMiddleware(
-                    requestContext.url.pathname,
-                    router.middleware,
-                  );
-            hasMiddleware = passMiddleware.length > 0;
-            const coreHandler = (): Promise<Response> =>
-              coreRequestHandler(passRequest, env, passUrl, variables, nonce);
-            return hasMiddleware
-              ? executeMiddleware(
-                  passMiddleware,
-                  passRequest,
-                  env,
-                  variables,
-                  coreHandler,
-                  createReverseFunction(getRequiredRouteMap()),
-                )
-              : coreHandler();
-          },
+          env,
+          variables,
+          firstPassMiddleware: matchedMiddleware,
+          core: (passRequest, passUrl) =>
+            coreRequestHandler(passRequest, env, passUrl, variables, nonce),
           onHop: (pass) => {
             span.setAttribute("rango.rewrite.target", pass.target.pathname);
             span.setAttribute("rango.rewrite.hops", pass.hops);
           },
-          report: (error, at) => {
-            callOnError(error, "routing", {
-              request: at.request,
-              url: at.url,
-              env,
-              handledByBoundary: false,
-            });
-          },
           // A loader fetch answers with the error `load()` rejects with.
           refuse: (error) =>
-            url.searchParams.has("_rsc_loader")
+            url.searchParams.has(WIRE.loader)
               ? renderLoaderError(
                   handlerCtx,
                   { message: (error as Error).message, name: "Error" },
@@ -752,7 +573,7 @@ export function createRSCHandler<
                     request,
                     url,
                     env,
-                    loaderId: url.searchParams.get("_rsc_loader") ?? "",
+                    loaderId: url.searchParams.get(WIRE.loader) ?? "",
                   },
                 )
               : undefined,
@@ -767,130 +588,60 @@ export function createRSCHandler<
           // Header and cookie writes from here on (a streaming loader or
           // render) no longer reach the response.
           requestContext._responseSent = true;
-          let response: Response;
-          if (hasMiddleware) {
-            if (
-              url.searchParams.has("_rsc_partial") ||
-              url.searchParams.has("_rsc_action")
-            ) {
-              const intercepted = interceptRedirectForPartial(
-                downstream,
-                createRedirectFlightResponse,
-                { requestOrigin: url.origin, basename: router.basename },
-              );
-              response = intercepted ?? finalizeResponse(downstream);
-            } else {
-              response = finalizeResponse(downstream);
-            }
-          } else {
-            response = downstream;
-          }
-
-          // Finalize metrics after all middleware (including post-next work)
-          // has completed so :post spans are captured in the timeline.
-          // Handler timing parts are always emitted (even without debug metrics)
-          // so non-debug requests still get bootstrap Server-Timing entries.
-          const handlerTimingArr: string[] = variables.__handlerTiming || [];
-          // Preserve any existing Server-Timing set by response routes or middleware
-          const existingTiming = response.headers.get("Server-Timing");
-          const timingParts = existingTiming
-            ? [existingTiming, ...handlerTimingArr]
-            : [...handlerTimingArr];
-
-          const metricsStore = requestContext._metricsStore;
-          if (metricsStore) {
-            // When the store was created at handler start (earlyMetricsStore),
-            // handler:total covers the full request. When ctx.debugPerformance()
-            // created the store mid-request its requestStart is now the threaded
-            // _handlerStart (== handlerStart), so both branches yield the true
-            // request entry; reading the store's own anchor keeps this correct even
-            // if a store ever lands without the threading (falls back to its start).
-            const totalStart = earlyMetricsStore
-              ? handlerStart
-              : metricsStore.requestStart;
-            appendMetric(
-              metricsStore,
-              "handler:total",
-              totalStart,
-              performance.now() - totalStart,
-            );
-            const metricsTiming = buildMetricsTiming(
-              request.method,
-              url.pathname,
-              metricsStore,
-            );
-            if (metricsTiming) timingParts.push(metricsTiming);
-          }
-
-          const fullTiming = timingParts.join(", ");
-          if (fullTiming) trySetHeader(response, "Server-Timing", fullTiming);
-          if (rewrittenTo !== undefined) {
-            trySetHeader(response, REWRITE_HEADER, rewrittenTo);
-          }
-
-          // Single open-redirect chokepoint: every response (PE, full-page,
-          // middleware short-circuit, response-route) funnels through here, so
-          // guarding browser-followed (3xx) redirects once covers them all and any
-          // future redirect exit. Soft SPA/Flight redirects are 200/204 and pass
-          // through untouched (validated client-side instead).
-          const guarded = guardOutgoingRedirect(
-            response,
-            url.origin,
-            router.basename,
-          );
-
-          // Stream-idle watchdog (opt-in via timeouts.streamIdleMs): bounds
-          // end-to-end idle flow on the streamed body — see rsc/stream-idle.ts
-          // for the semantics. Applied at this finalization chokepoint so every
-          // streaming exit is covered; websocket upgrades must never be
-          // reconstructed and bodiless responses have nothing to bound. The
-          // trip fires POST-handoff (the request ALS may be gone), so it
-          // reports via the eagerly captured surfaces — callOnError +
-          // router.telemetry directly — mirroring handleStore.onError.
-          // onTimeout does NOT apply: the response already left the handler,
-          // so no replacement Response can be served mid-stream.
-          let finalResponse = guarded;
-          const streamIdleMs = router.timeouts.streamIdleMs;
-          // Websocket check FIRST: a workerd upgrade response must never have
-          // its body getter poked (same invariant as the body_kind attribute
-          // below).
-          if (
-            isTimeoutEnabled(streamIdleMs) &&
-            !isWebSocketUpgradeResponse(guarded) &&
-            guarded.body
-          ) {
-            const routeKey = requestContext._routeName;
-            finalResponse = applyStreamIdleTimeout(
-              guarded,
-              streamIdleMs!,
-              (tripInfo) => {
-                callOnError(tripInfo.error, "handler", {
-                  request,
-                  url,
-                  env,
-                  routeKey,
-                  handledByBoundary: false,
-                  metadata: {
-                    timeout: true,
-                    phase: "stream-idle",
-                    durationMs: tripInfo.totalMs,
-                  },
-                });
-                if (router.telemetry) {
-                  safeEmit(resolveSink(router.telemetry), {
-                    type: "request.timeout",
-                    timestamp: performance.now(),
-                    requestId: getRequestId(request),
-                    phase: "stream-idle",
-                    pathname: url.pathname,
-                    routeKey,
-                    durationMs: tripInfo.totalMs,
-                    customHandler: false,
-                  });
-                }
-              },
-            );
-          }
+          const finalResponse = finalizeRequestResponse(downstream, {
+            ctx: handlerCtx,
+            reqCtx: requestContext,
+            request,
+            url,
+            env,
+            hasMiddleware,
+            rewrittenTo,
+            beforeGuard: (response) => {
+              // Finalize metrics after all middleware (including post-next
+              // work) has completed so :post spans are captured in the
+              // timeline. Handler timing parts are always emitted (even
+              // without debug metrics) so non-debug requests still get
+              // bootstrap Server-Timing entries.
+              // Preserve any existing Server-Timing set by response routes or
+              // middleware
+              const existingTiming = response.headers.get("Server-Timing");
+              const timingParts = existingTiming
+                ? [existingTiming, ...handlerTiming]
+                : [...handlerTiming];
+
+              const metricsStore = requestContext._metricsStore;
+              if (metricsStore) {
+                // When the store was created at handler start
+                // (earlyMetricsStore), handler:total covers the full request.
+                // When ctx.debugPerformance() created the store mid-request
+                // its requestStart is now the threaded _handlerStart
+                // (== handlerStart), so both branches yield the true request
+                // entry; reading the store's own anchor keeps this correct
+                // even if a store ever lands without the threading (falls
+                // back to its start).
+                const totalStart = earlyMetricsStore
+                  ? handlerStart
+                  : metricsStore.requestStart;
+                appendMetric(
+                  metricsStore,
+                  "handler:total",
+                  totalStart,
+                  performance.now() - totalStart,
+                );
+                const metricsTiming = buildMetricsTiming(
+                  request.method,
+                  url.pathname,
+                  metricsStore,
+                );
+                if (metricsTiming) timingParts.push(metricsTiming);
+              }
+
+              const fullTiming = timingParts.join(", ");
+              if (fullTiming) {
+                trySetHeader(response, "Server-Timing", fullTiming);
+              }
+            },
+          });
 
           // Attributes describe the response actually handed to the host (after
           // unsafe-redirect replacement), low-cardinality only. body_kind checks
@@ -920,8 +671,9 @@ export function createRSCHandler<
   };
 
   // Core request handling logic (separated for middleware wrapping).
-  // Uses the classify → execute model: classifyRequest produces a RequestPlan,
-  // then execution dispatches on the plan mode.
+  // The request stages (rsc/request-stages.ts) classify the request into a
+  // RequestPlan and answer its terminal plans; execution dispatches on the
+  // plan mode.
   async function coreRequestHandler(
     request: Request,
     env: TEnv,
@@ -929,44 +681,12 @@ export function createRSCHandler<
     variables: Record<string, any>,
     nonce: string | undefined,
   ): Promise<Response> {
-    const handlerTiming: string[] = variables.__handlerTiming || [];
+    const reqCtx = getRequestContext();
+    const handlerTiming: string[] = reqCtx._handlerTiming || [];
 
     // ---- 1. Classify ----
-    // classifyRequest may throw RouteNotFoundError for unknown routes.
-    // In that case, fall through to a full-render plan so the pipeline
-    // can render the 404 page via the existing error handling path.
     const classifyStart = performance.now();
-    let plan: RequestPlan<TEnv>;
-    try {
-      plan = await classifyRequest<TEnv>(request, url, {
-        findMatch: router.findMatch,
-        routerVersion: version,
-        routerId: router.id,
-      });
-    } catch (error) {
-      if (isRouteNotFoundError(error)) {
-        // Let the render path handle 404 — match()/matchPartial() will
-        // re-throw RouteNotFoundError and the catch block in
-        // executeRenderWithMiddleware renders the not-found page.
-        plan = {
-          mode: "full-render",
-          route: {
-            matched: null as any,
-            manifestEntry: null as any,
-            entries: [],
-            routeKey: "",
-            localRouteName: "",
-            params: {},
-            routeMiddleware: [],
-            cacheScope: null,
-            isPassthrough: false,
-          },
-          negotiated: false,
-        };
-      } else {
-        throw error;
-      }
-    }
+    const plan = await classify(request, url, handlerCtx);
     const classifyDur = performance.now() - classifyStart;
     handlerTiming.push(`handler-classify;dur=${classifyDur.toFixed(2)}`);
 
@@ -974,64 +694,16 @@ export function createRSCHandler<
     // — the outer handler tail cannot see the plan. Stays unset when middleware
     // short-circuits before core execution runs (reported as
     // "middleware-short-circuit").
-    getRequestContext()._requestMode = plan.mode;
-
-    // A rewritten pass of an action must reach the branch that runs it: the
-    // one that ran it re-renders from its outcome, and a JS action a global
-    // rewrite moved before it ran runs only on the action branch. Any other
-    // plan would serve the POST as a fresh request or drop the action; a
-    // reload (version mismatch, app switch) does neither.
-    const passCtx = getRequestContext();
-    const actionRan = passCtx._actionRan;
-    const actionMode = actionRan
-      ? actionRan.kind === "action"
-        ? "action"
-        : "pe-render"
-      : url.searchParams.has("_rsc_action") && rewriteTrail(passCtx)
-        ? "action"
-        : undefined;
-    if (
-      actionMode &&
-      plan.mode !== actionMode &&
-      plan.mode !== "version-mismatch" &&
-      plan.mode !== "app-switch"
-    ) {
-      throw new Error(
-        `A rewrite of a server action or form post must target a page ` +
-          `route; ${url.pathname} ${plan.mode === "response" ? "is a response route" : plan.mode === "redirect" ? "redirects" : "is not one"}.`,
-      );
-    }
+    reqCtx._requestMode = plan.mode;
 
     // ---- 2. Terminal plans (no execution needed) ----
-    if (plan.mode === "redirect") {
-      // Redirects are handled by the pipeline (match/matchPartial),
-      // but for partial requests we short-circuit with a Flight redirect.
-      if (url.searchParams.has("_rsc_partial")) {
-        return createRedirectFlightResponse(plan.redirectUrl);
-      }
-      // Full requests: let the pipeline handle the redirect via match()
-      // which returns { redirect: url }. Fall through to full-render.
-    }
-
-    // A reload points at the visitor's URL, never a rewrite target's.
-    if (plan.mode === "version-mismatch") {
-      console.log(
-        `[RSC] Version mismatch: client=${url.searchParams.get("_rsc_v")}, server=${version}. Forcing reload.`,
-      );
-      return createReloadResponse(getRequestContext(), plan.reloadUrl);
-    }
-
-    if (plan.mode === "app-switch") {
-      // Cross-app SPA navigation crossed a host-router app boundary. Force a
-      // real document navigation so the target app's document is re-established
-      // (stylesheets, theme, warmup, prefetch-TTL). See request-classification.
-      return createReloadResponse(getRequestContext(), plan.reloadUrl);
-    }
+    const terminal = terminalPlanResponse(plan, url, handlerCtx);
+    if (terminal) return terminal;
 
     // ---- 3. Origin guard (gate for action/loader/PE modes) ----
     const originPhase = ORIGIN_CHECK_PHASE_BY_MODE[plan.mode];
     if (originPhase) {
-      const originResult = await checkRequestOrigin(
+      const rejection = await checkRequestOrigin(
         request,
         url,
         router.originCheck,
@@ -1039,36 +711,15 @@ export function createRSCHandler<
         router.id,
         originPhase,
       );
-      if (originResult) {
-        const origin = requestHeaders(request).get("origin");
-        const host = requestHeaders(request).get("host");
-        const originError = new Error(
-          `Origin check rejected: ${origin ?? "none"} vs ${host ?? "none"}`,
-        );
-        originError.name = "OriginCheckError";
-
-        callOnError(originError, "origin", {
+      if (rejection) {
+        return originRejectedResponse(
+          rejection,
+          originPhase,
           request,
-          url,
           env,
-          handledByBoundary: false,
-          metadata: { phase: originPhase, origin, host },
-        });
-
-        if (router.telemetry) {
-          safeEmit(resolveSink(router.telemetry), {
-            type: "request.origin-rejected",
-            timestamp: performance.now(),
-            requestId: getRequestId(request),
-            method: request.method,
-            pathname: url.pathname,
-            phase: originPhase,
-            origin,
-            host,
-          });
-        }
-
-        return originResult;
+          url,
+          handlerCtx,
+        );
       }
     }
 
@@ -1108,7 +759,9 @@ export function createRSCHandler<
         params: reqCtx.params as Record<string, string>,
         handledByBoundary: true,
       });
-      if (router.telemetry) {
+      // A PPR shell capture's store inherits this onError
+      // (deriveShellCaptureContext); the capture sends nothing to the sink.
+      if (router.telemetry && !reqCtx._shellCaptureState?.run) {
         safeEmit(resolveSink(router.telemetry), {
           type: "handler.error",
           timestamp: performance.now(),
@@ -1122,57 +775,21 @@ export function createRSCHandler<
       }
     };
 
-    // Set route params early so all execution paths can access ctx.params.
-    // Also store the classified snapshot so match/matchPartial can reuse it
-    // instead of calling resolveRoute again.
-    if (plan.mode !== "redirect") {
-      setRequestContextParams(plan.route.params, plan.route.routeKey);
-      getRequestContext()._classifiedRoute = plan.route;
-    }
+    // Before any execution path, so each can read ctx.params.
+    recordPlanRoute(plan);
 
     const routeReverse = createReverseFunction(getRequiredRouteMap());
 
     // ---- Response route: skip entire RSC pipeline ----
     if (plan.mode === "response") {
-      // Build ResponseRouteMatch from plan fields. handleResponseRoute
-      // expects a flat object with params at the top level.
-      const responseMatch: ResponseRouteMatch = {
-        responseType: plan.responseType,
-        handler: plan.handler,
-        params: plan.route.params,
-        negotiated: plan.negotiated,
-        manifestEntry: plan.manifestEntry,
-        routeMiddleware: plan.routeMiddleware,
-      };
-      const responseOutcome = await withTimeout(
-        handleResponseRoute(
-          handlerCtx,
-          responseMatch,
-          request,
-          env,
-          url,
-          variables,
-        ),
-        router.timeouts.renderStartMs,
-        "render-start",
-      );
-      if (responseOutcome.timedOut) {
-        return handleTimeoutResponse(
-          request,
-          env,
-          url,
-          "render-start",
-          responseOutcome.durationMs,
-          plan.route.routeKey,
-        );
-      }
-      const response = responseOutcome.result;
-      if (plan.negotiated && !isWebSocketUpgradeResponse(response)) {
-        // handleResponseRoute (callHandlerWithVary) already appends Vary: Accept
-        // for negotiated responses; dedup so we don't emit Vary: Accept, Accept.
-        appendVaryAccept(response);
-      }
-      return response;
+      return serveResponseRoute(handlerCtx, {
+        match: responseRouteMatch(plan),
+        routeKey: plan.route.routeKey,
+        request,
+        url,
+        env,
+        variables,
+      });
     }
 
     // SSR setup: kick off in parallel for modes that need HTML rendering.
@@ -1285,7 +902,8 @@ export function createRSCHandler<
             "action",
           );
           if (actionOutcome.timedOut) {
-            return handleTimeoutResponse(
+            return timeoutResponse(
+              handlerCtx,
               request,
               env,
               url,
@@ -1325,7 +943,7 @@ export function createRSCHandler<
       // Actions from client-side navigation include _rsc_partial — preserve
       // the partial flag so the revalidation returns a Flight stream, not HTML.
       // App-switch is already excluded by classifyRequest (would be full-render).
-      const isPartialAction = url.searchParams.has("_rsc_partial");
+      const isPartialAction = url.searchParams.has(WIRE.partial);
       return executeRenderWithMiddleware(
         plan.route.routeMiddleware,
         plan.negotiated,
@@ -1615,7 +1233,8 @@ export function createRSCHandler<
       "render-start",
     );
     if (renderOutcome.timedOut) {
-      return handleTimeoutResponse(
+      return timeoutResponse(
+        handlerCtx,
         request,
         env,
         url,