@timber-js/app 0.2.0-alpha.9 → 0.2.0-alpha.90

package/src/server/pipeline.ts

@@ -13,7 +13,7 @@
 
 import { canonicalize } from './canonicalize.js';
 import { runProxy, type ProxyExport } from './proxy.js';
-import { runMiddleware, type MiddlewareFn } from './middleware-runner.js';
+import { runMiddlewareChain, type MiddlewareFn } from './middleware-runner.js';
 import { runWithTimingCollector, withTiming, getServerTimingHeader } from './server-timing.js';
 import {
   runWithRequestContext,
@@ -21,6 +21,7 @@ import {
   setMutableCookieContext,
   getSetCookieHeaders,
   markResponseFlushed,
+  setSegmentParams,
 } from './request-context.js';
 import {
   generateTraceId,
@@ -29,7 +30,7 @@ import {
   replaceTraceId,
   withSpan,
   setSpanAttribute,
-  traceId,
+  getTraceId,
 } from './tracing.js';
 import {
   logRequestReceived,
@@ -42,10 +43,35 @@ import {
 } from './logger.js';
 import { callOnRequestError } from './instrumentation.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 type { MiddlewareContext } from './types.js';
-import type { SegmentNode } from '#/routing/types.js';
+import type { SegmentNode } from '../routing/types.js';
+
+// ─── Prototype-Pollution-Safe Merge ────────────────────────────────────────
+
+/** Keys that must never be merged via Object.assign — they pollute Object.prototype. */
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Shallow merge that skips prototype-polluting keys.
+ *
+ * Used instead of Object.assign when the source object comes from
+ * user-authored codec output (segmentParams.parse), which could
+ * contain __proto__, constructor, or prototype keys.
+ *
+ * See TIM-655, design/13-security.md
+ */
+export function safeMerge(target: Record<string, unknown>, source: Record<string, unknown>): void {
+  for (const key of Object.keys(source)) {
+    if (!DANGEROUS_KEYS.has(key)) {
+      target[key] = source[key];
+    }
+  }
+}
 
 // ─── Route Match Result ────────────────────────────────────────────────────
 
@@ -53,10 +79,10 @@ import type { SegmentNode } from '#/routing/types.js';
 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;
+  /** Extracted segment params (catch-all segments produce string[]). */
+  segmentParams: 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. */
@@ -115,14 +141,25 @@ 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.js').InterceptionRewrite[];
   /**
-   * Emit Server-Timing header on responses for Chrome DevTools visibility.
-   * Only enable in dev mode — exposes internal timing data.
+   * Control Server-Timing header output.
    *
-   * Default: false (production-safe).
+   * - `'detailed'` — per-phase breakdown (proxy, middleware, render).
+   * - `'total'` — single `total;dur=N` entry (production-safe).
+   * - `false` — no Server-Timing header at all.
+   *
+   * Default: `'total'`.
    */
-  enableServerTiming?: boolean;
+  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
@@ -131,6 +168,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.
@@ -147,6 +185,64 @@ export interface PipelineConfig {
     req: Request,
     responseHeaders: Headers
   ) => 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
+  ) => Response | Promise<Response>;
+}
+
+// ─── 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 as unknown as import('./route-matcher.js').ManifestSegmentNode[];
+
+  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);
+      // Merge coerced values back — use safeMerge to prevent prototype pollution
+      // from malicious/buggy codec output. See TIM-655.
+      safeMerge(match.segmentParams, coerced as Record<string, unknown>);
+    } catch (err) {
+      throw new ParamCoercionError(err instanceof Error ? err.message : String(err));
+    }
+  }
 }
 
 // ─── Pipeline ──────────────────────────────────────────────────────────────
@@ -165,7 +261,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
     earlyHints,
     stripTrailingSlash = true,
     slowRequestMs = 3000,
-    enableServerTiming = false,
+    serverTiming = 'total',
     onPipelineError,
   } = config;
 
