@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

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,
+} from './ssr-render.ts';
+import { logRenderError } from './logger.ts';
+import { SsrStreamError } from './primitives.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 } 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.
  *
@@ -115,9 +122,10 @@ export async function handleSsr(
     // useSearchParams, useCookie, useParams, etc.).
     const ssrData: SsrData = {
       pathname: navContext.pathname,
-      searchParams: navContext.searchParams,
+      search: navContext.search,
       cookies: navContext.cookies ?? new Map(),
-      params: navContext.params,
+      params: navContext.segmentParams,
+      slotParams: navContext.slotParams,
       _navContext: navContext,
     };
 
@@ -127,57 +135,194 @@ 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.
+      //
+      // 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,
+          runNodePipelineWithErrorHandling,
+        } = _nodeStreamImports;
+
+        const renderTimeoutMs = _runtimeConfig.renderTimeoutMs ?? undefined;
+        const requestInfo = { method: 'GET', path: navContext.pathname };
+
+        let nodeHtmlStream: import('node:stream').Readable;
+        try {
+          nodeHtmlStream = await renderSsrNodeStream(wrappedElement, {
+            bootstrapScriptContent: navContext.bootstrapScriptContent || undefined,
+            nonce,
+            deferSuspenseFor: navContext.deferSuspenseFor,
+            signal: navContext.signal,
+            renderTimeoutMs,
+            requestInfo,
+            onFizzAllReadyResolved: (resolved) => {
+              navContext._fizzAllReadyResolved = resolved;
+            },
+          });
+        } catch (renderError) {
+          logRenderError({ ...requestInfo, 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 → 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 bufferedTransform = createNodeBufferedTransform();
+        const headInjector = createNodeHeadInjector(resolvedHeadHtml);
+        const flightInjector = createNodeFlightInjector(navContext.rscStream, {
+          renderTimeoutMs,
+          errorSignal: navContext._errorSignal,
+          nonce,
+        });
+        const moveSuffix = createNodeMoveSuffixTransform();
+
+        const output = runNodePipelineWithErrorHandling(
+          nodeHtmlStream,
+          [bufferedTransform, headInjector, flightInjector, moveSuffix],
+          navContext.signal,
+          nonce
+        );
+        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;
+      const requestInfo = { method: 'GET', path: navContext.pathname };
       let htmlStream: ReadableStream<Uint8Array>;
       try {
         htmlStream = await renderSsrStream(wrappedElement, {
           bootstrapScriptContent: navContext.bootstrapScriptContent || undefined,
+          nonce,
           deferSuspenseFor: navContext.deferSuspenseFor,
           signal: navContext.signal,
+          renderTimeoutMs,
+          requestInfo,
+          onFizzAllReadyResolved: (resolved) => {
+            navContext._fizzAllReadyResolved = resolved;
+          },
         });
       } 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({ ...requestInfo, 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).
+      // 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?.() ?? '');
+      let outputStream = htmlStream.pipeThrough(createBufferedTransformStream());
+      outputStream = injectHead(outputStream, resolvedHeadHtml);
+      outputStream = injectRscPayload(outputStream, navContext.rscStream, {
+        renderTimeoutMs,
+        errorSignal: navContext._errorSignal,
+        nonce,
+      });
+      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);