@timber-js/app 0.1.20 → 0.1.22

package/src/server/pipeline.ts

@@ -11,9 +11,15 @@
  * and design/17-logging.md §"Production Logging"
  */
 
+import { readFile } from 'node:fs/promises';
 import { canonicalize } from './canonicalize.js';
 import { runProxy, type ProxyExport } from './proxy.js';
 import { runMiddleware, type MiddlewareFn } from './middleware-runner.js';
+import {
+  runWithTimingCollector,
+  withTiming,
+  getServerTimingHeader,
+} from './server-timing.js';
 import {
   runWithRequestContext,
   applyRequestHeaderOverlay,
@@ -113,6 +119,13 @@ export interface PipelineConfig {
    * See design/07-routing.md §"Intercepting Routes"
    */
   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.
+   *
+   * Default: false (production-safe).
+   */
+  enableServerTiming?: boolean;
   /**
    * Dev pipeline error callback — called when a pipeline phase (proxy,
    * middleware, render) catches an unhandled error. Used to wire the error
@@ -155,6 +168,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
     earlyHints,
     stripTrailingSlash = true,
     slowRequestMs = 3000,
+    enableServerTiming = false,
     onPipelineError,
   } = config;
 
@@ -173,43 +187,65 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       // Establish request context ALS scope so headers() and cookies() work
       // throughout the entire request lifecycle (proxy, middleware, render).
       return runWithRequestContext(req, async () => {
-        logRequestReceived({ method, path });
-
-        const response = await withSpan(
-          'http.server.request',
-          { 'http.request.method': method, 'url.path': path },
-          async () => {
-            // If OTEL is active, the root span now exists — replace the UUID
-            // fallback with the real OTEL trace ID for log–trace correlation.
-            const otelIds = await getOtelTraceId();
-            if (otelIds) {
-              replaceTraceId(otelIds.traceId, otelIds.spanId);
+        // In dev mode, wrap with timing collector for Server-Timing header.
+        // The collector uses ALS so timing entries are per-request.
+        const runRequest = async () => {
+          logRequestReceived({ method, path });
+
+          const response = await withSpan(
+            'http.server.request',
+            { 'http.request.method': method, 'url.path': path },
+            async () => {
+              // If OTEL is active, the root span now exists — replace the UUID
+              // fallback with the real OTEL trace ID for log–trace correlation.
+              const otelIds = await getOtelTraceId();
+              if (otelIds) {
+                replaceTraceId(otelIds.traceId, otelIds.spanId);
+              }
+
+              let result: Response;
+              if (proxy || config.proxyLoader) {
+                result = await runProxyPhase(req, method, path);
+              } else {
+                result = await handleRequest(req, method, path);
+              }
+
+              // Set response status on the root span before it ends —
+              // DevSpanProcessor reads this for tree/summary output.
+              await setSpanAttribute('http.response.status_code', result.status);
+
+              // Append Server-Timing header in dev mode.
+              // At this point, pre-flush phases (proxy, middleware, render)
+              // have completed and their timing entries are collected.
+              // Response.redirect() creates immutable headers, so we must
+              // ensure mutability before writing Server-Timing.
+              if (enableServerTiming) {
+                const serverTiming = getServerTimingHeader();
+                if (serverTiming) {
+                  result = ensureMutableResponse(result);
+                  result.headers.set('Server-Timing', serverTiming);
+                }
+              }
+
+              return result;
             }
+          );
 
-            let result: Response;
-            if (proxy || config.proxyLoader) {
-              result = await runProxyPhase(req, method, path);
-            } else {
-              result = await handleRequest(req, method, path);
-            }
+          // Post-span: structured production logging
+          const durationMs = Math.round(performance.now() - startTime);
+          const status = response.status;
+          logRequestCompleted({ method, path, status, durationMs });
 
-            // Set response status on the root span before it ends —
-            // DevSpanProcessor reads this for tree/summary output.
-            await setSpanAttribute('http.response.status_code', result.status);
-            return result;
+          if (slowRequestMs > 0 && durationMs > slowRequestMs) {
+            logSlowRequest({ method, path, durationMs, threshold: slowRequestMs });
           }
-        );
 
-        // Post-span: structured production logging
-        const durationMs = Math.round(performance.now() - startTime);
-        const status = response.status;
-        logRequestCompleted({ method, path, status, durationMs });
-
-        if (slowRequestMs > 0 && durationMs > slowRequestMs) {
-          logSlowRequest({ method, path, durationMs, threshold: slowRequestMs });
-        }
+          return response;
+        };
 
-        return response;
+        return enableServerTiming
+          ? runWithTimingCollector(runRequest)
+          : runRequest();
       });
     });
   };
@@ -225,8 +261,12 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       } else {
         proxyExport = config.proxy!;
       }
+      const proxyFn = () =>
+        runProxy(proxyExport, req, () => handleRequest(req, method, path));
       return await withSpan('timber.proxy', {}, () =>
-        runProxy(proxyExport, req, () => handleRequest(req, method, path))
+        enableServerTiming
+          ? withTiming('proxy', 'proxy.ts', proxyFn)
+          : proxyFn()
       );
     } catch (error) {
       // Uncaught proxy.ts error → bare HTTP 500
@@ -253,6 +293,13 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       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 metaMatch.file.load()) as { default?: Function };
           if (typeof mod.default !== 'function') {
             return new Response('Metadata route must export a default function', { status: 500 });
@@ -360,15 +407,21 @@ 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 middlewareResponse = await withSpan('timber.middleware', {}, () =>
-          runMiddleware(match.middleware!, ctx)
+          enableServerTiming
+            ? withTiming('mw', 'middleware.ts', middlewareFn)
+            : middlewareFn()
         );
         setMutableCookieContext(false);
         if (middlewareResponse) {
-          // Apply cookie jar to short-circuit response
-          applyCookieJar(middlewareResponse.headers);
-          logMiddlewareShortCircuit({ method, path, status: middlewareResponse.status });
-          return middlewareResponse;
+          // Apply cookie jar to short-circuit response.
+          // Response.redirect() creates immutable headers, so ensure
+          // mutability before appending Set-Cookie entries.
+          const finalResponse = ensureMutableResponse(middlewareResponse);
+          applyCookieJar(finalResponse.headers);
+          logMiddlewareShortCircuit({ method, path, status: finalResponse.status });
+          return finalResponse;
         }
         // Middleware succeeded without short-circuiting — apply any
         // injected request headers so headers() returns them downstream.
@@ -410,8 +463,12 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
 
     // Stage 4: Render (access gates + element tree + renderToReadableStream)
     try {
+      const renderFn = () =>
+        render(req, match, responseHeaders, requestHeaderOverlay, interception);
       const response = await withSpan('timber.render', { 'http.route': canonicalPathname }, () =>
-        render(req, match, responseHeaders, requestHeaderOverlay, interception)
+        enableServerTiming
+          ? withTiming('render', 'RSC + SSR render', renderFn)
+          : renderFn()
       );
       markResponseFlushed();
       return response;
@@ -533,6 +590,36 @@ function applyCookieJar(headers: Headers): void {
   }
 }
 
+// ─── Immutable Response Helpers ──────────────────────────────────────────
+
+/**
+ * Ensure a Response has mutable headers so the pipeline can safely append
+ * Set-Cookie and Server-Timing entries.
+ *
+ * `Response.redirect()` and some platform-level responses return objects
+ * with immutable headers. Calling `.set()` or `.append()` on them throws
+ * `TypeError: immutable`. This helper detects the immutable case by
+ * attempting a no-op write and, on failure, clones into a fresh Response
+ * with mutable headers.
+ */
+function ensureMutableResponse(response: Response): Response {
+  try {
+    // Probe mutability with a benign operation that we immediately undo.
+    // We pick a header name that is extremely unlikely to collide with
+    // anything meaningful and delete it right away.
+    response.headers.set('X-Timber-Probe', '1');
+    response.headers.delete('X-Timber-Probe');
+    return response;
+  } catch {
+    // Headers are immutable — rebuild with mutable headers.
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: new Headers(response.headers),
+    });
+  }
+}
+
 // ─── Metadata Route Helpers ──────────────────────────────────────────────
 
 /**
@@ -577,3 +664,42 @@ function escapeXml(str: string): string {
     .replace(/"/g, '"')
     .replace(/'/g, ''');
 }
+
+// ─── Static Metadata File Serving ────────────────────────────────────────
+
+/**
+ * Content types that are text-based and should include charset=utf-8.
+ * Binary formats (images) should not include charset.
+ */
+const TEXT_CONTENT_TYPES = new Set([
+  'application/xml',
+  'text/plain',
+  'application/json',
+  'application/manifest+json',
+  'image/svg+xml',
+]);
+
+/**
+ * Serve a static metadata file by reading it from disk.
+ *
+ * Static metadata route files (.xml, .txt, .json, .png, .ico, .svg, etc.)
+ * are served as-is with the appropriate Content-Type header.
+ * Text files include charset=utf-8; binary files do not.
+ *
+ * See design/16-metadata.md §"Metadata Routes"
+ */
+async function serveStaticMetadataFile(
+  metaMatch: import('./route-matcher.js').MetadataRouteMatch
+): Promise<Response> {
+  const { contentType, file } = metaMatch;
+  const isText = TEXT_CONTENT_TYPES.has(contentType);
+
+  const body = await readFile(file.filePath);
+
+  const headers: Record<string, string> = {
+    'Content-Type': isText ? `${contentType}; charset=utf-8` : contentType,
+    'Content-Length': String(body.byteLength),
+  };
+
+  return new Response(body, { status: 200, headers });
+}

