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

package/src/server/ssr-render.ts

@@ -5,6 +5,17 @@
  * independently of the Vite RSC plugin runtime (which provides
  * createFromReadableStream for decoding RSC streams).
  *
+ * Uses a platform-adaptive rendering strategy:
+ * - **Node.js / Bun**: `renderToPipeableStream` — React pipes HTML chunks
+ *   through Node.js native streams (C++ implementation). Each chunk flows
+ *   through libuv buffers with zero Promise overhead.
+ * - **Cloudflare Workers / Edge**: `renderToReadableStream` — React outputs
+ *   to Web Streams which are V8-native C++ built-ins on these platforms.
+ *
+ * The detection is automatic at runtime. Both paths produce a Web
+ * `ReadableStream<Uint8Array>` so downstream transforms (injectHead,
+ * injectRscPayload, compression) work identically regardless of platform.
+ *
  * Design docs: 02-rendering-pipeline.md §"Single-Pass Rendering",
  *              18-build-system.md §"Entry Files"
  */
@@ -12,7 +23,38 @@
 import type { ReactNode } from 'react';
 import { renderToReadableStream } from 'react-dom/server';
 
-import { formatSsrError } from './error-formatter.js';
+import { createRenderTimeout, RenderTimeoutError } from './render-timeout.ts';
+import { logRenderError, logStreamingError } from './logger.ts';
+import { isAbortError, noindexScript } from './render-utils.ts';
+
+/**
+ * React's production error sanitization message. When NODE_ENV=production,
+ * React replaces all error messages with this string in renderToReadableStream
+ * and renderToPipeableStream. The original error was already logged by the
+ * RSC onError handler — logging the sanitized version in SSR is duplicate noise.
+ */
+const REACT_PROD_ERROR_PREFIX = 'An error occurred in the Server Components render';
+
+/**
+ * Returns true if this error was thrown in the RSC render and relayed by
+ * Flight, which means the RSC onError handler (rsc-stream.ts) already logged
+ * it with the full original message. Logging it again in SSR is a duplicate.
+ *
+ * In production React replaces a relayed error's message with a fixed
+ * sanitized one. In development it keeps the message, stamps the revived
+ * Error with the `environmentName` it was thrown in, and copies the digest
+ * our onError returned (`resolveErrorDev` and the `E` row in the Flight
+ * client). Both are needed: an Error passed as a *value* (a prop, `$Z`) is
+ * stamped with `environmentName` too but has no digest, and nothing logged
+ * it. When a client component throws one during SSR, it is logged here once,
+ * like any other error SSR throws itself (TIM-1537).
+ */
+function isFlightRelayedError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  if (error.message.startsWith(REACT_PROD_ERROR_PREFIX)) return true;
+  const digest: unknown = Reflect.get(error, 'digest');
+  return 'environmentName' in error && typeof digest === 'string' && digest !== '';
+}
 
 /**
  * Inline script that injects <meta name="robots" content="noindex"> into <head>.
@@ -25,96 +67,337 @@ import { formatSsrError } from './error-formatter.js';
  *
  * See design/05-streaming.md §"deny() inside Suspense"
  */
