@timber-js/app 0.2.0-alpha.208 → 0.2.0-alpha.209

package/src/server/rsc-entry/rsc-stream.ts

@@ -2,9 +2,9 @@
  * RSC Stream Renderer — Creates the RSC Flight stream with signal tracking.
  *
  * Wraps `renderToReadableStream` from `@vitejs/plugin-rsc/rsc` and captures
- * render-phase signals (DenySignal, RedirectSignal, RenderError) thrown by
+ * render-phase signals (DenySignal, RedirectSignal) thrown by
  * components during streaming. These signals are tracked in a shared
- * `RenderSignals` object so the caller can decide the HTTP response.
+ * read-only `RenderSignals` object so the caller can decide the HTTP response.
  *
  * Design docs: 02-rendering-pipeline.md §"Single-Pass Rendering",
  *              13-security.md §"Errors don't leak"
@@ -12,70 +12,22 @@
 
 import { renderToReadableStream } from '../../rsc-runtime/rsc.ts';
 import type { RscPayloadRoot } from '../../shared/payload-root.ts';
+import { encodeErrorDigest } from '../../shared/error-digest.ts';
 
 import { randomUUID } from 'node:crypto';
 
 import { matchDenyEntries, type DenyPageEntry } from '../deny-boundary.ts';
-import { logRenderError } from '../logger.ts';
-import {
-  isDenySignal,
-  isRedirectSignal,
-  isRenderError,
-  DenySignal,
-  RedirectSignal,
-  RenderError,
-} from '../primitives.ts';
+import { reportRenderError } from '../pipeline-helpers.ts';
+import { isDenySignal, isRedirectSignal } from '../signal-identity.ts';
 import { checkAndWarnRscPropError } from '../rsc-prop-warnings.ts';
 
 import { isAbortError } from './helpers.ts';
+import { createSignalRecorder, type RenderSignals } from './render-signals.ts';
 import { isDebug } from '../debug.ts';
 import { isDevMode } from '../debug.ts';
 
-/**
- * Mutable signal state captured during RSC rendering.
- *
- * Signals fire asynchronously via `onError` during stream consumption.
- * The first signal of each type wins — subsequent signals are ignored.
- *
- * `onSignal` is an optional callback fired when a DenySignal or
- * RedirectSignal is captured. Consumers use it with Promise.race to
- * react immediately instead of polling with setTimeout/queueMicrotask.
- */
-export interface RenderSignals {
-  denySignal: DenySignal | null;
-  /**
-   * The first deny that no in-tree catch site could place — no `owners`, so
-   * no boundary may claim its error row and only the re-render fallback can
-   * produce a page for it.
-   *
-   * Tracked apart from `denySignal` because one render can produce both. A
-   * deep page can hoist a 404 to a boundary that will render it while an
-   * outer layout separately throws a 403 nothing matches; whichever lands in
-   * `denySignal` first, the unplaced one still needs the fallback, and
-   * deciding from `denySignal.owners` alone would strand it. See TIM-1356.
-   */
-  unplacedDeny: DenySignal | null;
-  redirectSignal: RedirectSignal | null;
-  renderError: { error: unknown; status: number } | null;
-  /**
-   * The last unhandled error seen by RSC onError that isn't a signal.
-   * Used as a fallback when SSR fails (SsrStreamError) but no structured
-   * signal was captured — provides the original error for the error page
-   * instead of relying on SsrStreamError.cause extraction.
-   *
-   * NOT used for page-level error detection (that would break Suspense
-   * error isolation). Only consumed when SSR actually fails.
-   */
-  lastUnhandledError: unknown | null;
-  /** Callback fired when a redirect or deny signal is captured in onError. */
-  onSignal?: () => void;
-  /** Callback fired when an unhandled error (non-signal) is captured. Used
-   *  to halt Flight data injection into the inline stream. */
-  onUnhandledError?: () => void;
-}
-
 export interface RscStreamResult {
-  rscStream: ReadableStream<Uint8Array> | undefined;
+  rscStream: ReadableStream<Uint8Array>;
   signals: RenderSignals;
 }
 
