@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/src/server/route-element-helpers.ts

@@ -0,0 +1,37 @@
+/**
+ * Pure helpers for `route-element-builder.ts` — tree inspection and rewriting
+ * that need no request state. Split out so the builder stays within the
+ * 500-line limit as its wrapping steps grew (TIM-1450).
+ */
+
+import { createElement } from 'react';
+
+import { AccessGate } from './access-gate.tsx';
+import { MetadataCollector } from './metadata-collector.ts';
+import { SegmentOutlet } from '../client/segment-outlet.tsx';
+
+/**
+ * Replace the outermost SegmentOutlet in a partial payload with its
+ * SegmentProvider child. Walks through AccessGate wrappers (which sit
+ * outside SegmentOutlet) to find the outlet.
+ */
+export function replaceOutermostSegmentOutlet(
+  element: React.ReactElement,
+  replacement: React.ReactElement
+): React.ReactElement {
+  if (element.type === SegmentOutlet) {
+    return replacement;
+  }
+  // AccessGate and MetadataCollector wrap outside SegmentOutlet — recurse through them.
+  const props = element.props as Record<string, unknown>;
+  if ((element.type === AccessGate || element.type === MetadataCollector) && props.children) {
+    const inner = replaceOutermostSegmentOutlet(props.children as React.ReactElement, replacement);
+    /* eslint-disable react/no-children-prop -- createElement API */
+    return createElement(element.type as React.FunctionComponent<Record<string, unknown>>, {
+      ...props,
+      children: inner,
+    });
+    /* eslint-enable react/no-children-prop */
+  }
+  return element;
+}

package/src/server/route-handler.ts

@@ -8,7 +8,10 @@
  * See design/07-routing.md §"route.ts — API Endpoints"
  */
 
-import type { RouteContext } from './types.js';
+import type { RouteContext } from './types.ts';
+import { logRouteError } from './logger.ts';
+import { isDenySignal, isRedirectSignal } from './primitives.ts';
+import { stripHeadBody } from './head-response.ts';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -87,18 +90,17 @@ export async function handleRouteRequest(mod: RouteModule, ctx: RouteContext): P
     });
   }
 
-  // HEAD fallback — run GET, strip body
+  // HEAD fallback — dispatch to GET when the module exports no HEAD, so the
+  // headers are the ones a GET would produce. The body is stripped by the
+  // shared helper (also applied at the pipeline exit, where it is a no-op the
+  // second time) rather than open-coded here — one implementation means the
+  // discarded stream is cancelled on every path. See TIM-1324.
   if (method === 'HEAD') {
     if (mod.HEAD) {
-      return runHandler(mod.HEAD, ctx);
+      return stripHeadBody(await runHandler(mod.HEAD, ctx), method);
     }
     if (mod.GET) {
-      const res = await runHandler(mod.GET, ctx);
-      // Return headers + status but no body
-      return new Response(null, {
-        status: res.status,
-        headers: res.headers,
-      });
+      return stripHeadBody(await runHandler(mod.GET, ctx), method);
     }
   }
 
@@ -122,7 +124,13 @@ 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);
+    // Control-flow signals — propagate to the API route dispatcher so deny()
+    // gets the JSON status-file chain and redirect() gets a proper 3xx with
+    // Location. Not errors; don't log them.
+    if (isDenySignal(error) || isRedirectSignal(error)) {
+      throw error;
+    }
+    logRouteError({ method: ctx.req.method, path: new URL(ctx.req.url).pathname, error });
     return new Response(null, { status: 500 });
   }
 }
@@ -140,10 +148,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

@@ -8,67 +8,53 @@
  * See design/07-routing.md §"Request Lifecycle"
  */
 
-import type { RouteMatch } from './pipeline.js';
-import type { MiddlewareFn } from './middleware-runner.js';
+import type { RouteMatch } from './pipeline.ts';
+import type { MiddlewareFn } from './middleware-runner.ts';
+import type { SegmentNode, RouteTree } from '../routing/types.ts';
 import {
   METADATA_ROUTE_CONVENTIONS,
   isStaticMetadataExtension,
   resolveStaticContentType,
+  resolveServePathForFile,
   type MetadataRouteType,
-} from './metadata-routes.js';
+} from './metadata-routes.ts';
+import { matchUrlParts } from './tree-match.ts';
 
 // ─── 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 +74,47 @@ 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);
