@timber-js/app 0.1.21 → 0.1.23

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

@@ -0,0 +1,162 @@
+/**
+ * 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
+ * components during streaming. These signals are tracked in a shared
+ * `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"
+ */
+
+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 { createDebugChannelSink, isAbortError } from './helpers.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.
+ */
+export interface RenderSignals {
+  denySignal: DenySignal | null;
+  redirectSignal: RedirectSignal | null;
+  renderError: { error: unknown; status: number } | null;
+}
+
+export interface RscStreamResult {
+  rscStream: ReadableStream<Uint8Array> | undefined;
+  signals: RenderSignals;
+}
+
+/**
+ * Render a React element tree to an RSC Flight stream.
+ *
+ * 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.
+ */
+export function renderRscStream(
+  element: React.ReactElement,
+  req: Request
+): RscStreamResult {
+  const signals: RenderSignals = {
+    denySignal: null,
+    redirectSignal: null,
+    renderError: null,
+  };
+
+  let rscStream: ReadableStream<Uint8Array> | undefined;
+
+  try {
+    rscStream = renderToReadableStream(
+      element,
+      {
+        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 (error instanceof DenySignal) {
+            signals.denySignal = error;
+            // 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;
+            return JSON.stringify({
+              type: 'redirect',
+              location: error.location,
+              status: error.status,
+            });
+          }
+          if (error instanceof RenderError) {
+            // 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 (
+            process.env.NODE_ENV !== 'production' &&
+            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);
+          }
+
+          // 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 });
+        },
+        debugChannel: createDebugChannelSink(),
+      },
+      {
+        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 (error instanceof DenySignal) {
+      signals.denySignal = error;
+    } else if (error instanceof RedirectSignal) {
+      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: error instanceof RenderError ? error.status : 500,
+      };
+      logRenderError({ method: req.method, path: new URL(req.url).pathname, error });
+    }
+  }
+
+  return { rscStream, signals };
+}

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

