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

package/src/server/ssr-entry.ts

@@ -14,17 +14,68 @@
 
 // @ts-expect-error — virtual module provided by timber-entries plugin
 import config from 'virtual:timber-config';
-import { createFromReadableStream } from '#/rsc-runtime/ssr.js';
+// TIM-949: Populate the codec registry so server-rendered <Link> components
+// use codec.serialize() instead of String() fallback for URL interpolation.
+// @ts-expect-error — virtual module provided by timber-routing plugin
+import schemaCodecs from 'virtual:timber-schema';
+import { setLinkCodecs } from '../params/codec-registry.ts';
+setLinkCodecs(schemaCodecs);
+import {
+  createFromReadableStream,
+  createFromNodeStream,
+  hasNodeStreamDecode,
+} from '../rsc-runtime/ssr.ts';
 import { AsyncLocalStorage } from 'node:async_hooks';
 
-import { renderSsrStream, buildSsrResponse } from './ssr-render.js';
-import { formatSsrError } from './error-formatter.js';
-import { SsrStreamError } from './primitives.js';
-import { injectHead, injectRscPayload } from './html-injectors.js';
-import { withNuqsSsrAdapter } from './nuqs-ssr-provider.js';
-import { withSpan } from './tracing.js';
-import { setCurrentParams } from '#/client/use-params.js';
-import { registerSsrDataProvider, type SsrData } from '#/client/ssr-data.js';
+import {
+  renderSsrStream,
+  renderSsrNodeStream,
+  nodeReadableToWeb,
+  useNodeStreams,
+  buildSsrResponse,
+  type SsrStreamOptions,
+} from './ssr-render.ts';
+import { SsrStreamError } from './signal-identity.ts';
+import { createBufferedTransformStream, injectHead, injectRscPayload } from './html-injectors.ts';
+import { wrapSsrElement } from './ssr-wrappers.tsx';
+import { withSpan } from './tracing.ts';
+import { registerSsrDataProvider, type SsrData } from '../client/ssr-data.ts';
+import { splitPayloadRoot } from '../shared/payload-root.ts';
+import type { NavContext, SsrRenderResult } from './ssr-bridge-types.ts';
+
+// Pre-import Node.js stream modules at module load time — not per-request.
+// Dynamic imports of node-stream-transforms and node:stream/promises were
+// costing 3-17ms per request due to module resolution overhead.
+let _nodeStreamImports: {
+  createNodeBufferedTransform: typeof import('./node-stream-transforms.ts').createNodeBufferedTransform;
+  createNodeHeadInjector: typeof import('./node-stream-transforms.ts').createNodeHeadInjector;
+  createNodeMoveSuffixTransform: typeof import('./node-stream-transforms.ts').createNodeMoveSuffixTransform;
+  createNodeFlightInjector: typeof import('./node-stream-transforms.ts').createNodeFlightInjector;
+  runNodePipelineWithErrorHandling: typeof import('./node-stream-transforms.ts').runNodePipelineWithErrorHandling;
+  ReadableFromWeb: (
+    webStream: import('stream/web').ReadableStream
+  ) => import('node:stream').Readable;
+} | null = null;
+
+if (useNodeStreams) {
+  try {
+    const [transforms, stream] = await Promise.all([
+      import('./node-stream-transforms.ts'),
+      import('node:stream'),
+    ]);
+    _nodeStreamImports = {
+      createNodeBufferedTransform: transforms.createNodeBufferedTransform,
+      createNodeHeadInjector: transforms.createNodeHeadInjector,
+      createNodeMoveSuffixTransform: transforms.createNodeMoveSuffixTransform,
+      createNodeFlightInjector: transforms.createNodeFlightInjector,
+      runNodePipelineWithErrorHandling: transforms.runNodePipelineWithErrorHandling,
+      ReadableFromWeb: (webStream: import('stream/web').ReadableStream) =>
+        stream.Readable.fromWeb(webStream) as import('node:stream').Readable,
+    };
+  } catch {
+    // Fall back to Web Streams path
+  }
+}
 
 // ─── SSR Data ALS ─────────────────────────────────────────────────────────
 //
@@ -39,50 +90,6 @@ const ssrDataAls = new AsyncLocalStorage<SsrData>();
 // Register the ALS-backed provider so getSsrData() reads from ALS.
 registerSsrDataProvider(() => ssrDataAls.getStore());
 