-      }
-    };
-  }
+  const result = matchUrlParts(root, parts);
+  if (!result) return null;
 
   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,
+    segments: result.chain,
+    segmentParams: result.params,
+    middlewareChain: collectMiddlewareChain(result.chain),
   };
 }
 
 /**
- * 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.
+ * Collect middleware from a matched segment chain, root to leaf.
  *
- * 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]])
+ * Each entry is lazy-loaded via dynamic import on first invocation.
  *
- * 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).
+ * Shared with the children-path interception resolver
+ * (`children-interception.ts`), which assembles a chain from the tree rather
+ * than from a pathname but produces the same kind of `RouteMatch` — every
+ * `middleware.ts` above an intercepted page must run exactly as it does for
+ * the canonical route.
  */
-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;
+export function collectMiddlewareChain(chain: ManifestSegmentNode[]): MiddlewareFn[] {
+  const middlewareChain: MiddlewareFn[] = [];
+  for (const segment of 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 middlewareChain;
 }
 
 // ─── Metadata Route Matcher ─────────────────────────────────────────────
@@ -302,73 +134,134 @@ export interface MetadataRouteMatch {
    * that should be served from disk rather than executed as a handler.
    */
   isStatic: boolean;
+  /** Extracted segment params from dynamic segments in the URL prefix. */
+  segmentParams: Record<string, string | string[]>;
+}
+
+// Reverse lookup: serve path (with extension) → convention base name
+const SERVE_PATH_TO_CONVENTION = new Map<string, string>();
+for (const [baseName, convention] of Object.entries(METADATA_ROUTE_CONVENTIONS)) {
+  if (convention.serveExtension) {
+    for (const ext of [...convention.staticExtensions, convention.serveExtension]) {
+      SERVE_PATH_TO_CONVENTION.set(`${convention.servePath}.${ext}`, baseName);
+    }
+  } else {
+    SERVE_PATH_TO_CONVENTION.set(convention.servePath, baseName);
+  }
 }
 
 /**
  * Create a metadata route matcher from a manifest.
  *
- * Walks the segment tree and builds a map from serve paths to handler modules.
- * Metadata routes are matched by exact pathname (e.g., /sitemap.xml, /blog/sitemap.xml).
+ * Uses dynamic tree matching to resolve metadata routes, supporting
+ * dynamic segments like /docs/[slug]/opengraph-image.
  *
  * See design/16-metadata.md §"Metadata Routes"
  */
 export function createMetadataRouteMatcher(
   manifest: ManifestRoot
 ): (pathname: string) => MetadataRouteMatch | null {
-  // Build a static lookup map: pathname → match info
-  const routeMap = new Map<string, MetadataRouteMatch>();
-  collectMetadataRoutes(manifest.root, routeMap);
-
-  return (pathname: string) => routeMap.get(pathname) ?? null;
+  return (pathname: string) => matchMetadataPathname(manifest.root, pathname);
 }
 
 /**
- * Recursively collect metadata routes from the segment tree into a lookup map.
+ * Match a pathname against metadata routes in the segment tree.
+ *
+ * Checks if the last URL part is a known metadata route serve path,
+ * then walks the tree to find the segment that owns the route.
  */
-function collectMetadataRoutes(
-  node: ManifestSegmentNode,
-  map: Map<string, MetadataRouteMatch>
-): void {
-  if (node.metadataRoutes) {
-    for (const [baseName, file] of Object.entries(node.metadataRoutes)) {
-      const convention = METADATA_ROUTE_CONVENTIONS[baseName];
-      if (!convention) continue;
+function matchMetadataPathname(
+  root: ManifestSegmentNode,
+  pathname: string
+): MetadataRouteMatch | null {
+  const parts = pathname === '/' ? [] : pathname.slice(1).split('/');
+  if (parts.length === 0) return null;
+
+  const lastPart = parts[parts.length - 1];
+  const baseName = SERVE_PATH_TO_CONVENTION.get(lastPart);
+  if (!baseName) return null;
+
+  const convention = METADATA_ROUTE_CONVENTIONS[baseName];
+  if (!convention) return null;
+
+  // The prefix parts identify which segment owns this metadata route.
+  // For root-level routes (e.g. /sitemap.xml), prefix is empty → root segment.
+  const prefixParts = parts.slice(0, -1);
+
+  let segment: ManifestSegmentNode;
+  let params: Record<string, string | string[]>;
+
+  if (prefixParts.length === 0) {
+    segment = root;
+    params = {};
+  } else {
+    const result = matchUrlParts(root, prefixParts, { requireTerminal: false });
+    if (!result) return null;
+    segment = result.chain[result.chain.length - 1];
+    params = result.params;
+  }
 
-      // Non-nestable routes (robots, manifest, favicon) only serve from root
-      if (!convention.nestable && node.urlPath !== '/') continue;
+  // Non-nestable routes (robots, manifest, favicon) only serve from root
+  if (!convention.nestable && segment !== root) return null;
 
-      // Build the serve pathname: segment urlPath + serve path
-      const prefix = node.urlPath === '/' ? '' : node.urlPath;
-      const pathname = `${prefix}/${convention.servePath}`;
+  const file = findMetadataRouteInSegment(segment, baseName, convention.nestable);
+  if (!file) return null;
 
-      // 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);
+  // Validate the requested URL extension matches the file's resolved serve path.
+  // Prevents /icon.svg matching when only icon.png exists.
+  if (convention.serveExtension) {
+    const resolvedServePath = resolveServePathForFile(baseName, file.filePath);
+    if (lastPart !== resolvedServePath) return null;
+  }
 
-      // 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;
+  const ext = file.filePath.slice(file.filePath.lastIndexOf('.') + 1);
+  const isStatic = isStaticMetadataExtension(baseName, ext);
+  const contentType = isStatic
+    ? resolveStaticContentType(convention.contentType, ext)
+    : convention.contentType;
 
-      map.set(pathname, {
-        type: convention.type,
-        contentType,
-        file,
-        segment: node,
-        isStatic,
-      });
-    }
-  }
+  return {
+    type: convention.type,
+    contentType,
+    file,
+    segment,
+    isStatic,
+    segmentParams: params,
+  };
+}
 
-  for (const child of node.children) {
-    collectMetadataRoutes(child, map);
+/**
+ * Find a metadata route file in a segment, including children that match
+ * zero URL segments at the segment's own path:
+ *
+ * - Group children are transparent — they don't add URL depth.
+ * - Optional catch-all children ([[...slug]]) match zero segments, so
+ *   `app/docs/[[...path]]/icon.tsx` serves `/docs/icon`. The non-zero
+ *   case is handled by the tree walker (requireTerminal:false), but the
+ *   zero-segment case never reaches the walker — the parent node accepts
+ *   the fully-consumed prefix first, so the fallback lives here.
+ *
+ * Optional catch-all descent applies to NESTABLE conventions only. A
+ * non-nestable file (robots, manifest, favicon) inside `[[...slug]]` is
+ * not at the root — serving it there would bypass the root-only rule.
+ * Group descent is unconditional: groups are transparent and a group
+ * child of the root IS at the root.
+ *
+ * The segment's own metadata file wins over a zero-segment child's.
+ */
+function findMetadataRouteInSegment(
+  node: ManifestSegmentNode,
+  baseName: string,
+  nestable: boolean
+): ManifestFile | null {
+  if (node.metadataRoutes?.[baseName]) {
+    return node.metadataRoutes[baseName];
   }
-
-  // Also check inside group segments (they're transparent for URL paths)
-  for (const slotNode of Object.values(node.slots)) {
-    collectMetadataRoutes(slotNode, map);
+  for (const child of node.children) {
+    if (child.segmentType === 'group' || (nestable && child.segmentType === 'optional-catch-all')) {
+      const found = findMetadataRouteInSegment(child, baseName, nestable);
+      if (found) return found;
+    }
   }
+  return null;
 }