@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/server/pipeline.ts

@@ -2,26 +2,25 @@
  * Request pipeline — the central dispatch for all timber.js requests.
  *
  * Pipeline stages (in order):
- *   proxy.ts → canonicalize → route match → 103 Early Hints → middleware.ts → render
+ *   canonicalize → CSRF gate → proxy.ts → route match → 103 Early Hints → middleware.ts → render
  *
- * Each stage is a pure function or returns a Response to short-circuit.
- * Each request gets a trace ID, structured logging, and OTEL spans.
+ * The phase functions live in `pipeline-phases.ts` so each phase can be
+ * tested in isolation. The terminal `outcomeToResponse` translator and
+ * stateless helpers live in `pipeline-phases.ts` and `pipeline-helpers.ts`
+ * respectively. This file owns only the public type surface and the
+ * `createPipeline` entry point: trace ID setup, request-context ALS,
+ * Server-Timing wrapping, and the activeRequests counter.
  *
  * See design/07-routing.md §"Request Lifecycle", design/02-rendering-pipeline.md §"Request Flow",
  * and design/17-logging.md §"Production Logging"
  */
 
-import { canonicalize } from './canonicalize.js';
-import { runProxy, type ProxyExport } from './proxy.js';
-import { runMiddleware, type MiddlewareFn } from './middleware-runner.js';
-import { runWithTimingCollector, withTiming, getServerTimingHeader } from './server-timing.js';
-import {
-  runWithRequestContext,
-  applyRequestHeaderOverlay,
-  setMutableCookieContext,
-  getSetCookieHeaders,
-  markResponseFlushed,
-} from './request-context.js';
+import type { CoercedParams } from '../shared/param-value.ts';
+import type { ProxyExport } from './proxy.ts';
+import type { MiddlewareFn } from './middleware-runner.ts';
+import { runWithTimingCollector, getServerTimingHeader } from './server-timing.ts';
+import { wrapResponseWithStreamTiming } from './stream-utils.ts';
+import { runWithRequestContext } from './request-context.ts';
 import {
   generateTraceId,
   runWithTraceId,
@@ -29,34 +28,49 @@ import {
   replaceTraceId,
   withSpan,
   setSpanAttribute,
-  traceId,
-} from './tracing.js';
-import {
-  logRequestReceived,
-  logRequestCompleted,
-  logSlowRequest,
-  logProxyError,
-  logMiddlewareError,
-  logMiddlewareShortCircuit,
-  logRenderError,
-} from './logger.js';
-import { callOnRequestError } from './instrumentation.js';
-import { RedirectSignal, DenySignal } from './primitives.js';
-import { serveStaticMetadataFile, serializeSitemap } from './pipeline-metadata.js';
-import { findInterceptionMatch } from './pipeline-interception.js';
-import type { MiddlewareContext } from './types.js';
-import type { SegmentNode } from '#/routing/types.js';
+} from './tracing.ts';
+import { logRequestReceived, logRequestCompleted, logSlowRequest } from './logger.ts';
+import { DenySignal } from './primitives.ts';
+import type { ManifestSegmentNode } from './route-matcher.ts';
+import { csrfGate, makeProxyResolver } from './pipeline-helpers.ts';
+import type { CsrfConfig } from './csrf.ts';
+import { handleRequest, runProxyPhase } from './pipeline-phases.ts';
+import { outcomeToResponse } from './pipeline-outcome.ts';
+import { canonicalize } from './canonicalize.ts';
+import { enforceRscCacheKey, hardenRscPayloadResponse } from './rsc-cache-key-guard.ts';
+import { stripHeadBody } from './head-response.ts';
+import { RSC_KEY_HEADERS } from '../shared/rsc-cache-key.ts';
+import { isDebug } from './debug.ts';
 
 // ─── Route Match Result ────────────────────────────────────────────────────
 
-/** Result of matching a canonical pathname against the route tree. */
+/**
+ * Result of matching a canonical pathname against the route tree.
+ *
+ * `segments` is the runtime (`ManifestFile`-specialized) shape — the same
+ * nodes carried in the virtual route manifest. TIM-863 unified this: the
+ * matcher produces `ManifestSegmentNode[]` directly and every consumer
+ * (render, slots, params coercion, early hints, deny fallback) sees the
+ * same structural type with no `as unknown as` laundering.
+ */
 export interface RouteMatch {
   /** The matched segment chain from root to leaf. */
-  segments: SegmentNode[];
-  /** Extracted route params (catch-all segments produce string[]). */
-  params: Record<string, string | string[]>;
-  /** The leaf segment's middleware.ts export, if any. */
-  middleware?: MiddlewareFn;
+  segments: ManifestSegmentNode[];
+  /**
+   * Segment params as the page sees them. The matcher sets them to the raw
+   * values; whoever runs `coerceSegmentParams()` replaces them with its
+   * result, whose values may be non-string (TIM-1347).
+   */
+  segmentParams: CoercedParams;
+  /**
+   * Segment params as the URL carried them (catch-all segments produce
+   * string[]). Set by the matcher, which owns them, and never replaced.
+   * Slot resolution and URL-part reconstruction read these: coerced values
+   * need not round-trip to the URL (`"007"` → `7`).
+   */
+  rawSegmentParams: Record<string, string | string[]>;
+  /** Middleware chain from the segment tree, ordered root-to-leaf. */
+  middlewareChain: MiddlewareFn[];
 }
 
 /** Function that matches a canonical pathname to a route. */