@@ -186,7 +282,7 @@ 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
+      // Establish request context ALS scope so getHeaders() and getCookies() work
       // throughout the entire request lifecycle (proxy, middleware, render).
       return runWithRequestContext(req, async () => {
         // In dev mode, wrap with timing collector for Server-Timing header.
@@ -216,25 +312,25 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
               // DevSpanProcessor reads this for tree/summary output.
               await setSpanAttribute('http.response.status_code', result.status);
 
-              // Append Server-Timing header.
-              // In dev mode: detailed per-phase breakdown (proxy, middleware, render).
-              // In production: single total duration — safe to expose, no phase names.
+              // Append Server-Timing header based on configured mode.
               // Response.redirect() creates immutable headers, so we must
               // ensure mutability before writing Server-Timing.
-              if (enableServerTiming) {
-                const serverTiming = getServerTimingHeader();
-                if (serverTiming) {
+              if (serverTiming === 'detailed') {
+                // Detailed: per-phase breakdown (proxy, middleware, render).
+                const timingHeader = getServerTimingHeader();
+                if (timingHeader) {
                   result = ensureMutableResponse(result);
-                  result.headers.set('Server-Timing', serverTiming);
+                  result.headers.set('Server-Timing', timingHeader);
                 }
-              } else {
-                // Production: emit total request duration only.
-                // No phase breakdown — prevents information disclosure
-                // while giving browser DevTools useful timing data.
+              } 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;
             }
@@ -254,7 +350,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
           return response;
         };
 
-        return enableServerTiming ? runWithTimingCollector(runRequest) : runRequest();
+        return serverTiming === 'detailed' ? runWithTimingCollector(runRequest) : runRequest();
       });
     });
   };
@@ -272,7 +368,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       }
       const proxyFn = () => runProxy(proxyExport, req, () => handleRequest(req, method, path));
       return await withSpan('timber.proxy', {}, () =>
-        enableServerTiming ? withTiming('proxy', 'proxy.ts', proxyFn) : proxyFn()
+        serverTiming === 'detailed' ? withTiming('proxy', 'proxy.ts', proxyFn) : proxyFn()
       );
     } catch (error) {
       // Uncaught proxy.ts error → bare HTTP 500
@@ -283,6 +379,24 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
     }
   }
 
+  /**
+   * Build a redirect Response from a RedirectSignal.
+   *
+   * For RSC payload requests (client navigation), returns 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.
+   */
+  function buildRedirectResponse(signal: RedirectSignal, req: Request, headers: Headers): Response {
+    const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
+    if (isRsc) {
+      headers.set('X-Timber-Redirect', signal.location);
+      return new Response(null, { status: 204, headers });
+    }
+    headers.set('Location', signal.location);
+    return new Response(null, { status: signal.status, headers });
+  }
+
   async function handleRequest(req: Request, method: string, path: string): Promise<Response> {
     // Stage 1: URL canonicalization
     const url = new URL(req.url);
@@ -306,7 +420,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
             return await serveStaticMetadataFile(metaMatch);
           }
 
-          const mod = (await metaMatch.file.load()) as { default?: Function };
+          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 });
           }
@@ -339,6 +453,36 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       }
     }
 
+    // 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 sitemapResponse;
+      } catch (error) {
+        logRenderError({ method, path, error });
+        if (onPipelineError && error instanceof Error) 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 = matchRoute(canonicalPathname);
     let interception: InterceptionContext | undefined;
@@ -397,18 +541,57 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       }
     }
 
