@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/server/rsc-entry/deny-fallback.ts

@@ -0,0 +1,93 @@
+/**
+ * Deny fallback renderer — renders the deny page (403.tsx, 404.tsx, etc.)
+ * for DenySignals that escape from middleware or the render phase.
+ *
+ * Extracted from index.ts (TIM-968) as a pure move. The factory captures
+ * the root segment and client bootstrap config once at handler creation;
+ * the returned function is wired into `PipelineConfig.renderDenyFallback`
+ * and reused by the action-dispatch wrapper.
+ *
+ * Design docs: 04-authorization.md, 10-error-handling.md
+ */
+
+import type { LayoutEntry } from '../deny-renderer.ts';
+import { renderDenyPage, renderDenyPageAsRsc } from '../deny-renderer.ts';
+import type { ClientBootstrapConfig } from '../html-injectors.ts';
+import { logRenderError } from '../logger.ts';
+import type { PipelineConfig, RouteMatch } from '../pipeline.ts';
+import type { ManifestSegmentNode } from '../route-matcher.ts';
+import { loadModule } from '../safe-load.ts';
+import { createDebugChannelSink } from './helpers.ts';
+import { isRscRequest } from '../../shared/rsc-media-type.ts';
+import { callSsr } from './ssr-bridge.ts';
+
+/**
+ * Create the pipeline's deny fallback renderer.
+ *
+ * When the pipeline already matched a route (the common case — matching
+ * runs before middleware and rendering), resolve the status file against
+ * the matched chain so colocated files like a nested `403.tsx` or an API
+ * route's `401.json` are picked up. Fall back to the root chain when no
+ * match is available (e.g. proxy-stage deny before route matching).
+ * See TIM-822, design/04-authorization.md, design/10-error-handling.md.
+ */
+export function createDenyFallbackRenderer(options: {
+  rootSegment: ManifestSegmentNode;
+  clientBootstrap: ClientBootstrapConfig;
+}): NonNullable<PipelineConfig['renderDenyFallback']> {
+  const { rootSegment, clientBootstrap } = options;
+  return async (deny, req, responseHeaders, matchedRoute) => {
+    const chain: ManifestSegmentNode[] = matchedRoute ? matchedRoute.segments : [rootSegment];
+    const layoutComponents: LayoutEntry[] = [];
+    try {
+      for (const segment of chain) {
+        if (!segment.layout) continue;
+        const mod = await loadModule(segment.layout);
+        if (mod.default) {
+          layoutComponents.push({
+            component: mod.default as (...args: unknown[]) => unknown,
+            segment,
+          });
+        }
+      }
+    } catch (layoutError) {
+      // Layout failed to load — proceed without it. Partial layout chains
+      // are acceptable; the deny renderer wraps in whatever loaded.
+      logRenderError({ method: req.method, path: new URL(req.url).pathname, error: layoutError });
+    }
+    // Reuse the matched route's params/middleware metadata when present so
+    // downstream rendering sees the real route shape. Otherwise synthesise
+    // a root-only stub (no params, no middleware).
+    const match: RouteMatch = matchedRoute ?? {
+      segments: chain,
+      segmentParams: {},
+      middlewareChain: [],
+    };
+    // For client navigation (Accept: text/x-component), the timber router
+    // decodes the response as React Flight. Returning HTML to a Flight
+    // decoder breaks navigation, so dispatch to the RSC renderer when the
+    // request is an RSC payload request — mirroring the normal render path.
+    // See design/19-client-navigation.md §"RSC Payload Handling" and TIM-823.
+    if (isRscRequest(req)) {
+      return renderDenyPageAsRsc(
+        deny,
+        chain,
+        layoutComponents,
+        req,
+        responseHeaders,
+        createDebugChannelSink
+      );
+    }
+    return renderDenyPage(
+      deny,
+      chain,
+      layoutComponents,
+      req,
+      match,
+      responseHeaders,
+      clientBootstrap,
+      createDebugChannelSink,
+      callSsr
+    );
+  };
+}

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

