@timber-js/app 0.1.0 → 0.1.2

package/src/server/route-matcher.ts

@@ -0,0 +1,316 @@
+/**
+ * Route matcher — resolves a canonical pathname to a RouteMatch.
+ *
+ * Walks the manifest segment tree to find the best matching route.
+ * Priority: static > dynamic > catch-all > optional-catch-all.
+ * Groups are transparent (don't add URL depth).
+ *
+ * See design/07-routing.md §"Request Lifecycle"
+ */
+
+import type { RouteMatch } from './pipeline.js';
+import type { MiddlewareFn } from './middleware-runner.js';
+import {
+  METADATA_ROUTE_CONVENTIONS,
+  type MetadataRouteType,
+} from './metadata-routes.js';
+
+// ─── Manifest Types ───────────────────────────────────────────────────────
+// The virtual module manifest has a slightly different shape than SegmentNode:
+// file references are { load, filePath } instead of RouteFile.
+
+/** A file reference in the manifest (lazy import + path). */
+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>;
+}
+
+/** The manifest shape from virtual:timber-route-manifest. */
+export interface ManifestRoot {
+  root: ManifestSegmentNode;
+  proxy?: ManifestFile;
+}
+
+// ─── Matcher ──────────────────────────────────────────────────────────────
+
+/**
+ * Create a route matcher function from a manifest.
+ *
+ * The returned function takes a canonical pathname and returns a RouteMatch
+ * or null if no route matches.
+ */
+export function createRouteMatcher(
+  manifest: ManifestRoot
+): (pathname: string) => RouteMatch | null {
+  return (pathname: string) => matchPathname(manifest.root, pathname);
+}
+
+/**
+ * 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.
+ */
+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,
+  };
+}
+
+/**
+ * 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 but their
+ * children are checked as if they were direct children of the parent.
+ */
+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;
+        }
+      }
+    }
+
+    // Check optional catch-all children (they can match zero segments)
+    for (const child of node.children) {
+      if (child.segmentType === 'optional-catch-all') {
+        if (child.page || child.route) {
+          segments.push(child);
+          // Zero segments → param is undefined (not set), matching Next.js semantics
+          return true;
+        }
+      }
+    }
+
+    segments.pop();
+    return false;
+  }
+
+  const part = parts[index];
+
+  // Try children in priority order
+
+  // 1. Static segments
+  for (const child of node.children) {
+    if (child.segmentType === 'static' && child.segmentName === part) {
+      if (matchSegments(child, parts, index + 1, segments, params)) {
+        return true;
+      }
+    }
+  }
+
+  // 2. Group segments (transparent — recurse without consuming)
+  for (const child of node.children) {
+    if (child.segmentType === 'group') {
+      if (matchSegments(child, parts, index, segments, params)) {
+        return true;
+      }
+    }
+  }
+
+  // 3. Dynamic segments ([param])
+  for (const child of node.children) {
+    if (child.segmentType === 'dynamic' && child.paramName) {
+      const prevParam = params[child.paramName];
+      params[child.paramName] = part;
+      if (matchSegments(child, parts, index + 1, segments, params)) {
+        return true;
+      }
+      // Backtrack
+      if (prevParam !== undefined) {
+        params[child.paramName] = prevParam;
+      } else {
+        delete params[child.paramName];
+      }
+    }
+  }
+
+  // 4. Catch-all segments ([...param])
+  for (const child of node.children) {
+    if (child.segmentType === 'catch-all' && child.paramName) {
+      if (child.page || child.route) {
+        const remaining = parts.slice(index);
+        segments.push(child);
+        params[child.paramName] = remaining;
+        return true;
+      }
+    }
+  }
+
+  // 5. Optional catch-all segments ([[...param]])
+  for (const child of node.children) {
+    if (child.segmentType === 'optional-catch-all' && child.paramName) {
+      if (child.page || child.route) {
+        const remaining = parts.slice(index);
+        segments.push(child);
+        params[child.paramName] = remaining;
+        return true;
+      }
+    }
+  }
+
+  segments.pop();
+  return false;
+}
+
+// ─── Metadata Route Matcher ─────────────────────────────────────────────
+
+/** Result of matching a metadata route. */
+export interface MetadataRouteMatch {
+  /** The metadata route type (sitemap, robots, icon, etc.) */
+  type: MetadataRouteType;
+  /** Content-Type header for the response. */
+  contentType: string;
+  /** The manifest file reference for the handler module. */
+  file: ManifestFile;
+  /** The matched segment (for context/params if needed). */
+  segment: ManifestSegmentNode;
+}
+
+/**
+ * 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).
+ *
+ * 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;
+}
+
+/**
+ * Recursively collect metadata routes from the segment tree into a lookup map.
+ */
+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;
+
+      // Non-nestable routes (robots, manifest, favicon) only serve from root
+      if (!convention.nestable && node.urlPath !== '/') continue;
+
+      // Build the serve pathname: segment urlPath + serve path
+      const prefix = node.urlPath === '/' ? '' : node.urlPath;
+      const pathname = `${prefix}/${convention.servePath}`;
+
+      map.set(pathname, {
+        type: convention.type,
+        contentType: convention.contentType,
+        file,
+        segment: node,
+      });
+    }
+  }
+
+  for (const child of node.children) {
+    collectMetadataRoutes(child, map);
+  }
+
+  // Also check inside group segments (they're transparent for URL paths)
+  for (const slotNode of Object.values(node.slots)) {
+    collectMetadataRoutes(slotNode, map);
+  }
+}

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

