@timber-js/app 0.2.0-alpha.96 → 0.2.0-alpha.98

package/src/server/pipeline-phases.ts

@@ -0,0 +1,591 @@
+/**
+ * Pipeline phase functions — module-level free functions that take their
+ * dependencies as explicit parameters. Each phase returns a `PhaseOutcome`
+ * (a discriminated union over response / redirect / deny / error). The
+ * terminal `outcomeToResponse` translates outcomes into Responses.
+ *
+ * Lifted out of `createPipeline` so each phase can be unit-tested in
+ * isolation. The lift is mechanical — these functions used to be closures
+ * over `config`; they now take `config` as an explicit parameter.
+ *
+ * See design/07-routing.md §"Request Lifecycle", design/02-rendering-pipeline.md §"Request Flow".
+ */
+
+import { canonicalize } from './canonicalize.js';
+import { runProxy } from './proxy.js';
+import { runMiddlewareChain } from './middleware-runner.js';
+import { withTiming } from './server-timing.js';
+import {
+  applyRequestHeaderOverlay,
+  setMutableCookieContext,
+  markResponseFlushed,
+  setSegmentParams,
+} from './request-context.js';
+import { withSpan } from './tracing.js';
+import {
+  logProxyError,
+  logMiddlewareError,
+  logMiddlewareShortCircuit,
+  logRenderError,
+} from './logger.js';
+import { RedirectSignal, DenySignal } from './primitives.js';
+import { ParamCoercionError } from './route-element-builder.js';
+import { checkVersionSkew, applyReloadHeaders } from './version-skew.js';
+import { serveStaticMetadataFile, serializeSitemap } from './pipeline-metadata.js';
+import { loadModule } from './safe-load.js';
+import { findInterceptionMatch } from './pipeline-interception.js';
+import {
+  applyCookieJar,
+  buildRedirectResponse,
+  cloneWithMutableHeaders,
+  fireOnRequestError,
+  mergeMissingHeaders,
+  safeMerge,
+  type ProxyResolver,
+} from './pipeline-helpers.js';
+import type { InterceptionContext, PipelineConfig, RouteMatch } from './pipeline.js';
+import type { MiddlewareContext } from './types.js';
+
+// ─── Phase Outcome ─────────────────────────────────────────────────────────
+
+export type PhaseName = 'proxy' | 'middleware' | 'render';
+
+export type PhaseOutcome =
+  | { kind: 'response'; phase: PhaseName; response: Response }
+  | { kind: 'redirect'; phase: PhaseName; signal: RedirectSignal }
+  | { kind: 'deny'; phase: PhaseName; signal: DenySignal }
+  | { kind: 'error'; phase: PhaseName; error: unknown };
+
+export interface OutcomeContext {
+  req: Request;
+  method: string;
+  path: string;
+  responseHeaders?: Headers;
+  match?: RouteMatch;
+}
+
+interface RenderContext {
+  canonicalPathname: string;
+  interception?: InterceptionContext;
+}
+
+// ─── Param Coercion ────────────────────────────────────────────────────────
+
+/**
+ * Run segment param coercion on the matched route's segments.
+ *
+ * Loads params.ts modules from segments that have them, extracts the
+ * segmentParams definition, and coerces raw string params through codecs.
+ * Throws ParamCoercionError if any codec fails (→ 404).
+ *
+ * This runs BEFORE middleware, so ctx.segmentParams is already typed.
+ * See design/07-routing.md §"Where Coercion Runs"
+ */
+export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
+  const segments = match.segments;
+  let mergeTarget = match.segmentParams as Record<string, unknown>;
+  let usesNullPrototypeTarget = Object.getPrototypeOf(mergeTarget) === null;
+
+  for (const segment of segments) {
+    // Only process segments that have a params.ts convention file
+    if (!segment.params) continue;
+
+    let mod: Record<string, unknown>;
+    try {
+      mod = await loadModule(segment.params);
+    } catch (err) {
+      throw new ParamCoercionError(
+        `Failed to load params module for segment "${segment.segmentName}": ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+
+    const segmentParamsDef = mod.segmentParams as
+      | { parse(raw: Record<string, string | string[]>): Record<string, unknown> }
+      | undefined;
+
+    if (!segmentParamsDef || typeof segmentParamsDef.parse !== 'function') continue;
+
+    try {
+      const coerced = segmentParamsDef.parse(match.segmentParams);
+
+      if (!usesNullPrototypeTarget) {
+        mergeTarget = Object.create(null) as Record<string, unknown>;
+        safeMerge(mergeTarget, match.segmentParams as Record<string, unknown>);
+        match.segmentParams = mergeTarget as RouteMatch['segmentParams'];
+        usesNullPrototypeTarget = true;
+      }
+
+      // safeMerge blocks shallow prototype-polluting keys from codec output.
+      // The null-prototype target above provides the deeper guarantee for
+      // nested values without paying the cost of a deep sanitizer.
+      safeMerge(mergeTarget, coerced as Record<string, unknown>);
+    } catch (err) {
+      throw new ParamCoercionError(err instanceof Error ? err.message : String(err));
+    }
+  }
+}
+
+// ─── Phase: Proxy ──────────────────────────────────────────────────────────
+
+/**
+ * Run the proxy.ts phase. Calls user proxy code and uses `handleRequest` as
+ * the inner `next()` continuation. The proxy resolver was picked at pipeline
+ * construction time so the hot path sees no per-request branching on the
+ * `ProxyConfig` discriminant.
+ */
+export async function runProxyPhase(
+  config: PipelineConfig,
+  getProxy: ProxyResolver,
+  req: Request,
+  method: string,
+  path: string
+): Promise<PhaseOutcome> {
+  const detailed = config.serverTiming === 'detailed';
+  try {
+    const proxyExport = await getProxy();
+    const proxyFn = () =>
+      runProxy(proxyExport, req, () => handleRequest(config, req, method, path));
+    const response = await withSpan('timber.proxy', {}, () =>
+      detailed ? withTiming('proxy', 'proxy.ts', proxyFn) : proxyFn()
+    );
+    return { kind: 'response', phase: 'proxy', response };
+  } catch (error) {
+    return { kind: 'error', phase: 'proxy', error };
+  }
+}
+
+// ─── Phase: Middleware ─────────────────────────────────────────────────────
+
+/**
+ * Run the middleware chain phase. If the chain short-circuits with a Response,
+ * returns it as a 'response' outcome. Otherwise applies the request header
+ * overlay and falls through to the render phase.
+ */
+export async function runMiddlewarePhase(
+  config: PipelineConfig,
+  req: Request,
+  match: RouteMatch,
+  responseHeaders: Headers,
+  requestHeaderOverlay: Headers,
+  renderContext: RenderContext
+): Promise<PhaseOutcome> {
+  const detailed = config.serverTiming === 'detailed';
+  const ctx: MiddlewareContext = {
+    req,
+    requestHeaders: requestHeaderOverlay,
+    headers: responseHeaders,
+    segmentParams: match.segmentParams,
+    earlyHints: (hints) => {
+      for (const hint of hints) {
+        // Match Cloudflare's cached Early Hints attribute order: `as` before `rel`.
+        // Cloudflare caches Link headers and re-emits them on subsequent 200s.
+        // If our order differs, the browser sees duplicate preloads and warns.
+        let value: string;
+        if (hint.as !== undefined) {
+          value = `<${hint.href}>; as=${hint.as}; rel=${hint.rel}`;
+        } else {
+          value = `<${hint.href}>; rel=${hint.rel}`;
+        }
+        if (hint.crossOrigin !== undefined) value += `; crossorigin=${hint.crossOrigin}`;
+        if (hint.fetchPriority !== undefined) value += `; fetchpriority=${hint.fetchPriority}`;
+        responseHeaders.append('Link', value);
+      }
+    },
+  };
+
+  try {
+    const chainFn = () => runMiddlewareChain(match.middlewareChain, ctx);
+    // Enable cookie mutation during middleware (design/29-cookies.md §"Context Tracking")
+    const middlewareResponse = await (async () => {
+      setMutableCookieContext(true);
+      try {
+        return await withSpan('timber.middleware', {}, () =>
+          detailed ? withTiming('mw', 'middleware.ts', chainFn) : chainFn()
+        );
+      } finally {
+        setMutableCookieContext(false);
+      }
+    })();
+    if (middlewareResponse) {
+      return { kind: 'response', phase: 'middleware', response: middlewareResponse };
+    }
+    // Middleware chain completed without short-circuiting — apply any
+    // injected request headers so getHeaders() returns them downstream.
+    applyRequestHeaderOverlay(requestHeaderOverlay);
+
+    // Apply cookie jar to response headers before render commits them.
+    // This preserves the historical ordering where middleware cookie writes
+    // are visible to route-handler header merging, while handler Set-Cookie
+    // values still come after middleware cookies and therefore take precedence.
+    applyCookieJar(responseHeaders);
+
+    return runRenderPhase(config, req, match, responseHeaders, requestHeaderOverlay, renderContext);
+  } catch (error) {
+    if (error instanceof RedirectSignal) {
+      return { kind: 'redirect', phase: 'middleware', signal: error };
+    }
+    if (error instanceof DenySignal) {
+      return { kind: 'deny', phase: 'middleware', signal: error };
+    }
+    return { kind: 'error', phase: 'middleware', error };
+  }
+}
+
+// ─── Phase: Render ─────────────────────────────────────────────────────────
+
+/**
+ * Run the render phase. Wraps the configured renderer in a span and a
+ * timing scope, and translates thrown signals into outcome variants.
+ */
+export async function runRenderPhase(
+  config: PipelineConfig,
+  req: Request,
+  match: RouteMatch,
+  responseHeaders: Headers,
+  requestHeaderOverlay: Headers,
+  { canonicalPathname, interception }: RenderContext
+): Promise<PhaseOutcome> {
+  const detailed = config.serverTiming === 'detailed';
+  try {
+    const renderFn = () =>
+      config.render(req, match, responseHeaders, requestHeaderOverlay, 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 (error instanceof DenySignal) {
+      return { kind: 'deny', phase: 'render', signal: error };
+    }
+    if (error instanceof RedirectSignal) {
+      return { kind: 'redirect', phase: 'render', signal: error };
+    }
+    return { kind: 'error', phase: 'render', error };
+  }
+}
+
+// ─── Request Handler ───────────────────────────────────────────────────────
+
+/**
+ * Process a single request from canonicalization through phase dispatch.
+ *
+ * Stages: canonicalize → metadata routes → auto-sitemap → version skew →
+ * route match → interception → early hints → param coercion → middleware →
+ * render → outcome translation. Pre-routing short-circuits return Responses
+ * directly; post-match dispatch goes through `outcomeToResponse`.
+ *
+ * Used both as the top-level entry (when no proxy.ts is configured) and as
+ * the `next()` continuation passed to `runProxy()`.
+ */
+export async function handleRequest(
+  config: PipelineConfig,
+  req: Request,
+  method: string,
+  path: string
+): Promise<Response> {
+  const stripTrailingSlash = config.stripTrailingSlash ?? true;
+
+  // 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 loadModule<{ default?: Function }>(metaMatch.file);
+        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, normalize headers so the
+        // outer Server-Timing writer can append without hitting an
+        // immutable header bag (e.g. user returns Response.redirect()).
+        if (handlerResult instanceof Response) {
+          return cloneWithMutableHeaders(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 (config.onPipelineError && error instanceof Error)
+          config.onPipelineError(error, 'metadata-route');
+        return new Response(null, { status: 500 });
+      }
+    }
+  }
+
+  // Stage 1b.2: Auto-generated sitemap — serves /sitemap.xml and /sitemap/N.xml
+  // when sitemap generation is enabled and no user-authored sitemap exists.
+  // Runs after metadata route matching so user sitemaps always take precedence.
+  // See design/16-metadata.md §"Auto-generated Sitemap"
+  if (config.autoSitemapHandler) {
+    try {
+      const sitemapResponse = await config.autoSitemapHandler(canonicalPathname);
+      if (sitemapResponse) return cloneWithMutableHeaders(sitemapResponse);
+    } catch (error) {
+      logRenderError({ method, path, error });
+      if (config.onPipelineError && error instanceof Error)
+        config.onPipelineError(error, 'auto-sitemap');
+      return new Response(null, { status: 500 });
+    }
+  }
+
+  // Stage 1c: Version skew detection (TIM-446).
+  // For RSC payload requests (client navigation), check if the client's
+  // deployment ID matches the current build. On mismatch, signal the
+  // client to do a full page reload instead of returning an RSC payload
+  // that references mismatched module IDs.
+  const isRscRequest = (req.headers.get('Accept') ?? '').includes('text/x-component');
+  if (isRscRequest) {
+    const skewCheck = checkVersionSkew(req);
+    if (!skewCheck.ok) {
+      const reloadHeaders = new Headers();
+      applyReloadHeaders(reloadHeaders);
+      return new Response(null, { status: 204, headers: reloadHeaders });
+    }
+  }
+
+  // Stage 2: Route matching
+  let match = config.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 = config.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 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();
+
+  // 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 (config.earlyHints) {
+    try {
+      await config.earlyHints(match, req, responseHeaders);
+    } catch {
+      // Early hints failure is non-fatal
+    }
+  }
+
+  // Stage 2c: Param coercion (before middleware)
+  // Load params.ts modules from matched segments and coerce raw string
+  // params through defineSegmentParams codecs. Coercion failure → 404
+  // (middleware never runs). See design/07-routing.md §"Where Coercion Runs"
+  try {
+    await coerceSegmentParams(match);
+  } catch (error) {
+    if (error instanceof ParamCoercionError) {
+      // 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 });
+      }
+      // 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));
+      }
+      return new Response(null, { status: 404 });
+    }
+    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);
+
+  const outcome =
+    match.middlewareChain.length > 0
+      ? await runMiddlewarePhase(config, req, match, responseHeaders, requestHeaderOverlay, {
+          canonicalPathname,
+          interception,
+        })
+      : await runRenderPhase(config, req, match, responseHeaders, requestHeaderOverlay, {
+          canonicalPathname,
+          interception,
+        });
+
+  return outcomeToResponse(config, outcome, {
+    req,
+    method,
+    path,
+    responseHeaders,
+    match,
+  });
+}
+
+// ─── Outcome Translation ───────────────────────────────────────────────────
+
+/**
+ * Terminal outcome handler — converts a `PhaseOutcome` into a final
+ * `Response`, applying cookies, building redirects, rendering deny pages
+ * and fallback error pages, and firing instrumentation hooks.
+ *
+ * This is the single source of truth for how phase outputs become wire
+ * responses; the per-phase try/catch blocks now produce values, not
+ * Responses, so the conversion logic lives in exactly one place.
+ */
+export async function outcomeToResponse(
+  config: PipelineConfig,
+  outcome: PhaseOutcome,
+  ctx: OutcomeContext
+): Promise<Response> {
+  switch (outcome.kind) {
+    case 'response': {
+      // Clone unconditionally so downstream code (cookie/header merge,
+      // Server-Timing in createPipeline) can write headers without paying
+      // for a try/catch immutability probe per request. User middleware,
+      // proxy, and route code may all return `Response.redirect()` or
+      // platform-level responses with frozen header bags. See TIM-866.
+      const finalResponse = cloneWithMutableHeaders(outcome.response);
+
+      if (outcome.phase === 'proxy') return finalResponse;
+
+      if (outcome.phase === 'middleware' && ctx.responseHeaders) {
+        applyCookieJar(finalResponse.headers);
+        mergeMissingHeaders(finalResponse.headers, ctx.responseHeaders);
+        logMiddlewareShortCircuit({
+          method: ctx.method,
+          path: ctx.path,
+          status: finalResponse.status,
+        });
+      }
+
+      if (outcome.phase === 'render') {
+        markResponseFlushed();
+      }
+
+      return finalResponse;
+    }
+
+    case 'redirect': {
+      const headers = ctx.responseHeaders ?? new Headers();
+      applyCookieJar(headers);
+      return buildRedirectResponse(outcome.signal, ctx.req, headers);
+    }
+
+    case 'deny': {
+      const headers = ctx.responseHeaders ?? new Headers();
+      applyCookieJar(headers);
+      if (config.renderDenyFallback) {
+        try {
+          // Clone user-supplied deny-page responses so downstream
+          // Server-Timing writes are safe against frozen header bags
+          // (e.g. user returned Response.redirect from the hook).
+          return cloneWithMutableHeaders(
+            await config.renderDenyFallback(outcome.signal, ctx.req, headers, ctx.match)
+          );
+        } catch {
+          // Deny page rendering failed — fall through to bare response
+        }
+      }
+      return new Response(null, { status: outcome.signal.status, headers });
+    }
+
+    case 'error': {
+      if (outcome.phase === 'proxy') {
+        logProxyError({ error: outcome.error });
+        await fireOnRequestError(outcome.error, ctx.req, 'proxy');
+        if (config.onPipelineError && outcome.error instanceof Error)
+          config.onPipelineError(outcome.error, 'proxy');
+        return new Response(null, { status: 500 });
+      }
+
+      if (outcome.phase === 'middleware') {
+        logMiddlewareError({ method: ctx.method, path: ctx.path, error: outcome.error });
+        await fireOnRequestError(outcome.error, ctx.req, 'handler');
+        if (config.onPipelineError && outcome.error instanceof Error) {
+          config.onPipelineError(outcome.error, 'middleware');
+        }
+        return new Response(null, { status: 500 });
+      }
+
+      const headers = ctx.responseHeaders ?? new Headers();
+      applyCookieJar(headers);
+      logRenderError({ method: ctx.method, path: ctx.path, error: outcome.error });
+      await fireOnRequestError(outcome.error, ctx.req, 'render');
+      if (config.onPipelineError && outcome.error instanceof Error)
+        config.onPipelineError(outcome.error, 'render');
+      if (config.renderFallbackError) {
+        try {
+          // Clone user-supplied fallback error responses so downstream
+          // Server-Timing writes are safe against frozen header bags.
+          return cloneWithMutableHeaders(
+            await config.renderFallbackError(outcome.error, ctx.req, headers)
+          );
+        } catch {
+          // Fallback rendering itself failed — fall through to bare 500
+        }
+      }
+      return new Response(null, { status: 500 });
+    }
+  }
+}