@timber-js/app 0.2.0-alpha.12 → 0.2.0-alpha.121

package/src/server/route-handler.ts

@@ -9,6 +9,7 @@
  */
 
 import type { RouteContext } from './types.js';
+import { logRouteError } from './logger.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -122,7 +123,7 @@ async function runHandler(handler: RouteHandler, ctx: RouteContext): Promise<Res
     const res = await handler(ctx);
     return mergeResponseHeaders(res, ctx.headers);
   } catch (error) {
-    console.error('[timber] Uncaught error in route.ts handler:', error);
+    logRouteError({ method: ctx.req.method, path: new URL(ctx.req.url).pathname, error });
     return new Response(null, { status: 500 });
   }
 }
@@ -140,10 +141,29 @@ function mergeResponseHeaders(res: Response, ctxHeaders: Headers): Response {
   });
   if (!hasCtxHeaders) return res;
 
-  // Merge: ctx.headers first, then handler response headers override
+  // Merge: ctx.headers first, then handler response headers override.
+  // Set-Cookie needs special handling: Headers.set() replaces all values
+  // for a key, but each Set-Cookie must be its own header per RFC 6265 §4.1.
+  // Use append for Set-Cookie, set for everything else.
   const merged = new Headers();
-  ctxHeaders.forEach((value, key) => merged.set(key, value));
-  res.headers.forEach((value, key) => merged.set(key, value));
+  ctxHeaders.forEach((value, key) => {
+    if (key.toLowerCase() === 'set-cookie') {
+      merged.append(key, value);
+    } else {
+      merged.set(key, value);
+    }
+  });
+  // Response Set-Cookie headers: use getSetCookie() to preserve individual
+  // cookies (forEach joins them with ", " into one entry).
+  const resCookies = res.headers.getSetCookie();
+  for (const cookie of resCookies) {
+    merged.append('Set-Cookie', cookie);
+  }
+  res.headers.forEach((value, key) => {
+    if (key.toLowerCase() !== 'set-cookie') {
+      merged.set(key, value);
+    }
+  });
 
   return new Response(res.body, {
     status: res.status,

package/src/server/route-matcher.ts

@@ -10,65 +10,50 @@
 
 import type { RouteMatch } from './pipeline.js';
 import type { MiddlewareFn } from './middleware-runner.js';
+import type { SegmentNode, RouteTree } from '../routing/types.js';
 import {
   METADATA_ROUTE_CONVENTIONS,
   isStaticMetadataExtension,
   resolveStaticContentType,
   type MetadataRouteType,
 } from './metadata-routes.js';
+import { matchUrlParts } from './tree-match.js';
 
 // ─── Manifest Types ───────────────────────────────────────────────────────
-// The virtual module manifest has a slightly different shape than SegmentNode:
-// file references are { load, filePath } instead of RouteFile.
+//
+// TIM-848: the runtime route manifest re-uses the same `SegmentNode<TFile>`
+// / `RouteTree<TFile>` interfaces from `routing/types.ts`. The only
+// difference between build-time and runtime is the file reference payload
+// — build-time has `{ filePath, extension }`, runtime has `{ filePath, load }`.
+// Walkers parameterized over `TFile` work on either; there is no separate
+// "manifest" tree shape.
 
 /** A file reference in the manifest (lazy import + path). */
-interface ManifestFile {
+export interface ManifestFile {
   load: () => Promise<unknown>;
   filePath: string;
 }
 
-/** A segment node as it appears in the virtual:timber-route-manifest module. */
-export interface ManifestSegmentNode {
-  segmentName: string;
-  segmentType:
-    | 'static'
-    | 'dynamic'
-    | 'catch-all'
-    | 'optional-catch-all'
-    | 'group'
-    | 'slot'
-    | 'intercepting';
-  urlPath: string;
-  paramName?: string;
-  /** For intercepting segments: the marker used, e.g. "(.)". */
-  interceptionMarker?: '(.)' | '(..)' | '(...)' | '(..)(..)';
-  /** For intercepting segments: the segment name after stripping the marker. */
-  interceptedSegmentName?: string;
-
-  page?: ManifestFile;
-  layout?: ManifestFile;
-  middleware?: ManifestFile;
-  access?: ManifestFile;
-  route?: ManifestFile;
-  error?: ManifestFile;
-  default?: ManifestFile;
-  denied?: ManifestFile;
-  searchParams?: ManifestFile;
-  statusFiles?: Record<string, ManifestFile>;
-  jsonStatusFiles?: Record<string, ManifestFile>;
-  legacyStatusFiles?: Record<string, ManifestFile>;
-  prerender?: ManifestFile;
-  /** Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.) keyed by base name */
-  metadataRoutes?: Record<string, ManifestFile>;
-
-  children: ManifestSegmentNode[];
-  slots: Record<string, ManifestSegmentNode>;
-}
+/**
+ * A segment node as it appears in the virtual:timber-route-manifest module.
+ *
+ * Type alias for `SegmentNode<ManifestFile>` — the same shape used by the
+ * scanner, only with lazy `load` functions instead of build-time extension
+ * metadata.
+ */
+export type ManifestSegmentNode = SegmentNode<ManifestFile>;
 
-/** The manifest shape from virtual:timber-route-manifest. */
-export interface ManifestRoot {
-  root: ManifestSegmentNode;
-  proxy?: ManifestFile;
+/**
+ * The manifest shape from virtual:timber-route-manifest.
+ *
+ * Extends `RouteTree<ManifestFile>` with `viteRoot`, the absolute path
+ * to the Vite project root captured at build/load time. Used by dev-only
+ * features (e.g., dev error page frame classification) that need a
+ * correct project root even when CWD differs (e.g., monorepo custom root).
+ * See TIM-807 / TIM-808.
+ */
+export interface ManifestRoot extends RouteTree<ManifestFile> {
+  viteRoot: string;
 }
 
 // ─── Matcher ──────────────────────────────────────────────────────────────
@@ -88,201 +73,35 @@ export function createRouteMatcher(
 /**
  * Match a canonical pathname against the segment tree.
  *
- * Splits the pathname into segments and walks the tree depth-first.
- * Returns the segment chain and extracted params on match.
+ * Splits the pathname into segments and delegates to the shared
+ * tree walker. Collects middleware from the matched segment chain.
  */
 function matchPathname(root: ManifestSegmentNode, pathname: string): RouteMatch | null {
-  // Split pathname into segments: "/blog/hello-world" → ["blog", "hello-world"]
-  // "/" → [] (empty segments)
   const parts = pathname === '/' ? [] : pathname.slice(1).split('/');
 
-  const segments: ManifestSegmentNode[] = [];
-  const params: Record<string, string | string[]> = {};
-
-  const matched = matchSegments(root, parts, 0, segments, params);
-  if (!matched) return null;
-
-  // Convert ManifestSegmentNodes to the SegmentNode shape expected by RouteMatch.
-  // The pipeline and tree builder use SegmentNode which has RouteFile references,
-  // but we pass the manifest nodes directly — they're structurally compatible
-  // for the fields the pipeline cares about (segments array + params).
-  // Resolve the leaf segment's middleware.ts if present.
-  // Only the leaf route's middleware runs — no chain, no inheritance.
-  const leafSegment = segments[segments.length - 1];
-  let middleware: MiddlewareFn | undefined;
-  if (leafSegment?.middleware) {
-    const loader = leafSegment.middleware.load;
-    middleware = async (ctx) => {
-      const mod = (await loader()) as { default?: MiddlewareFn };
-      if (mod.default) {
-        return mod.default(ctx);
-      }
-    };
-  }
-
-  return {
-    // The pipeline uses segments as opaque objects passed to the renderer.
-    // Cast is safe — the renderer receives what the manifest provides.
-    segments: segments as unknown as RouteMatch['segments'],
-    params,
-    middleware,
-  };
-}
-
-/**
- * An effective child flattened through group segments.
- * Includes the chain of group nodes that must be added to the segments
- * array before the child itself (to preserve the group → child nesting
- * that the renderer expects).
- */
-interface EffectiveChild {
-  child: ManifestSegmentNode;
-  groupChain: ManifestSegmentNode[];
-}
-
-/**
- * Collect effective children by flattening through group segments.
- *
- * Groups are transparent for URL matching — their non-group descendants
- * are returned with the chain of group nodes that lead to them. This
- * allows the caller to apply priority ordering (static > dynamic > ...)
- * across all groups uniformly instead of per-group.
- */
-function collectEffectiveChildren(
-  node: ManifestSegmentNode,
-  groupChain: ManifestSegmentNode[] = []
-): EffectiveChild[] {
-  const result: EffectiveChild[] = [];
-  for (const child of node.children) {
-    if (child.segmentType === 'group') {
-      // Look through the group — its children become effective children
-      // with this group prepended to their chain
-      const nested = collectEffectiveChildren(child, [...groupChain, child]);
-      result.push(...nested);
-    } else {
-      result.push({ child, groupChain });
-    }
-  }
-  return result;
-}
-
-/**
- * Recursively match URL segments against the segment tree.
- *
- * Priority order for children at each level:
- *   1. Static segments (exact match)
- *   2. Dynamic segments ([param])
- *   3. Catch-all segments ([...param])
- *   4. Optional catch-all segments ([[...param]])
- *
- * Groups are transparent — they don't consume URL segments. Children
- * are flattened through groups so that priority ordering applies across
- * all groups uniformly (a static in group A always beats a dynamic in
- * group B, regardless of group ordering).
- */
-function matchSegments(
-  node: ManifestSegmentNode,
-  parts: string[],
-  index: number,
-  segments: ManifestSegmentNode[],
-  params: Record<string, string | string[]>
-): boolean {
-  segments.push(node);
-
-  // All parts consumed — check if this node has a page or route
-  if (index >= parts.length) {
-    if (node.page || node.route) {
-      return true;
-    }
-
-    // Check group children (they don't consume URL segments)
-    for (const child of node.children) {
-      if (child.segmentType === 'group') {
-        if (matchSegments(child, parts, index, segments, params)) {
-          return true;
+  const result = matchUrlParts(root, parts);
+  if (!result) return null;
+
+  // Collect middleware from all segments in the chain, root to leaf.
+  // Each middleware is lazy-loaded via dynamic import on first invocation.
+  const middlewareChain: MiddlewareFn[] = [];
+  for (const segment of result.chain) {
+    if (segment.middleware) {
+      const loader = segment.middleware.load;
+      middlewareChain.push(async (ctx) => {
+        const mod = (await loader()) as { default?: MiddlewareFn };
+        if (mod.default) {
+          return mod.default(ctx);
         }
-      }
-    }
-
-    // Check optional catch-all children (direct and through groups)
-    const effective = collectEffectiveChildren(node);
-    for (const { child, groupChain } of effective) {
-      if (child.segmentType === 'optional-catch-all') {
-        if (child.page || child.route) {
-          segments.push(...groupChain, child);
-          // Zero segments → param is undefined (not set), matching Next.js semantics
-          return true;
-        }
-      }
-    }
-
-    segments.pop();
-    return false;
-  }
-
-  const part = parts[index];
-
-  // Flatten children through groups so priority ordering applies globally
-  // across all groups, not per-group.
-  const effective = collectEffectiveChildren(node);
-
-  // 1. Static segments
-  for (const { child, groupChain } of effective) {
-    if (child.segmentType === 'static' && child.segmentName === part) {
-      segments.push(...groupChain);
-      if (matchSegments(child, parts, index + 1, segments, params)) {
-        return true;
-      }
-      // Backtrack group chain
-      segments.length -= groupChain.length;
-    }
-  }
-
-  // 2. Dynamic segments ([param])
-  for (const { child, groupChain } of effective) {
-    if (child.segmentType === 'dynamic' && child.paramName) {
-      segments.push(...groupChain);
-      const prevParam = params[child.paramName];
-      params[child.paramName] = part;
-      if (matchSegments(child, parts, index + 1, segments, params)) {
-        return true;
-      }
-      // Backtrack
-      segments.length -= groupChain.length;
-      if (prevParam !== undefined) {
-        params[child.paramName] = prevParam;
-      } else {
-        delete params[child.paramName];
-      }
-    }
-  }
-
-  // 3. Catch-all segments ([...param])
-  for (const { child, groupChain } of effective) {
-    if (child.segmentType === 'catch-all' && child.paramName) {
-      if (child.page || child.route) {
-        const remaining = parts.slice(index);
-        segments.push(...groupChain, child);
-        params[child.paramName] = remaining;
-        return true;
-      }
-    }
-  }
-
-  // 4. Optional catch-all segments ([[...param]])
-  for (const { child, groupChain } of effective) {
-    if (child.segmentType === 'optional-catch-all' && child.paramName) {
-      if (child.page || child.route) {
-        const remaining = parts.slice(index);
-        segments.push(...groupChain, child);
-        params[child.paramName] = remaining;
-        return true;
-      }
+      });
     }
   }
 
-  segments.pop();
-  return false;
+  return {
+    segments: result.chain,
+    segmentParams: result.params,
+    middlewareChain,
+  };
 }
 
 // ─── Metadata Route Matcher ─────────────────────────────────────────────

package/src/server/rsc-entry/action-middleware-runner.ts

@@ -0,0 +1,167 @@
+/**
+ * Middleware-on-actions runner — runs the matched route's `middleware.ts`
+ * chain for an action POST inside its own `runWithRequestContext` scope
+ * and returns a `MiddlewareOutcome` value the dispatcher can translate.
+ *
+ * Lifted out of `wrap-action-dispatch.ts` (TIM-853) so the dispatcher
+ * can be read top-to-bottom without scrolling past the chain runner. The
+ * function is intentionally a free function (not a closure over deps)
+ * so it can be unit-tested in isolation. It does not import virtual
+ * modules and does not call into the action handler — it owns exactly
+ * the "run middleware once" step and nothing else.
+ *
+ * Failure modes are encoded as outcome variants rather than thrown so the
+ * caller never has to wrap this in try/catch. The only thrown errors are
+ * truly unexpected (programmer bugs) and propagate naturally.
+ *
+ * See TIM-871 for the full design rationale (closing the
+ * CVE-2025-29927-class bug where actions silently bypass middleware).
+ */
+
+import { getCookiesForSsr, getSetCookieHeaders } from '../cookie-context.js';
+import {
+  applyRequestHeaderOverlay,
+  runWithRequestContext,
+  setMutableCookieContext,
+  setSegmentParams,
+} from '../request-context.js';
+import { runMiddlewareChain } from '../middleware-runner.js';
+import { DenySignal, RedirectSignal } from '../primitives.js';
+import { ParamCoercionError } from '../route-element-builder.js';
+import type { RouteMatch } from '../pipeline.js';
+import type { MiddlewareContext } from '../types.js';
+
+/** Coerce a matched route's segment params via its `params.ts` codecs. */
+export type CoerceSegmentParamsFn = (match: RouteMatch) => Promise<void>;
+
+/**
+ * Outcome of running middleware on an action request, surfaced from the
+ * inner `runWithRequestContext` scope so the outer dispatcher can convert
+ * it to a Response (short-circuit) or continue to the action handler.
+ *
+ * Each variant carries the post-middleware Set-Cookie snapshot so the
+ * outer scope can apply cookies to whichever Response it ultimately
+ * returns. The middleware ALS scope ends before the action ALS scope
+ * begins, so cookie state must be threaded explicitly across the boundary
+ * via `seedRequestCookies` (cookie reads) and `setCookieHeaders` (cookie
+ * writes).
+ */
+export type MiddlewareOutcome =
+  | {
+      kind: 'continue';
+      overlay: Headers;
+      cookies: Map<string, string>;
+      setCookieHeaders: string[];
+    }
+  | {
+      kind: 'short-circuit';
+      response: Response;
+      setCookieHeaders: string[];
+    }
+  | {
+      kind: 'redirect';
+      signal: RedirectSignal;
+      setCookieHeaders: string[];
+    }
+  | {
+      kind: 'deny';
+      signal: DenySignal;
+      match: RouteMatch;
+      setCookieHeaders: string[];
+    }
+  | {
+      kind: 'param-coercion-error';
+    }
+  | {
+      kind: 'error';
+      error: unknown;
+    };
+
+/**
+ * Run the matched route's middleware chain inside a fresh request-context
+ * scope, captured as a `MiddlewareOutcome` value the outer dispatcher can
+ * translate to a Response or use as the seed for the action handler.
+ */
+export async function runMiddlewareForAction(
+  req: Request,
+  match: RouteMatch,
+  coerceSegmentParams: CoerceSegmentParamsFn
+): Promise<MiddlewareOutcome> {
+  return runWithRequestContext(req, async (): Promise<MiddlewareOutcome> => {
+    // ─── Coerce segment params (mirrors page pipeline) ──────────────
+    try {
+      await coerceSegmentParams(match);
+    } catch (err) {
+      if (err instanceof ParamCoercionError) {
+        return { kind: 'param-coercion-error' };
+      }
+      return { kind: 'error', error: err };
+    }
+    setSegmentParams(match.segmentParams);
+
+    // ─── Build the middleware context ───────────────────────────────
+    const responseHeaders = new Headers();
+    const requestHeaderOverlay = new Headers();
+    const ctx: MiddlewareContext = {
+      req,
+      requestHeaders: requestHeaderOverlay,
+      headers: responseHeaders,
+      segmentParams: match.segmentParams,
+      // 103 Early Hints are a page-render concern — server actions are
+      // RPC and never produce HTML, so there is nothing to hint about.
+      // Provide a no-op so user middleware can call `ctx.earlyHints()`
+      // unconditionally without branching on request kind.
+      earlyHints: () => {},
+    };
+
+    // ─── Run the chain ──────────────────────────────────────────────
+    setMutableCookieContext(true);
+    try {
+      let middlewareResponse: Response | undefined;
+      try {
+        middlewareResponse = await runMiddlewareChain(match.middlewareChain, ctx);
+      } catch (err) {
+        if (err instanceof RedirectSignal) {
+          return {
+            kind: 'redirect',
+            signal: err,
+            setCookieHeaders: getSetCookieHeaders(),
+          };
+        }
+        if (err instanceof DenySignal) {
+          return {
+            kind: 'deny',
+            signal: err,
+            match,
+            setCookieHeaders: getSetCookieHeaders(),
+          };
+        }
+        return { kind: 'error', error: err };
+      }
+
+      if (middlewareResponse) {
+        return {
+          kind: 'short-circuit',
+          response: middlewareResponse,
+          setCookieHeaders: getSetCookieHeaders(),
+        };
+      }
+
+      // Middleware passed — apply the request-header overlay to the
+      // current scope so any code that might still read it within
+      // this scope sees the merged view. The overlay is also captured
+      // in the outcome so the caller can re-apply it inside the
+      // action's request-context scope (which is a separate ALS run).
+      applyRequestHeaderOverlay(requestHeaderOverlay);
+
+      return {
+        kind: 'continue',
+        overlay: requestHeaderOverlay,
+        cookies: getCookiesForSsr(),
+        setCookieHeaders: getSetCookieHeaders(),
+      };
+    } finally {
+      setMutableCookieContext(false);
+    }
+  });
+}

package/src/server/rsc-entry/api-handler.ts

@@ -6,13 +6,14 @@
  * See design/04-authorization.md §"Auth in API Routes".
  */
 
-import { withSpan, setSpanAttribute } from '#/server/tracing.js';
-import type { ManifestSegmentNode } from '#/server/route-matcher.js';
-import type { RouteMatch } from '#/server/pipeline.js';
-import { DenySignal, RedirectSignal } from '#/server/primitives.js';
-import { handleRouteRequest } from '#/server/route-handler.js';
-import type { RouteModule } from '#/server/route-handler.js';
-import type { RouteContext } from '#/server/types.js';
+import { withSpan, setSpanAttribute } from '../tracing.js';
+import type { ManifestSegmentNode } from '../route-matcher.js';
+import { loadModule } from '../safe-load.js';
+import type { RouteMatch } from '../pipeline.js';
+import { DenySignal, RedirectSignal } from '../primitives.js';
+import { handleRouteRequest } from '../route-handler.js';
+import type { RouteModule } from '../route-handler.js';
+import type { RouteContext } from '../types.js';
 
 export async function handleApiRoute(
   req: Request,
@@ -26,10 +27,8 @@ export async function handleApiRoute(
   // Each access.ts is independent — deny()/redirect() throws a signal.
   for (const segment of segments) {
     if (segment.access) {
-      const accessMod = (await segment.access.load()) as Record<string, unknown>;
-      const accessFn = accessMod.default as
-        | ((ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown)
-        | undefined;
+      const accessMod = await loadModule(segment.access);
+      const accessFn = accessMod.default as (() => unknown) | undefined;
       if (accessFn) {
         try {
           await withSpan(
@@ -37,7 +36,7 @@ export async function handleApiRoute(
             { 'timber.segment': segment.segmentName ?? 'unknown' },
             async () => {
               try {
-                await accessFn({ params: match.params, searchParams: {} });
+                await accessFn();
                 await setSpanAttribute('timber.result', 'pass');
               } catch (error) {
                 if (error instanceof DenySignal) {
@@ -68,10 +67,10 @@ export async function handleApiRoute(
   }
 
   // Load route.ts module and dispatch
-  const routeMod = (await leaf.route!.load()) as RouteModule;
+  const routeMod = await loadModule<RouteModule>(leaf.route!);
   const ctx: RouteContext = {
     req,
-    params: match.params,
+    params: match.segmentParams,
     searchParams: new URL(req.url).searchParams,
     headers: responseHeaders,
   };
@@ -90,11 +89,11 @@ async function renderApiDeny(
   segments: ManifestSegmentNode[],
   responseHeaders: Headers
 ): Promise<Response> {
-  const { resolveManifestStatusFile } = await import('#/server/manifest-status-resolver.js');
+  const { resolveStatusFile } = await import('../status-code-resolver.js');
 
-  const resolution = resolveManifestStatusFile(deny.status, segments, 'json');
+  const resolution = resolveStatusFile(deny.status, segments, 'json');
   if (resolution) {
-    const mod = (await resolution.file.load()) as Record<string, unknown>;
+    const mod = await loadModule(resolution.file);
     const jsonContent = mod.default ?? mod;
     responseHeaders.set('content-type', 'application/json; charset=utf-8');
     return new Response(JSON.stringify(jsonContent), {