package/src/server/primitives.ts

@@ -3,6 +3,101 @@
 // These are the core runtime signals that components, middleware, and access gates
 // use to control request flow. See design/10-error-handling.md.
 
+import type { JsonSerializable } from './types.js';
+
+// ─── Dev-mode validation ────────────────────────────────────────────────────
+
+/**
+ * Check if a value is JSON-serializable without data loss.
+ * Returns a description of the first non-serializable value found, or null if OK.
+ *
+ * @internal Exported for testing only.
+ */
+export function findNonSerializable(value: unknown, path = 'data'): string | null {
+  if (value === null || value === undefined) return null;
+
+  switch (typeof value) {
+    case 'string':
+    case 'number':
+    case 'boolean':
+      return null;
+    case 'bigint':
+      return `${path} contains a BigInt — BigInt throws in JSON.stringify`;
+    case 'function':
+      return `${path} is a function — functions are not JSON-serializable`;
+    case 'symbol':
+      return `${path} is a symbol — symbols are not JSON-serializable`;
+    case 'object':
+      break;
+    default:
+      return `${path} has unsupported type "${typeof value}"`;
+  }
+
+  if (value instanceof Date) {
+    return `${path} is a Date — Dates silently coerce to strings in JSON.stringify`;
+  }
+  if (value instanceof Map) {
+    return `${path} is a Map — Maps serialize as {} in JSON.stringify (data loss)`;
+  }
+  if (value instanceof Set) {
+    return `${path} is a Set — Sets serialize as {} in JSON.stringify (data loss)`;
+  }
+  if (value instanceof RegExp) {
+    return `${path} is a RegExp — RegExps serialize as {} in JSON.stringify`;
+  }
+  if (value instanceof Error) {
+    return `${path} is an Error — Errors serialize as {} in JSON.stringify`;
+  }
+
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      const result = findNonSerializable(value[i], `${path}[${i}]`);
+      if (result) return result;
+    }
+    return null;
+  }
+
+  // Plain object — only Object.prototype is safe. Null-prototype objects
+  // (Object.create(null)) survive JSON.stringify but React Flight rejects
+  // them with "Classes or null prototypes are not supported", so the
+  // pre-flush deny path (renderDenyPage → renderToReadableStream) would throw.
+  const proto = Object.getPrototypeOf(value);
+  if (proto === null) {
+    return `${path} is a null-prototype object — React Flight rejects null prototypes`;
+  }
+  if (proto !== Object.prototype) {
+    const name = (value as object).constructor?.name ?? 'unknown';
+    return `${path} is a ${name} instance — class instances may lose data in JSON.stringify`;
+  }
+
+  for (const key of Object.keys(value as Record<string, unknown>)) {
+    const result = findNonSerializable(
+      (value as Record<string, unknown>)[key],
+      `${path}.${key}`
+    );
+    if (result) return result;
+  }
+  return null;
+}
+
+/**
+ * Emit a dev-mode warning if data is not JSON-serializable.
+ * No-op in production.
+ */
+function warnIfNotSerializable(data: unknown, callerName: string): void {
+  if (process.env.NODE_ENV === 'production') return;
+  if (data === undefined) return;
+
+  const issue = findNonSerializable(data);
+  if (issue) {
+    console.warn(
+      `[timber] ${callerName}: ${issue}. ` +
+        'Data passed to deny() or RenderError must be JSON-serializable because ' +
+        'the post-flush path uses JSON.stringify, not React Flight.'
+    );
+  }
+}
+
 // ─── DenySignal ─────────────────────────────────────────────────────────────
 
 /**
@@ -11,9 +106,9 @@
  */
 export class DenySignal extends Error {
   readonly status: number;
-  readonly data: unknown;
+  readonly data: JsonSerializable | undefined;
 
-  constructor(status: number, data?: unknown) {
+  constructor(status: number, data?: JsonSerializable) {
     super(`Access denied with status ${status}`);
     this.name = 'DenySignal';
     this.status = status;
@@ -58,15 +153,16 @@ export class DenySignal extends Error {
  * - Inside Suspense (after flush): error boundary + noindex meta
  *
  * @param status - Any 4xx HTTP status code. Defaults to 403.
- * @param data - Optional data passed as `dangerouslyPassData` prop to status-code files.
+ * @param data - Optional JSON-serializable data passed as `dangerouslyPassData` prop to status-code files.
  */
-export function deny(status: number = 403, data?: unknown): never {
+export function deny(status: number = 403, data?: JsonSerializable): never {
   if (status < 400 || status > 499) {
     throw new Error(
       `deny() requires a 4xx status code, got ${status}. ` +
         'For 5xx errors, throw a RenderError instead.'
     );
   }
+  warnIfNotSerializable(data, 'deny()');
   throw new DenySignal(status, data);
 }
 
@@ -181,7 +277,10 @@ export function redirectExternal(url: string, allowList: string[], status: numbe
  * Typed digest that crosses the RSC → client boundary.
  * The `code` identifies the error class; `data` carries JSON-serializable context.
  */
-export interface RenderErrorDigest<TCode extends string = string, TData = unknown> {
+export interface RenderErrorDigest<
+  TCode extends string = string,
+  TData extends JsonSerializable = JsonSerializable,
+> {
   code: TCode;
   data: TData;
 }
@@ -200,7 +299,10 @@ export interface RenderErrorDigest<TCode extends string = string, TData = unknow
  * })
  * ```
  */
-export class RenderError<TCode extends string = string, TData = unknown> extends Error {
+export class RenderError<
+  TCode extends string = string,
+  TData extends JsonSerializable = JsonSerializable,
+> extends Error {
   readonly code: TCode;
   readonly digest: RenderErrorDigest<TCode, TData>;
   readonly status: number;
@@ -211,6 +313,8 @@ export class RenderError<TCode extends string = string, TData = unknown> extends
     this.code = code;
     this.digest = { code, data };
 
+    warnIfNotSerializable(data, 'RenderError');
+
     const status = options?.status ?? 500;
     if (status < 400 || status > 599) {
       throw new Error(`RenderError status must be 4xx or 5xx, got ${status}.`);

package/src/server/request-context.ts

@@ -10,44 +10,16 @@
  * See design/29-cookies.md for cookie mutation semantics.
  */
 
-import { AsyncLocalStorage } from 'node:async_hooks';
 import { createHmac, timingSafeEqual } from 'node:crypto';
 import type { Routes } from '#/index.js';
-
-// ─── ALS Store ────────────────────────────────────────────────────────────
-
-interface RequestContextStore {
-  /** Incoming request headers (read-only view). */
-  headers: Headers;
-  /** Raw cookie header string, parsed lazily into a Map on first access. */
-  cookieHeader: string;
-  /** Lazily-parsed cookie map (mutable — reflects write-overlay from set()). */
-  parsedCookies?: Map<string, string>;
-  /** Original (pre-overlay) frozen headers, kept for overlay merging. */
-  originalHeaders: Headers;
-  /**
-   * Promise resolving to the route's typed search params (when search-params.ts
-   * exists) or to the raw URLSearchParams. Stored as a Promise so the framework
-   * can later support partial pre-rendering where param resolution is deferred.
-   */
-  searchParamsPromise: Promise<URLSearchParams | Record<string, unknown>>;
-  /** Outgoing Set-Cookie entries (name → serialized value + options). Last write wins. */
-  cookieJar: Map<string, CookieEntry>;
-  /** Whether the response has flushed (headers committed). */
-  flushed: boolean;
-  /** Whether the current context allows cookie mutation. */
-  mutableContext: boolean;
-}
-
-/** A single outgoing cookie entry in the cookie jar. */
-interface CookieEntry {
-  name: string;
-  value: string;
-  options: CookieOptions;
-}
-
-/** @internal */
-export const requestContextAls = new AsyncLocalStorage<RequestContextStore>();
+import {
+  requestContextAls,
+  type RequestContextStore,
+  type CookieEntry,
+} from './als-registry.js';
+
+// Re-export the ALS for framework-internal consumers that need direct access.
+export { requestContextAls };
 
 // No fallback needed — we use enterWith() instead of run() to ensure
 // the ALS context persists for the entire request lifecycle including

package/src/server/route-matcher.ts

@@ -10,7 +10,12 @@
 
 import type { RouteMatch } from './pipeline.js';
 import type { MiddlewareFn } from './middleware-runner.js';
-import { METADATA_ROUTE_CONVENTIONS, type MetadataRouteType } from './metadata-routes.js';
+import {
+  METADATA_ROUTE_CONVENTIONS,
+  isStaticMetadataExtension,
+  resolveStaticContentType,
+  type MetadataRouteType,
+} from './metadata-routes.js';
 
 // ─── Manifest Types ───────────────────────────────────────────────────────
 // The virtual module manifest has a slightly different shape than SegmentNode:
@@ -292,6 +297,11 @@ export interface MetadataRouteMatch {
   file: ManifestFile;
   /** The matched segment (for context/params if needed). */
   segment: ManifestSegmentNode;
+  /**
+   * Whether this is a static file (e.g. sitemap.xml, favicon.ico, icon.png)
+   * that should be served from disk rather than executed as a handler.
+   */
+  isStatic: boolean;
 }
 
 /**
@@ -331,11 +341,24 @@ function collectMetadataRoutes(
       const prefix = node.urlPath === '/' ? '' : node.urlPath;
       const pathname = `${prefix}/${convention.servePath}`;
 
+      // Determine if this is a static file based on its extension.
+      // Static files (.xml, .txt, .png, .ico, etc.) are served from disk.
+      // Dynamic files (.ts, .tsx) export a handler function.
+      const ext = file.filePath.slice(file.filePath.lastIndexOf('.') + 1);
+      const isStatic = isStaticMetadataExtension(baseName, ext);
+
+      // Resolve generic content types (e.g. image/*) to concrete MIME types
+      // based on the file extension for static files.
+      const contentType = isStatic
+        ? resolveStaticContentType(convention.contentType, ext)
+        : convention.contentType;
+
       map.set(pathname, {
         type: convention.type,
-        contentType: convention.contentType,
+        contentType,
         file,
         segment: node,
+        isStatic,
       });
     }
   }

package/src/server/rsc-entry/error-renderer.ts

@@ -5,7 +5,7 @@
  */
 
 import { createElement } from 'react';
-import { renderToReadableStream } from '@vitejs/plugin-rsc/rsc';
+import { renderToReadableStream } from '#/rsc-runtime/rsc.js';
 
 import type { RouteMatch } from '#/server/pipeline.js';
 import { logRenderError } from '#/server/logger.js';