-const NOINDEX_SCRIPT =
-  '<script>document.head.appendChild(Object.assign(document.createElement("meta"),{name:"robots",content:"noindex"}))</script>';
+
+// ─── Platform Detection ──────────────────────────────────────────────────────
+//
+// Detect whether we're running on a platform with native Node.js streams.
+// On Node.js/Bun, `node:stream` is backed by C++ (libuv). On Cloudflare
+// Workers, `node:stream` via nodejs_compat is a JS polyfill — Web Streams
+// are the faster path there (V8-native C++ built-ins).
+//
+// We detect once at module load to avoid per-request overhead.
+// The check: process.versions.node exists AND we can import node:stream.
+// Cloudflare Workers with nodejs_compat may polyfill process.versions but
+// the streams won't be native. The Readable.toWeb check confirms native support.
+
+let _useNodeStreams = false;
+let _PassThrough: typeof import('node:stream').PassThrough | null = null;
+let _ReadableToWeb: ((readable: import('node:stream').Readable) => ReadableStream) | null = null;
+let _renderToPipeableStream: typeof import('react-dom/server').renderToPipeableStream | null = null;
+
+try {
+  // Dynamic imports to avoid bundling node:stream and the Node.js-specific
+  // react-dom/server entry for CF Workers builds.
+  // On Node.js/Bun this resolves to native C++ streams.
+  // On CF Workers this either fails or returns a JS polyfill.
+  const nodeStream = await import('node:stream');
+  if (
+    typeof nodeStream.PassThrough === 'function' &&
+    typeof nodeStream.Readable.toWeb === 'function' &&
+    // Real Node.js — not a polyfill. Polyfills typically don't set
+    // process.release.name to 'node'.
+    typeof process !== 'undefined' &&
+    process.release?.name === 'node'
+  ) {
+    // Dynamically import renderToPipeableStream from the Node.js-specific
+    // entry point. The SSR bundle resolves react-dom/server to the edge/browser
+    // export (which lacks renderToPipeableStream), so we import the .node file
+    // directly. This is safe because we're inside a process.release.name === 'node'
+    // guard — this code only runs on real Node.js.
+    const reactDomServer = await import('react-dom/server.node');
+    if (typeof reactDomServer.renderToPipeableStream === 'function') {
+      _useNodeStreams = true;
+      _PassThrough = nodeStream.PassThrough;
+      _ReadableToWeb = nodeStream.Readable.toWeb as (
+        readable: import('node:stream').Readable
+      ) => ReadableStream;
+      _renderToPipeableStream = reactDomServer.renderToPipeableStream;
+    }
+  }
+} catch {
+  // node:stream or renderToPipeableStream not available — use Web Streams path
+}
+
+/** Options shared by both SSR render paths (Node streams and Web Streams). */
+export interface SsrStreamOptions {
+  bootstrapScriptContent?: string;
+  /** Request CSP nonce — stamped by Fizz on the bootstrap and runtime scripts. */
+  nonce?: string;
+  deferSuspenseFor?: number;
+  signal?: AbortSignal;
+  renderTimeoutMs?: number;
+  /** Request info threaded into render-error logs (method/path). */
+  requestInfo?: { method: string; path: string };
+  /**
+   * Fired synchronously when the render function is about to resolve
+   * (i.e. at hold-end / shell-ready). `resolved` reports whether Fizz's
+   * allReady had already settled by that moment. The SSR entry returns it
+   * as `SsrRenderResult.fizzAllReadyResolved` so the RSC renderer can
+   * decide whether signal promotion can be short-circuited.
+   */
+  onFizzAllReadyResolved?: (resolved: boolean) => void;
+}
 
 /**
  * Render a React element tree to a ReadableStream of HTML.
  *
- * Uses renderToReadableStream (NOT renderToString) for streaming SSR.
+ * Automatically selects the optimal rendering path for the platform:
+ * - Node.js/Bun: `renderToPipeableStream` → Node.js native streams → `Readable.toWeb()`
+ * - CF Workers/Edge: `renderToReadableStream` → native Web Streams
+ *
  * The returned stream begins yielding after onShellReady — everything
  * outside <Suspense> boundaries is in the shell.
  *
- * With progressive streaming, the RSC stream is piped directly to SSR
- * without buffering. If deny() was called outside a Suspense boundary,
- * the RSC stream encodes an error in the shell — renderToReadableStream
- * rejects, and the RSC entry catches this to render a deny page with
- * the correct HTTP status code. If deny() was inside Suspense, the shell
- * succeeds (200 committed) and the error streams as an error boundary.
- *
  * @param element - The React element tree decoded from the RSC stream
  * @param options - Optional configuration
- * @param options.bootstrapScriptContent - Inline JS injected by React as a
- *   non-deferred `<script>` in the shell HTML. Executes immediately during
- *   parsing — even while Suspense boundaries are still streaming. Used to
- *   kick off module loading via dynamic `import()` so hydration can start
- *   before the HTML stream closes.
  * @returns A ReadableStream of HTML bytes with hydration markers
  */
 export async function renderSsrStream(
   element: ReactNode,
-  options?: { bootstrapScriptContent?: string; deferSuspenseFor?: number; signal?: AbortSignal }
+  options?: SsrStreamOptions
 ): Promise<ReadableStream<Uint8Array>> {
+  return renderViaReadableStream(element, options);
+}
+
+/** Whether the current platform uses native Node.js streams for SSR. */
+export const useNodeStreams = _useNodeStreams;
+
+// ─── Node.js Path: renderToPipeableStream ────────────────────────────────────
+//
+// Uses React's Node.js-native API. HTML chunks flow through C++ stream
+// buffers with zero Promise allocations per chunk. Returns a Node.js
+// Readable — the caller (ssr-entry.ts) pipes through Node.js Transform
+// streams for injectHead/injectRscPayload before converting to Web
+// ReadableStream at the Response boundary.
+
+/**
+ * Render via renderToPipeableStream, returning a Node.js Readable.
+ *
+ * The entire HTML rendering + post-processing pipeline stays in native
+ * Node.js streams (C++ backed). Only converted to Web ReadableStream
+ * at the very end for the Response body.
+ */
+export async function renderSsrNodeStream(
+  element: ReactNode,
+  options?: SsrStreamOptions
+): Promise<import('node:stream').Readable> {
   const signal = options?.signal;
-  const stream = await renderToReadableStream(element, {
-    bootstrapScriptContent: options?.bootstrapScriptContent || undefined,
-    signal,
-    onError(error: unknown) {
-      // Suppress logging for connection aborts — the user refreshed or
-      // navigated away, not an application error.
-      if (isAbortError(error) || signal?.aborted) return;
-      console.error('[timber] SSR render error:', formatSsrError(error));
-    },
+  const deferMs = options?.deferSuspenseFor;
+  const timeoutMs = options?.renderTimeoutMs;
+  const requestInfo = options?.requestInfo;
+  const onFizzAllReadyResolved = options?.onFizzAllReadyResolved;
+
+  return new Promise<import('node:stream').Readable>((resolve, reject) => {
+    const passthrough = new _PassThrough!();
+
+    let allReadyResolve: (() => void) | null = null;
+    let allReadyReject: ((reason?: unknown) => void) | null = null;
+    let allReadyFired = false;
+    const allReady = new Promise<void>((resolve, reject) => {
+      allReadyResolve = resolve;
+      allReadyReject = reject;
+    });
+    allReady.catch(() => {});
+
+    const { pipe, abort } = _renderToPipeableStream!(element, {
+      bootstrapScriptContent: options?.bootstrapScriptContent || undefined,
+      nonce: options?.nonce,
+
+      onShellReady() {
+        if (deferMs && deferMs > 0) {
+          Promise.race([allReady, new Promise<void>((r) => setTimeout(r, deferMs))]).then(() => {
+            onFizzAllReadyResolved?.(allReadyFired);
+            pipe(passthrough);
+            resolve(passthrough);
+          });
+        } else {
+          // No hold — allReady has almost certainly not fired yet.
+          // Report false so the RSC entry runs the microtask retry loop.
+          onFizzAllReadyResolved?.(allReadyFired);
+          pipe(passthrough);
+          resolve(passthrough);
+        }
+      },
+
+      onAllReady() {
+        allReadyFired = true;
+        allReadyResolve?.();
+      },
+
+      onShellError(error: unknown) {
+        // Reject allReady so the render timeout is cancelled.
+        // Without this, a pre-shell failure leaves the timer
+        // running for the full timeout window.
+        allReadyReject?.(error);
+        reject(error);
+      },
+
+      onError(error: unknown) {
+        if (isAbortError(error) || signal?.aborted) return;
+        // Skip errors Flight relayed — the original was already logged by
+        // the RSC onError with full details.
+        if (isFlightRelayedError(error)) return;
+        logRenderError({
+          method: requestInfo?.method ?? '',
+          path: requestInfo?.path ?? '',
+          error,
+        });
+      },
+    });
+
+    // Wire abort to both request signal AND render timeout.
+    // If the client stays connected but a downstream fetch hangs,
+    // the timeout ensures abort() is eventually called.
+    if (signal) {
+      if (signal.aborted) {
+        abort();
+      } else {
+        signal.addEventListener('abort', () => abort(), { once: true });
+      }
+    }
+
+    if (timeoutMs && timeoutMs > 0) {
+      const renderTimeout = createRenderTimeout(timeoutMs, signal);
+      renderTimeout.signal.addEventListener(
+        'abort',
+        () => {
+          logRenderError({
+            method: requestInfo?.method ?? '',
+            path: requestInfo?.path ?? '',
+            error: new Error(
+              `SSR render timed out after ${timeoutMs}ms — aborting. ` +
+                'A Suspense component or downstream fetch may be hanging.'
+            ),
+          });
+          abort(renderTimeout.signal.reason);
+        },
+        { once: true }
+      );
+      // Cancel the timeout when the render completes OR on pre-shell
+      // failure. Without the catch branch, onShellError → reject()
+      // would leave the timer running for the full timeout window.
+      allReady.then(
+        () => renderTimeout.cancel(),
+        () => renderTimeout.cancel()
+      );
+    }
   });
+}
+
+/** Convert a Node.js Readable to a Web ReadableStream (zero-copy bridge). */
+export function nodeReadableToWeb(
+  readable: import('node:stream').Readable
+): ReadableStream<Uint8Array> {
+  return _ReadableToWeb!(readable) as ReadableStream<Uint8Array>;
+}
+
+// ─── Web Streams Path: renderToReadableStream ────────────────────────────────
+//
+// Uses React's Web Streams API. On Cloudflare Workers, ReadableStream is a
+// V8-native C++ built-in, making this the fastest path for that platform.
+// On Node.js, Web Streams are a JS reimplementation — slower, but this path
+// is only used as a fallback when Node.js native streams aren't available.
+
+async function renderViaReadableStream(
+  element: ReactNode,
+  options?: SsrStreamOptions
+): Promise<ReadableStream<Uint8Array>> {
+  const signal = options?.signal;
+  const timeoutMs = options?.renderTimeoutMs;
+  const requestInfo = options?.requestInfo;
+  const onFizzAllReadyResolved = options?.onFizzAllReadyResolved;
+
+  // If a render timeout is configured, create a combined signal that
+  // fires on either request abort OR timeout — whichever comes first.
+  let renderTimeout: import('./render-timeout.ts').RenderTimeout | null = null;
+  let effectiveSignal = signal;
+  if (timeoutMs && timeoutMs > 0) {
+    renderTimeout = createRenderTimeout(timeoutMs, signal);
+    effectiveSignal = renderTimeout.signal;
+  }
+
+  let stream: Awaited<ReturnType<typeof renderToReadableStream>>;
+  try {
+    stream = await renderToReadableStream(element, {
+      bootstrapScriptContent: options?.bootstrapScriptContent || undefined,
+      nonce: options?.nonce,
+      signal: effectiveSignal,
+      onError(error: unknown) {
+        if (isAbortError(error) || effectiveSignal?.aborted) return;
+        if (error instanceof RenderTimeoutError) {
+          logRenderError({
+            method: requestInfo?.method ?? '',
+            path: requestInfo?.path ?? '',
+            error: new Error(
+              `SSR render timed out after ${timeoutMs}ms — aborting. ` +
+                'A Suspense component or downstream fetch may be hanging.'
+            ),
+          });
+          return;
+        }
+        // Skip errors Flight relayed — the original was already logged by
+        // the RSC onError with full details.
+        if (isFlightRelayedError(error)) return;
+        logRenderError({
+          method: requestInfo?.method ?? '',
+          path: requestInfo?.path ?? '',
+          error,
+        });
+      },
+    });
+  } catch (error) {
+    // Pre-shell failure (e.g. RSC stream error). Cancel the render
+    // timeout so it doesn't leak a timer + abort callback for the
+    // full timeout window. Under repeated pre-shell failures this
+    // would accumulate unnecessary timers.
+    renderTimeout?.cancel();
+    throw error;
+  }
 
   // Prevent unhandled promise rejection from streaming-phase errors.
-  // React DOM Server exposes `allReady` — a promise that resolves when
-  // ALL content (including Suspense boundaries) has been rendered. If a
-  // streaming-phase error occurs (e.g. React boundary flush failure),
-  // `allReady` rejects independently of the stream. Without this catch,
-  // the rejection becomes an unhandled promise rejection that crashes
-  // the Node.js process.
   stream.allReady.catch(() => {});
 
+  // Cancel the render timeout once allReady resolves (render completed).
+  if (renderTimeout) {
+    stream.allReady.then(() => renderTimeout!.cancel()).catch(() => renderTimeout!.cancel());
+  }
+
   // deferSuspenseFor hold: delay the first read so React can resolve
   // fast-completing Suspense boundaries before we read the shell HTML.
-  // renderToReadableStream generates HTML lazily on pull — if we wait
-  // before reading, React resolves pending boundaries and inlines their
-  // content instead of serializing fallbacks. Race allReady against
-  // deferSuspenseFor so we don't wait longer than necessary.
   // See design/05-streaming.md §"deferSuspenseFor"
+  //
+  // While we're holding, also track whether `stream.allReady` settled
+  // before the timer. That boolean is the Option-1 signal-promotion
+  // short-circuit key — see SsrRenderResult.fizzAllReadyResolved and
+  // design/spike-signal-promotion-protocol.md.
+  let fizzAllReadyResolved = false;
+  const allReadyTap = stream.allReady.then(
+    () => {
+      fizzAllReadyResolved = true;
+    },
+    () => {
+      // allReady rejections are already swallowed above; keep false.
+    }
+  );
   const deferMs = options?.deferSuspenseFor;
   if (deferMs && deferMs > 0) {
-    await Promise.race([
-      stream.allReady,
-      new Promise<void>((resolve) => setTimeout(resolve, deferMs)),
-    ]);
+    await Promise.race([allReadyTap, new Promise<void>((resolve) => setTimeout(resolve, deferMs))]);
   }
+  onFizzAllReadyResolved?.(fizzAllReadyResolved);
 
-  // renderToReadableStream resolves after onShellReady by default.
-  // The stream is ready to read — the shell (everything outside
-  // Suspense boundaries) is available. Suspense content streams
-  // into the open connection as it resolves.
-  //
-  // Wrap the stream in an error-resilient transform. With progressive
-  // streaming, errors inside Suspense boundaries (e.g. deny() or throws
-  // in async components) cause React's stream to error during the flush
-  // phase. The onError callback logs the error, but the stream error
-  // would become an unhandled promise rejection and crash the process.
-  // The transform catches these post-shell streaming errors and closes
-  // the stream cleanly — the shell (with correct status code) has
-  // already been sent.
-  return wrapStreamWithErrorHandling(stream, signal);
+  return wrapStreamWithErrorHandling(stream, signal, options?.nonce);
 }
 
+// ─── Shared Utilities ────────────────────────────────────────────────────────
+
 /**
  * Wrap an HTML stream with error handling for the streaming phase.
  *
  * During progressive RSC→SSR streaming, errors in Suspense boundaries
  * (e.g. deny() inside Suspense, throws in async components) cause
- * React DOM's renderToReadableStream to error after the shell has been
- * flushed. Without this wrapper, the stream error becomes an unhandled
- * promise rejection that crashes the process.
+ * React DOM's stream to error after the shell has been flushed. Without
+ * this wrapper, the stream error becomes an unhandled promise rejection
+ * that crashes the process.
  *
  * The wrapper catches streaming-phase errors, logs them, and closes
  * the output stream cleanly. The shell (headers, status code, content
@@ -123,7 +406,8 @@ export async function renderSsrStream(
 /** @internal Exported for testing only. */
 export function wrapStreamWithErrorHandling(
   stream: ReadableStream<Uint8Array>,
-  signal?: AbortSignal
+  signal?: AbortSignal,
+  nonce?: string
 ): ReadableStream<Uint8Array> {
   const reader = stream.getReader();
   const encoder = new TextEncoder();
@@ -138,19 +422,12 @@ export function wrapStreamWithErrorHandling(
         }
         controller.enqueue(value);
       } catch (error) {
-        // Connection abort (user refreshed or navigated away) — close
-        // silently without logging. This is not an application error.
         if (isAbortError(error) || signal?.aborted) {
           controller.close();
           return;
         }
-        // Streaming-phase error (e.g. React boundary flush failure,
-        // deny() or throw inside Suspense after flush).
-        // The shell has already been sent with status 200. Inject a
-        // noindex meta tag so search engines don't index this error page,
-        // then close cleanly. See design/05-streaming.md.
-        console.error('[timber] SSR streaming error (post-shell):', formatSsrError(error));
-        controller.enqueue(encoder.encode(NOINDEX_SCRIPT));
+        logStreamingError({ error });
+        controller.enqueue(encoder.encode(noindexScript(nonce)));
         controller.close();
       }
     },
@@ -160,41 +437,27 @@ export function wrapStreamWithErrorHandling(
   });
 }
 