-    // Stage 3: Leaf middleware.ts (only the leaf route's middleware runs)
-    if (match.middleware) {
+    // 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 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);
+
+    // Stage 3: Middleware chain (root-to-leaf, short-circuits on first Response)
+    if (match.middlewareChain.length > 0) {
       const ctx: MiddlewareContext = {
         req,
         requestHeaders: requestHeaderOverlay,
         headers: responseHeaders,
-        params: match.params,
-        searchParams: new URL(req.url).searchParams,
+        segmentParams: match.segmentParams,
         earlyHints: (hints) => {
           for (const hint of hints) {
-            let value = `<${hint.href}>; rel=${hint.rel}`;
-            if (hint.as !== undefined) value += `; as=${hint.as}`;
+            // 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);
@@ -419,9 +602,9 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       try {
         // Enable cookie mutation during middleware (design/29-cookies.md §"Context Tracking")
         setMutableCookieContext(true);
-        const middlewareFn = () => runMiddleware(match.middleware!, ctx);
+        const chainFn = () => runMiddlewareChain(match.middlewareChain, ctx);
         const middlewareResponse = await withSpan('timber.middleware', {}, () =>
-          enableServerTiming ? withTiming('mw', 'middleware.ts', middlewareFn) : middlewareFn()
+          serverTiming === 'detailed' ? withTiming('mw', 'middleware.ts', chainFn) : chainFn()
         );
         setMutableCookieContext(false);
         if (middlewareResponse) {
@@ -430,32 +613,43 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
           // mutability before appending Set-Cookie entries.
           const finalResponse = ensureMutableResponse(middlewareResponse);
           applyCookieJar(finalResponse.headers);
+          // Merge parent-set responseHeaders onto the short-circuit response.
+          // Child-set headers take precedence — only add headers not already present.
+          // Snapshot existing keys first so multi-value headers (Set-Cookie, Link)
+          // from the parent are all appended when the child didn't set that key.
+          const existingKeys = new Set(
+            [...finalResponse.headers.keys()].map((k) => k.toLowerCase())
+          );
+          for (const [key, value] of responseHeaders.entries()) {
+            if (!existingKeys.has(key.toLowerCase())) {
+              finalResponse.headers.append(key, value);
+            }
+          }
           logMiddlewareShortCircuit({ method, path, status: finalResponse.status });
           return finalResponse;
         }
-        // Middleware succeeded without short-circuiting — apply any
-        // injected request headers so headers() returns them downstream.
+        // Middleware chain completed without short-circuiting — apply any
+        // injected request headers so getHeaders() 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.
+        // RedirectSignal from middleware → HTTP redirect (not an error)
         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 });
+          return buildRedirectResponse(error, req, responseHeaders);
         }
-        // DenySignal from middleware → HTTP deny status
+        // DenySignal from middleware → render deny page with correct status code.
+        // Previously returned bare Response(null) — now renders 403.tsx etc.
         if (error instanceof DenySignal) {
-          return new Response(null, { status: error.status });
+          applyCookieJar(responseHeaders);
+          if (config.renderDenyFallback) {
+            try {
+              return await config.renderDenyFallback(error, req, responseHeaders);
+            } catch {
+              // Deny page rendering failed — fall through to bare response
+            }
+          }
+          return new Response(null, { status: error.status, headers: responseHeaders });
         }
         // Middleware throw → HTTP 500 (middleware runs before rendering,
         // no error boundary to catch it)
@@ -476,28 +670,29 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       const renderFn = () =>
         render(req, match, responseHeaders, requestHeaderOverlay, interception);
       const response = await withSpan('timber.render', { 'http.route': canonicalPathname }, () =>
-        enableServerTiming ? withTiming('render', 'RSC + SSR render', renderFn) : renderFn()
+        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.
+      // Render the deny page with the correct status code.
       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 });
+        if (config.renderDenyFallback) {
+          try {
+            return await config.renderDenyFallback(error, req, responseHeaders);
+          } catch {
+            // Deny page rendering failed — fall through to bare response
+          }
         }
-        responseHeaders.set('Location', error.location);
         return new Response(null, { status: error.status, headers: responseHeaders });
       }
+      // RedirectSignal leaked from render — honour the redirect
+      if (error instanceof RedirectSignal) {
+        return buildRedirectResponse(error, req, responseHeaders);
+      }
       logRenderError({ method, path, error });
       await fireOnRequestError(error, req, 'render');
       if (onPipelineError && error instanceof Error) onPipelineError(error, 'render');
@@ -532,7 +727,7 @@ async function fireOnRequestError(
   await callOnRequestError(
     error,
     { method: req.method, path: url.pathname, headers: headersObj },
-    { phase, routePath: url.pathname, routeType: 'page', traceId: traceId() }
+    { phase, routePath: url.pathname, routeType: 'page', traceId: getTraceId() }
   );
 }