@@ -0,0 +1,228 @@
+/**
+ * SSR Renderer — Pipes the RSC stream through SSR to produce HTML.
+ *
+ * Tees the RSC stream into two copies:
+ * 1. SSR stream — decoded and rendered to HTML
+ * 2. Inline stream — embedded as progressive <script> tags for hydration
+ *
+ * Handles signal promotion (redirect/deny discovered during SSR) and
+ * SSR shell failures (errors outside Suspense boundaries).
+ *
+ * Design docs: 02-rendering-pipeline.md §"RSC → SSR → Client Hydration",
+ *              05-streaming.md §"deferSuspenseFor and the Hold Window"
+ */
+
+import type { ClientBootstrapConfig } from '#/server/html-injectors.js';
+import type { LayoutEntry } from '#/server/deny-renderer.js';
+import { renderDenyPage } from '#/server/deny-renderer.js';
+import type { RouteMatch } from '#/server/pipeline.js';
+import { SsrStreamError } from '#/server/primitives.js';
+import type { LayoutComponentEntry } from '#/server/route-element-builder.js';
+import type { ManifestSegmentNode } from '#/server/route-matcher.js';
+import type { NavContext } from '#/server/ssr-entry.js';
+
+import {
+  buildRedirectResponse,
+  buildSegmentInfo,
+  createDebugChannelSink,
+  isAbortError,
+  parseCookiesFromHeader,
+} from './helpers.js';
+import { renderErrorPage } from './error-renderer.js';
+import { callSsr } from './ssr-bridge.js';
+import type { RenderSignals } from './rsc-stream.js';
+
+interface SsrRenderOptions {
+  req: Request;
+  rscStream: ReadableStream<Uint8Array>;
+  signals: RenderSignals;
+  segments: ManifestSegmentNode[];
+  layoutComponents: LayoutComponentEntry[];
+  match: RouteMatch;
+  responseHeaders: Headers;
+  clientBootstrap: ClientBootstrapConfig;
+  clientJsDisabled: boolean;
+  headHtml: string;
+  deferSuspenseFor: number;
+}
+
+/**
+ * Render the RSC stream to HTML via SSR.
+ *
+ * Progressive streaming: pipes the RSC stream directly to SSR without
+ * buffering. This enables proper Suspense streaming behavior.
+ *
+ * For async deny() (inside components that await before calling deny()),
+ * SSR will attempt to render the element tree progressively. Two outcomes:
+ *
+ * 1. deny() outside Suspense: the error appears in the RSC shell. SSR's
+ *    renderToReadableStream fails (rejects). We catch the failure, check
+ *    denySignal, and render the deny page with the correct status code.
+ *
+ * 2. deny() inside Suspense: the SSR shell succeeds (200 committed). The
+ *    error streams into the connection as a React error boundary. The
+ *    status is already committed — per design/05-streaming.md this is the
+ *    expected degraded behavior for deny inside Suspense.
+ */
+export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Response> {
+  const {
+    req,
+    rscStream,
+    signals,
+    segments,
+    layoutComponents,
+    match,
+    responseHeaders,
+    clientBootstrap,
+    clientJsDisabled,
+    headHtml,
+    deferSuspenseFor,
+  } = opts;
+
+  // Tee the RSC stream — one copy goes to SSR for HTML rendering,
+  // the other is inlined in the HTML for client-side hydration.
+  const [ssrStream, inlineStream] = rscStream.tee();
+
+  // Embed segment metadata in HTML for initial hydration.
+  // The client reads this to populate its segment cache before the
+  // first navigation, enabling state tree diffing from the start.
+  // Skipped when client JS is disabled — no client JS to consume it.
+  const segmentScript = clientJsDisabled
+    ? ''
+    : `<script>self.__timber_segments=${JSON.stringify(buildSegmentInfo(segments, layoutComponents))}</script>`;
+
+  // Embed route params in HTML so useParams() works on initial hydration.
+  // Without this, useParams() returns {} until the first client navigation.
+  const paramsScript =
+    clientJsDisabled || Object.keys(match.params).length === 0
+      ? ''
+      : `<script>self.__timber_params=${JSON.stringify(match.params)}</script>`;
+
+  const navContext: NavContext = {
+    pathname: new URL(req.url).pathname,
+    params: match.params,
+    searchParams: Object.fromEntries(new URL(req.url).searchParams),
+    statusCode: 200,
+    responseHeaders,
+    headHtml: headHtml + clientBootstrap.preloadLinks + segmentScript + paramsScript,
+    bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
+    // Skip RSC inline stream when client JS is disabled — no client to hydrate.
+    rscStream: clientJsDisabled ? undefined : inlineStream,
+    deferSuspenseFor: deferSuspenseFor > 0 ? deferSuspenseFor : undefined,
+    signal: req.signal,
+    cookies: parseCookiesFromHeader(req.headers.get('cookie') ?? ''),
+  };
+
+  // Helper: check if render-phase signals were captured and return the
+  // appropriate HTTP response. Used after both successful SSR (signal
+  // promotion from Suspense) and failed SSR (signal outside Suspense).
+  //
+  // When `skipHandledDeny` is true (SSR success path), skip DenySignal
+  // promotion if the denial was already handled by a TimberErrorBoundary
+  // (e.g., slot error boundary). The boundary sets navContext._denyHandledByBoundary
+  // during SSR rendering. See LOCAL-298.
+  function checkCapturedSignals(
+    skipHandledDeny = false
+  ): Response | Promise<Response> | null {
+    if (signals.redirectSignal) {
+      return buildRedirectResponse(req, signals.redirectSignal, responseHeaders);
+    }
+    if (signals.denySignal && !(skipHandledDeny && navContext._denyHandledByBoundary)) {
+      return renderDenyPage(
+        signals.denySignal,
+        segments,
+        layoutComponents as LayoutEntry[],
+        req,
+        match,
+        responseHeaders,
+        clientBootstrap,
+        createDebugChannelSink,
+        callSsr
+      );
+    }
+    if (signals.renderError) {
+      return renderErrorPage(
+        signals.renderError.error,
+        signals.renderError.status,
+        segments,
+        layoutComponents as LayoutEntry[],
+        req,
+        match,
+        responseHeaders,
+        clientBootstrap
+      );
+    }
+    return null;
+  }
+
+  try {
+    const ssrResponse = await callSsr(ssrStream, navContext);
+
+    // Signal promotion: yield one tick so async component rejections
+    // propagate to the RSC onError callback, then check if any signals
+    // were captured during rendering inside Suspense boundaries.
+    // The Response hasn't been sent yet — it's an unconsumed stream.
+    // See design/05-streaming.md §"deferSuspenseFor and the Hold Window"
+    await new Promise<void>((r) => setTimeout(r, 0));
+
+    const promoted = checkCapturedSignals(/* skipHandledDeny */ true);
+    if (promoted) {
+      ssrResponse.body?.cancel();
+      return promoted;
+    }
+    return ssrResponse;
+  } catch (ssrError) {
+    // Connection abort — the client disconnected (page refresh, navigation
+    // away). No response needed; return empty 499 (client closed request).
+    if (isAbortError(ssrError) || req.signal?.aborted) {
+      return new Response(null, { status: 499 });
+    }
+
+    // SsrStreamError: SSR's renderToReadableStream failed because the RSC
+    // stream contained an uncontained error (e.g., slot without error boundary).
+    // Render the deny/error page WITHOUT layout wrapping to avoid re-executing
+    // server components (which call headers()/cookies() and fail in SSR's
+    // separate ALS scope). See LOCAL-293.
+    if (ssrError instanceof SsrStreamError) {
+      if (signals.redirectSignal) {
+        return buildRedirectResponse(req, signals.redirectSignal, responseHeaders);
+      }
+      if (signals.denySignal) {
+        // Render deny page without layouts — pass empty layout list
+        return renderDenyPage(
+          signals.denySignal,
+          segments,
+          [] as LayoutEntry[],
+          req,
+          match,
+          responseHeaders,
+          clientBootstrap,
+          createDebugChannelSink,
+          callSsr
+        );
+      }
+      if (signals.renderError) {
+        return renderErrorPage(
+          signals.renderError.error,
+          signals.renderError.status,
+          segments,
+          [] as LayoutEntry[],
+          req,
+          match,
+          responseHeaders,
+          clientBootstrap
+        );
+      }
+      // No captured signal — return bare 500
+      return new Response(null, { status: 500, headers: responseHeaders });
+    }
+
+    // SSR shell rendering failed — the error was outside Suspense.
+    // Check captured signals (redirect, deny, render error).
+    const signalResponse = checkCapturedSignals();
+    if (signalResponse) return signalResponse;
+
+    // No tracked error — rethrow (infrastructure failure)
+    throw ssrError;
+  }
+}