-/**
- * Check if an error is an abort error (connection closed by client).
- *
- * When the browser aborts a request (page refresh, navigation away),
- * the AbortSignal fires and React/streams throw an AbortError. This
- * is not an application error — suppress it from error boundaries and logs.
- */
-function isAbortError(error: unknown): boolean {
-  if (error instanceof DOMException && error.name === 'AbortError') return true;
-  if (error instanceof Error && error.name === 'AbortError') return true;
-  return false;
-}
-
 /**
  * Build a Response from the SSR HTML stream with the correct
  * status code and headers from the navigation context.
  *
- * Sets content-type to text/html if not already set by middleware.
+ * React 19.3+ automatically emits `<!DOCTYPE html>` when the root
+ * element is `<html>`, so no framework-level doctype prepending is needed.
  *
- * @param htmlStream - The HTML stream from renderSsrStream
- * @param statusCode - The committed HTTP status code from RSC
- * @param responseHeaders - Response headers from middleware/proxy
- * @returns A Response ready to send to the client
+ * Sets content-type to text/html if not already set by middleware. The
+ * default goes on a response-local copy: `responseHeaders` is the
+ * pipeline's shared bag, handed over on `NavContext`, and SSR only reads
+ * it (design/49 §"A2").
  */
 export function buildSsrResponse(
   htmlStream: ReadableStream<Uint8Array>,
   statusCode: number,
   responseHeaders: Headers
 ): Response {
-  if (!responseHeaders.has('content-type')) {
-    responseHeaders.set('content-type', 'text/html; charset=utf-8');
+  const headers = new Headers(responseHeaders);
+  if (!headers.has('content-type')) {
+    headers.set('content-type', 'text/html; charset=utf-8');
   }
 
-  return new Response(htmlStream, {
-    status: statusCode,
-    headers: responseHeaders,
-  });
+  return new Response(htmlStream, { status: statusCode, headers });
 }