@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.181

package/src/server/pipeline-phases.ts

@@ -0,0 +1,545 @@
+/**
+ * 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) defined
+ * in `pipeline-outcome.ts`. The terminal `outcomeToResponse` (also in
+ * `pipeline-outcome.ts`) 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,
+  setSegmentParams,
+  setMatchedSegmentPath,
+} from './request-context.js';
+import { withSpan } from './tracing.js';
+import { 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, cloneWithMutableHeaders, type ProxyResolver } from './pipeline-helpers.js';
+import { coerceSegmentParams } from './param-coercion.js';
+import { outcomeToResponse, type PhaseOutcome } from './pipeline-outcome.js';
+import type { InterceptionContext, PipelineConfig, RouteMatch } from './pipeline.js';
+import type { MetadataHandler, MetadataRoute, MiddlewareContext } from './types.js';
+import { swallow } from './logger.js';
+import { isDebug } from './debug.js';
+
+interface RenderContext {
+  canonicalPathname: string;
+  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 ──────────────────────────────────────────────────────────
+
+/**
+ * Run the proxy.ts phase. Calls user proxy code with a `next()` continuation.
+ *
+ * When `next` is provided, it replaces the default `handleRequest` as the
+ * continuation — this lets the pipeline inject action dispatch between proxy
+ * and route matching (TIM-1213). 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,
+  next?: () => Promise<Response>
+): Promise<PhaseOutcome> {
+  const detailed = config.serverTiming === 'detailed';
+  try {
+    const proxyExport = await getProxy();
+    const continuation = next ?? (() => handleRequest(config, req, method, path, true));
+    const proxyFn = () => runProxy(proxyExport, req, continuation);
+    const response = await withSpan('timber.proxy', {}, () =>
+      detailed ? withTiming('proxy', 'proxy.ts', proxyFn) : proxyFn()
+    );
+    return { kind: 'response', phase: 'proxy', response };
+  } catch (error) {
+    if (error instanceof RedirectSignal) {
+      return { kind: 'redirect', phase: 'proxy', signal: error };
+    }
+    if (error instanceof DenySignal) {
+      return { kind: 'deny', phase: 'proxy', signal: 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()`.
+ *
+ * @param pathIsCanonical When true, `path` has already been canonicalized by
+ *   `createPipeline` — skip re-canonicalization to prevent double-decode.
+ *   When false (default), runs canonicalize as a safety net for direct callers.
+ */
+export async function handleRequest(
+  config: PipelineConfig,
+  req: Request,
+  method: string,
+  path: string,
+  pathIsCanonical?: boolean
+): Promise<Response> {
+  const stripTrailingSlash = config.stripTrailingSlash ?? true;
+
+  // Stage 1: URL canonicalization.
+  // When pathIsCanonical is true, createPipeline has already run canonicalize()
+  // and passed the result as `path`. Re-canonicalizing would double-decode
+  // percent-encoded characters (e.g., %61dmin → admin). See TIM-1004.
+  //
+  // When pathIsCanonical is false, this is a safety net for direct callers
+  // (tests, non-pipeline usage) that haven't pre-canonicalized.
+  let canonicalPathname: string;
+  if (pathIsCanonical) {
+    canonicalPathname = path;
+  } else {
+    const result = canonicalize(path, stripTrailingSlash);
+    if (!result.ok) {
+      if (isDebug()) {
+        console.warn(
+          `[timber] URL canonicalization rejected ${method} ${path} — responding with ${result.status}\n` +
+            `  This usually means the URL contains encoded separators (%2f, %5c),\n` +
+            `  null bytes (%00), path traversal (..), or malformed percent-encoding.`
+        );
+      }
+      return new Response(null, { status: result.status });
+    }
+    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);
+        }
+
+        setSegmentParams(metaMatch.segmentParams);
+        const mod = await loadModule<{ default?: MetadataHandler }>(metaMatch.file);
+        if (typeof mod.default !== 'function') {
+          if (isDebug()) {
+            console.warn(
+              `[timber] Metadata route ${metaMatch.file} does not export a default function — responding with 500\n` +
+                `  Metadata routes must export a default function that returns the metadata content.`
+            );
+          }
+          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) {
+          if (method === 'HEAD') {
+            const headHeaders = new Headers(handlerResult.headers);
+            if (handlerResult.ok && !headHeaders.has('Cache-Control')) {
+              headHeaders.set('Cache-Control', 'public, max-age=14400, must-revalidate');
+            }
+            return new Response(null, {
+              status: handlerResult.status,
+              statusText: handlerResult.statusText,
+              headers: headHeaders,
+            });
+          }
+          const res = cloneWithMutableHeaders(handlerResult);
+          if (res.ok && !res.headers.has('Cache-Control')) {
+            res.headers.set('Cache-Control', 'public, max-age=14400, must-revalidate');
+          }
+          return res;
+        }
+        // Otherwise, serialize based on content type. The type discriminator
+        // here is the metadata route's declared content type (from the file
+        // convention), not the shape of `handlerResult` — TS can't narrow the
+        // `MetadataResult` union on that, so we assert against the expected
+        // shape at each branch.
+        const contentType = metaMatch.contentType;
+        let body: string;
+        if (typeof handlerResult === 'string') {
+          body = handlerResult;
+        } else if (contentType === 'application/xml') {
+          body = serializeSitemap(handlerResult as MetadataRoute.Sitemap);
+        } else if (contentType === 'application/manifest+json') {
+          body = JSON.stringify(handlerResult, null, 2);
+        } else {
+          body = String(handlerResult);
+        }
+        return new Response(body, {
+          status: 200,
+          headers: {
+            'Content-Type': `${contentType}; charset=utf-8`,
+            'Cache-Control': 'public, max-age=14400, must-revalidate',
+          },
+        });
+      } catch (error) {
+        // Control-flow signals from the metadata handler (e.g. a sitemap that
+        // calls deny(404) for an unknown tenant, or a dynamic icon that
+        // redirects to a CDN-hosted asset) translate to proper HTTP responses
+        // instead of being logged as 500s.
+        if (error instanceof RedirectSignal) {
+          return new Response(null, {
+            status: error.status,
+            headers: { Location: error.location },
+          });
+        }
+        if (error instanceof DenySignal) {
+          return new Response(null, { status: error.status });
+        }
+        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).
+  // 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 (isRscRequest && config.interceptionRewrites?.length) {
+    const rawSourceUrl = req.headers.get('X-Timber-URL');
+    const validatedSourceUrl = rawSourceUrl
+      ? validateInterceptionHeader(rawSourceUrl, stripTrailingSlash)
+      : null;
+    if (validatedSourceUrl) {
+      const intercepted = findInterceptionMatch(
+        canonicalPathname,
+        validatedSourceUrl,
+        config.interceptionRewrites
+      );
+      if (intercepted) {
+        const sourceMatch = config.matchRoute(intercepted.sourcePathname);
+        if (sourceMatch) {
+          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();
+
+  // 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.
+  //
+  // 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 && !isRscRequest && !isApiRoute) {
+    try {
+      await config.earlyHints(match, req, responseHeaders);
+    } catch (err) {
+      swallow(err, 'early hints hook threw');
+    }
+  }
+
+  // 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"
+  //
+  // 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.
+  match.rawSegmentParams = { ...match.segmentParams };
+  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.
+      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 params.ts codec rejected the URL params.\n` +
+            `  Check that all fields in defineSegmentParams() are optional for params\n` +
+            `  that don't appear at every route depth (e.g. year, month, day).`
+        );
+      }
+      // 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);
+
+  // 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}`);
+
+  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,
+  });
+}