@@ -1,136 +1,371 @@
 /**
  * RSC Error & No-Match Renderers — handles error pages and 404s.
  *
- * Renders error.tsx / status files and 404 pages through the RSC → SSR pipeline.
+ * Error pages are 'use client' components rendered through the RSC → SSR
+ * pipeline: the Error is converted to SerializableError, wrapped with
+ * ErrorReconstituter to reconstitute a real Error on the client.
+ *
+ * Design docs: 10-error-handling.md §"Three-Tier Error Page Rendering"
  */
 
 import { createElement } from 'react';
-import { renderToReadableStream } from '#/rsc-runtime/rsc.js';
-
-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';
+import { renderToReadableStream } from '../../rsc-runtime/rsc.ts';
+
+import type { RouteMatch } from '../pipeline.ts';
+import { logRenderError } from '../logger.ts';
+import { appVisibleSearch } from '../../shared/rsc-cache-key.ts';
+import { getSlotParamsForClient } from '../request-context.ts';
+import type { ManifestSegmentNode } from '../route-matcher.ts';
+import { isRenderError, DenySignal, RenderError } from '../primitives.ts';
+import type { ClientBootstrapConfig } from '../html-injectors.ts';
+import { flightInitScript, htmlEscapeJsonString } from '../flight-scripts.ts';
+import { getCspNonce } from '../csp-nonce.ts';
+import { renderDenyPage, renderDenyPageAsRsc } from '../deny-renderer.ts';
+import type { DefaultPageRenderer, LayoutEntry } from '../deny-renderer.ts';
+import type { NavContext } from '../ssr-bridge-types.ts';
+import { createDebugChannelSink } from './helpers.ts';
+import { isRscRequest } from '../../shared/rsc-media-type.ts';
+import { withPublishedParams } from '../publish-params.ts';
+import { getCookiesForSsr } from '../cookie-context.ts';
+import { callSsr } from './ssr-bridge.ts';
+import { teeWithErrorPropagation } from '../stream-utils.ts';
+import { isDevMode } from '../debug.ts';
+import { ErrorReconstituter } from '../../client/error-reconstituter.tsx';
+import type { SerializableError } from '../../client/error-reconstituter.tsx';
+import { loadModule } from '../safe-load.ts';
+import { sourceMapError } from '../dev-source-map.ts';
+import { defaultStatusPageResponse } from '../default-status-page.ts';
+import { rscErrorEnvelope } from '../rsc-error-envelope.ts';
 
 /**
- * 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
+ * A manifest file reference with lazy import and path.
+ * Mirrors the shape from ManifestSegmentNode but kept local to avoid
+ * exporting internal types from route-matcher.
+ */
+export interface GlobalErrorFile {
+  load: () => Promise<unknown>;
+  filePath: string;
+}
+
+/**
+ * Result of walking the segment chain for an error file.
+ */
+interface ErrorFileResolution {
+  /** The loaded component */
+  component: (...args: unknown[]) => unknown;
+  /** Index of the segment where the file was found */
+  segmentIndex: number;
+}
+
+/**
+ * Walk segments from leaf to root to find the nearest error file.
  *
- * Renders the found component with { error, digest, reset } props
- * wrapped in layouts, with the correct HTTP status code.
+ * Fallback chain at each segment:
+ *   1. Specific status file (e.g., 503.tsx) — exact match
+ *   2. 5xx.tsx — category catch-all
+ *   3. error.tsx — catches all unmatched errors
  */
-export async function renderErrorPage(
-  error: unknown,
+async function resolveErrorFile(
   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--) {
+  maxIndex?: number
+): Promise<ErrorFileResolution | null> {
+  const start =
+    maxIndex !== undefined ? Math.min(segments.length - 1, maxIndex) : segments.length - 1;
+  for (let i = start; i >= 0; i--) {
     const segment = segments[i];
 
-    // Check specific status file (e.g. 503.tsx)
     if (segment.statusFiles) {
+      // Check specific status file (e.g. 503.tsx)
       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;
+        // .catch: if the error page module itself fails to load (syntax error,
+        // missing file), fall through to next tier instead of recursive failure.
+        // See TIM-584, design/spike-TIM-551-dynamic-import-audit.md §H1.
+        const mod = await loadModule(specificFile).catch(() => null);
+        if (mod?.default) {
+          return {
+            component: mod.default as (...args: unknown[]) => unknown,
+            segmentIndex: i,
+          };
         }
       }
 
       // 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;
+        const mod = await loadModule(categoryFile).catch(() => null);
+        if (mod?.default) {
+          return {
+            component: mod.default as (...args: unknown[]) => unknown,
+            segmentIndex: i,
+          };
         }
       }
     }
 
     // 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;
+      const mod = await loadModule(segment.error).catch(() => null);
+      if (mod?.default) {
+        return {
+          component: mod.default as (...args: unknown[]) => unknown,
+          segmentIndex: i,
+        };
       }
     }
   }
 