@@ -65,7 +79,7 @@ export type RouteMatcher = (pathname: string) => RouteMatch | null;
 /** Function that matches a canonical pathname to a metadata route. */
 export type MetadataRouteMatcher = (
   pathname: string
-) => import('./route-matcher.js').MetadataRouteMatch | null;
+) => import('./route-matcher.ts').MetadataRouteMatch | null;
 
 /** Context for intercepting route resolution (modal pattern). */
 export interface InterceptionContext {
@@ -78,7 +92,6 @@ export type RouteRenderer = (
   req: Request,
   match: RouteMatch,
   responseHeaders: Headers,
-  requestHeaderOverlay: Headers,
   interception?: InterceptionContext
 ) => Response | Promise<Response>;
 
@@ -91,13 +104,40 @@ export type EarlyHintsEmitter = (
 
 // ─── Pipeline Configuration ────────────────────────────────────────────────
 
+/**
+ * Proxy source — a tagged union so the choice between "already-resolved
+ * export" and "lazy HMR-friendly loader" is encoded in the type, not
+ * inferred per-request.
+ *
+ * - `static` — the proxy export is already resolved (production, tests).
+ * - `lazy`   — a loader is called per-request for HMR freshness (dev).
+ *
+ * `PipelineConfig.proxy` also accepts a bare `ProxyExport` (a function or
+ * function array) as shorthand for the static variant — convenient for tests
+ * that construct a `createPipeline` config inline. Omit the field entirely
+ * when the app has no `proxy.ts`.
+ *
+ * See design/07-routing.md §"proxy.ts — Global Middleware".
+ */
+export type ProxyConfig =
+  | { kind: 'static'; export: ProxyExport }
+  | { kind: 'lazy'; loader: () => Promise<{ default: ProxyExport }> };
+
 export interface PipelineConfig {
-  /** The proxy.ts default export (function or array). Undefined if no proxy.ts. */
-  proxy?: ProxyExport;
-  /** Lazy loader for proxy.ts — called per-request so HMR updates take effect. */
-  proxyLoader?: () => Promise<{ default: ProxyExport }>;
+  /**
+   * proxy.ts source. Undefined if the app has no proxy.ts. Accepts either a
+   * tagged `ProxyConfig` (canonical) or a bare `ProxyExport` as sugar for the
+   * static variant.
+   */
+  proxy?: ProxyConfig | ProxyExport;
   /** Route matcher — resolves a canonical pathname to a RouteMatch. */
   matchRoute: RouteMatcher;
+  /**
+   * CSRF configuration (`allowedOrigins`, the `csrf: false` switch). The
+   * gate is on when this is omitted — protection is never opt-in. See
+   * design/08-forms-and-actions.md §"CSRF Protection".
+   */
+  csrf?: CsrfConfig;
   /** Metadata route matcher — resolves metadata route pathnames (sitemap.xml, robots.txt, etc.) */
   matchMetadataRoute?: MetadataRouteMatcher;
   /** Renderer — produces the final Response for a matched route. */
@@ -115,7 +155,18 @@ export interface PipelineConfig {
    * Generated at build time from intercepting route directories.
    * See design/07-routing.md §"Intercepting Routes"
    */
-  interceptionRewrites?: import('#/routing/interception.js').InterceptionRewrite[];
+  interceptionRewrites?: import('../routing/interception.ts').InterceptionRewrite[];
+  /**
+   * Resolver for children-path interceptions — the sibling layout swap.
+   *
+   * Separate from `matchRoute` because it addresses the owner directory by
+   * tree path rather than by pathname, which needs the manifest tree itself.
+   * Omitting it disables the `'children'` interception shape and leaves the
+   * canonical route rendering, which is the fail-safe outcome.
+   *
+   * See design/07-routing.md §"Intercepting Routes"
+   */
+  matchInterceptedRoute?: import('./children-interception.ts').InterceptedRouteMatcher;
   /**
    * Control Server-Timing header output.
    *
@@ -126,6 +177,14 @@ export interface PipelineConfig {
    * Default: `'total'`.
    */
   serverTiming?: 'detailed' | 'total' | false;
+  /**
+   * Auto-generated sitemap handler. When provided, the pipeline intercepts
+   * `/sitemap.xml` and `/sitemap/N.xml` requests and delegates to this
+   * function. Returns a Response or null (pass-through to regular routing).
+   *
+   * See design/16-metadata.md §"Auto-generated Sitemap"
+   */
+  autoSitemapHandler?: (pathname: string) => Promise<Response | null>;
   /**
    * Dev pipeline error callback — called when a pipeline phase (proxy,
    * middleware, render) catches an unhandled error. Used to wire the error
@@ -134,6 +193,7 @@ export interface PipelineConfig {
    * Undefined in production — zero overhead.
    */
   onPipelineError?: (error: Error, phase: string) => void;
+
   /**
    * Fallback error renderer — called when a catastrophic error escapes the
    * render phase. Produces an HTML Response instead of a bare empty 500.
@@ -148,8 +208,62 @@ export interface PipelineConfig {
   renderFallbackError?: (
     error: unknown,
     req: Request,
-    responseHeaders: Headers
+    responseHeaders: Headers,
+    /**
+     * The matched route, when the error came after matching. A route.ts
+     * match is answered in the API route's JSON format, never a page
+     * (design/10-error-handling.md §"JSON Error Pages").
+     */
+    match?: RouteMatch
   ) => Response | Promise<Response>;
+  /**
+   * Fallback deny page renderer — called when a DenySignal escapes from
+   * middleware or the render phase. Renders the appropriate status-code
+   * page (403.tsx, 404.tsx, etc.) instead of returning a bare empty response.
+   *
+   * If this function throws, the pipeline falls back to a bare
+   * `new Response(null, { status: denyStatus })`.
+   */
+  renderDenyFallback?: (
+    deny: DenySignal,
+    req: Request,
+    responseHeaders: Headers,
+    /**
+     * The matched route, if available. Provided by both the middleware-stage
+     * and render-stage catch blocks (matching runs before middleware). When
+     * present, the renderer should resolve the deny status file against the
+     * matched chain so colocated `403.tsx`/`4xx.tsx`/`401.json` files are
+     * picked up. Falls back to the root-only chain when omitted (e.g. for
+     * deny()s thrown before route matching could complete). See TIM-822.
+     */
+    match?: RouteMatch
+  ) => Response | Promise<Response>;
+
+  /**
+   * Server action dispatch — called after proxy.ts runs for POST requests
+   * that look like server actions. Returns a Response if the request was
+   * handled as an action, or null to fall through to normal routing.
+   *
+   * `canonicalPath` is the already-decoded canonical pathname — the same
+   * value that `handleRequest` and `matchRoute` use. Do NOT re-derive it
+   * from `req.url` (which re-encodes).
+   *
+   * The `reenter` parameter is the full pipeline function (including proxy,
+   * ALS, tracing) for the no-JS validation rerender path — the synthetic
+   * GET flows through the complete pipeline. Its `cookies` argument becomes
+   * that request's parsed cookies (`runWithRequestContext`'s `cookies`
+   * option), so the rerender reads the action's post-mutation state without
+   * the pipeline needing the same `Request` object to reach it.
+   *
+   * Moved into the pipeline (TIM-1213) so proxy.ts runs on action POSTs,
+   * matching the design doc contract: "proxy.ts runs on every request,
+   * no exclusions."
+   */
+  dispatchAction?: (
+    req: Request,
+    canonicalPath: string,
+    reenter: (req: Request, cookies: Map<string, string>) => Promise<Response>
+  ) => Promise<Response | null>;
 }
 
 // ─── Pipeline ──────────────────────────────────────────────────────────────
@@ -157,31 +271,35 @@ export interface PipelineConfig {
 /**
  * Create the request handler from a pipeline configuration.
  *
- * Returns a function that processes an incoming Request through all pipeline stages
- * and produces a Response. This is the top-level entry point for the server.
+ * Returns a function that processes an incoming Request through all pipeline
+ * stages and produces a Response. This is the top-level entry point for the
+ * server. The body is intentionally small — phase logic lives in
+ * `pipeline-phases.ts`. This function only owns the per-request setup that
+ * has to wrap the entire dispatch: trace ID, request context ALS, span
+ * scope, Server-Timing header emission, and the active-request counter.
  */
 export function createPipeline(config: PipelineConfig): (req: Request) => Promise<Response> {
-  const {
-    proxy,
-    matchRoute,
-    render,
-    earlyHints,
-    stripTrailingSlash = true,
-    slowRequestMs = 3000,
-    serverTiming = 'total',
-    onPipelineError,
-  } = config;
+  // Resolve the proxy source once. The request hot path calls this closure
+  // directly with no discriminant check — the branch is taken here during
+  // setup. For the lazy variant, `loader()` still runs per-request so HMR
+  // continues to re-import the user's proxy.ts.
+  const proxyResolver = makeProxyResolver(config.proxy);
+  const slowRequestMs = config.slowRequestMs ?? 3000;
+  const serverTiming = config.serverTiming ?? 'total';
 
   // Concurrent request counter — tracks how many requests are in-flight.
   // Logged with each request for diagnosing resource contention.
   let activeRequests = 0;
 
-  return async (req: Request): Promise<Response> => {
+  // Self-reference for re-entry — the no-JS validation rerender path
+  // passes a synthetic GET back through the full pipeline (including
+  // proxy, ALS, tracing). The inner closure captures `pipelineFn` by
+  // name; by the time it's invoked, the const binding is initialized.
+  const pipelineFn = async (req: Request, cookies?: Map<string, string>): Promise<Response> => {
     const url = new URL(req.url);
     const method = req.method;
     const path = url.pathname;
     const startTime = performance.now();
-    activeRequests++;
 
     // Establish per-request trace ID scope (design/17-logging.md §"trace_id is Always Set").
     // This runs before runWithRequestContext so traceId() is available from the
@@ -189,65 +307,224 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
     const traceIdValue = generateTraceId();
 
     return runWithTraceId(traceIdValue, async () => {
-      // Establish request context ALS scope so headers() and cookies() work
-      // throughout the entire request lifecycle (proxy, middleware, render).
-      return runWithRequestContext(req, async () => {
+      // Runs in the request context ALS scope, so getHeaders() and getCookies()
+      // work throughout the entire request lifecycle (proxy, middleware, render).
+      const inRequestContext = async () => {
         // In dev mode, wrap with timing collector for Server-Timing header.
         // The collector uses ALS so timing entries are per-request.
         const runRequest = async () => {
           logRequestReceived({ method, path });
 
-          const response = await withSpan(
-            'http.server.request',
-            { 'http.request.method': method, 'url.path': path },
-            async () => {
-              // If OTEL is active, the root span now exists — replace the UUID
-              // fallback with the real OTEL trace ID for log–trace correlation.
-              const otelIds = await getOtelTraceId();
-              if (otelIds) {
-                replaceTraceId(otelIds.traceId, otelIds.spanId);
-              }
+          // Incremented and decremented in one scope, the decrement in
+          // `finally`: a rejection that escaped the span used to skip it and
+          // leave the request counted as in flight for the life of the
+          // process (TIM-1537).
+          activeRequests++;
+          let concurrency = activeRequests;
+          let response: Response;
+          try {
+            response = await withSpan(
+              'http.server.request',
+              { 'http.request.method': method, 'url.path': path },
+              async () => {
+                // If OTEL is active, the root span now exists — replace the UUID
+                // fallback with the real OTEL trace ID for log–trace correlation.
+                const otelTraceId = await getOtelTraceId();
+                if (otelTraceId) {
+                  replaceTraceId(otelTraceId);
+                }
 
-              let result: Response;
-              if (proxy || config.proxyLoader) {
-                result = await runProxyPhase(req, method, path);
-              } else {
-                result = await handleRequest(req, method, path);
-              }
+                // Stage 0: Canonicalize URL at the outer boundary — before
+                // proxy.ts sees the request. Every layer (proxy, middleware,
+                // access, render) must see the same canonical path.
+                // See design/07-routing.md §"URL Canonicalization & Security".
+                const stripTrailingSlash = config.stripTrailingSlash ?? true;
+                const canonResult = canonicalize(url.pathname, stripTrailingSlash);
+                if (!canonResult.ok) {
+                  if (isDebug()) {
+                    console.warn(
+                      `[timber] URL canonicalization rejected ${method} ${url.pathname} — responding with ${canonResult.status}\n` +
+                        `  This usually means the URL contains encoded separators (%2f, %5c),\n` +
+                        `  null bytes (%00), path traversal (..), or malformed percent-encoding.`
+                    );
+                  }
+                  // Early returns set the span status themselves: the shared
+                  // assignment below never runs for them, and a span with
+                  // none reads as 200 in DevSpanProcessor.
+                  await setSpanAttribute('http.response.status_code', canonResult.status);
+                  return new Response(null, { status: canonResult.status });
+                }
+                const canonicalPath = canonResult.pathname;
+
+                // Construct a Request with the canonical URL so proxy.ts sees
+                // the same path that route matching will use. This prevents
+                // auth bypass via /admin/, /%61dmin, etc.
+                let canonicalReq = req;
+                if (url.pathname !== canonicalPath) {
+                  const canonicalUrl = new URL(req.url);
+                  canonicalUrl.pathname = canonicalPath;
+                  canonicalReq = new Request(canonicalUrl.toString(), req);
+                }
 
-              // Set response status on the root span before it ends —
-              // DevSpanProcessor reads this for tree/summary output.
-              await setSpanAttribute('http.response.status_code', result.status);
-
-              // Append Server-Timing header based on configured mode.
-              // Response.redirect() creates immutable headers, so we must
-              // ensure mutability before writing Server-Timing.
-              if (serverTiming === 'detailed') {
-                // Detailed: per-phase breakdown (proxy, middleware, render).
-                const timingHeader = getServerTimingHeader();
-                if (timingHeader) {
-                  result = ensureMutableResponse(result);
-                  result.headers.set('Server-Timing', timingHeader);
+                // Stage 0b: CSRF gate — every unsafe-method request, before
+                // proxy.ts or any other user code, and before action
+                // dispatch, so route.ts handlers are covered too (LOCAL-773).
+                const csrfRejection = csrfGate(
+                  canonicalReq,
+                  canonicalPath,
+                  config.csrf ?? {},
+                  config.matchRoute
+                );
+                if (csrfRejection) {
+                  await setSpanAttribute('http.response.status_code', csrfRejection.status);
+                  return csrfRejection;
                 }
-              } else if (serverTiming === 'total') {
-                // Total only: single `total;dur=N` — no phase names.
-                // Prevents information disclosure while giving browser
-                // DevTools useful timing data.
-                const totalMs = Math.round(performance.now() - startTime);
-                result = ensureMutableResponse(result);
-                result.headers.set('Server-Timing', `total;dur=${totalMs}`);
-              }
-              // serverTiming === false: no header at all
 
-              return result;
-            }
-          );
+                // Build the inner handler — runs after proxy, before route
+                // matching. Checks for server action POSTs and dispatches them
+                // without entering the route match → middleware → render chain.
+                // Falls through to handleRequest for normal route handling.
+                // TIM-1213: action dispatch is now INSIDE the pipeline so
+                // proxy.ts runs on every request, including action POSTs.
+                const innerHandler = async (): Promise<Response> => {
+                  if (config.dispatchAction) {
+                    const actionResult = await config.dispatchAction(
+                      canonicalReq,
+                      canonicalPath,
+                      pipelineFn
+                    );
+                    if (actionResult) return actionResult;
+                  }
+                  return handleRequest(config, canonicalReq, method, canonicalPath, true);
+                };
+
+                let result: Response;
+                if (proxyResolver) {
+                  const outcome = await runProxyPhase(
+                    config,
+                    proxyResolver,
+                    canonicalReq,
+                    method,
+                    canonicalPath,
+                    innerHandler
+                  );
+                  result = await outcomeToResponse(config, outcome, {
+                    req: canonicalReq,
+                    method,
+                    path: canonicalPath,
+                  });
+                } else {
+                  result = await innerHandler();
+                }
+
+                // Set response status on the root span before it ends —
+                // DevSpanProcessor reads this for tree/summary output.
+                await setSpanAttribute('http.response.status_code', result.status);
+
+                // Vary on exactly the headers the `_rsc` cache key hashes.
+                //
+                // Those two mechanisms answer the same question — which request
+                // headers change this response — so they are the same list, not
+                // two lists that happen to agree. A separate hand-written list
+                // here drifted from `RSC_KEY_HEADERS` the moment the key set
+                // grew, and the drift is invisible: `Vary` is the *fallback*
+                // layer, used only when a cache omits the query from its key,
+                // which is precisely when nobody is watching (TIM-1268).
+                //
+                // Why any of it: without `Vary: Accept` a shared cache may serve
+                // an RSC Flight payload to a browser expecting HTML, or the
+                // reverse (GHSA-wfc6-r584-vfw7, design/13-security.md). The
+                // `_rsc` param puts that distinction in the URL, so correctness
+                // no longer *depends* on `Vary` — which is opt-in configuration
+                // on Cloudflare and CloudFront. `Vary` covers the requests that
+                // arrive without the param: a stripped query, a hand-rolled
+                // client.
+                //
+                // It costs no hit rate. Document requests send no `X-Timber-*`
+                // header at all, so they collapse to a single cache key; payload
+                // requests are already fragmented by these same values via the
+                // URL.
+                const varyTokens = [...RSC_KEY_HEADERS];
+                const existingVary = result.headers.get('Vary');
+                const existingTokens = existingVary
+                  ? existingVary
+                      .toLowerCase()
+                      .split(',')
+                      .map((t) => t.trim())
+                  : [];
+                const newTokens = varyTokens.filter(
+                  (t) => !existingTokens.includes(t.toLowerCase())
+                );
+                if (newTokens.length > 0) {
+                  result.headers.set(
+                    'Vary',
+                    existingVary ? `${existingVary}, ${newTokens.join(', ')}` : newTokens.join(', ')
+                  );
+                }
+
+                // A request may only claim an `_rsc` cache key that matches its
+                // own headers. The key is predictable by design, so without this
+                // a caller could render its own variant under another client's
+                // key and have a shared cache store it there (TIM-1268).
+                await enforceRscCacheKey(canonicalReq, result);
+
+                // Flight payloads must never be sniffable into a renderable
+                // type — applied at this single exit so every producer is
+                // covered, not just the success path (TIM-1268).
+                hardenRscPayloadResponse(result);
+
+                // A HEAD response carries the headers its GET would produce and
+                // no content (RFC 9110 §9.3.2). Applied at this single exit so
+                // every response shape is covered — page render, API route,
+                // metadata route, deny page, error page, proxy short-circuit —
+                // rather than per-renderer, where it was missing for page
+                // renders entirely (TIM-1324). The render still runs: the
+                // headers have to be the ones a GET would have sent.
+                result = stripHeadBody(result, method);
+
+                // Append Server-Timing header based on configured mode.
+                // Header mutability is guaranteed by the producer-side clone
+                // in `outcomeToResponse` and the metadata-route / auto-sitemap
+                // user-handler clones in `handleRequest`, so we can write
+                // directly without a runtime probe. See TIM-866.
+                if (serverTiming === 'detailed') {
+                  // Detailed: per-phase breakdown (proxy, middleware, render).
+                  const timingHeader = getServerTimingHeader();
+                  if (timingHeader) {
+                    result.headers.set('Server-Timing', timingHeader);
+                  }
+                } else if (serverTiming === 'total') {
+                  // Total only: single `total;dur=N` — no phase names.
+                  // Prevents information disclosure while giving browser
+                  // DevTools useful timing data.
+                  const totalMs = Math.round(performance.now() - startTime);
+                  result.headers.set('Server-Timing', `total;dur=${totalMs}`);
+                }
+                // serverTiming === false: no header at all
+
+                // Wrap the response body with stream-lifecycle timing when
+                // detailed mode is on. Logs firstChunk/lastChunk/maxGap/close
+                // on stream close — measures the post-flush stream tail that
+                // the Server-Timing header can't capture (TIM-1106).
+                if (serverTiming === 'detailed' && result.body) {
+                  result = new Response(wrapResponseWithStreamTiming(result.body, startTime), {
+                    status: result.status,
+                    statusText: result.statusText,
+                    headers: result.headers,
+                  });
+                }
+
+                return result;
+              }
+            );
+          } finally {
+            concurrency = activeRequests;
+            activeRequests--;
+          }
 
           // Post-span: structured production logging
           const durationMs = Math.round(performance.now() - startTime);
           const status = response.status;
-          const concurrency = activeRequests;
-          activeRequests--;
           logRequestCompleted({ method, path, status, durationMs, concurrency });
 
           if (slowRequestMs > 0 && durationMs > slowRequestMs) {
@@ -258,329 +535,10 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
         };
 
         return serverTiming === 'detailed' ? runWithTimingCollector(runRequest) : runRequest();
-      });
+      };
+      return runWithRequestContext(req, inRequestContext, { cookies });
     });
   };
 
-  async function runProxyPhase(req: Request, method: string, path: string): Promise<Response> {
-    try {
-      // Resolve the proxy export. When a proxyLoader is provided (lazy import),
-      // it is called per-request so HMR updates in dev take effect immediately.
-      let proxyExport: ProxyExport;
-      if (config.proxyLoader) {
-        const mod = await config.proxyLoader();
-        proxyExport = mod.default;
-      } else {
-        proxyExport = config.proxy!;
-      }
-      const proxyFn = () => runProxy(proxyExport, req, () => handleRequest(req, method, path));
-      return await withSpan('timber.proxy', {}, () =>
-        serverTiming === 'detailed' ? withTiming('proxy', 'proxy.ts', proxyFn) : proxyFn()
-      );
-    } catch (error) {
-      // Uncaught proxy.ts error → bare HTTP 500
-      logProxyError({ error });
-      await fireOnRequestError(error, req, 'proxy');
-      if (onPipelineError && error instanceof Error) onPipelineError(error, 'proxy');
-      return new Response(null, { status: 500 });
-    }
-  }
-
-  async function handleRequest(req: Request, method: string, path: string): Promise<Response> {
-    // Stage 1: URL canonicalization
-    const url = new URL(req.url);
-    const result = canonicalize(url.pathname, stripTrailingSlash);
-    if (!result.ok) {
-      return new Response(null, { status: result.status });
-    }
-    const canonicalPathname = result.pathname;
-
-    // Stage 1b: Metadata route matching — runs before regular route matching.
-    // Metadata routes skip middleware.ts and access.ts (public endpoints for crawlers).
-    // See design/16-metadata.md §"Pipeline Integration"
-    if (config.matchMetadataRoute) {
-      const metaMatch = config.matchMetadataRoute(canonicalPathname);
-      if (metaMatch) {
-        try {
-          // Static metadata files (.xml, .txt, .png, .ico, etc.) are served
-          // directly from disk. Dynamic metadata routes (.ts, .tsx) export a
-          // handler function that generates the response.
-          if (metaMatch.isStatic) {
-            return await serveStaticMetadataFile(metaMatch);
-          }
-
-          const mod = (await metaMatch.file.load()) as { default?: Function };
-          if (typeof mod.default !== 'function') {
-            return new Response('Metadata route must export a default function', { status: 500 });
-          }
-          const handlerResult = await mod.default();
-          // If the handler returns a Response, use it directly
-          if (handlerResult instanceof Response) {
-            return handlerResult;
-          }
-          // Otherwise, serialize based on content type
-          const contentType = metaMatch.contentType;
-          let body: string;
-          if (typeof handlerResult === 'string') {
-            body = handlerResult;
-          } else if (contentType === 'application/xml') {
-            body = serializeSitemap(handlerResult);
-          } else if (contentType === 'application/manifest+json') {
-            body = JSON.stringify(handlerResult, null, 2);
-          } else {
-            body = typeof handlerResult === 'string' ? handlerResult : String(handlerResult);
-          }
-          return new Response(body, {
-            status: 200,
-            headers: { 'Content-Type': `${contentType}; charset=utf-8` },
-          });
-        } catch (error) {
-          logRenderError({ method, path, error });
-          if (onPipelineError && error instanceof Error) onPipelineError(error, 'metadata-route');
-          return new Response(null, { status: 500 });
-        }
-      }
-    }
-
-    // Stage 2: Route matching
-    let match = matchRoute(canonicalPathname);
-    let interception: InterceptionContext | undefined;
-
-    // Stage 2a: Intercepting route resolution (modal pattern).
-    // On soft navigation, check if an intercepting route should render instead.
-    // The client sends X-Timber-URL with the current pathname (where they're
-    // navigating FROM). If a rewrite matches, re-route to the source URL so
-    // the source layout renders with the intercepted content in the slot.
-    const sourceUrl = req.headers.get('X-Timber-URL');
-    if (sourceUrl && config.interceptionRewrites?.length) {
-      const intercepted = findInterceptionMatch(
-        canonicalPathname,
-        sourceUrl,
-        config.interceptionRewrites
-      );
-      if (intercepted) {
-        const sourceMatch = matchRoute(intercepted.sourcePathname);
-        if (sourceMatch) {
-          match = sourceMatch;
-          interception = { targetPathname: canonicalPathname };
-        }
-      }
-    }
-
-    if (!match) {
-      // No route matched — render 404.tsx in root layout if available,
-      // otherwise fall back to a bare 404 Response.
-      if (config.renderNoMatch) {
-        const responseHeaders = new Headers();
-        return config.renderNoMatch(req, responseHeaders);
-      }
-      return new Response(null, { status: 404 });
-    }
-
-    // Response and request header containers — created before early hints so
-    // the emitter can append Link headers (e.g. for Cloudflare CDN → 103).
-    const responseHeaders = new Headers();
-    const requestHeaderOverlay = new Headers();
-
-    // Set Cache-Control for dynamic HTML responses. Without this header,
-    // CDNs (particularly Cloudflare) may attempt to buffer/process the
-    // response differently, causing intermittent multi-second delays.
-    // This matches Next.js's default behavior.
-    responseHeaders.set('Cache-Control', 'private, no-cache, no-store, max-age=0, must-revalidate');
-
-    // Stage 2b: 103 Early Hints (before middleware, after match)
-    // Fires before middleware so the browser can begin fetching critical
-    // assets while middleware runs. Non-fatal — a failing emitter never
-    // blocks the request.
-    if (earlyHints) {
-      try {
-        await earlyHints(match, req, responseHeaders);
-      } catch {
-        // Early hints failure is non-fatal
-      }
-    }
-
-    // Stage 3: Leaf middleware.ts (only the leaf route's middleware runs)
-    if (match.middleware) {
-      const ctx: MiddlewareContext = {
-        req,
-        requestHeaders: requestHeaderOverlay,
-        headers: responseHeaders,
-        params: match.params,
-        searchParams: new URL(req.url).searchParams,
-        earlyHints: (hints) => {
-          for (const hint of hints) {
-            let value = `<${hint.href}>; rel=${hint.rel}`;
-            if (hint.as !== undefined) value += `; as=${hint.as}`;
-            if (hint.crossOrigin !== undefined) value += `; crossorigin=${hint.crossOrigin}`;
-            if (hint.fetchPriority !== undefined) value += `; fetchpriority=${hint.fetchPriority}`;
-            responseHeaders.append('Link', value);
-          }
-        },
-      };
-
-      try {
-        // Enable cookie mutation during middleware (design/29-cookies.md §"Context Tracking")
-        setMutableCookieContext(true);
-        const middlewareFn = () => runMiddleware(match.middleware!, ctx);
-        const middlewareResponse = await withSpan('timber.middleware', {}, () =>
-          serverTiming === 'detailed'
-            ? withTiming('mw', 'middleware.ts', middlewareFn)
-            : middlewareFn()
-        );
-        setMutableCookieContext(false);
-        if (middlewareResponse) {
-          // Apply cookie jar to short-circuit response.
-          // Response.redirect() creates immutable headers, so ensure
-          // mutability before appending Set-Cookie entries.
-          const finalResponse = ensureMutableResponse(middlewareResponse);
-          applyCookieJar(finalResponse.headers);
-          logMiddlewareShortCircuit({ method, path, status: finalResponse.status });
-          return finalResponse;
-        }
-        // Middleware succeeded without short-circuiting — apply any
-        // injected request headers so headers() returns them downstream.
-        applyRequestHeaderOverlay(requestHeaderOverlay);
-      } catch (error) {
-        setMutableCookieContext(false);
-        // RedirectSignal from middleware → HTTP redirect (not an error).
-        // For RSC payload requests (client navigation), return 204 + X-Timber-Redirect
-        // so the client router can perform a soft SPA redirect. A raw 302 would be
-        // turned into an opaque redirect by fetch({redirect:'manual'}), crashing
-        // createFromFetch. See design/19-client-navigation.md.
-        if (error instanceof RedirectSignal) {
-          applyCookieJar(responseHeaders);
-          const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
-          if (isRsc) {
-            responseHeaders.set('X-Timber-Redirect', error.location);
-            return new Response(null, { status: 204, headers: responseHeaders });
-          }
-          responseHeaders.set('Location', error.location);
-          return new Response(null, { status: error.status, headers: responseHeaders });
-        }
-        // DenySignal from middleware → HTTP deny status
-        if (error instanceof DenySignal) {
-          return new Response(null, { status: error.status });
-        }
-        // Middleware throw → HTTP 500 (middleware runs before rendering,
-        // no error boundary to catch it)
-        logMiddlewareError({ method, path, error });
-        await fireOnRequestError(error, req, 'handler');
-        if (onPipelineError && error instanceof Error) onPipelineError(error, 'middleware');
-        return new Response(null, { status: 500 });
-      }
-    }
-
-    // Apply cookie jar to response headers before render commits them.
-    // Middleware may have set cookies; they need to be on responseHeaders
-    // before flushResponse creates the Response object.
-    applyCookieJar(responseHeaders);
-
-    // Stage 4: Render (access gates + element tree + renderToReadableStream)
-    try {
-      const renderFn = () =>
-        render(req, match, responseHeaders, requestHeaderOverlay, interception);
-      const response = await withSpan('timber.render', { 'http.route': canonicalPathname }, () =>
-        serverTiming === 'detailed'
-          ? withTiming('render', 'RSC + SSR render', renderFn)
-          : renderFn()
-      );
-      markResponseFlushed();
-      return response;
-    } catch (error) {
-      // DenySignal leaked from render (e.g. notFound() in metadata()).
-      // Return the deny status code instead of 500.
-      if (error instanceof DenySignal) {
-        return new Response(null, { status: error.status });
-      }
-      // RedirectSignal leaked from render — honour the redirect.
-      // For RSC payload requests, return 204 + X-Timber-Redirect so the
-      // client router can perform a soft SPA redirect (same as middleware path).
-      if (error instanceof RedirectSignal) {
-        const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
-        if (isRsc) {
-          responseHeaders.set('X-Timber-Redirect', error.location);
-          return new Response(null, { status: 204, headers: responseHeaders });
-        }
-        responseHeaders.set('Location', error.location);
-        return new Response(null, { status: error.status, headers: responseHeaders });
-      }
-      logRenderError({ method, path, error });
-      await fireOnRequestError(error, req, 'render');
-      if (onPipelineError && error instanceof Error) onPipelineError(error, 'render');
-      // Try fallback error page before bare 500
-      if (config.renderFallbackError) {
-        try {
-          return await config.renderFallbackError(error, req, responseHeaders);
-        } catch {
-          // Fallback rendering itself failed — fall through to bare 500
-        }
-      }
-      return new Response(null, { status: 500 });
-    }
-  }
-}
-
-/**
- * Fire the user's onRequestError hook with request context.
- * Extracts request info from the Request object and calls the instrumentation hook.
- */
-async function fireOnRequestError(
-  error: unknown,
-  req: Request,
-  phase: 'proxy' | 'handler' | 'render' | 'action' | 'route'
-): Promise<void> {
-  const url = new URL(req.url);
-  const headersObj: Record<string, string> = {};
-  req.headers.forEach((v, k) => {
-    headersObj[k] = v;
-  });
-
-  await callOnRequestError(
-    error,
-    { method: req.method, path: url.pathname, headers: headersObj },
-    { phase, routePath: url.pathname, routeType: 'page', traceId: traceId() }
-  );
-}
-
-// ─── Cookie Helpers ──────────────────────────────────────────────────────
-
-/**
- * Apply all Set-Cookie headers from the cookie jar to a Headers object.
- * Each cookie gets its own Set-Cookie header per RFC 6265 §4.1.
- */
-function applyCookieJar(headers: Headers): void {
-  for (const value of getSetCookieHeaders()) {
-    headers.append('Set-Cookie', value);
-  }
-}
-
-// ─── Immutable Response Helpers ──────────────────────────────────────────
-
-/**
- * Ensure a Response has mutable headers so the pipeline can safely append
- * Set-Cookie and Server-Timing entries.
- *
- * `Response.redirect()` and some platform-level responses return objects
- * with immutable headers. Calling `.set()` or `.append()` on them throws
- * `TypeError: immutable`. This helper detects the immutable case by
- * attempting a no-op write and, on failure, clones into a fresh Response
- * with mutable headers.
- */
-function ensureMutableResponse(response: Response): Response {
-  try {
-    // Probe mutability with a benign operation that we immediately undo.
-    // We pick a header name that is extremely unlikely to collide with
-    // anything meaningful and delete it right away.
-    response.headers.set('X-Timber-Probe', '1');
-    response.headers.delete('X-Timber-Probe');
-    return response;
-  } catch {
-    // Headers are immutable — rebuild with mutable headers.
-    return new Response(response.body, {
-      status: response.status,
-      statusText: response.statusText,
-      headers: new Headers(response.headers),
-    });
-  }
+  return pipelineFn;
 }