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

package/src/server/pipeline-phases.ts

@@ -0,0 +1,496 @@
+/**
+ * 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.ts';
+import { runProxy } from './proxy.ts';
+import { runMiddlewareChain } from './middleware-runner.ts';
+import { withTiming } from './server-timing.ts';
+import {
+  applyRequestHeaderOverlay,
+  setMutableCookieContext,
+  setSegmentParams,
+  setMatchedSegmentPath,
+} from './request-context.ts';
+import { withSpan } from './tracing.ts';
+import { requestCspNonce } from './csp-nonce.ts';
+import { logRenderError } from './logger.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 { 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, 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';
+import { isDebug } from './debug.ts';
+import { isRscRequest } from '../shared/rsc-media-type.ts';
+
+interface RenderContext {
+  canonicalPathname: string;
+  interception?: InterceptionContext;
+}
+
+// ─── 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) {
+    return thrownOutcome('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,
+  renderContext: RenderContext
+): Promise<PhaseOutcome> {
+  const detailed = config.serverTiming === 'detailed';
+  const requestHeaderOverlay = new Headers();
+  const ctx: MiddlewareContext = {
+    req,
+    requestHeaders: requestHeaderOverlay,
+    headers: responseHeaders,
+    segmentParams: match.segmentParams,
+    // Lazy: reading it is the opt-in that makes the render nonce its scripts.
+    get nonce() {
+      return requestCspNonce();
+    },
+    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);
+
+    return runRenderPhase(config, req, match, responseHeaders, renderContext);
+  } catch (error) {
+    return thrownOutcome('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.
+ *
+ * The render phase owns `responseHeaders` from here on, so it is the one
+ * place the cookie jar is applied to that bag (design/29-cookies.md
+ * §"Applied Exactly Once"). Doing it here rather than in the middleware
+ * phase means every render-phase outcome — a 200, or a deny / redirect /
+ * error thrown from render — carries the jar whether or not a middleware
+ * chain ran, and `outcomeToResponse` can skip render-phase outcomes
+ * unconditionally (TIM-1491). Application precedes `config.render` so
+ * middleware cookie writes are visible to route-handler header merging,
+ * while handler `Set-Cookie` values still come after them and take
+ * precedence.
+ */
+export async function runRenderPhase(
+  config: PipelineConfig,
+  req: Request,
+  match: RouteMatch,
+  responseHeaders: Headers,
+  { canonicalPathname, interception }: RenderContext
+): Promise<PhaseOutcome> {
+  const detailed = config.serverTiming === 'detailed';
+  applyCookieJar(responseHeaders);
+  try {
+    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) {
+    return thrownOutcome('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) {
+          return cloneWithMutableHeaders(handlerResult);
+        }
+        // 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 (isRedirectSignal(error)) {
+          return new Response(null, {
+            status: error.status,
+            headers: { Location: error.location },
+          });
+        }
+        if (isDenySignal(error)) {
+          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 });
+      }
+    }
+  }
+
+  // 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 });
+      await fireOnRequestError(error, req, 'route');
+      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 isRsc = isRscRequest(req);
+  if (isRsc) {
+    const skewCheck = checkVersionSkew(req);
+    if (!skewCheck.ok) {
+      const reloadHeaders = new Headers();
+      applyReloadHeaders(reloadHeaders);
+      return new Response(null, { status: 204, headers: reloadHeaders });
+    }
+  }
+
+  // Response and request header containers — created before early hints so
+  // the emitter can append Link headers (e.g. for Cloudflare CDN → 103).
+  // Seeded with the dynamic-page cache policy, which the no-match 404
+  // rendered below carries too.
+  const responseHeaders = dynamicResponseHeaders();
+
+  // 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.
+  //
+  // 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 {
+      return cloneWithMutableHeaders(await config.renderNoMatch(req, headers));
+    } catch (error) {
+      return outcomeToResponse(config, thrownOutcome('render', error), {
+        req,
+        method,
+        path,
+        responseHeaders: headers,
+      });
+    }
+  };
+  let match: RouteMatch | null = null;
+  let interception: InterceptionContext | undefined;
+  try {
+    // 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()) {
+        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.
+      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');
+      }
+    }
+
+    // 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);
+      }
+      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}`);
+  } 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, {
+          canonicalPathname,
+          interception,
+        })
+      : await runRenderPhase(config, req, match, responseHeaders, {
+          canonicalPathname,
+          interception,
+        });
+
+  return outcomeToResponse(config, outcome, {
+    req,
+    method,
+    path,
+    responseHeaders,
+    match,
+  });
+}