@timber-js/app 0.2.0-alpha.1 → 0.2.0-alpha.100

package/src/server/pipeline-helpers.ts

@@ -0,0 +1,204 @@
+/**
+ * Pipeline helpers — small utility functions used by `pipeline.ts` and
+ * `pipeline-phases.ts`. Lifted out of `pipeline.ts` to keep that file
+ * focused on the request handler entry point.
+ *
+ * Each helper is intentionally a free function with no closure capture, so
+ * it can be unit-tested in isolation.
+ *
+ * See design/07-routing.md §"Request Lifecycle".
+ */
+
+import type { ProxyExport } from './proxy.js';
+import { getSetCookieHeaders } from './cookie-context.js';
+import { callOnRequestError } from './instrumentation.js';
+import { getTraceId } from './tracing.js';
+import { RedirectSignal } from './primitives.js';
+import type { ProxyConfig } from './pipeline.js';
+
+// ─── Prototype-Pollution-Safe Sanitizer ────────────────────────────────────
+
+/**
+ * Only __proto__ needs stripping — it has a language-level setter that
+ * changes the prototype chain of spread copies. constructor and prototype
+ * are harmless own properties on null-prototype objects.
+ */
+const DANGEROUS_KEYS = new Set(['__proto__']);
+
+/**
+ * Deep-walk a value returned by a segment param codec, producing a
+ * sanitized copy where every plain object is null-prototype and
+ * dangerous keys (__proto__, constructor, prototype) are stripped at
+ * every depth.
+ *
+ * Non-plain objects (Date, Map, class instances, etc.) are returned
+ * as-is — they cannot be poisoned by `{...x}` spread and may carry
+ * author-intended prototype methods.
+ *
+ * Arrays are walked element-wise.
+ *
+ * Performance: URL params are bounded by URL length (~8 KB). Realistic
+ * trees are <1 KB. The recursive walk is sub-microsecond.
+ *
+ * See TIM-655, TIM-855, TIM-873, design/13-security.md
+ */
+export function sanitizeParamValue(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return value;
+
+  if (Array.isArray(value)) {
+    return value.map(sanitizeParamValue);
+  }
+
+  // Only walk plain objects — anything with a custom prototype (Date, Map,
+  // class instances) is left untouched.
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return value;
+
+  const out: Record<string, unknown> = Object.create(null);
+  for (const key of Object.keys(value as Record<string, unknown>)) {
+    if (!DANGEROUS_KEYS.has(key)) {
+      out[key] = sanitizeParamValue((value as Record<string, unknown>)[key]);
+    }
+  }
+  return out;
+}
+
+// ─── Proxy Resolver ────────────────────────────────────────────────────────
+
+/**
+ * Resolver closure produced once at pipeline construction. The lazy variant
+ * still calls `loader()` per-request (HMR relies on re-importing), but the
+ * choice of which branch to take is made once, not on every request.
+ */
+export type ProxyResolver = () => ProxyExport | Promise<ProxyExport>;
+
+/**
+ * Build a proxy resolver closure from the declared source. Called exactly
+ * once at `createPipeline` setup time, so the hot path sees only the branch
+ * that corresponds to this pipeline's configured variant.
+ *
+ * Returns `null` when the app has no proxy.ts — the hot path short-circuits
+ * around `runProxyPhase` entirely in that case.
+ *
+ * Accepts the sugar form (a bare `ProxyExport` — function or function array)
+ * and normalises it to the static variant. Functions and arrays are
+ * structurally distinct from the tagged `{ kind: 'lazy', loader }` object,
+ * so discrimination is unambiguous.
+ */
+export function makeProxyResolver(
+  proxy: ProxyConfig | ProxyExport | undefined
+): ProxyResolver | null {
+  if (proxy === undefined) return null;
+  // Sugar: a bare ProxyExport (function or function array) — treat as static.
+  if (typeof proxy === 'function' || Array.isArray(proxy)) {
+    const exp = proxy;
+    return () => exp;
+  }
+  if (proxy.kind === 'static') {
+    const exp = proxy.export;
+    return () => exp;
+  }
+  const loader = proxy.loader;
+  return async () => (await loader()).default;
+}
+
+// ─── Cookie / Header Helpers ───────────────────────────────────────────────
+
+/**
+ * Apply all Set-Cookie headers from the cookie jar to a Headers object.
+ * Each cookie gets its own Set-Cookie header per RFC 6265 §4.1.
+ */
+export function applyCookieJar(headers: Headers): void {
+  for (const value of getSetCookieHeaders()) {
+    headers.append('Set-Cookie', value);
+  }
+}
+
+/**
+ * Merge framework-managed response headers onto a terminal response without
+ * overwriting headers the terminal response already set itself.
+ */
+export function mergeMissingHeaders(target: Headers, source: Headers): void {
+  const existingKeys = new Set([...target.keys()].map((key) => key.toLowerCase()));
+  for (const [key, value] of source.entries()) {
+    if (!existingKeys.has(key.toLowerCase())) {
+      target.append(key, value);
+    }
+  }
+}
+
+// ─── Mutable Response Cloning ──────────────────────────────────────────────
+
+/**
+ * Clone a Response into a fresh one whose header bag is guaranteed mutable.
+ *
+ * `Response.redirect()` and some platform-level passthrough responses (notably
+ * on Cloudflare Workers) return objects with frozen header bags. Calling
+ * `.set()` or `.append()` on them throws `TypeError: immutable`, which the
+ * pipeline can hit when it appends Set-Cookie or Server-Timing entries.
+ *
+ * The pipeline calls this at the producer sites where user-controlled
+ * responses enter the framework — `outcomeToResponse` for all phase outcomes,
+ * and `handleRequest` for metadata-route and auto-sitemap user handlers — so
+ * downstream code can write headers without runtime feature-detection.
+ *
+ * The clone is unconditional. This is a deliberate trade: we avoid a
+ * try/catch + thrown `TypeError` on every request (the previous probe-based
+ * approach paid that cost on the hot path) and accept one cheap Response
+ * rewrap at the framework boundary instead.
+ */
+export function cloneWithMutableHeaders(response: Response): Response {
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: new Headers(response.headers),
+  });
+}
+
+// ─── Redirect Builder ──────────────────────────────────────────────────────
+
+/**
+ * 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.
+ */
+export 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 });
+}
+
+// ─── Instrumentation ───────────────────────────────────────────────────────
+
+/**
+ * Fire the user's onRequestError hook with request context.
+ * Extracts request info from the Request object and calls the instrumentation hook.
+ */
+export async function fireOnRequestError(
+  error: unknown,
+  req: Request,
+  phase: 'proxy' | 'handler' | 'render' | 'action' | 'route'
+): Promise<void> {
+  const url = new URL(req.url);
+  const headersObj: Record<string, string> = {};
+  req.headers.forEach((v, k) => {
+    headersObj[k] = v;
+  });
+
+  await callOnRequestError(
+    error,
+    { method: req.method, path: url.pathname, headers: headersObj },
+    { phase, routePath: url.pathname, routeType: 'page', traceId: getTraceId() }
+  );
+}

