@timber-js/app 0.2.0-alpha.12 → 0.2.0-alpha.120

package/src/server/ssr-entry.ts

@@ -14,17 +14,70 @@
 
 // @ts-expect-error — virtual module provided by timber-entries plugin
 import config from 'virtual:timber-config';
-import { createFromReadableStream } from '#/rsc-runtime/ssr.js';
+// TIM-830: Populate the search-params registry eagerly so <Link> rendered
+// during SSR can serialize flat `Partial<T>` values via registry lookup.
+// @ts-expect-error — virtual module provided by timber-routing plugin
+import 'virtual:timber-search-params-registry';
+import {
+  createFromReadableStream,
+  createFromNodeStream,
+  hasNodeStreamDecode,
+} from '../rsc-runtime/ssr.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 
-import { renderSsrStream, buildSsrResponse } from './ssr-render.js';
-import { formatSsrError } from './error-formatter.js';
+import {
+  renderSsrStream,
+  renderSsrNodeStream,
+  nodeReadableToWeb,
+  useNodeStreams,
+  buildSsrResponse,
+} from './ssr-render.js';
+import { logRenderError } from './logger.js';
 import { SsrStreamError } from './primitives.js';
-import { injectHead, injectRscPayload } from './html-injectors.js';
-import { withNuqsSsrAdapter } from './nuqs-ssr-provider.js';
+import { createBufferedTransformStream, injectHead, injectRscPayload } from './html-injectors.js';
+import { wrapSsrElement } from './ssr-wrappers.js';
 import { withSpan } from './tracing.js';
