@timber-js/app 0.2.0-alpha.6 → 0.2.0-alpha.61

package/src/server/pipeline.ts

@@ -21,6 +21,7 @@ import {
   setMutableCookieContext,
   getSetCookieHeaders,
   markResponseFlushed,
+  setSegmentParams,
 } from './request-context.js';
 import {
   generateTraceId,
@@ -42,10 +43,12 @@ 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 { 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';
 
 // ─── Route Match Result ────────────────────────────────────────────────────
 
@@ -115,14 +118,17 @@ 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;
   /**
    * Dev pipeline error callback — called when a pipeline phase (proxy,
    * middleware, render) catches an unhandled error. Used to wire the error
@@ -149,6 +155,42 @@ export interface PipelineConfig {
   ) => 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;
+
+    const mod = (await segment.params.load()) as Record<string, unknown>;
+    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.params);
+      // Merge coerced values back into match.params
+      Object.assign(match.params, coerced);
+    } catch (err) {
+      throw new ParamCoercionError(err instanceof Error ? err.message : String(err));
+    }
+  }
+}
+
 // ─── Pipeline ──────────────────────────────────────────────────────────────
 
 /**
@@ -165,7 +207,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
     earlyHints,
     stripTrailingSlash = true,
     slowRequestMs = 3000,
-    enableServerTiming = false,
+    serverTiming = 'total',
     onPipelineError,
   } = config;
 
@@ -216,25 +258,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 +296,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
           return response;
         };
 
-        return enableServerTiming ? runWithTimingCollector(runRequest) : runRequest();
+        return serverTiming === 'detailed' ? runWithTimingCollector(runRequest) : runRequest();
       });
     });
   };
@@ -272,7 +314,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 +325,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);
@@ -339,6 +399,21 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       }
     }
 
+    // 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 +472,57 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       }
     }
 
+    // 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 rawSegmentParams() instead of receiving them as a prop.
+    // See design/07-routing.md §"params.ts — Convention File for Typed Params"
+    setSegmentParams(match.params);
+
     // Stage 3: Leaf middleware.ts (only the leaf route's middleware runs)
     if (match.middleware) {
       const ctx: MiddlewareContext = {
         req,
         requestHeaders: requestHeaderOverlay,
         headers: responseHeaders,
-        params: match.params,
-        searchParams: new URL(req.url).searchParams,
+        segmentParams: match.params,
         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);
@@ -421,7 +535,9 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
         setMutableCookieContext(true);
         const middlewareFn = () => runMiddleware(match.middleware!, ctx);
         const middlewareResponse = await withSpan('timber.middleware', {}, () =>
-          enableServerTiming ? withTiming('mw', 'middleware.ts', middlewareFn) : middlewareFn()
+          serverTiming === 'detailed'
+            ? withTiming('mw', 'middleware.ts', middlewareFn)
+            : middlewareFn()
         );
         setMutableCookieContext(false);
         if (middlewareResponse) {
@@ -438,20 +554,10 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
         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
         if (error instanceof DenySignal) {
@@ -476,7 +582,9 @@ 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;
@@ -486,10 +594,9 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       if (error instanceof DenySignal) {
         return new Response(null, { status: error.status });
       }
-      // RedirectSignal leaked from render — honour the redirect.
+      // RedirectSignal leaked from render — honour the redirect
       if (error instanceof RedirectSignal) {
-        responseHeaders.set('Location', error.location);
-        return new Response(null, { status: error.status, headers: responseHeaders });
+        return buildRedirectResponse(error, req, responseHeaders);
       }
       logRenderError({ method, path, error });
       await fireOnRequestError(error, req, 'render');

package/src/server/primitives.ts

@@ -6,6 +6,8 @@
 import type { JsonSerializable } from './types.js';
 import { getWaitUntil as _getWaitUntil } from './waituntil-bridge.js';
 import { isDebug } from './debug.js';
+import { getRequestSearchString } from './request-context.js';
+import { mergePreservedSearchParams } from '../shared/merge-search-params.js';
 
 // ─── Dev-mode validation ────────────────────────────────────────────────────
 
@@ -209,14 +211,46 @@ export class RedirectSignal extends Error {
 /** Pattern matching absolute URLs: http(s):// or protocol-relative // */
 const ABSOLUTE_URL_RE = /^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/\/)/;
 
+/**
+ * Options for redirect() — alternative to passing a bare status code.
+ */
+export interface RedirectOptions {
+  /** HTTP redirect status code (3xx). Defaults to 302. */
+  status?: number;
+  /**
+   * Preserve search params from the current request URL on the redirect target.
+   *
+   * - `true` — preserve ALL current search params (target params take precedence)
+   * - `string[]` — preserve only the named params (e.g. `['private', 'token']`)
+   *
+   * Target path's own query params always take precedence over preserved ones.
+   */
+  preserveSearchParams?: true | string[];
+}
+
 /**
  * Redirect to a relative path. Rejects absolute and protocol-relative URLs.
  * Use `redirectExternal()` for external redirects with an allow-list.
  *
  * @param path - Relative path (e.g. '/login', 'settings', '/login?returnTo=/dash')
- * @param status - HTTP redirect status code (3xx). Defaults to 302.
+ * @param statusOrOptions - HTTP status code (3xx, default 302) or options object.
+ *
+ * @example
+ * // Simple redirect
+ * redirect('/login');
+ *
+ * // With status code
+ * redirect('/login', 301);
+ *
+ * // With preserved search params
+ * redirect(`/docs/${version}/${slug}`, { preserveSearchParams: ['foo'] });
  */
-export function redirect(path: string, status: number = 302): never {
+export function redirect(path: string, statusOrOptions?: number | RedirectOptions): never {
+  const status =
+    typeof statusOrOptions === 'number' ? statusOrOptions : (statusOrOptions?.status ?? 302);
+  const preserveSearchParams =
+    typeof statusOrOptions === 'object' ? statusOrOptions.preserveSearchParams : undefined;
+
   if (status < 300 || status > 399) {
     throw new Error(`redirect() requires a 3xx status code, got ${status}.`);
   }
@@ -226,7 +260,14 @@ export function redirect(path: string, status: number = 302): never {
         'Use redirectExternal(url, allowList) for external redirects.'
     );
   }
-  throw new RedirectSignal(path, status);
+
+  let resolvedPath = path;
+  if (preserveSearchParams) {
+    const currentSearch = getRequestSearchString();
+    resolvedPath = mergePreservedSearchParams(path, currentSearch, preserveSearchParams);
+  }
+
+  throw new RedirectSignal(resolvedPath, status);
 }
 
 /**
@@ -236,9 +277,10 @@ export function redirect(path: string, status: number = 302): never {
  * will replay POST requests to the new location. This matches Next.js behavior.
  *
  * @param path - Relative path (e.g. '/new-page', '/dashboard')
+ * @param options - Optional redirect options (e.g. preserveSearchParams).
  */
-export function permanentRedirect(path: string): never {
-  redirect(path, 308);
+export function permanentRedirect(path: string, options?: Omit<RedirectOptions, 'status'>): never {
+  redirect(path, { status: 308, ...options });
 }
 
 /**

package/src/server/render-timeout.ts

@@ -0,0 +1,108 @@
+/**
+ * Render timeout utilities for SSR streaming pipeline.
+ *
+ * Provides a RenderTimeoutError class and a helper to create
+ * timeout-guarded AbortSignals. Used to defend against hung RSC
+ * streams and infinite SSR renders.
+ *
+ * Design doc: 02-rendering-pipeline.md §"Streaming Constraints"
+ */
+
+/**
+ * Error thrown when an SSR render or RSC stream read exceeds the
+ * configured timeout. Callers can check `instanceof RenderTimeoutError`
+ * to distinguish timeout from other errors and return a 504 or close
+ * the connection cleanly.
+ */
+export class RenderTimeoutError extends Error {
+  readonly timeoutMs: number;
+
+  constructor(timeoutMs: number, context?: string) {
+    const message = context
+      ? `Render timeout after ${timeoutMs}ms: ${context}`
+      : `Render timeout after ${timeoutMs}ms`;
+    super(message);
+    this.name = 'RenderTimeoutError';
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+/**
+ * Result of createRenderTimeout — an AbortSignal that fires after
+ * the given duration, plus a cancel function to clear the timer
+ * when the render completes normally.
+ */
+export interface RenderTimeout {
+  /** AbortSignal that aborts after timeoutMs. */
+  signal: AbortSignal;
+  /** Cancel the timeout timer. Call this when the render completes. */
+  cancel: () => void;
+}
+
+/**
+ * Create a render timeout that aborts after the given duration.
+ *
+ * Returns an AbortSignal and a cancel function. The signal fires
+ * with a RenderTimeoutError as the abort reason after `timeoutMs`.
+ * Call `cancel()` when the render completes to prevent the timeout
+ * from firing.
+ *
+ * If an existing `parentSignal` is provided, the returned signal
+ * aborts when either the parent signal or the timeout fires —
+ * whichever comes first.
+ */
+export function createRenderTimeout(timeoutMs: number, parentSignal?: AbortSignal): RenderTimeout {
+  const controller = new AbortController();
+  const reason = new RenderTimeoutError(timeoutMs, 'RSC stream read timed out');
+
+  const timer = setTimeout(() => {
+    controller.abort(reason);
+  }, timeoutMs);
+
+  // If there's a parent signal (e.g. request abort), chain it
+  if (parentSignal) {
+    if (parentSignal.aborted) {
+      clearTimeout(timer);
+      controller.abort(parentSignal.reason);
+    } else {
+      parentSignal.addEventListener(
+        'abort',
+        () => {
+          clearTimeout(timer);
+          controller.abort(parentSignal.reason);
+        },
+        { once: true }
+      );
+    }
+  }
+
+  return {
+    signal: controller.signal,
+    cancel: () => {
+      clearTimeout(timer);
+    },
+  };
+}
+
+/**
+ * Race a promise against a timeout. Rejects with RenderTimeoutError
+ * if the promise does not resolve within `timeoutMs`.
+ *
+ * Used to guard individual `rscReader.read()` calls inside pullLoop.
+ */
+export function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  context?: string
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeoutPromise = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(new RenderTimeoutError(timeoutMs, context));
+    }, timeoutMs);
+  });
+
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    clearTimeout(timer!);
+  });
+}