-  // No error component found — fall back to bare response
-  if (!errorComponent) {
-    return new Response(null, { status, headers: responseHeaders });
+  return null;
+}
+
+/**
+ * Build the layouts-to-wrap list for an error file at a given segment index.
+ */
+function getLayoutsForErrorFile(
+  segments: ManifestSegmentNode[],
+  layoutComponents: LayoutEntry[],
+  foundSegmentIndex: number,
+  firstDeniedIndex = Infinity
+): LayoutEntry[] {
+  // Clamp so a denied segment's layout never wraps the error page.
+  // The file resolution is unbounded (errors may use leaf files), but the
+  // layout wrapping must still respect the denial boundary. TIM-1358.
+  const ceiling = Math.min(foundSegmentIndex, firstDeniedIndex - 1);
+  const resolvedSegments = new Set(segments.slice(0, ceiling + 1));
+  return layoutComponents.filter((lc) => resolvedSegments.has(lc.segment));
+}
+
+/**
+ * Convert an error to a SerializableError for RSC Flight serialization.
+ * Stack traces are stripped in production (gated by isDevMode).
+ *
+ * See design/13-security.md §"Debug Flag Security Boundary" — uses isDevMode(),
+ * not isDebug(), because this data crosses the RSC → client boundary.
+ */
+function toSerializableError(error: unknown): SerializableError {
+  const err = error instanceof Error ? error : new Error(String(error));
+  const devMode = isDevMode();
+  return {
+    message: devMode ? err.message : 'An unexpected error occurred.',
+    name: devMode ? err.name : 'Error',
+    ...(devMode && err.stack ? { stack: err.stack } : {}),
+  };
+}
+
+/**
+ * Render an error page for unhandled throws or RenderError outside Suspense.
+ *
+ * All error pages (TSX and MDX) go through RSC → SSR:
+ * - TSX: ErrorReconstituter wrapper converts SerializableError → real Error
+ * - MDX: Plain props ({ status }), no wrapper needed
+ *
+ * ...except for a client-navigation request, which gets the hard-navigate
+ * envelope instead. Every tier below produces an HTML document, and the
+ * client's Flight decoder is waiting for `text/x-component`; handing it HTML
+ * crashes the decode. The check lives here rather than at the call sites
+ * because it holds for all five of them, and the deny path's equivalent split
+ * (`renderDenyPage` / `renderDenyPageAsRsc`) had already been forgotten at one
+ * of this function's — the synchronous render-error exit in `render-route.ts`
+ * (TIM-1322). Four of the five are unreachable for an RSC request today
+ * (`render-route.ts` returns the payload before it reaches SSR, and
+ * `outcomeToResponse` answers RSC errors itself), so this fires on one path
+ * and guards the rest against drift.
+ */
+export async function renderErrorPage(
+  error: unknown,
+  status: number,
+  segments: ManifestSegmentNode[],
+  layoutComponents: LayoutEntry[],
+  req: Request,
+  match: RouteMatch,
+  responseHeaders: Headers,
+  clientBootstrap: ClientBootstrapConfig,
+  globalError?: GlobalErrorFile,
+  firstDeniedIndex = Infinity
+): Promise<Response> {
+  // The error itself is not logged here — every producer of a `renderError`
+  // signal already logged it at the point it was caught (`rsc-stream.ts`'s
+  // `onError`, `outcomeToResponse`), so a log on this exit would double up.
+  if (isRscRequest(req)) {
+    return rscErrorEnvelope(status, responseHeaders);
+  }
+
+  // Source-map the error's stack trace in dev mode so the error page
+  // shows original source positions instead of transpiled/bundled ones.
+  // See TIM-811.
+  sourceMapError(error);
+  // Walk segments from leaf to root to find the error component.
+  // When firstDeniedIndex is finite, bound the walk so error files below
+  // the denied segment are not selected — matching the deny renderer's
+  // behavior. For plain errors (firstDeniedIndex = Infinity), the full
+  // chain is searched. See TIM-1358.
+  const errorMaxIndex = firstDeniedIndex < Infinity ? firstDeniedIndex : undefined;
+  const resolution = await resolveErrorFile(status, segments, errorMaxIndex);
+
+  // Tier 2: No segment-level error file — try global-error.tsx
+  if (!resolution && globalError) {
+    return renderGlobalErrorPage(
+      error,
+      status,
+      globalError,
+      req,
+      match,
+      responseHeaders,
+      clientBootstrap
+    );
+  }
+
+  // Tier 3: No error component found at any level — framework default page.
+  // The deny chain's terminal is the same page, so an app with no error files
+  // gets a readable status page for both 4xx and 5xx rather than a blank
+  // document. It carries the status and nothing else — never the error
+  // (design/13-security.md principle 4). See TIM-1258.
+  if (!resolution) {
+    return defaultStatusPageResponse(status, responseHeaders);
   }
 
-  // Build digest prop for RenderError, null for unhandled errors
-  const digest =
-    error instanceof RenderError ? { code: error.code, data: error.digest.data } : null;
+  const { component: errorComponent, segmentIndex } = resolution;
+  const layoutsToWrap = getLayoutsForErrorFile(
+    segments,
+    layoutComponents,
+    segmentIndex,
+    firstDeniedIndex
+  );
+
+  return renderErrorPageViaRsc(
+    error,
+    errorComponent,
+    status,
+    layoutsToWrap,
+    req,
+    match,
+    responseHeaders,
+    clientBootstrap
+  );
+}
 