@@ -85,177 +37,125 @@ export interface RscStreamResult {
  * The stream serializes server components as rendered output and client
  * components ("use client") as serialized references with module ID + export name.
  *
- * DenySignal detection: deny() in sync components throws during
- * renderToReadableStream (caught in try/catch). deny() in async components
- * fires onError during stream consumption. Signals are captured in the
- * returned `signals` object for the caller to handle.
+ * Signals are captured in the returned `signals` object for the caller to
+ * handle. Every one arrives through `onError`, never as a throw from this
+ * call: Flight starts rendering in a microtask after the stream is created,
+ * so even a component that throws synchronously is reported asynchronously.
  */
 export function renderRscStream(
   payload: RscPayloadRoot,
   req: Request,
   leafDenyChain?: DenyPageEntry[]
 ): RscStreamResult {
-  const signals: RenderSignals = {
-    denySignal: null,
-    unplacedDeny: null,
-    redirectSignal: null,
-    renderError: null,
-    lastUnhandledError: null,
-  };
+  const recorder = createSignalRecorder();
 
-  let rscStream: ReadableStream<Uint8Array> | undefined;
-
-  try {
-    rscStream = renderToReadableStream(
-      payload,
-      {
-        signal: req.signal,
-        onError(error: unknown) {
-          // Connection abort (user refreshed or navigated away) — suppress.
-          // Not an application error; no need to track or log.
-          if (isAbortError(error) || req.signal?.aborted) return;
-          if (isDenySignal(error)) {
-            // Late addressing (TIM-1450): a nested-component deny escapes
-            // all in-tree catch sites and arrives here without owners.
-            // Resolve it against the leaf deny chain and stamp the full
-            // candidate list so the client can find the first reachable
-            // owner via its ancestry context.
-            if (!error.owners && leafDenyChain) {
-              const entries = matchDenyEntries(leafDenyChain, error.status);
-              if (entries.length > 0) {
-                error.owners = entries.map((e) => e.ownerKey);
-              }
+  const rscStream = renderToReadableStream(
+    payload,
+    {
+      signal: req.signal,
+      onError(error: unknown) {
+        // Connection abort (user refreshed or navigated away) — suppress.
+        // Not an application error; no need to track or log.
+        if (isAbortError(error) || req.signal?.aborted) return;
+        if (isDenySignal(error)) {
+          // Late addressing (TIM-1450): a nested-component deny escapes
+          // all in-tree catch sites and arrives here without owners.
+          // Resolve it against the leaf deny chain and stamp the full
+          // candidate list so the client can find the first reachable
+          // owner via its ancestry context.
+          if (!error.owners && leafDenyChain) {
+            const entries = matchDenyEntries(leafDenyChain, error.status);
+            if (entries.length > 0) {
+              error.owners = entries.map((e) => e.ownerKey);
             }
-            // First-wins: two concurrent denies from separately serialized
-            // subtrees must commit a deterministic status. See
-            // spike-TIM-1441 §"two-concurrent-denials scenario".
-            signals.denySignal ??= error;
-            if (!error.owners) signals.unplacedDeny ??= error;
-            signals.onSignal?.();
-            return JSON.stringify({
-              type: 'deny',
-              status: error.status,
-              data: error.data,
-              owners: error.owners,
-            });
-          }
-          if (isRedirectSignal(error)) {
-            signals.redirectSignal = error;
-            signals.onSignal?.();
-            return JSON.stringify({
-              type: 'redirect',
-              location: error.location,
-              status: error.status,
-            });
-          }
-          if (isRenderError(error)) {
-            // Track the first render error for pre-flush handling
-            if (!signals.renderError) {
-              signals.renderError = { error, status: error.status };
-            }
-            logRenderError({ method: req.method, path: new URL(req.url).pathname, error });
-            return JSON.stringify({
-              type: 'render-error',
-              code: error.code,
-              data: error.digest.data,
-              status: error.status,
-            });
-          }
-          // Dev diagnostic: detect "Invalid hook call" errors which indicate
-          // a 'use client' component is being executed during RSC rendering
-          // instead of being serialized as a client reference. This happens when
-          // the RSC plugin's transform doesn't detect the directive — e.g., the
-          // directive isn't at the very top of the file, or the component is
-          // re-exported through a barrel file without 'use client'.
-          // See LOCAL-297.
-          if (isDebug() && error instanceof Error && error.message.includes('Invalid hook call')) {
-            console.error(
-              '[timber] A React hook was called during RSC rendering. This usually means a ' +
-                "'use client' component is being executed as a server component instead of " +
-                'being serialized as a client reference.\n\n' +
-                'Common causes:\n' +
-                "  1. The 'use client' directive is not the FIRST statement in the file (before any imports)\n" +
-                "  2. The component is re-exported through a barrel file (index.ts) that lacks 'use client'\n" +
-                '  3. @vitejs/plugin-rsc is not loaded or is misconfigured\n\n' +
-                `Request: ${req.method} ${new URL(req.url).pathname}`
-            );
           }
-
-          // Dev-mode: detect non-serializable RSC props and provide
-          // actionable fix suggestions (TIM-358).
-          // checkAndWarnRscPropError no-ops in production internally.
-          if (error instanceof Error) {
-            checkAndWarnRscPropError(error, new URL(req.url).pathname);
-          }
-
-          // Log the error but do NOT track it as a page-level render error.
-          // If this error is inside a <Suspense> boundary, React will emit
-          // an error row in the Flight stream and the Suspense fallback will
-          // render on the client. Tracking it as signals.renderError would
-          // cause the pipeline to treat the entire page as a 500, even though
-          // the shell rendered successfully. See TIM-524.
-          //
-          // Only track as renderError if no Suspense boundary contains it —
-          // React will call onShellError for truly unrecoverable errors.
-
-          // Track the last unhandled error so the pipeline can use it
-          // if SSR fails (SsrStreamError). This is NOT used for page-level
-          // error detection — only as a fallback when SSR actually fails.
-          signals.lastUnhandledError = error;
-          signals.onUnhandledError?.();
-
-          // Return a digest so React emits a per-row error in the Flight
-          // stream instead of leaving the lazy reference unresolved.
-          //
-          // SECURITY: Never include error.message in the digest — it may
-          // contain SQL queries, filesystem paths, secret fragments, or
-          // internal IDs. Use a generic message with a correlation ID so
-          // the error can be matched to server logs.
-          // See design/13-security.md §"Errors don't leak".
-          const errorId = randomUUID();
-          logRenderError({
-            method: req.method,
-            path: new URL(req.url).pathname,
-            error,
-            errorId,
+          recorder.deny(error);
+          return JSON.stringify({
+            type: 'deny',
+            status: error.status,
+            data: error.data,
+            owners: error.owners,
           });
+        }
+        if (isRedirectSignal(error)) {
+          recorder.redirect(error);
           return JSON.stringify({
-            type: 'error',
-            message: isDevMode()
-              ? error instanceof Error
-                ? error.message
-                : String(error)
-              : 'An unexpected error occurred.',
-            errorId,
+            type: 'redirect',
+            location: error.location,
+            status: error.status,
           });
-        },
+        }
+        // Dev diagnostic: detect "Invalid hook call" errors which indicate
+        // a 'use client' component is being executed during RSC rendering
+        // instead of being serialized as a client reference. This happens when
+        // the RSC plugin's transform doesn't detect the directive — e.g., the
+        // directive isn't at the very top of the file, or the component is
+        // re-exported through a barrel file without 'use client'.
+        // See LOCAL-297.
+        if (isDebug() && error instanceof Error && error.message.includes('Invalid hook call')) {
+          console.error(
+            '[timber] A React hook was called during RSC rendering. This usually means a ' +
+              "'use client' component is being executed as a server component instead of " +
+              'being serialized as a client reference.\n\n' +
+              'Common causes:\n' +
+              "  1. The 'use client' directive is not the FIRST statement in the file (before any imports)\n" +
+              "  2. The component is re-exported through a barrel file (index.ts) that lacks 'use client'\n" +
+              '  3. @vitejs/plugin-rsc is not loaded or is misconfigured\n\n' +
+              `Request: ${req.method} ${new URL(req.url).pathname}`
+          );
+        }
+
+        // Dev-mode: detect non-serializable RSC props and provide
+        // actionable fix suggestions (TIM-358).
+        // checkAndWarnRscPropError no-ops in production internally.
+        if (error instanceof Error) {
+          checkAndWarnRscPropError(error, new URL(req.url).pathname);
+        }
+
+        // Log the error but do NOT track it as a page-level signal. If this
+        // error is inside a <Suspense> boundary, React will emit an error
+        // row in the Flight stream and the nearest error boundary renders
+        // it on the client; treating it as page-level would turn a page
+        // whose shell rendered into a 500. See TIM-524. An error no
+        // boundary contains fails SSR's shell instead, and the SSR renderer
+        // answers that with the error page.
+        recorder.unhandledError();
+
+        // Return a digest so React emits a per-row error in the Flight
+        // stream instead of leaving the lazy reference unresolved.
+        //
+        // SECURITY: Never include error.message in the digest — it may
+        // contain SQL queries, filesystem paths, secret fragments, or
+        // internal IDs. Use a generic message with a correlation ID so
+        // the error can be matched to server logs. The ID is the `digest`
+        // prop error pages receive (shared/error-digest.ts).
+        // See design/13-security.md §"Errors don't leak".
+        //
+        // This is the error's one log and one `onRequestError` report,
+        // whether a Suspense boundary contains it or it crashes the shell
+        // and the renderer answers with the error page (design/49
+        // §"Deferred: render-error handoff").
+        const errorId = randomUUID();
+        reportRenderError(error, req, { errorId });
+        return encodeErrorDigest({
+          message: isDevMode()
+            ? error instanceof Error
+              ? error.message
+              : String(error)
+            : 'An unexpected error occurred.',
+          errorId,
+        });
+      },
+    },
+    {
+      onClientReference(info: { id: string; name: string; deps: unknown }) {
+        // Client reference callback — invoked when a "use client"
+        // component is serialized into the RSC stream. Can be extended
+        // for CSS dep collection and Early Hints.
+        void info;
       },
-      {
-        onClientReference(info: { id: string; name: string; deps: unknown }) {
-          // Client reference callback — invoked when a "use client"
-          // component is serialized into the RSC stream. Can be extended
-          // for CSS dep collection and Early Hints.
-          void info;
-        },
-      }
-    );
-  } catch (error) {
-    if (isDenySignal(error)) {
-      signals.denySignal ??= error;
-      if (!error.owners) signals.unplacedDeny ??= error;
-    } else if (isRedirectSignal(error)) {
-      signals.redirectSignal = error;
-    } else {
-      // Synchronous render error — component threw during
-      // renderToReadableStream creation. Capture instead of crashing
-      // the server; the error page will be rendered below.
-      signals.renderError = {
-        error,
-        status: isRenderError(error) ? error.status : 500,
-      };
-      logRenderError({ method: req.method, path: new URL(req.url).pathname, error });
     }
-  }
+  );
 
-  return { rscStream, signals };
+  return { rscStream, signals: recorder.signals };
 }

package/src/server/rsc-entry/ssr-bridge.ts

@@ -8,12 +8,12 @@
 
 /// <reference types="@vitejs/plugin-rsc/types" />
 
-import type { NavContext } from '../ssr-bridge-types.ts';
+import type { NavContext, SsrRenderResult } from '../ssr-bridge-types.ts';
 
 export async function callSsr(
   rscStream: ReadableStream<Uint8Array>,
   navContext: NavContext
-): Promise<Response> {
+): Promise<SsrRenderResult> {
   let ssrEntry: typeof import('../ssr-entry.ts');
   try {
     ssrEntry = await import.meta.viteRsc.import<typeof import('../ssr-entry.ts')>(