package/src/server/pipeline-interception.ts

@@ -9,6 +9,8 @@
  * See design/07-routing.md §"Intercepting Routes"
  */
 
+import { classifyUrlSegment } from '../routing/segment-classify.js';
+
 /** Result of a successful interception match. */
 export interface InterceptionMatchResult {
   /** The pathname to re-match (the source/intercepting route's parent). */
@@ -26,7 +28,7 @@ export interface InterceptionMatchResult {
 export function findInterceptionMatch(
   targetPathname: string,
   sourceUrl: string,
-  rewrites: import('#/routing/interception.js').InterceptionRewrite[]
+  rewrites: import('../routing/interception.js').InterceptionRewrite[]
 ): InterceptionMatchResult | null {
   for (const rewrite of rewrites) {
     // Check if the source URL starts with the intercepting prefix
@@ -53,23 +55,22 @@ export function pathnameMatchesPattern(pathname: string, pattern: string): boole
 
   let pi = 0;
   for (let i = 0; i < patternParts.length; i++) {
-    const segment = patternParts[i];
-
-    // Catch-all: [...param] or [[...param]] — matches rest of URL
-    if (segment.startsWith('[...') || segment.startsWith('[[...')) {
-      return pi < pathParts.length || segment.startsWith('[[...');
-    }
+    const seg = classifyUrlSegment(patternParts[i]);
 
-    // Dynamic: [param] — matches any single segment
-    if (segment.startsWith('[') && segment.endsWith(']')) {
-      if (pi >= pathParts.length) return false;
-      pi++;
-      continue;
+    switch (seg.kind) {
+      case 'catch-all':
+        return pi < pathParts.length;
+      case 'optional-catch-all':
+        return true;
+      case 'dynamic':
+        if (pi >= pathParts.length) return false;
+        pi++;
+        continue;
+      case 'static':
+        if (pi >= pathParts.length || pathParts[pi] !== seg.value) return false;
+        pi++;
+        continue;
     }
-
-    // Static — must match exactly
-    if (pi >= pathParts.length || pathParts[pi] !== segment) return false;
-    pi++;
   }
 
   return pi === pathParts.length;

package/src/server/pipeline-metadata.ts

@@ -79,6 +79,19 @@ export function serializeSitemap(
   return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>`;
 }
 
+/**
+ * Serialize a sitemap index (list of sub-sitemap URLs) to XML.
+ * Used for pagination when the total URL count exceeds 50,000.
+ * Follows the sitemap.org protocol: https://www.sitemaps.org/protocol.html
+ */
+export function serializeSitemapIndex(sitemapUrls: string[]): string {
+  const sitemaps = sitemapUrls
+    .map((url) => `  <sitemap>\n    <loc>${escapeXml(url)}</loc>\n  </sitemap>`)
+    .join('\n');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${sitemaps}\n</sitemapindex>`;
+}
+
 /** Escape special XML characters. */
 export function escapeXml(str: string): string {
   return str

package/src/server/pipeline-outcome.ts

@@ -0,0 +1,167 @@
+/**
+ * Pipeline outcome translator — converts a `PhaseOutcome` (the value
+ * each phase function returns) into a final `Response`.
+ *
+ * Lifted out of `pipeline-phases.ts` (TIM-853) so the per-phase try /
+ * catch logic and the terminal Response-building logic each live in
+ * their own file. The phases produce values; this module is the single
+ * source of truth for how those values become wire responses.
+ *
+ * See design/07-routing.md §"Request Lifecycle".
+ */
+
+import {
+  applyCookieJar,
+  buildRedirectResponse,
+  cloneWithMutableHeaders,
+  fireOnRequestError,
+  mergeMissingHeaders,
+} from './pipeline-helpers.js';
+import {
+  logProxyError,
+  logMiddlewareError,
+  logMiddlewareShortCircuit,
+  logRenderError,
+} from './logger.js';
+import { markResponseFlushed } from './request-context.js';
+import { RedirectSignal, DenySignal } from './primitives.js';
+import type { PipelineConfig, RouteMatch } from './pipeline.js';
+
+// ─── Phase Outcome ─────────────────────────────────────────────────────────
+
+export type PhaseName = 'proxy' | 'middleware' | 'render';
+
+export type PhaseOutcome =
+  | { kind: 'response'; phase: PhaseName; response: Response }
+  | { kind: 'redirect'; phase: PhaseName; signal: RedirectSignal }
+  | { kind: 'deny'; phase: PhaseName; signal: DenySignal }
+  | { kind: 'error'; phase: PhaseName; error: unknown };
+
+export interface OutcomeContext {
+  req: Request;
+  method: string;
+  path: string;
+  responseHeaders?: Headers;
+  match?: RouteMatch;
+}
+
+// ─── Translator ────────────────────────────────────────────────────────────
+
+/**
+ * Terminal outcome handler — converts a `PhaseOutcome` into a final
+ * `Response`, applying cookies, building redirects, rendering deny pages
+ * and fallback error pages, and firing instrumentation hooks.
+ *
+ * This is the single source of truth for how phase outputs become wire
+ * responses; the per-phase try/catch blocks now produce values, not
+ * Responses, so the conversion logic lives in exactly one place.
+ */
+export async function outcomeToResponse(
+  config: PipelineConfig,
+  outcome: PhaseOutcome,
+  ctx: OutcomeContext
+): Promise<Response> {
+  switch (outcome.kind) {
+    case 'response': {
+      // Clone unconditionally so downstream code (cookie/header merge,
+      // Server-Timing in createPipeline) can write headers without paying
+      // for a try/catch immutability probe per request. User middleware,
+      // proxy, and route code may all return `Response.redirect()` or
+      // platform-level responses with frozen header bags. See TIM-866.
+      const finalResponse = cloneWithMutableHeaders(outcome.response);
+
+      if (outcome.phase === 'proxy') return finalResponse;
+
+      if (outcome.phase === 'middleware' && ctx.responseHeaders) {
+        applyCookieJar(finalResponse.headers);
+        mergeMissingHeaders(finalResponse.headers, ctx.responseHeaders);
+        logMiddlewareShortCircuit({
+          method: ctx.method,
+          path: ctx.path,
+          status: finalResponse.status,
+        });
+      }
+
+      if (outcome.phase === 'render') {
+        markResponseFlushed();
+      }
+
+      return finalResponse;
+    }
+
+    case 'redirect': {
+      const headers = ctx.responseHeaders ?? new Headers();
+      applyCookieJar(headers);
+      return buildRedirectResponse(outcome.signal, ctx.req, headers);
+    }
+
+    case 'deny': {
+      const headers = ctx.responseHeaders ?? new Headers();
+      applyCookieJar(headers);
+      if (config.renderDenyFallback) {
+        try {
+          // Clone user-supplied deny-page responses so downstream
+          // Server-Timing writes are safe against frozen header bags
+          // (e.g. user returned Response.redirect from the hook).
+          return cloneWithMutableHeaders(
+            await config.renderDenyFallback(outcome.signal, ctx.req, headers, ctx.match)
+          );
+        } catch (denyRenderError) {
+          // Deny page rendering failed — log before falling through to bare response.
+          // Without this, a crashing deny page produces a blank response with zero
+          // server-side signal. See TIM-876.
+          logRenderError({ method: ctx.method, path: ctx.path, error: denyRenderError });
+          await fireOnRequestError(denyRenderError, ctx.req, 'render');
+          if (config.onPipelineError && denyRenderError instanceof Error)
+            config.onPipelineError(denyRenderError, 'render');
+        }
+      }
+      return new Response(null, { status: outcome.signal.status, headers });
+    }
+
+    case 'error': {
+      if (outcome.phase === 'proxy') {
+        logProxyError({ error: outcome.error });
+        await fireOnRequestError(outcome.error, ctx.req, 'proxy');
+        if (config.onPipelineError && outcome.error instanceof Error)
+          config.onPipelineError(outcome.error, 'proxy');
+        return new Response(null, { status: 500 });
+      }
+
+      if (outcome.phase === 'middleware') {
+        logMiddlewareError({ method: ctx.method, path: ctx.path, error: outcome.error });
+        await fireOnRequestError(outcome.error, ctx.req, 'handler');
+        if (config.onPipelineError && outcome.error instanceof Error) {
+          config.onPipelineError(outcome.error, 'middleware');
+        }
+        return new Response(null, { status: 500 });
+      }
+
+      const headers = ctx.responseHeaders ?? new Headers();
+      applyCookieJar(headers);
+      logRenderError({ method: ctx.method, path: ctx.path, error: outcome.error });
+      await fireOnRequestError(outcome.error, ctx.req, 'render');
+      if (config.onPipelineError && outcome.error instanceof Error)
+        config.onPipelineError(outcome.error, 'render');
+      if (config.renderFallbackError) {
+        try {
+          // Clone user-supplied fallback error responses so downstream
+          // Server-Timing writes are safe against frozen header bags.
+          return cloneWithMutableHeaders(
+            await config.renderFallbackError(outcome.error, ctx.req, headers)
+          );
+        } catch (fallbackRenderError) {
+          // Fallback rendering itself failed — log the secondary error before
+          // falling through to bare 500. The original render error was already
+          // logged above; this captures the fallback renderer's own crash so it
+          // doesn't vanish silently. See TIM-876.
+          logRenderError({ method: ctx.method, path: ctx.path, error: fallbackRenderError });
+          await fireOnRequestError(fallbackRenderError, ctx.req, 'render');
+          if (config.onPipelineError && fallbackRenderError instanceof Error)
+            config.onPipelineError(fallbackRenderError, 'render');
+        }
+      }
+      return new Response(null, { status: 500 });
+    }
+  }
+}