@@ -0,0 +1,112 @@
+/**
+ * RSC API Route Handler — handles route.ts requests (non-React).
+ *
+ * Runs access.ts standalone for all segments in the chain (no React render
+ * pass, no AccessGate component). Then dispatches to the route handler.
+ * 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';
+
+export async function handleApiRoute(
+  req: Request,
+  match: RouteMatch,
+  segments: ManifestSegmentNode[],
+  responseHeaders: Headers
+): Promise<Response> {
+  const leaf = segments[segments.length - 1];
+
+  // Run access.ts for every segment in the chain, top-down.
+  // 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;
+      if (accessFn) {
+        try {
+          await withSpan(
+            'timber.access',
+            { 'timber.segment': segment.segmentName ?? 'unknown' },
+            async () => {
+              try {
+                await accessFn({ params: match.params, searchParams: {} });
+                await setSpanAttribute('timber.result', 'pass');
+              } catch (error) {
+                if (error instanceof DenySignal) {
+                  await setSpanAttribute('timber.result', 'deny');
+                  await setSpanAttribute('timber.deny_status', error.status);
+                  if (error.sourceFile) {
+                    await setSpanAttribute('timber.deny_file', error.sourceFile);
+                  }
+                } else if (error instanceof RedirectSignal) {
+                  await setSpanAttribute('timber.result', 'redirect');
+                }
+                throw error;
+              }
+            }
+          );
+        } catch (error) {
+          if (error instanceof DenySignal) {
+            return renderApiDeny(error, segments, responseHeaders);
+          }
+          if (error instanceof RedirectSignal) {
+            responseHeaders.set('Location', error.location);
+            return new Response(null, { status: error.status, headers: responseHeaders });
+          }
+          throw error;
+        }
+      }
+    }
+  }
+
+  // Load route.ts module and dispatch
+  const routeMod = (await leaf.route!.load()) as RouteModule;
+  const ctx: RouteContext = {
+    req,
+    params: match.params,
+    searchParams: new URL(req.url).searchParams,
+    headers: responseHeaders,
+  };
+  return handleRouteRequest(routeMod, ctx);
+}
+
+/**
+ * Render a deny response for an API route (route.ts).
+ *
+ * Tries JSON status file chain first. Falls back to bare JSON response.
+ * Never renders a component — API consumers get structured JSON, not HTML.
+ * See design/10-error-handling.md §"Format Selection for deny()"
+ */
+async function renderApiDeny(
+  deny: DenySignal,
+  segments: ManifestSegmentNode[],
+  responseHeaders: Headers
+): Promise<Response> {
+  const { resolveManifestStatusFile } = await import('#/server/manifest-status-resolver.js');
+
+  const resolution = resolveManifestStatusFile(deny.status, segments, 'json');
+  if (resolution) {
+    const mod = (await resolution.file.load()) as Record<string, unknown>;
+    const jsonContent = mod.default ?? mod;
+    responseHeaders.set('content-type', 'application/json; charset=utf-8');
+    return new Response(JSON.stringify(jsonContent), {
+      status: deny.status,
+      headers: responseHeaders,
+    });
+  }
+
+  // No JSON status file — bare JSON fallback
+  responseHeaders.set('content-type', 'application/json; charset=utf-8');
+  return new Response(JSON.stringify({ error: true, status: deny.status }), {
+    status: deny.status,
+    headers: responseHeaders,
+  });
+}

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