-/**
- * Navigation context passed from the RSC environment to SSR.
- *
- * Per-request state must be explicitly passed across the RSC→SSR
- * environment boundary since they are separate Vite module graphs.
- */
-export interface NavContext {
-  /** The requested pathname */
-  pathname: string;
-  /** Extracted route params (catch-all segments produce string[]) */
-  params: Record<string, string | string[]>;
-  /** Search params from the URL */
-  searchParams: Record<string, string>;
-  /** The committed HTTP status code */
-  statusCode: number;
-  /** Response headers from middleware/proxy */
-  responseHeaders: Headers;
-  /** Pre-rendered metadata HTML to inject before </head> */
-  headHtml: string;
-  /** Inline JS for React's bootstrapScriptContent — kicks off module loading */
-  bootstrapScriptContent: string;
-  /** Tee'd RSC stream for client-side hydration (inlined into HTML) */
-  rscStream?: ReadableStream<Uint8Array>;
-  /** Max Suspense hold window (ms). SSR delays the first flush by this
-   *  duration, racing allReady so that fast-resolving boundaries render inline
-   *  without ever showing a fallback. Derived from route `deferSuspenseFor` exports.
-   *  See design/05-streaming.md §"deferSuspenseFor". */
-  deferSuspenseFor?: number;
-  /** Request abort signal. When the client disconnects (page refresh,
-   *  navigation away), this signal fires. Passed to renderToReadableStream
-   *  so React stops rendering and doesn't fire error boundaries for aborts. */
-  signal?: AbortSignal;
-  /** Request cookies as name→value pairs. Used by useCookie() during SSR
-   *  to return correct cookie values before hydration. */
-  cookies?: Map<string, string>;
-  /**
-   * Mutable flag: set by TimberErrorBoundary during SSR when it catches
-   * a DenySignal (via digest). This tells the RSC entry that the denial
-   * was contained by a slot error boundary and should NOT be promoted
-   * to a page-level deny. See LOCAL-298.
-   */
-  _denyHandledByBoundary?: boolean;
-}
-
 /**
  * Handle SSR: decode an RSC stream and render it to hydration-ready HTML.
  *
@@ -92,33 +99,35 @@ export interface NavContext {
  * 2. Render the decoded tree to HTML via renderToReadableStream (streaming)
  * 3. Wait for onShellReady before flushing (handled by renderSsrStream)
  * 4. Inject metadata into <head> and client scripts before </body>
- * 5. Return Response with navContext.statusCode and navContext.responseHeaders
+ * 5. Return the Response (navContext.statusCode, navContext.responseHeaders)
+ *    with the SSR sub-phase timings and whether Fizz allReady settled
+ *    within the hold window
  *
  * The RSC stream is piped progressively — not buffered. For deny() outside
  * Suspense, the RSC stream encodes an error in the shell region, causing
  * renderToReadableStream to reject. The error propagates back to the RSC
- * entry which renders the deny page. For deny() inside Suspense, the shell
+ * entry, which rethrows the captured DenySignal for the pipeline to render
+ * the deny page. For deny() inside Suspense, the shell
  * succeeds and the error streams as a React error boundary after flush.
  *
  * @param rscStream - The ReadableStream from the RSC environment
  * @param navContext - Per-request state passed across RSC→SSR boundary
- * @returns A Response containing the HTML stream with hydration markers
+ * @returns The HTML Response with hydration markers, plus SSR diagnostics
  */
 export async function handleSsr(
   rscStream: ReadableStream<Uint8Array>,
   navContext: NavContext
-): Promise<Response> {
+): Promise<SsrRenderResult> {
   return withSpan('timber.ssr', { 'timber.environment': 'ssr' }, async () => {
     const _runtimeConfig = config;
 
-    // Build per-request SSR data for client hooks (usePathname,
-    // useSearchParams, useCookie, useParams, etc.).
+    // Per-request SSR data for the client code with no React context to
+    // read during SSR (useCookie, <Link preserveSearchParams>; useSearchParams
+    // uses it only to detect SSR). Route params reach client components through
+    // ParamsContext, decoded from the payload root, not through here.
     const ssrData: SsrData = {
-      pathname: navContext.pathname,
-      searchParams: navContext.searchParams,
+      search: navContext.search,
       cookies: navContext.cookies ?? new Map(),
-      params: navContext.params,
-      _navContext: navContext,
     };
 
     // Run the entire render inside the SSR data ALS scope.
@@ -127,60 +136,172 @@ export async function handleSsr(
     // Client hooks read from getSsrData() which delegates to this
     // ALS store via the registered provider.
     return ssrDataAls.run(ssrData, async () => {
-      // Also set the module-level currentParams for useParams().
-      // useParams reads from getSsrData() during SSR (ALS-backed),
-      // but setCurrentParams is kept for the client-side path where
-      // the segment router updates params on navigation.
-      setCurrentParams(navContext.params);
-
       // Decode the RSC stream into a React element tree.
       // createFromReadableStream resolves client component references
       // (from "use client" modules) using the SSR environment's module
       // map, importing the actual components for server-side rendering.
-      const element = createFromReadableStream(rscStream) as React.ReactNode;
+      const _ssrStart = performance.now();
+
+      // Decode the RSC stream into a React element tree.
+      // On Node.js: convert Web ReadableStream → Node Readable → createFromNodeStream
+      //   (eliminates Promise-per-chunk overhead from Web Streams reader)
+      // On Workers: createFromReadableStream (Web Streams are V8-native C++ there)
+      //
+      // The request CSP nonce goes to the Flight decoder too: Flight emits
+      // `<script>` preinits for client-reference modules, and those need
+      // the nonce as much as timber's own inline tags do (TIM-1414).
+      const nonce = navContext.nonce;
+      let root: unknown;
+      if (hasNodeStreamDecode && _nodeStreamImports) {
+        const nodeRscStream = _nodeStreamImports.ReadableFromWeb(
+          rscStream as import('stream/web').ReadableStream
+        );
+        root = createFromNodeStream(nodeRscStream, { nonce });
+      } else {
+        root = createFromReadableStream(rscStream, { nonce });
+      }
+      // The payload root is `{ tree, params, slotParams }` — params ride
+      // beside the tree rather than in a provider around it (TIM-1297).
+      // splitPayloadRoot is the same split the browser performs: the tree
+      // renders, and the params half feeds PayloadRoot inside the wrapper
+      // chain so `useSegmentParams()` reads the identical derivation on
+      // both sides (TIM-1424).
+      const { tree, params } = splitPayloadRoot(root);
+      const element = tree as React.ReactNode;
+      const _decodeEnd = performance.now();
 
-      // Wrap with a server-safe nuqs adapter so that 'use client' components
-      // that call nuqs hooks (useQueryStates, useQueryState) can SSR correctly.
-      // The client-side TimberNuqsAdapter (injected by browser-entry.ts) takes
-      // over after hydration. This provider supplies the request's search params
-      // as a static snapshot so nuqs renders the right initial values on the server.
-      const wrappedElement = withNuqsSsrAdapter(navContext.searchParams, element);
+      // Wrap with the same component tree the client hydrates —
+      // real NavigationProvider and PayloadRoot, not no-op mirrors —
+      // so hooks resolve identically and useId() matches on both sides.
+      // See TIM-532, TIM-1424.
+      const hasTopLoader = _runtimeConfig.topLoader?.enabled !== false;
+      const wrappedElement = wrapSsrElement(element, {
+        pathname: navContext.pathname,
+        search: navContext.search,
+        paramsSource: params,
+        hasTopLoader,
+      });
 
       // Render to HTML stream (waits for onShellReady).
-      // Pass bootstrapScriptContent so React injects a non-deferred <script>
-      // in the shell HTML. This executes immediately during parsing — even
-      // while Suspense boundaries are still streaming — triggering module
-      // loading via dynamic import() so hydration can start early.
-      let htmlStream: ReadableStream<Uint8Array>;
-      try {
-        htmlStream = await renderSsrStream(wrappedElement, {
-          bootstrapScriptContent: navContext.bootstrapScriptContent || undefined,
-          deferSuspenseFor: navContext.deferSuspenseFor,
-          signal: navContext.signal,
-        });
-      } catch (renderError) {
-        // SSR shell rendering failed — the RSC stream contained an error
-        // that wasn't caught by any error boundary in the decoded tree.
-        // Wrap in SsrStreamError so the RSC entry can handle it without
-        // re-executing server components via renderDenyPage.
-        // See LOCAL-293.
-        console.error(
-          '[timber] SSR shell failed from RSC stream error:',
-          formatSsrError(renderError)
-        );
+      //
+      // Two paths based on platform:
+      // - Node.js: renderToPipeableStream → Node Transform pipeline → Readable.toWeb() → Response
+      //   Entire pipeline stays in C++ native streams until the Response boundary.
+      // - Workers: renderToReadableStream → Web TransformStream pipeline → Response
+      //   Web Streams are V8-native C++ built-ins on Workers.
+      //
+      // `onFizzAllReadyResolved` fires synchronously before the render
+      // promise resolves, so the flag is settled once the render is awaited.
+      const renderTimeoutMs = _runtimeConfig.renderTimeoutMs ?? undefined;
+      const requestInfo = { method: 'GET', path: navContext.pathname };
+      let fizzAllReadyResolved = false;
+      const renderOptions: SsrStreamOptions = {
+        bootstrapScriptContent: navContext.bootstrapScriptContent || undefined,
+        nonce,
+        deferSuspenseFor: navContext.deferSuspenseFor,
+        signal: navContext.signal,
+        renderTimeoutMs,
+        requestInfo,
+        onFizzAllReadyResolved: (resolved) => {
+          fizzAllReadyResolved = resolved;
+        },
+      };
+      // Not logged here. Fizz's onError (ssr-render.ts) has already logged a
+      // shell error SSR produced itself, and skips one Flight relayed,
+      // which the RSC onError (rsc-stream.ts) logged. Logging the rejection
+      // again doubled every shell failure (TIM-1537).
+      const renderFailed = (renderError: unknown): never => {
         throw new SsrStreamError(
           'SSR renderToReadableStream failed due to RSC stream error',
           renderError
         );
-      }
+      };
+
+      let outputStream: ReadableStream<Uint8Array>;
+      let _renderEnd: number;
+      if (_nodeStreamImports) {
+        // Node.js fast path: full pipeline in native streams
+        const {
+          createNodeBufferedTransform,
+          createNodeHeadInjector,
+          createNodeMoveSuffixTransform,
+          createNodeFlightInjector,
+          runNodePipelineWithErrorHandling,
+        } = _nodeStreamImports;
 
-      // Inject metadata into <head>, then interleave RSC payload chunks
-      // into the body as they arrive from the tee'd RSC stream.
-      let outputStream = injectHead(htmlStream, navContext.headHtml);
-      outputStream = injectRscPayload(outputStream, navContext.rscStream);
+        const nodeHtmlStream = await renderSsrNodeStream(wrappedElement, renderOptions).catch(
+          renderFailed
+        );
+        _renderEnd = performance.now();
+
+        // React 19.3+ emits <!DOCTYPE html> automatically when the root
+        // element is <html>, so no framework-level doctype prepend needed.
+        //
+        // Pipeline: buffer → headInjector → flightInjector → moveSuffix → output
+        //
+        // 1. buffer: coalesces Fizz micro-chunks into coherent fragments (TIM-528)
+        // 2. headInjector: injects metadata before </head>
+        // 3. flightInjector: interleaves RSC scripts between HTML chunks (TIM-529)
+        // 4. moveSuffix: strips </body></html>, re-emits at end (TIM-530)
+        //
+        // Post-shell error handling lives in the pump, not in a pipeline
+        // stage: pipeline() destroys every stage on failure, so only an
+        // output kept outside the pipeline can append the noindex script
+        // and close cleanly (TIM-1019).
+        // Resolve the lazy segment script now that the shell is ready
+        // (AccessGates have settled, ALS deny index is authoritative).
+        const resolvedHeadHtml = navContext.headHtml + (navContext.getHeadSegmentScript?.() ?? '');
+        const output = runNodePipelineWithErrorHandling(
+          nodeHtmlStream,
+          [
+            createNodeBufferedTransform(),
+            createNodeHeadInjector(resolvedHeadHtml),
+            createNodeFlightInjector(navContext.rscStream, {
+              renderTimeoutMs,
+              errorSignal: navContext._errorSignal,
+              nonce,
+            }),
+            createNodeMoveSuffixTransform(),
+          ],
+          navContext.signal,
+          nonce
+        );
+        outputStream = nodeReadableToWeb(output);
+      } else {
+        // Web Streams path (CF Workers / fallback)
+        const htmlStream = await renderSsrStream(wrappedElement, renderOptions).catch(renderFailed);
+        _renderEnd = performance.now();
+
+        // Pipeline: buffer → injectHead → injectRscPayload
+        //
+        // The buffered transform coalesces Fizz micro-chunks into coherent
+        // HTML fragments so downstream transforms never see chunk boundaries
+        // mid-tag. This prevents RSC script injection from breaking HTML
+        // structure (TIM-527).
+        // Resolve the lazy segment script now that the shell is ready
+        // (AccessGates have settled, ALS deny index is authoritative).
+        const resolvedHeadHtml = navContext.headHtml + (navContext.getHeadSegmentScript?.() ?? '');
+        outputStream = htmlStream.pipeThrough(createBufferedTransformStream());
+        outputStream = injectHead(outputStream, resolvedHeadHtml);
+        outputStream = injectRscPayload(outputStream, navContext.rscStream, {
+          renderTimeoutMs,
+          errorSignal: navContext._errorSignal,
+          nonce,
+        });
+      }
+      const _pipelineEnd = performance.now();
 
-      // Build and return the Response.
-      return buildSsrResponse(outputStream, navContext.statusCode, navContext.responseHeaders);
+      return {
+        response: buildSsrResponse(outputStream, navContext.statusCode, navContext.responseHeaders),
+        timings: {
+          decodeMs: Math.round(_decodeEnd - _ssrStart),
+          shellMs: Math.round(_renderEnd - _decodeEnd),
+          pipelineMs: Math.round(_pipelineEnd - _renderEnd),
+          totalMs: Math.round(_pipelineEnd - _ssrStart),
+          nodeStreams: _nodeStreamImports !== null,
+        },
+        fizzAllReadyResolved,
+      };
     });
   });
 }