@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

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

@@ -1,177 +1,365 @@
 /**
- * RSC Error & No-Match Renderers — handles error pages and 404s.
+ * RSC Error Renderer — handles error pages. (The 404 page for an unmatched
+ * URL is a deny page, assembled by `deny-fallback.ts`.)
  *
- * 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 { loadFallbackModule, reportRenderError } from '../pipeline-helpers.ts';
+import { appVisibleSearch } from '../../shared/rsc-cache-key.ts';
+import type { ManifestSegmentNode } from '../route-matcher.ts';
+import { errorDigestId } from '../../shared/error-digest.ts';
+import type { ClientBootstrapConfig } from '../html-injectors.ts';
+import { flightInitScript, htmlEscapeJsonString } from '../flight-scripts.ts';
+import { getCspNonce } from '../csp-nonce.ts';
+import type { LayoutEntry } from '../deny-renderer.ts';
+import type { NavContext } from '../ssr-bridge-types.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 type { ManifestLoader } from '../safe-load.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--) {
+  load: (file: ManifestLoader) => Promise<Record<string, unknown> | null>,
+  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;
+        // `load` returns null when the error page module itself fails to
+        // load (syntax error, missing file), after reporting it, so the next
+        // tier answers instead of a recursive failure.
+        // See TIM-584, design/spike-TIM-551-dynamic-import-audit.md §H1.
+        const mod = await load(specificFile);
+        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 load(categoryFile);
+        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 load(segment.error);
+      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 an unhandled throw 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 every one of them, and the deny path's equivalent split
+ * (the deny fallback's page / Flight branches) had already been forgotten at one
+ * of this function's — a since-deleted synchronous render-error exit in
+ * `render-route.ts` (TIM-1322). Neither remaining caller is reachable for an
+ * RSC request today (`render-route.ts` returns the payload before it reaches
+ * SSR, and `outcomeToResponse` answers RSC errors itself), so this guards
+ * against drift rather than firing on a live path.
+ */
+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 already logged it
+  // where it was caught, so a log on this exit would double up: `rsc-stream.ts`'s
+  // `onError` for an error the RSC render threw, Fizz's `onError`
+  // (`ssr-render.ts`) for a shell error SSR threw itself, `outcomeToResponse`
+  // for a pipeline error. Each of them is also the error's one
+  // `onRequestError` report, except Fizz's, which reaches no hook; see
+  // design/17 §"Which errors reach it".
+  if (isRscRequest(req)) {
+    return rscErrorEnvelope(status, responseHeaders);
   }
 
-  // Build digest prop for RenderError, null for unhandled errors
-  const digest =
-    error instanceof RenderError ? { code: error.code, data: error.digest.data } : null;
+  // 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 load = (file: ManifestLoader) => loadFallbackModule(file, req, segments);
+  const resolution = await resolveErrorFile(status, segments, load, 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);
+  }
+
+  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);
+  // The ID the server logged this error with, when it crossed Flight — a
+  // shell crash SSR relays here. A pipeline error has none.
+  const digest = errorDigestId(error);
+
+  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) {
+        reportRenderError(err, req, { segments: match.segments });
+      },
+    });
 
-  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') ?? ''),
-  };
+    const nonce = getCspNonce();
+    const navContext: NavContext = {
+      pathname: url.pathname,
+      search: appVisibleSearch(url).search,
+      statusCode: status,
+      responseHeaders,
+      headHtml: flightInitScript(nonce),
+      bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
+      nonce,
+      rscStream: inlineStream,
+      signal: req.signal,
+      cookies: getCookiesForSsr(),
+    };
 
-  return callSsr(ssrStream, navContext);
+    // `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)).response;
+  } 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);
+  }
 }
 
 /**
- * Render a 404 page for URLs that don't match any route.
+ * Tier 2 — Render global-error.tsx as a standalone full-page replacement.
  *
- * 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.
+ * No layout wrapping. The component must provide its own <html> and <body>.
+ *
+ * See design/10-error-handling.md §"Tier 2 — Global Error Page"
  */
-export async function renderNoMatchPage(
+async function renderGlobalErrorPage(
+  error: unknown,
+  status: number,
+  globalError: GlobalErrorFile,
   req: Request,
-  rootSegment: ManifestSegmentNode,
+  match: RouteMatch,
   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,
-      });
-    }
+  // If global-error.tsx fails to load (reported) 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 loadFallbackModule(globalError, req, match.segments);
+  if (!mod?.default) {
+    return defaultStatusPageResponse(status, responseHeaders);
   }
 
-  const deny = new DenySignal(404);
-  const match: RouteMatch = { segments: segments as never, params: {} };
+  const component = mod.default as (...args: unknown[]) => unknown;
 
-  return renderDenyPage(
-    deny,
-    segments,
-    layoutComponents,
+  return renderErrorPageViaRsc(
+    error,
+    component,
+    status,
+    [], // No layouts — global-error is standalone
     req,
     match,
     responseHeaders,
-    clientBootstrap,
-    createDebugChannelSink,
-    callSsr
+    clientBootstrap
   );
 }