-import { setCurrentParams } from '#/client/use-params.js';
-import { registerSsrDataProvider, type SsrData } from '#/client/ssr-data.js';
+import { setCurrentParams } from '../client/use-segment-params.js';
+import { registerSsrDataProvider, type SsrData } from '../client/ssr-data.js';
+
+// 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.js').createNodeBufferedTransform;
+  createNodeHeadInjector: typeof import('./node-stream-transforms.js').createNodeHeadInjector;
+  createNodeMoveSuffixTransform: typeof import('./node-stream-transforms.js').createNodeMoveSuffixTransform;
+  createNodeFlightInjector: typeof import('./node-stream-transforms.js').createNodeFlightInjector;
+  createNodeErrorHandler: typeof import('./node-stream-transforms.js').createNodeErrorHandler;
+  pipeline: typeof import('node:stream/promises').pipeline;
+  PassThrough: typeof import('node:stream').PassThrough;
+  ReadableFromWeb: (
+    webStream: import('stream/web').ReadableStream
+  ) => import('node:stream').Readable;
+} | null = null;
+
+if (useNodeStreams) {
+  try {
+    const [transforms, streamPromises, stream] = await Promise.all([
+      import('./node-stream-transforms.js'),
+      import('node:stream/promises'),
+      import('node:stream'),
+    ]);
+    _nodeStreamImports = {
+      createNodeBufferedTransform: transforms.createNodeBufferedTransform,
+      createNodeHeadInjector: transforms.createNodeHeadInjector,
+      createNodeMoveSuffixTransform: transforms.createNodeMoveSuffixTransform,
+      createNodeFlightInjector: transforms.createNodeFlightInjector,
+      createNodeErrorHandler: transforms.createNodeErrorHandler,
+      pipeline: streamPromises.pipeline,
+      PassThrough: stream.PassThrough,
+      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 ─────────────────────────────────────────────────────────
 //
@@ -81,6 +134,37 @@ export interface NavContext {
    * to a page-level deny. See LOCAL-298.
    */
   _denyHandledByBoundary?: boolean;
+
+  /**
+   * Mutable: SSR timing data populated by handleSsr().
+   * Read by the RSC entry to record sub-phase Server-Timing entries
+   * when `serverTiming: 'detailed'` is configured.
+   *
+   * This bridges the RSC→SSR environment boundary: the SSR entry populates
+   * these fields, the RSC entry reads them after callSsr() returns.
+   */
+  _ssrTimings?: {
+    /** Time to decode RSC stream (createFromReadableStream/createFromNodeStream) */
+    decodeMs: number;
+    /** Time for Fizz to render the shell (onShellReady) */
+    shellMs: number;
+    /** Time for pipe() to flush shell bytes to the output stream */
+    pipeMs: number;
+    /** Time to set up Node.js Transform pipeline / Web Stream transforms */
+    pipelineMs: number;
+    /** Total SSR time (decode → response ready) */
+    totalMs: number;
+    /** Whether the Node.js native stream path was used */
+    nodeStreams: boolean;
+  };
+
+  /**
+   * Signal that fires when an unhandled RSC error is detected.
+   * The Flight injector checks this before writing each script tag —
+   * when aborted, it stops injecting Flight data to prevent corrupted
+   * chunks from crashing the client's Flight decoder.
+   */
+  _errorSignal?: AbortSignal;
 }
 
 /**
@@ -127,7 +211,7 @@ 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().
+      // Also set the module-level currentParams for useSegmentParams().
       // 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.
@@ -137,47 +221,160 @@ export async function handleSsr(
       // 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)
+      let element: React.ReactNode;
+      if (hasNodeStreamDecode && _nodeStreamImports) {
+        const nodeRscStream = _nodeStreamImports.ReadableFromWeb(
+          rscStream as import('stream/web').ReadableStream
+        );
+        element = createFromNodeStream(nodeRscStream) as React.ReactNode;
+      } else {
+        element = createFromReadableStream(rscStream) 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 structure as the client hydration
+      // tree (NavigationRoot → PendingNavigationProvider → TopLoader →
+      // TimberNuqsAdapter → NuqsAdapterProvider → NavigationProvider).
+      // This ensures useId() produces matching IDs on both sides, preventing
+      // hydration mismatches in libraries like Radix UI. See TIM-532.
+      const hasTopLoader = _runtimeConfig.topLoader?.enabled !== false;
+      const wrappedElement = wrapSsrElement(element, navContext.searchParams, 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.
+      //
+      // 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.
+      if (_nodeStreamImports) {
+        // Node.js fast path: full pipeline in native streams
+        const {
+          createNodeBufferedTransform,
+          createNodeHeadInjector,
+          createNodeMoveSuffixTransform,
+          createNodeFlightInjector,
+          createNodeErrorHandler,
+          pipeline,
+          PassThrough,
+        } = _nodeStreamImports;
+
+        const renderTimeoutMs = _runtimeConfig.renderTimeoutMs ?? undefined;
+
+        let nodeHtmlStream: import('node:stream').Readable;
+        try {
+          nodeHtmlStream = await renderSsrNodeStream(wrappedElement, {
+            bootstrapScriptContent: navContext.bootstrapScriptContent || undefined,
+            deferSuspenseFor: navContext.deferSuspenseFor,
+            signal: navContext.signal,
+            renderTimeoutMs,
+          });
+        } catch (renderError) {
+          logRenderError({ method: '', path: '', error: renderError });
+          throw new SsrStreamError(
+            'SSR renderToReadableStream failed due to RSC stream error',
+            renderError
+          );
+        }
+        const _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 → errorHandler → headInjector → flightInjector → moveSuffix → output
+        //
+        // 1. buffer: coalesces Fizz micro-chunks into coherent fragments (TIM-528)
+        // 2. errorHandler: catches post-shell streaming errors
+        // 3. headInjector: injects metadata before </head>
+        // 4. flightInjector: interleaves RSC scripts between HTML chunks (TIM-529)
+        // 5. moveSuffix: strips </body></html>, re-emits at end (TIM-530)
+        const bufferedTransform = createNodeBufferedTransform();
+        const errorHandler = createNodeErrorHandler(navContext.signal);
+        const headInjector = createNodeHeadInjector(navContext.headHtml);
+        const flightInjector = createNodeFlightInjector(navContext.rscStream, {
+          renderTimeoutMs,
+          errorSignal: navContext._errorSignal,
+        });
+        const moveSuffix = createNodeMoveSuffixTransform();
+
+        const output = new PassThrough();
+        pipeline(
+          nodeHtmlStream,
+          bufferedTransform,
+          errorHandler,
+          headInjector,
+          flightInjector,
+          moveSuffix,
+          output
+        ).catch(() => {
+          // Pipeline errors are handled by errorHandler transform
+        });
+        const _pipelineEnd = performance.now();
+
+        // Record SSR sub-timings for Server-Timing header (detailed mode).
+        navContext._ssrTimings = {
+          decodeMs: Math.round(_decodeEnd - _ssrStart),
+          shellMs: Math.round(_renderEnd - _decodeEnd),
+          pipeMs: 0, // pipe() timing is inside renderSsrNodeStream
+          pipelineMs: Math.round(_pipelineEnd - _renderEnd),
+          totalMs: Math.round(_pipelineEnd - _ssrStart),
+          nodeStreams: true,
+        };
+
+        const webStream = nodeReadableToWeb(output);
+        return buildSsrResponse(webStream, navContext.statusCode, navContext.responseHeaders);
+      }
+
+      // Web Streams path (CF Workers / fallback)
+      const renderTimeoutMs = _runtimeConfig.renderTimeoutMs ?? undefined;
       let htmlStream: ReadableStream<Uint8Array>;
       try {
         htmlStream = await renderSsrStream(wrappedElement, {
           bootstrapScriptContent: navContext.bootstrapScriptContent || undefined,
           deferSuspenseFor: navContext.deferSuspenseFor,
           signal: navContext.signal,
+          renderTimeoutMs,
         });
       } 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)
-        );
+        logRenderError({ method: '', path: '', error: renderError });
         throw new SsrStreamError(
           'SSR renderToReadableStream failed due to RSC stream error',
           renderError
         );
       }
 
-      // 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 _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).
+      let outputStream = htmlStream.pipeThrough(createBufferedTransformStream());
+      outputStream = injectHead(outputStream, navContext.headHtml);
+      outputStream = injectRscPayload(
+        outputStream,
+        navContext.rscStream,
+        renderTimeoutMs,
+        navContext._errorSignal
+      );
+      const _pipelineEnd = performance.now();
+
+      navContext._ssrTimings = {
+        decodeMs: Math.round(_decodeEnd - _ssrStart),
+        shellMs: Math.round(_renderEnd - _decodeEnd),
+        pipeMs: 0,
+        pipelineMs: Math.round(_pipelineEnd - _renderEnd),
+        totalMs: Math.round(_pipelineEnd - _ssrStart),
+        nodeStreams: false,
+      };
 
       // Build and return the Response.
       return buildSsrResponse(outputStream, navContext.statusCode, navContext.responseHeaders);