@timber-js/app 0.2.0-alpha.7 → 0.2.0-alpha.71

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

@@ -9,12 +9,12 @@
  *              16-metadata.md §"Head Elements"
  */
 
-import type { LayoutEntry } from '#/server/deny-renderer.js';
-import { renderDenyPageAsRsc } from '#/server/deny-renderer.js';
-import type { RouteMatch } from '#/server/pipeline.js';
-import type { RedirectSignal } from '#/server/primitives.js';
-import type { HeadElement, LayoutComponentEntry } from '#/server/route-element-builder.js';
-import type { ManifestSegmentNode } from '#/server/route-matcher.js';
+import type { LayoutEntry } from '../deny-renderer.js';
+import { renderDenyPageAsRsc } from '../deny-renderer.js';
+import type { RouteMatch } from '../pipeline.js';
+import type { RedirectSignal } from '../primitives.js';
+import type { HeadElement, LayoutComponentEntry } from '../route-element-builder.js';
+import type { ManifestSegmentNode } from '../route-matcher.js';
 
 import {
   buildRedirectResponse,
@@ -45,18 +45,60 @@ export async function buildRscPayloadResponse(
   skippedSegments?: string[]
 ): Promise<Response> {
   // Read the first chunk from the RSC stream before committing headers.
+  // Race the first read against signal detection — if an async component
+  // throws a RedirectSignal or DenySignal, the onError callback fires
+  // signals.onSignal() and we can react immediately without waiting for
+  // the full macrotask queue.
+  //
+  // The rejection chain for an async-wrapped page component:
+  //   1. PageComponent throws RedirectSignal
+  //   2. withSpan catches and re-throws (microtask 1)
+  //   3. TracedPage promise rejects (microtask 2)
+  //   4. React Flight rejection handler → onError (microtask 3+)
+  //
+  // Promise.race reacts the instant onError fires, eliminating the
+  // per-request setTimeout(0) macrotask delay for the common case
+  // (no signal). A 50ms ceiling timeout guards against edge cases
+  // where onError never fires.
   const reader = rscStream.getReader();
-  const firstRead = await reader.read();
+  const signalDetected = new Promise<void>((resolve) => {
+    signals.onSignal = resolve;
+  });
 
-  // Yield to the microtask queue so that async component rejections
-  // (e.g. an async-wrapped page component that throws redirect())
-  // propagate to the onError callback before we check the signals.
-  // The rejected Promise from an async component resolves in the next
-  // microtask after read(), so we need at least one tick.
-  //
-  // Uses queueMicrotask instead of setTimeout(0) to stay within the
-  // same tick — no full event loop round-trip needed.
-  await new Promise<void>((r) => queueMicrotask(r));
+  type RaceResult =
+    | { type: 'data'; chunk: ReadableStreamReadResult<Uint8Array> }
+    | { type: 'signal' };
+
+  let first: RaceResult;
+  try {
+    first = await Promise.race([
+      reader.read().then((chunk) => ({ type: 'data' as const, chunk })),
+      signalDetected.then(() => ({ type: 'signal' as const })),
+    ]);
+  } catch (_readError) {
+    // RSC stream failed on first read — unhandled error in the page component.
+    // Return an error response so the client can hard-navigate for the
+    // SSR-rendered error page. See design/10-error-handling.md.
+    reader.cancel().catch(() => {});
+    signals.onSignal = undefined;
+    responseHeaders.set('X-Timber-Error', '1');
+    responseHeaders.set('content-type', 'application/json; charset=utf-8');
+    return new Response(JSON.stringify({ error: true, status: 500 }), {
+      status: 500,
+      headers: responseHeaders,
+    });
+  }
+
+  // If data arrived first, still check signals — they may have fired
+  // concurrently. Also do a final ceiling timeout check for edge cases
+  // where the signal fires just after the first read resolves.
+  if (first.type === 'data' && !signals.redirectSignal && !signals.denySignal) {
+    // Brief yield to let any in-flight microtask rejections complete.
+    await new Promise<void>((r) => setTimeout(r, 0));
+  }
+
+  // Detach the callback — no longer needed after this point.
+  signals.onSignal = undefined;
 
   // Check for redirect/deny signals detected during initial rendering
   const trackedRedirect = signals.redirectSignal as RedirectSignal | null;
@@ -75,6 +117,37 @@ export async function buildRscPayloadResponse(
     );
   }
 
+  // Check for unhandled errors (RenderError or plain Error).
+  // These aren't redirect/deny signals but the RSC stream will be broken.
+  // Return an error response so the client can hard-navigate for the
+  // SSR-rendered error page. See design/10-error-handling.md
+  // §"Error Page Rendering for Client Navigation".
+  if (signals.renderError) {
+    reader.cancel().catch(() => {});
+    responseHeaders.set('X-Timber-Error', '1');
+    responseHeaders.set('content-type', 'application/json; charset=utf-8');
+    return new Response(
+      JSON.stringify({
+        error: true,
+        status: signals.renderError.status,
+      }),
+      { status: signals.renderError.status, headers: responseHeaders }
+    );
+  }
+
+  // Extract the first chunk from the race result.
+  // If the signal won the race but neither redirect nor deny was detected
+  // (edge case), cancel the reader immediately rather than issuing a bare
+  // read() that could hang forever if the RSC stream has stalled.
+  // See TIM-519.
+  let firstRead: ReadableStreamReadResult<Uint8Array>;
+  if (first.type === 'data') {
+    firstRead = first.chunk;
+  } else {
+    await reader.cancel();
+    firstRead = { done: true, value: undefined };
+  }
+
   // Reconstruct the stream: prepend the buffered first chunk,
   // then continue piping from the original reader.
   const patchedStream = new ReadableStream<Uint8Array>({
@@ -123,14 +196,20 @@ export async function buildRscPayloadResponse(
     responseHeaders.set('X-Timber-Skipped-Segments', JSON.stringify(skippedSegments));
   }
 
-  // Send route params so the client can populate useParams() after
-  // SPA navigation. Without this, useParams() returns {}.
-  if (Object.keys(match.params).length > 0) {
-    responseHeaders.set('X-Timber-Params', JSON.stringify(match.params));
+  // Send route params so the client can populate useSegmentParams() after
+  // SPA navigation. Without this, useSegmentParams() returns {}.
+  if (Object.keys(match.segmentParams).length > 0) {
+    responseHeaders.set('X-Timber-Params', JSON.stringify(match.segmentParams));
   }
 
+  // Check if a DenySignal was caught in-tree by AccessGate or
+  // PageDenyBoundary. The deny page is in the Flight stream as a normal
+  // element — use the deny status for the HTTP response. See TIM-666.
+  const { getDenyStatus } = await import('../deny-page-resolver.js');
+  const denyStatus = getDenyStatus();
+
   return new Response(patchedStream, {
-    status: 200,
+    status: denyStatus ?? 200,
     headers: responseHeaders,
   });
 }

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

@@ -10,30 +10,46 @@
  *              13-security.md §"Errors don't leak"
  */
 
-import { renderToReadableStream } from '#/rsc-runtime/rsc.js';
+import { renderToReadableStream } from '../../rsc-runtime/rsc.js';
 
-import { logRenderError } from '#/server/logger.js';
-import { DenySignal, RedirectSignal, RenderError } from '#/server/primitives.js';
-import { checkAndWarnRscPropError } from '#/server/rsc-prop-warnings.js';
+import { randomUUID } from 'node:crypto';
 
-import { createDebugChannelSink, isAbortError } from './helpers.js';
-import { isDebug } from '#/server/debug.js';
+import { logRenderError } from '../logger.js';
+import { DenySignal, RedirectSignal, RenderError } from '../primitives.js';
+import { checkAndWarnRscPropError } from '../rsc-prop-warnings.js';
+
+import {
+  createDebugChannelSink,
+  createDebugChannelCollector,
+  isAbortError,
+  type DebugComponentEntry,
+} from './helpers.js';
+import { isDebug } from '../debug.js';
+import { isDevMode } from '../debug.js';
 
 /**
  * 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;
   redirectSignal: RedirectSignal | null;
   renderError: { error: unknown; status: number } | null;
+  /** Callback fired when a redirect or deny signal is captured in onError. */
+  onSignal?: () => void;
 }
 
 export interface RscStreamResult {
   rscStream: ReadableStream<Uint8Array> | undefined;
   signals: RenderSignals;
+  /** Dev-only: server component debug info from the Flight debug channel. */
+  getDebugComponents?: () => DebugComponentEntry[];
 }
 
 /**
@@ -56,6 +72,10 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
 
   let rscStream: ReadableStream<Uint8Array> | undefined;
 
+  // In dev mode, collect debug channel data for the error overlay.
+  // In production, use the discard sink (no overhead).
+  const debugChannel = isDevMode() ? createDebugChannelCollector() : createDebugChannelSink();
+
   try {
     rscStream = renderToReadableStream(
       element,
@@ -67,11 +87,13 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
           if (isAbortError(error) || req.signal?.aborted) return;
           if (error instanceof DenySignal) {
             signals.denySignal = error;
+            signals.onSignal?.();
             // Return structured digest for client-side error boundaries
             return JSON.stringify({ type: 'deny', status: error.status, data: error.data });
           }
           if (error instanceof RedirectSignal) {
             signals.redirectSignal = error;
+            signals.onSignal?.();
             return JSON.stringify({
               type: 'redirect',
               location: error.location,
@@ -98,11 +120,7 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
           // 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')
-          ) {
+          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 " +
@@ -122,13 +140,42 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
             checkAndWarnRscPropError(error, new URL(req.url).pathname);
           }
 
-          // Track unhandled errors for pre-flush handling (500 status)
-          if (!signals.renderError) {
-            signals.renderError = { error, status: 500 };
-          }
-          logRenderError({ method: req.method, path: new URL(req.url).pathname, error });
+          // 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.
+
+          // 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,
+          });
+          return JSON.stringify({
+            type: 'error',
+            message: isDevMode()
+              ? error instanceof Error
+                ? error.message
+                : String(error)
+              : 'An unexpected error occurred.',
+            errorId,
+          });
         },
-        debugChannel: createDebugChannelSink(),
+        debugChannel,
       },
       {
         onClientReference(info: { id: string; name: string; deps: unknown }) {
@@ -156,5 +203,14 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
     }
   }
 
-  return { rscStream, signals };
+  return {
+    rscStream,
+    signals,
+    // Expose the debug channel collector's getComponents in dev mode.
+    // The caller can retrieve component tree info when handling errors.
+    getDebugComponents:
+      'getComponents' in debugChannel
+        ? (debugChannel as { getComponents: () => DebugComponentEntry[] }).getComponents
+        : undefined,
+  };
 }

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

@@ -4,15 +4,24 @@
 
 /// <reference types="@vitejs/plugin-rsc/types" />
 
-import type { NavContext } from '#/server/ssr-entry.js';
+import type { NavContext } from '../ssr-entry.js';
 
 export async function callSsr(
   rscStream: ReadableStream<Uint8Array>,
   navContext: NavContext
 ): Promise<Response> {
-  const ssrEntry = await import.meta.viteRsc.import<typeof import('#/server/ssr-entry.js')>(
-    '../ssr-entry.js',
-    { environment: 'ssr' }
-  );
+  let ssrEntry: typeof import('../ssr-entry.js');
+  try {
+    ssrEntry = await import.meta.viteRsc.import<typeof import('../ssr-entry.js')>(
+      '../ssr-entry.js',
+      { environment: 'ssr' }
+    );
+  } catch (error) {
+    const original = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `[timber] Failed to load SSR entry from RSC environment.\n  ${original}\n  This usually means a module evaluation error in the SSR bundle.`,
+      { cause: error }
+    );
+  }
   return ssrEntry.handleSsr(rscStream, navContext);
 }