package/src/server/rsc-prop-warnings.ts

@@ -0,0 +1,187 @@
+/**
+ * Dev-mode RSC prop serialization warnings.
+ *
+ * Detects common non-serializable types in React Flight errors and provides
+ * actionable suggestions with the specific fix for each type.
+ *
+ * React's dev build logs "Only plain objects can be passed to Client Components"
+ * but the message is generic. This module adds timber-specific context:
+ * - Identifies the exact type (RegExp, URL, class instance, etc.)
+ * - Suggests the specific fix (e.g., .toString() for RegExp, .href for URL)
+ * - References the serialization audit document
+ *
+ * Dev-only — zero overhead in production.
+ *
+ * Design doc: design/30-rsc-serialization-audit.md §"Identified Improvements" #1
+ * Task: TIM-358
+ */
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+export interface NonSerializableTypeInfo {
+  /** The detected type name (e.g., 'RegExp', 'URL', 'class instance'). */
+  type: string;
+  /** Actionable fix suggestion. */
+  suggestion: string;
+}
+
+// ─── Detection Patterns ──────────────────────────────────────────────────
+
+/**
+ * Detection rules for common non-serializable types.
+ *
+ * Each rule has a pattern to match against the error message and
+ * the type info to return if matched. Rules are checked in order;
+ * first match wins.
+ */
+const DETECTION_RULES: Array<{
+  pattern: RegExp;
+  info: NonSerializableTypeInfo;
+}> = [
+  {
+    pattern: /RegExp/i,
+    info: {
+      type: 'RegExp',
+      suggestion:
+        'Use .toString() to serialize, and new RegExp() to reconstruct on the client.',
+    },
+  },
+  {
+    // URL appears as a class instance error, but we detect it by name
+    pattern: /\bURL\b(?!SearchParams)/,
+    info: {
+      type: 'URL',
+      suggestion: 'Pass .href or .toString() instead of the URL object.',
+    },
+  },
+  {
+    pattern: /URLSearchParams/,
+    info: {
+      type: 'URLSearchParams',
+      suggestion:
+        'Pass .toString() to serialize, or spread entries: Object.fromEntries(params).',
+    },
+  },
+  {
+    pattern: /Headers/,
+    info: {
+      type: 'Headers',
+      suggestion:
+        'Convert to a plain object: Object.fromEntries(headers.entries()).',
+    },
+  },
+  {
+    pattern: /Symbol/i,
+    info: {
+      type: 'Symbol',
+      suggestion:
+        'Symbols cannot be serialized. Use a string identifier instead.',
+    },
+  },
+  {
+    pattern: /Functions cannot be passed/i,
+    info: {
+      type: 'function',
+      suggestion:
+        'Functions cannot cross the RSC boundary. Mark with "use server" for server actions, ' +
+        'or restructure to pass data instead of callbacks.',
+    },
+  },
+  {
+    pattern: /Classes or null prototypes/i,
+    info: {
+      type: 'class instance',
+      suggestion:
+        'Spread to a plain object: { ...instance } or extract the needed properties.',
+    },
+  },
+  {
+    // Generic fallback for "Only plain objects" errors not caught above
+    pattern: /Only plain objects can be passed to Client Components/i,
+    info: {
+      type: 'non-serializable object',
+      suggestion:
+        'Convert to a plain object or primitive before passing to a client component. ' +
+        'Supported types: string, number, boolean, null, undefined, Date, Map, Set, ' +
+        'BigInt, Promise, ArrayBuffer, TypedArray, and plain objects/arrays.',
+    },
+  },
+];
+
+// ─── Public API ───────────────────────────────────────────────────────────
+
+/**
+ * Detect a non-serializable type from an RSC error message.
+ *
+ * Returns type info with an actionable fix, or null if the error
+ * is not related to RSC prop serialization.
+ */
+export function detectNonSerializableType(
+  errorMessage: string
+): NonSerializableTypeInfo | null {
+  if (!errorMessage) return null;
+
+  for (const rule of DETECTION_RULES) {
+    if (rule.pattern.test(errorMessage)) {
+      return rule.info;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Format a human-readable warning message for a non-serializable RSC prop.
+ *
+ * Includes the type, suggestion, and a reference to the serialization audit doc.
+ *
+ * @param info - The detected type info
+ * @param requestPath - Optional request path for context
+ * @param originalMessage - Optional original error message for debugging
+ */
+export function formatRscPropWarning(
+  info: NonSerializableTypeInfo,
+  requestPath?: string,
+  originalMessage?: string
+): string {
+  let msg =
+    `Non-serializable RSC prop detected: ${info.type}\n` +
+    `  Fix: ${info.suggestion}\n` +
+    '  See: design/30-rsc-serialization-audit.md for full type support matrix';
+
+  if (requestPath) {
+    msg += `\n  Request: ${requestPath}`;
+  }
+
+  if (originalMessage) {
+    msg += `\n  Original error: ${originalMessage}`;
+  }
+
+  return msg;
+}
+
+/**
+ * Check an RSC onError error for non-serializable prop patterns and emit
+ * a dev warning if detected.
+ *
+ * Called from the RSC renderToReadableStream onError callback.
+ * No-ops in production.
+ *
+ * @param error - The error from onError
+ * @param requestPath - The request pathname for context
+ * @returns true if a warning was emitted
+ */
+export function checkAndWarnRscPropError(
+  error: unknown,
+  requestPath: string
+): boolean {
+  if (process.env.NODE_ENV === 'production') return false;
+  if (!(error instanceof Error)) return false;
+
+  const info = detectNonSerializableType(error.message);
+  if (!info) return false;
+
+  const warning = formatRscPropWarning(info, requestPath, error.message);
+  process.stderr.write(`\x1b[33m[timber]\x1b[0m ${warning}\n`);
+  return true;
+}