@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/src/server/pipeline-interception.ts

@@ -9,33 +9,97 @@
  * See design/07-routing.md §"Intercepting Routes"
  */
 
-/** Result of a successful interception match. */
-export interface InterceptionMatchResult {
-  /** The pathname to re-match (the source/intercepting route's parent). */
-  sourcePathname: string;
-}
+import { classifyUrlSegment } from '../routing/segment-classify.js';
+import type { InterceptionRewrite } from '../routing/interception.js';
 
 /**
  * Check if an intercepting route applies for this soft navigation.
  *
- * Matches the target pathname against interception rewrites, constrained
- * by the source URL (X-Timber-URL header — where the user navigates FROM).
+ * Two conditions must hold:
+ *
+ * 1. The **target** pathname matches the rewrite's intercepted pattern.
+ * 2. The **source** route — the page the user is navigating FROM, per the
+ *    validated X-Timber-URL header — renders the segment that owns the slot
+ *    holding the intercepting page (`interceptingScope`). Only then does that
+ *    slot exist in the rendered tree, so only then can the intercepting page
+ *    render.
+ *
+ * Condition 2 replaced a URL-prefix check (TIM-1279). A prefix cannot
+ * distinguish a route-group-scoped interception from a genuinely root-level
+ * one — route groups are invisible in `urlPath`, so both collapse to "/" and
+ * the guard degenerates to always-true. Tree paths carry group identity.
+ * The scope check also subsumes the old segment-boundary rule: a source route
+ * under /feed-private has no "/feed" in its chain.
+ *
+ * A third condition lives with the caller, which owns route matching, and it
+ * applies to the `'slot'` shape only: the route produced by re-matching
+ * `interceptingPrefix` must pass through the scope too. Conditions 1–2 are
+ * about the route the user is leaving; the slot has to exist in the tree that
+ * actually renders. The `'children'` shape resolves its owner from the scope
+ * directly rather than from a pathname, so it satisfies that by construction.
+ *
+ * `resolveSourceScopes` is a thunk so its inputs are only resolved when some
+ * rewrite's pattern actually matches the target — the common case is no match
+ * at all. It returns the two client-supplied answers to "what is on screen?"
+ * as **separate sets, most authoritative first**: the tree paths the client
+ * says it has mounted, then those of the route the departing URL matches. It
+ * returns null only when neither yields anything, which is not a soft
+ * navigation this can reason about.
+ *
+ * They are two sets rather than one union because ranking needs a chain
+ * (TIM-1318). Each channel describes a single rendered chain, so within one the
+ * scopes are strictly nested and the deepest is the innermost owner. Unioned
+ * they are not: once a modal is open the address bar holds the *intercepted*
+ * URL, so the second channel describes the canonical branch — possibly an
+ * exclusive route group the client never mounted — and a deeper scope from
+ * there would outrank the owner actually on screen. Trying the mounted channel
+ * to exhaustion first keeps the fallback the union was there to provide while
+ * ranking only within one chain.
  *
- * Returns the source pathname to re-match if interception applies, or null.
+ * Returns the winning build-time rewrite, or null. Only build-time values ever
+ * reach the renderer: the client-supplied header selects a rewrite but never
+ * becomes a rendered route or pathname.
+ *
+ * The **first** matching rewrite wins, and the caller does not fall back to the
+ * next one when the winner fails to resolve. That is deliberate and pre-dates
+ * the two shapes: a rewrite that matched the target and the scope described the
+ * author's intent, and quietly rendering some other author's interception
+ * instead would be harder to explain than rendering the canonical route.
+ *
+ * "First" is meaningful because the list arrives **deepest scope first** —
+ * `collectInterceptionRewrites` sorts it at build time, so the deepest owner a
+ * single chain passes through wins and nothing here has to score (TIM-1318).
+ * Tree-walk order used to decide it, which meant renaming a route group flipped
+ * which modal opened. The precondition is a property of the manifest this reads
+ * rather than something it can re-derive, so it is asserted at its source:
+ * `tests/interception.test.ts` §"rewrite order is decided by scope depth".
  */
 export function findInterceptionMatch(
   targetPathname: string,
-  sourceUrl: string,
-  rewrites: import('#/routing/interception.js').InterceptionRewrite[]
-): InterceptionMatchResult | null {
-  for (const rewrite of rewrites) {
-    // Check if the source URL starts with the intercepting prefix
-    if (!sourceUrl.startsWith(rewrite.interceptingPrefix)) continue;
+  resolveSourceScopes: () => ReadonlySet<string>[] | null,
+  rewrites: InterceptionRewrite[]
+): InterceptionRewrite | null {
+  // Dynamic segments in the pattern match any single URL segment. Collected up
+  // front rather than inside the channel loop so a pattern is matched once
+  // however many channels are tried — and the common case, no rewrite matching
+  // at all, costs exactly the same scan it always did and resolves no scope.
+  const candidates = rewrites.filter((rewrite) =>
+    pathnameMatchesPattern(targetPathname, rewrite.interceptedPattern)
+  );
+  if (candidates.length === 0) return null;
+
+  // Nothing at all is known about the source tree — no scope can contain
+  // anything, so no rewrite can apply.
+  const scopes = resolveSourceScopes();
+  if (!scopes) return null;
 
-    // Check if the target URL matches the intercepted pattern.
-    // Dynamic segments in the pattern match any single URL segment.
-    if (pathnameMatchesPattern(targetPathname, rewrite.interceptedPattern)) {
-      return { sourcePathname: rewrite.interceptingPrefix };
+  // `candidates` is deepest scope first (`collectInterceptionRewrites`), so
+  // within one channel the first hit is the innermost owner that channel
+  // reports. Channels are tried in order, so a scope the client says it has
+  // mounted always beats one only the address bar implies.
+  for (const scope of scopes) {
+    for (const rewrite of candidates) {
+      if (scope.has(rewrite.interceptingScope)) return rewrite;
     }
   }
   return null;
@@ -53,23 +117,35 @@ export function pathnameMatchesPattern(pathname: string, pattern: string): boole
 
   let pi = 0;
   for (let i = 0; i < patternParts.length; i++) {
-    const segment = patternParts[i];
+    const seg = classifyUrlSegment(patternParts[i]);
 
-    // Catch-all: [...param] or [[...param]] — matches rest of URL
-    if (segment.startsWith('[...') || segment.startsWith('[[...')) {
-      return pi < pathParts.length || segment.startsWith('[[...');
+    switch (seg.kind) {
+      case 'catch-all':
+        return pi < pathParts.length;
+      case 'optional-catch-all':
+        return true;
+      case 'dynamic': {
+        if (pi >= pathParts.length) return false;
+        const prefix = seg.prefix ?? '';
+        const suffix = seg.suffix ?? '';
+        const pathPart = pathParts[pi];
+        if (prefix || suffix) {
+          if (
+            pathPart.length <= prefix.length + suffix.length ||
+            (prefix && !pathPart.startsWith(prefix)) ||
+            (suffix && !pathPart.endsWith(suffix))
+          ) {
+            return false;
+          }
+        }
+        pi++;
+        continue;
+      }
+      case 'static':
+        if (pi >= pathParts.length || pathParts[pi] !== seg.value) return false;
+        pi++;
+        continue;
     }
-
-    // Dynamic: [param] — matches any single segment
-    if (segment.startsWith('[') && segment.endsWith(']')) {
-      if (pi >= pathParts.length) 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

@@ -41,6 +41,7 @@ export async function serveStaticMetadataFile(
   const headers: Record<string, string> = {
     'Content-Type': isText ? `${contentType}; charset=utf-8` : contentType,
     'Content-Length': String(body.byteLength),
+    'Cache-Control': 'public, max-age=14400, must-revalidate',
   };
 
   return new Response(body, { status: 200, headers });
@@ -79,6 +80,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,196 @@
+/**
+ * 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 { isDebug } from './debug.js';
+import { rscErrorEnvelope } from '../shared/rsc-error-envelope.js';
+import { isRscRequest } from '../shared/rsc-media-type.js';
+import type { PipelineConfig, RouteMatch } from './pipeline.js';
+
+// ─── Helpers ───────────────────────────────────────────────────────────────
+
+function rscErrorResponse(isRsc: boolean, status: number, headers?: Headers): Response {
+  if (!isRsc) return new Response(null, { status });
+  return rscErrorEnvelope(status, headers);
+}
+
+// ─── 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');
+        }
+      }
+      if (isDebug()) {
+        console.warn(
+          `[timber] DenySignal(${outcome.signal.status}) from ${outcome.phase} phase — ` +
+            `no renderDenyFallback configured, returning bare ${outcome.signal.status} response\n` +
+            `  Request: ${ctx.method} ${ctx.path}\n` +
+            `  Add a status-code file (e.g. 404.tsx) or error.tsx to render a custom deny page.`
+        );
+      }
+      return new Response(null, { status: outcome.signal.status, headers });
+    }
+
+    case 'error': {
+      // RSC payload requests (client navigation) expect Flight data, not HTML.
+      // Signal the error via X-Timber-Error so the client hard-navigates
+      // to the server-rendered error page instead of feeding HTML to the
+      // Flight decoder (which crashes with "enqueueModel is not a function").
+      const isRsc = isRscRequest(ctx.req);
+
+      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 rscErrorResponse(isRsc, 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 rscErrorResponse(isRsc, 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 (isRsc) {
+        return rscErrorResponse(true, 500, headers);
+      }
+
+      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 });
+    }
+  }
+}