-  // 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)),
+/**
+ * Render an error page through the RSC → SSR pipeline.
+ *
+ * Error pages are 'use client' components wrapped with ErrorReconstituter
+ * to reconstitute a real Error instance on the client.
+ */
+async function renderErrorPageViaRsc(
+  error: unknown,
+  errorComponent: (...args: unknown[]) => unknown,
+  status: number,
+  layoutsToWrap: LayoutEntry[],
+  req: Request,
+  match: RouteMatch,
+  responseHeaders: Headers,
+  clientBootstrap: ClientBootstrapConfig
+): Promise<Response> {
+  const h = createElement as (...args: unknown[]) => React.ReactElement;
+  const url = new URL(req.url);
+
+  const serializedError = toSerializableError(error);
+  const digest = isRenderError(error) ? { code: error.code, data: error.digest.data } : null;
+
+  let element: React.ReactElement = h(ErrorReconstituter, {
+    error: serializedError,
     digest,
-    reset: undefined, // reset is only meaningful on the client
+    reset: undefined,
+    component: errorComponent,
   });
 
-  // 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));
+  // Wrap in layouts
   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(),
-  });
+  // Render through RSC → SSR (same path as deny pages) — including the params
+  // wrap, which every payload the server sends needs. An error page on a
+  // dynamic route reads params like any other page, and SSR would get them
+  // from the request ALS while the hydrated client got an empty record.
+  try {
+    const rscStream = renderToReadableStream(withPublishedParams(element), {
+      signal: req.signal,
+      onError(err: unknown) {
+        logRenderError({ method: req.method, path: url.pathname, error: err });
+      },
+      debugChannel: createDebugChannelSink(),
+    });
 
-  const [ssrStream, inlineStream] = rscStream.tee();
+    const [ssrStream, inlineStream] = teeWithErrorPropagation(rscStream);
 
-  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') ?? ''),
-  };
+    // Params ride the payload root, beside the tree, so there is no
+    // bootstrap script. Read here for the SSR-side ALS context below.
+    const slotParams = getSlotParamsForClient();
+
+    const nonce = getCspNonce();
+    const navContext: NavContext = {
+      pathname: url.pathname,
+      search: appVisibleSearch(url).search,
+      segmentParams: match.segmentParams,
+      slotParams,
+      statusCode: status,
+      responseHeaders,
+      headHtml: flightInitScript(nonce),
+      bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
+      nonce,
+      rscStream: inlineStream,
+      signal: req.signal,
+      cookies: getCookiesForSsr(),
+    };
+
+    // `await` inside the try on purpose: SSR of the error page fails
+    // asynchronously far more often than synchronously, and returning the
+    // promise bare let every such rejection escape this guard.
+    return await callSsr(ssrStream, navContext);
+  } catch (renderError) {
+    // The error page itself failed to render — guards against recursive
+    // errors in user error page code. Terminates in the framework default
+    // page, not a blank body: a crashing error page is precisely when the
+    // reader has nothing else to go on (TIM-1258).
+    logRenderError({ method: req.method, path: url.pathname, error: renderError });
+    return defaultStatusPageResponse(status, responseHeaders);
+  }
+}
+
+/**
+ * Tier 2 — Render global-error.tsx as a standalone full-page replacement.
+ *
+ * No layout wrapping. The component must provide its own <html> and <body>.
+ *
+ * See design/10-error-handling.md §"Tier 2 — Global Error Page"
+ */
+async function renderGlobalErrorPage(
+  error: unknown,
+  status: number,
+  globalError: GlobalErrorFile,
+  req: Request,
+  match: RouteMatch,
+  responseHeaders: Headers,
+  clientBootstrap: ClientBootstrapConfig
+): Promise<Response> {
+  // .catch: if global-error.tsx fails to load or exports no component, it is
+  // not a usable Tier 2 match — fall through to the framework default page
+  // rather than a blank body. See TIM-584, TIM-1258.
+  const mod = await loadModule(globalError).catch(() => null);
+  if (!mod?.default) {
+    return defaultStatusPageResponse(status, responseHeaders);
+  }
+
+  const component = mod.default as (...args: unknown[]) => unknown;
 
-  return callSsr(ssrStream, navContext);
+  return renderErrorPageViaRsc(
+    error,
+    component,
+    status,
+    [], // No layouts — global-error is standalone
+    req,
+    match,
+    responseHeaders,
+    clientBootstrap
+  );
 }
 
 /**
@@ -144,15 +379,18 @@ export async function renderNoMatchPage(
   req: Request,
   rootSegment: ManifestSegmentNode,
   responseHeaders: Headers,
-  clientBootstrap: ClientBootstrapConfig
+  clientBootstrap: ClientBootstrapConfig,
+  defaultPage?: DefaultPageRenderer
 ): Promise<Response> {
   const segments = [rootSegment];
 
-  // Load root layout if present
+  // Load root layout if present. A layout that fails to import or evaluate
+  // must not take the 404 down with it — render the status page unwrapped,
+  // as renderFallbackError does for the same reason.
   const layoutComponents: LayoutEntry[] = [];
   if (rootSegment.layout) {
-    const mod = (await rootSegment.layout.load()) as Record<string, unknown>;
-    if (mod.default) {
+    const mod = await loadModule(rootSegment.layout).catch(() => null);
+    if (mod?.default) {
       layoutComponents.push({
         component: mod.default as (...args: unknown[]) => unknown,
         segment: rootSegment,
@@ -161,7 +399,18 @@ export async function renderNoMatchPage(
   }
 
   const deny = new DenySignal(404);
-  const match: RouteMatch = { segments: segments as never, params: {} };
+  const match: RouteMatch = { segments, segmentParams: {}, middlewareChain: [] };
+
+  if (isRscRequest(req)) {
+    return renderDenyPageAsRsc(
+      deny,
+      segments,
+      layoutComponents,
+      req,
+      responseHeaders,
+      createDebugChannelSink
+    );
+  }
 
   return renderDenyPage(
     deny,
@@ -172,6 +421,7 @@ export async function renderNoMatchPage(
     responseHeaders,
     clientBootstrap,
     createDebugChannelSink,
-    callSsr
+    callSsr,
+    defaultPage
   );
 }