@@ -0,0 +1,177 @@
+/**
+ * RSC Error & No-Match Renderers — handles error pages and 404s.
+ *
+ * Renders error.tsx / status files and 404 pages through the RSC → SSR pipeline.
+ */
+
+import { createElement } from 'react';
+import { renderToReadableStream } from '@vitejs/plugin-rsc/rsc';
+
+import type { RouteMatch } from '#/server/pipeline.js';
+import { logRenderError } from '#/server/logger.js';
+import type { ManifestSegmentNode } from '#/server/route-matcher.js';
+import { DenySignal, RenderError } from '#/server/primitives.js';
+import type { ClientBootstrapConfig } from '#/server/html-injectors.js';
+import { renderDenyPage } from '#/server/deny-renderer.js';
+import type { LayoutEntry } from '#/server/deny-renderer.js';
+import type { NavContext } from '#/server/ssr-entry.js';
+import { createDebugChannelSink, parseCookiesFromHeader } from './helpers.js';
+import { callSsr } from './ssr-bridge.js';
+
+/**
+ * Render an error page for unhandled throws or RenderError outside Suspense.
+ *
+ * Walks the segment chain from leaf to root looking for:
+ *   1. Specific status file (e.g. 503.tsx) matching the error's status
+ *   2. 5xx.tsx category catch-all
+ *   3. error.tsx
+ *
+ * Renders the found component with { error, digest, reset } props
+ * wrapped in layouts, with the correct HTTP status code.
+ */
+export async function renderErrorPage(
+  error: unknown,
+  status: number,
+  segments: ManifestSegmentNode[],
+  layoutComponents: LayoutEntry[],
+  req: Request,
+  match: RouteMatch,
+  responseHeaders: Headers,
+  clientBootstrap: ClientBootstrapConfig
+): Promise<Response> {
+  const h = createElement as (...args: unknown[]) => React.ReactElement;
+
+  // Walk segments from leaf to root to find the error component
+  let errorComponent: ((...args: unknown[]) => unknown) | null = null;
+  let foundSegmentIndex = -1;
+
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const segment = segments[i];
+
+    // Check specific status file (e.g. 503.tsx)
+    if (segment.statusFiles) {
+      const statusKey = String(status);
+      const specificFile = segment.statusFiles[statusKey];
+      if (specificFile) {
+        const mod = (await specificFile.load()) as Record<string, unknown>;
+        if (mod.default) {
+          errorComponent = mod.default as (...args: unknown[]) => unknown;
+          foundSegmentIndex = i;
+          break;
+        }
+      }
+
+      // Check 5xx.tsx category catch-all
+      const categoryFile = segment.statusFiles['5xx'];
+      if (categoryFile && status >= 500 && status <= 599) {
+        const mod = (await categoryFile.load()) as Record<string, unknown>;
+        if (mod.default) {
+          errorComponent = mod.default as (...args: unknown[]) => unknown;
+          foundSegmentIndex = i;
+          break;
+        }
+      }
+    }
+
+    // Check error.tsx
+    if (segment.error) {
+      const mod = (await segment.error.load()) as Record<string, unknown>;
+      if (mod.default) {
+        errorComponent = mod.default as (...args: unknown[]) => unknown;
+        foundSegmentIndex = i;
+        break;
+      }
+    }
+  }
+
+  // No error component found — fall back to bare response
+  if (!errorComponent) {
+    return new Response(null, { status, headers: responseHeaders });
+  }
+
+  // Build digest prop for RenderError, null for unhandled errors
+  const digest =
+    error instanceof RenderError ? { code: error.code, data: error.digest.data } : null;
+
+  // Error pages receive { error, digest, reset } per design/10-error-handling.md
+  let element = h(errorComponent, {
+    error: error instanceof Error ? error : new Error(String(error)),
+    digest,
+    reset: undefined, // reset is only meaningful on the client
+  });
+
+  // Wrap in layouts from root up to the segment where the error file was found
+  const resolvedSegments = new Set(segments.slice(0, foundSegmentIndex + 1));
+  const layoutsToWrap = layoutComponents.filter((lc) => resolvedSegments.has(lc.segment));
+  for (let i = layoutsToWrap.length - 1; i >= 0; i--) {
+    const { component } = layoutsToWrap[i];
+    element = h(component, null, element);
+  }
+
+  // Render to fresh RSC Flight stream
+  const rscStream = renderToReadableStream(element, {
+    onError(err: unknown) {
+      logRenderError({ method: req.method, path: new URL(req.url).pathname, error: err });
+    },
+    debugChannel: createDebugChannelSink(),
+  });
+
+  const [ssrStream, inlineStream] = rscStream.tee();
+
+  const navContext: NavContext = {
+    pathname: new URL(req.url).pathname,
+    params: match.params,
+    searchParams: Object.fromEntries(new URL(req.url).searchParams),
+    statusCode: status,
+    responseHeaders,
+    headHtml: '',
+    bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
+    rscStream: inlineStream,
+    cookies: parseCookiesFromHeader(req.headers.get('cookie') ?? ''),
+  };
+
+  return callSsr(ssrStream, navContext);
+}
+
+/**
+ * Render a 404 page for URLs that don't match any route.
+ *
+ * Uses the root segment's 404.tsx (or 4xx.tsx / error.tsx fallback)
+ * wrapped in the root layout, via the same renderDenyPage path
+ * used for in-route deny() calls.
+ */
+export async function renderNoMatchPage(
+  req: Request,
+  rootSegment: ManifestSegmentNode,
+  responseHeaders: Headers,
+  clientBootstrap: ClientBootstrapConfig
+): Promise<Response> {
+  const segments = [rootSegment];
+
+  // Load root layout if present
+  const layoutComponents: LayoutEntry[] = [];
+  if (rootSegment.layout) {
+    const mod = (await rootSegment.layout.load()) as Record<string, unknown>;
+    if (mod.default) {
+      layoutComponents.push({
+        component: mod.default as (...args: unknown[]) => unknown,
+        segment: rootSegment,
+      });
+    }
+  }
+
+  const deny = new DenySignal(404);
+  const match: RouteMatch = { segments: segments as never, params: {} };
+
+  return renderDenyPage(
+    deny,
+    segments,
+    layoutComponents,
+    req,
+    match,
+    responseHeaders,
+    clientBootstrap,
+    createDebugChannelSink,
+    callSsr
+  );
+}