@timber-js/app 0.2.0-alpha.207 → 0.2.0-alpha.209

package/src/server/pipeline-phases.ts

@@ -25,17 +25,22 @@ import {
 import { withSpan } from './tracing.ts';
 import { requestCspNonce } from './csp-nonce.ts';
 import { logRenderError } from './logger.ts';
-import { isDenySignal, isRedirectSignal } from './primitives.ts';
+import { isDenySignal, isRedirectSignal } from './signal-identity.ts';
 import { ParamCoercionError } from './param-coercion.ts';
 import { checkVersionSkew, applyReloadHeaders } from './version-skew.ts';
 import { serveStaticMetadataFile, serializeSitemap } from './pipeline-metadata.ts';
 import { loadModule } from './safe-load.ts';
-import { findInterceptionMatch } from './pipeline-interception.ts';
-import { computeSegmentTreePaths } from '../routing/segment-keys.ts';
-import { parseClientStateTree } from './state-tree-diff.ts';
-import { applyCookieJar, cloneWithMutableHeaders, type ProxyResolver } from './pipeline-helpers.ts';
+import { resolveInterceptedRoute } from './pipeline-interception.ts';
+import { isApiRouteChain } from './route-matcher.ts';
+import {
+  applyCookieJar,
+  cloneWithMutableHeaders,
+  dynamicResponseHeaders,
+  fireOnRequestError,
+  type ProxyResolver,
+} from './pipeline-helpers.ts';
 import { coerceSegmentParams } from './param-coercion.ts';
-import { outcomeToResponse, type PhaseOutcome } from './pipeline-outcome.ts';
+import { outcomeToResponse, thrownOutcome, type PhaseOutcome } from './pipeline-outcome.ts';
 import type { InterceptionContext, PipelineConfig, RouteMatch } from './pipeline.ts';
 import type { MetadataHandler, MetadataRoute, MiddlewareContext } from './types.ts';
 import { swallow } from './logger.ts';
@@ -47,26 +52,6 @@ interface RenderContext {
   interception?: InterceptionContext;
 }
 
-/**
- * Validate and canonicalize the X-Timber-URL header value.
- *
- * Returns the canonical pathname if valid, or null if rejected:
- * - Must start with '/' (relative pathname, no scheme/authority)
- * - Must not contain control characters
- * - Must pass canonicalization (no encoded separators, null bytes, etc.)
- */
-function validateInterceptionHeader(raw: string, stripTrailingSlash: boolean): string | null {
-  if (!raw.startsWith('/')) return null;
-  if (raw.startsWith('//')) return null;
-  for (let i = 0; i < raw.length; i++) {
-    const code = raw.charCodeAt(i);
-    if (code <= 0x1f || code === 0x7f) return null;
-  }
-  const result = canonicalize(raw, stripTrailingSlash);
-  if (!result.ok) return null;
-  return result.pathname;
-}
-
 // ─── Phase: Proxy ──────────────────────────────────────────────────────────
 
 /**
@@ -96,13 +81,7 @@ export async function runProxyPhase(
     );
     return { kind: 'response', phase: 'proxy', response };
   } catch (error) {
-    if (isRedirectSignal(error)) {
-      return { kind: 'redirect', phase: 'proxy', signal: error };
-    }
-    if (isDenySignal(error)) {
-      return { kind: 'deny', phase: 'proxy', signal: error };
-    }
-    return { kind: 'error', phase: 'proxy', error };
+    return thrownOutcome('proxy', error);
   }
 }
 
@@ -118,10 +97,10 @@ export async function runMiddlewarePhase(
   req: Request,
   match: RouteMatch,
   responseHeaders: Headers,
-  requestHeaderOverlay: Headers,
   renderContext: RenderContext
 ): Promise<PhaseOutcome> {
   const detailed = config.serverTiming === 'detailed';
+  const requestHeaderOverlay = new Headers();
   const ctx: MiddlewareContext = {
     req,
     requestHeaders: requestHeaderOverlay,
@@ -169,15 +148,9 @@ export async function runMiddlewarePhase(
     // injected request headers so getHeaders() returns them downstream.
     applyRequestHeaderOverlay(requestHeaderOverlay);
 
-    return runRenderPhase(config, req, match, responseHeaders, requestHeaderOverlay, renderContext);
+    return runRenderPhase(config, req, match, responseHeaders, renderContext);
   } catch (error) {
-    if (isRedirectSignal(error)) {
-      return { kind: 'redirect', phase: 'middleware', signal: error };
-    }
-    if (isDenySignal(error)) {
-      return { kind: 'deny', phase: 'middleware', signal: error };
-    }
-    return { kind: 'error', phase: 'middleware', error };
+    return thrownOutcome('middleware', error);
   }
 }
 
@@ -203,26 +176,18 @@ export async function runRenderPhase(
   req: Request,
   match: RouteMatch,
   responseHeaders: Headers,
-  requestHeaderOverlay: Headers,
   { canonicalPathname, interception }: RenderContext
 ): Promise<PhaseOutcome> {
   const detailed = config.serverTiming === 'detailed';
   applyCookieJar(responseHeaders);
   try {
-    const renderFn = () =>
-      config.render(req, match, responseHeaders, requestHeaderOverlay, interception);
+    const renderFn = () => config.render(req, match, responseHeaders, interception);
     const response = await withSpan('timber.render', { 'http.route': canonicalPathname }, () =>
       detailed ? withTiming('render', 'RSC + SSR render', renderFn) : renderFn()
     );
     return { kind: 'response', phase: 'render', response };
   } catch (error) {
-    if (isDenySignal(error)) {
-      return { kind: 'deny', phase: 'render', signal: error };
-    }
-    if (isRedirectSignal(error)) {
-      return { kind: 'redirect', phase: 'render', signal: error };
-    }
-    return { kind: 'error', phase: 'render', error };
+    return thrownOutcome('render', error);
   }
 }
 
@@ -347,6 +312,7 @@ export async function handleRequest(
           return new Response(null, { status: error.status });
         }
         logRenderError({ method, path, error });
+        await fireOnRequestError(error, req, 'route');
         if (config.onPipelineError && error instanceof Error)
           config.onPipelineError(error, 'metadata-route');
         return new Response(null, { status: 500 });
@@ -364,6 +330,7 @@ export async function handleRequest(
       if (sitemapResponse) return cloneWithMutableHeaders(sitemapResponse);
     } catch (error) {
       logRenderError({ method, path, error });
+      await fireOnRequestError(error, req, 'route');
       if (config.onPipelineError && error instanceof Error)
         config.onPipelineError(error, 'auto-sitemap');
       return new Response(null, { status: 500 });
@@ -385,213 +352,136 @@ export async function handleRequest(
     }
   }
 
-  // Stage 2: Route matching
-  let match = config.matchRoute(canonicalPathname);
-  let interception: InterceptionContext | undefined;
-
-  // Stage 2a: Intercepting route resolution (modal pattern).
-  // Only honored on RSC client-navigation requests (Accept: text/x-component)
-  // to prevent spoofing from plain HTML navigations or raw HTTP clients.
-  // The header value must be a valid relative pathname — reject schemes,
-  // authority, and control characters. Canonicalize before matching.
-  if (isRsc && config.interceptionRewrites?.length) {
-    const rawSourceUrl = req.headers.get('X-Timber-URL');
-    const validatedSourceUrl = rawSourceUrl
-      ? validateInterceptionHeader(rawSourceUrl, stripTrailingSlash)
-      : null;
-    if (validatedSourceUrl) {
-      // The scope of an interception is the segment that owns the intercepting
-      // slot, so the guard asks whether the route the user is LEAVING renders
-      // that segment. Two independent answers to "what is on screen?", tried in
-      // order — deferred behind a thunk so neither runs unless a rewrite's
-      // target pattern matches.
-      //
-      // 1. What the client says it has mounted (X-Timber-State-Tree
-      //    `treePaths`). Authoritative about tree shape and nothing else.
-      // 2. What re-matching X-Timber-URL implies. Correct while the address bar
-      //    still holds the source page, which stops being true the moment a
-      //    modal is open — the address is then the *intercepted* URL and
-      //    re-matching it resolves through whichever group owns the canonical
-      //    page (TIM-1282).
-      //
-      // Neither is trusted: both are client-supplied, and satisfying the scope
-      // only selects which build-time rewrite applies. The rendered pathname is
-      // always the rewrite's own `interceptingPrefix`, the server re-derives the
-      // rendered chain from it below, and every access.ts runs regardless.
-      //
-      // They are handed over as two sets in that order rather than one union:
-      // each describes a single rendered chain, and only within one chain does
-      // "the deepest scope" name the innermost owner (TIM-1318). Unioned, a
-      // deeper scope from the address-implied canonical branch — which after
-      // (2) may be a route group the client never mounted — would outrank the
-      // owner actually on screen.
-      const resolveSourceScopes = () => {
-        const mounted = new Set(parseClientStateTree(req)?.treePaths ?? []);
-        const sourceRoute = config.matchRoute(validatedSourceUrl);
-        const addressed = new Set(sourceRoute ? computeSegmentTreePaths(sourceRoute.segments) : []);
-        const scopes = [mounted, addressed].filter((scope) => scope.size > 0);
-        // Neither channel produced a tree — no scope can contain anything, and
-        // an origin that matches no route is not a legitimate soft navigation.
-        return scopes.length > 0 ? scopes : null;
-      };
-      const rewrite = findInterceptionMatch(
-        canonicalPathname,
-        resolveSourceScopes,
-        config.interceptionRewrites
-      );
-      if (rewrite?.mode === 'children') {
-        // Sibling layout swap (TIM-1280). Nothing is re-matched: the resolver
-        // addresses the owner directory by tree path and returns the chain
-        // `[…owner ancestors, interceptingNode, …descendants]`, which renders
-        // as an ordinary route. `interception` stays unset — there is no slot
-        // to intercept into, and setting it would additionally arm the modal
-        // path for every slot in the tree we are about to render.
-        //
-        // A null here means the scope named nothing in this manifest, or no
-        // intercepting child matched the target. Both fall through to the
-        // canonical route, which is what a hard navigation renders.
-        const interceptedMatch = config.matchInterceptedRoute?.(
-          canonicalPathname,
-          rewrite.interceptingScope
-        );
-        if (interceptedMatch) match = interceptedMatch;
-      } else if (rewrite) {
-        const sourceMatch = config.matchRoute(rewrite.interceptingPrefix);
-        // The scope test above was about the route the user is LEAVING. The
-        // route we are about to render is a different one —
-        // `interceptingPrefix` is URL-derived, and route groups are
-        // URL-invisible, so `/` can resolve into a sibling group that does not
-        // own the slot. Rendering that would reproduce the TIM-1278 failure on
-        // a valid tree: the rewrite hijacks the navigation and no slot exists
-        // to render the intercepting page. Fall through to the canonical
-        // target route instead.
-        const rendersTheSlot =
-          sourceMatch !== null &&
-          computeSegmentTreePaths(sourceMatch.segments).includes(rewrite.interceptingScope);
-        if (rendersTheSlot) {
-          match = sourceMatch;
-          interception = { targetPathname: canonicalPathname };
-        }
-      }
-    }
-  }
-
-  if (!match) {
-    // Dev-time diagnostic: log the unmatched pathname so developers can
-    // see why a request 404'd without needing to add breakpoints.
-    if (isDebug()) {
-      console.warn(
-        `[timber] No route matched for pathname: ${canonicalPathname}\n` +
-          `  Input path: ${path}\n` +
-          `  Method: ${method}`
-      );
-    }
-    // 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 cloneWithMutableHeaders(await 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();
+  // Seeded with the dynamic-page cache policy, which the no-match 404
+  // rendered below carries too.
+  const responseHeaders = dynamicResponseHeaders();
 
-  // 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.
+  // Stages 2–2c are route setup. Anything they throw — a matcher bug, a
+  // codec returning a value a param cannot hold — is a `'setup'` outcome:
+  // logged, reported to onRequestError, and answered with the fallback page,
+  // with the match when there is one so a route.ts match keeps its format.
+  // Before TIM-1537 it escaped `createPipeline`, or was reported as
+  // "proxy.ts threw" when a proxy wrapped it.
   //
-  // Skip on RSC requests (client-side navigations) — the browser already
-  // has CSS, fonts, and JS chunks from the initial full-page load.
-  // Skip on API routes (route.ts without page.tsx) — they return data
-  // (JSON, images, etc.), not HTML that needs CSS/JS/font hints.
-  const leafSegment = match.segments[match.segments.length - 1] as
-    | { route?: unknown; page?: unknown }
-    | undefined;
-  const isApiRoute = leafSegment?.route && !leafSegment?.page;
-  if (config.earlyHints && !isRsc && !isApiRoute) {
+  // Rendering the 404 page is render work, not setup, so its own failure is
+  // a `'render'` outcome even when setup decided the request is a 404.
+  const renderNotFound = async (headers: Headers): Promise<Response> => {
+    if (!config.renderNoMatch) return new Response(null, { status: 404 });
     try {
-      await config.earlyHints(match, req, responseHeaders);
-    } catch (err) {
-      swallow(err, 'early hints hook threw');
+      return cloneWithMutableHeaders(await config.renderNoMatch(req, headers));
+    } catch (error) {
+      return outcomeToResponse(config, thrownOutcome('render', error), {
+        req,
+        method,
+        path,
+        responseHeaders: headers,
+      });
     }
-  }
-
-  // Stage 2c: Param coercion (before middleware)
-  // Coerce raw string params through the app/schema.ts codecs.
-  // Coercion failure → 404
-  // (middleware never runs). See design/07-routing.md §"Where Coercion Runs"
-  //
-  // Snapshot raw params before coercion — slot resolution needs the
-  // original string values to reconstruct URL parts for tree matching.
-  // Coerced params may have been transformed by codecs.
-  // segmentParams is typed CoercedParams but is still raw strings here
-  // (coercion runs below). The snapshot preserves the pre-coercion shape.
-  match.rawSegmentParams = { ...match.segmentParams } as Record<string, string | string[]>;
+  };
+  let match: RouteMatch | null = null;
+  let interception: InterceptionContext | undefined;
   try {
-    await coerceSegmentParams(match);
-  } catch (error) {
-    if (error instanceof ParamCoercionError) {
-      // Dev-time diagnostic: log param coercion failures so developers can
-      // see why a matched route 404'd. Silent coercion 404s are brutal to debug.
+    // Stage 2: Route matching, then 2a: intercepting route resolution.
+    match = config.matchRoute(canonicalPathname);
+    ({ match, interception } = resolveInterceptedRoute(config, req, canonicalPathname, match));
+
+    if (!match) {
+      // Dev-time diagnostic: log the unmatched pathname so developers can
+      // see why a request 404'd without needing to add breakpoints.
       if (isDebug()) {
-        const segmentChain = match.segments.map((s) => s.segmentName || '/').join(' → ');
         console.warn(
-          `[timber] Param coercion failed for ${method} ${canonicalPathname} — responding with 404\n` +
-            `  Matched segments: ${segmentChain}\n` +
-            `  Error: ${error.message}\n` +
-            `  This usually means a codec in app/schema.ts rejected the URL value.\n` +
-            `  Check the codec for the bracket key of the segment named above.`
+          `[timber] No route matched for pathname: ${canonicalPathname}\n` +
+            `  Input path: ${path}\n` +
+            `  Method: ${method}`
         );
       }
-      // For API routes (route.ts), return a bare 404 — not an HTML page.
-      // API consumers expect JSON/empty responses, not rendered HTML.
-      const leafSegment = match.segments[match.segments.length - 1];
-      if ((leafSegment as { route?: unknown }).route && !(leafSegment as { page?: unknown }).page) {
-        return new Response(null, { status: 404 });
+      // No route matched — render 404.tsx in root layout if available,
+      // otherwise fall back to a bare 404 Response.
+      return await renderNotFound(responseHeaders);
+    }
+
+    // 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.
+    //
+    // Skip on RSC requests (client-side navigations) — the browser already
+    // has CSS, fonts, and JS chunks from the initial full-page load.
+    // Skip on API routes (route.ts without page.tsx) — they return data
+    // (JSON, images, etc.), not HTML that needs CSS/JS/font hints.
+    if (config.earlyHints && !isRsc && !isApiRouteChain(match.segments)) {
+      try {
+        await config.earlyHints(match, req, responseHeaders);
+      } catch (err) {
+        swallow(err, 'early hints hook threw');
       }
-      // Route through the app's 404 page (404.tsx in root layout) instead of
-      // returning a bare empty 404 Response. Falls back to bare 404 only if
-      // no renderNoMatch renderer is configured.
-      if (config.renderNoMatch) {
-        return cloneWithMutableHeaders(await config.renderNoMatch(req, responseHeaders));
+    }
+
+    // Stage 2c: Param coercion (before middleware)
+    // Coerce raw string params through the app/schema.ts codecs.
+    // Coercion failure → 404
+    // (middleware never runs). See design/07-routing.md §"Where Coercion Runs"
+    try {
+      match = { ...match, segmentParams: await coerceSegmentParams(match) };
+    } catch (error) {
+      if (error instanceof ParamCoercionError) {
+        // Dev-time diagnostic: log param coercion failures so developers can
+        // see why a matched route 404'd. Silent coercion 404s are brutal to debug.
+        if (isDebug()) {
+          const segmentChain = match.segments.map((s) => s.segmentName || '/').join(' → ');
+          console.warn(
+            `[timber] Param coercion failed for ${method} ${canonicalPathname} — responding with 404\n` +
+              `  Matched segments: ${segmentChain}\n` +
+              `  Error: ${error.message}\n` +
+              `  This usually means a codec in app/schema.ts rejected the URL value.\n` +
+              `  Check the codec for the bracket key of the segment named above.`
+          );
+        }
+        // For API routes (route.ts), return a bare 404 — not an HTML page.
+        // API consumers expect JSON/empty responses, not rendered HTML.
+        if (isApiRouteChain(match.segments)) {
+          return new Response(null, { status: 404 });
+        }
+        // Route through the app's 404 page (404.tsx in root layout) instead of
+        // returning a bare empty 404 Response. Falls back to bare 404 only if
+        // no renderNoMatch renderer is configured.
+        return await renderNotFound(responseHeaders);
       }
-      return new Response(null, { status: 404 });
+      throw error;
     }
-    throw error;
-  }
 
-  // Store coerced segment params in ALS so components can access them
-  // via getSegmentParams() instead of receiving them as a prop.
-  // See design/07-routing.md §"params.ts — Convention File for Typed Params"
-  setSegmentParams(match.segmentParams);
+    // Store coerced segment params in ALS so components can access them
+    // via getSegmentParams() instead of receiving them as a prop.
+    // See design/07-routing.md §"params.ts — Convention File for Typed Params"
+    setSegmentParams(match.segmentParams);
 
-  // Store the matched segment path for dev-mode validation in getSegmentParams().
-  // Build the tree path from the segment chain (includes groups and slots).
-  const segmentPath =
-    match.segments
-      .map((s) => s.segmentName)
-      .filter(Boolean)
-      .join('/') || '/';
-  setMatchedSegmentPath(segmentPath.startsWith('/') ? segmentPath : `/${segmentPath}`);
+    // Store the matched segment path for dev-mode validation in getSegmentParams().
+    // Build the tree path from the segment chain (includes groups and slots).
+    const segmentPath =
+      match.segments
+        .map((s) => s.segmentName)
+        .filter(Boolean)
+        .join('/') || '/';
+    setMatchedSegmentPath(segmentPath.startsWith('/') ? segmentPath : `/${segmentPath}`);
+  } catch (error) {
+    return outcomeToResponse(config, thrownOutcome('setup', error), {
+      req,
+      method,
+      path,
+      responseHeaders,
+      match: match ?? undefined,
+    });
+  }
 
   const outcome =
     match.middlewareChain.length > 0
-      ? await runMiddlewarePhase(config, req, match, responseHeaders, requestHeaderOverlay, {
+      ? await runMiddlewarePhase(config, req, match, responseHeaders, {
           canonicalPathname,
           interception,
         })
-      : await runRenderPhase(config, req, match, responseHeaders, requestHeaderOverlay, {
+      : await runRenderPhase(config, req, match, responseHeaders, {
           canonicalPathname,
           interception,
         });