@timber-js/app 0.2.0-alpha.97 → 0.2.0-alpha.99

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

@@ -31,28 +31,20 @@ import loadUserInstrumentation from 'virtual:timber-instrumentation';
 // @ts-expect-error — virtual module provided by timber-entries plugin
 import loadCacheHandler from 'virtual:timber-cache-handler';
 
-import type { FormRerender } from '../action-handler.js';
-import { handleActionRequest, isActionRequest } from '../action-handler.js';
+import { wrapPipelineWithActionDispatch } from './wrap-action-dispatch.js';
 import type { BodyLimitsConfig } from '../body-limits.js';
 import type { BuildManifest } from '../build-manifest.js';
-import {
-  buildFontPreloadTags,
-  buildModulepreloadTags,
-  collectRouteFonts,
-  collectRouteModulepreloads,
-} from '../build-manifest.js';
 import type { LayoutEntry } from '../deny-renderer.js';
 import { renderDenyPage, renderDenyPageAsRsc } from '../deny-renderer.js';
-import { resolveLogMode } from '../dev-logger.js';
+import { resolveLogMode } from '../../dev-tools/logger.js';
 import { sendEarlyHints103 } from '../early-hints-sender.js';
 import { collectEarlyHintHeaders } from '../early-hints.js';
-import { runWithFormFlash } from '../form-flash.js';
-import type { ClientBootstrapConfig } from '../html-injectors.js';
 import { buildClientScripts } from '../html-injectors.js';
 import type { InterceptionContext, PipelineConfig, RouteMatch } from '../pipeline.js';
-import { createPipeline, coerceSegmentParams } from '../pipeline.js';
+import { createPipeline } from '../pipeline.js';
+import { coerceSegmentParams } from '../param-coercion.js';
 import { setSegmentParams } from '../request-context.js';
-import { buildRouteElement, ParamCoercionError } from '../route-element-builder.js';
+import { buildRouteElement } from '../route-element-builder.js';
 import type { ManifestSegmentNode } from '../route-matcher.js';
 import { createMetadataRouteMatcher, createRouteMatcher } from '../route-matcher.js';
 import { initDevTracing } from '../tracing.js';
@@ -61,23 +53,16 @@ import { renderFallbackError as renderFallback } from '../fallback-error.js';
 import { loadInstrumentation } from '../instrumentation.js';
 import { loadModule } from '../safe-load.js';
 import { logRenderError } from '../logger.js';
-import { handleApiRoute } from './api-handler.js';
-import { renderErrorPage, renderNoMatchPage } from './error-renderer.js';
+import { renderNoMatchPage } from './error-renderer.js';
 import {
-  buildRedirectResponse,
   createDebugChannelSink,
-  escapeHtml,
   isRscPayloadRequest,
   type DebugComponentEntry,
 } from './helpers.js';
-import { parseClientStateTree } from '../state-tree-diff.js';
-import { buildRscPayloadResponse } from './rsc-payload.js';
-import { renderRscStream } from './rsc-stream.js';
-import { renderSsrResponse } from './ssr-renderer.js';
+import { renderRoute } from './render-route.js';
 import { callSsr } from './ssr-bridge.js';
 import { isDebug, isDevMode, setDebugFromConfig } from '../debug.js';
 import { setSourceMapCallback } from '../dev-source-map.js';
-import { recordTiming } from '../server-timing.js';
 import { requestContextAls } from '../als-registry.js';
 import { createAutoSitemapHandler } from '../sitemap-handler.js';
 
@@ -232,15 +217,22 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       await initDevTracing({ mode: devLogMode, slowPhaseMs });
       // Patch globalThis.fetch to create OTEL spans for fetch calls.
       // Spans appear as children of the active component span in the dev log tree.
-      const { instrumentDevFetch } = await import('../dev-fetch-instrumentation.js');
+      const { instrumentDevFetch } = await import('../../dev-tools/instrumentation.js');
       instrumentDevFetch();
     }
   }
 
   const typedBuildManifest = buildManifest as BuildManifest;
 
+  // The routing plugin emits `manifest.proxy = { load, filePath }` only when
+  // the app has an `app/proxy.ts`. Convert that to the pipeline's lazy variant
+  // so HMR re-imports per request; leave it undefined when there's no proxy.
+  const proxyConfig: PipelineConfig['proxy'] = manifest.proxy?.load
+    ? { kind: 'lazy', loader: manifest.proxy.load }
+    : undefined;
+
   const pipelineConfig: PipelineConfig = {
-    proxyLoader: manifest.proxy?.load,
+    proxy: proxyConfig,
     matchRoute,
     matchMetadataRoute,
     // 103 Early Hints — fires after route match, before middleware.
@@ -248,11 +240,7 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
     // so the browser starts fetching critical resources while the server renders.
     // In dev mode the manifest is empty — no hints are sent.
     earlyHints: (match: RouteMatch, _req: Request, responseHeaders: Headers) => {
-      const segments = match.segments as unknown as Array<{
-        layout?: { filePath: string };
-        page?: { filePath: string };
-      }>;
-      const headers = collectEarlyHintHeaders(segments, typedBuildManifest, {
+      const headers = collectEarlyHintHeaders(match.segments, typedBuildManifest, {
         skipJs: clientJsDisabled,
       });
       for (const h of headers) {
@@ -273,11 +261,14 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
         req,
         match,
         responseHeaders,
-        clientBootstrap,
-        clientJsDisabled,
-        interception,
-        manifest.root,
-        manifest.globalError
+        {
+          clientBootstrap,
+          clientJsDisabled,
+          rootSegment: manifest.root,
+          buildManifest: typedBuildManifest,
+          globalError: manifest.globalError,
+        },
+        interception
       );
     },
     renderNoMatch: async (req: Request, responseHeaders: Headers) => {
@@ -295,7 +286,7 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       // should receive the bare 404 without an HTML body (TIM-793).
       const acceptsHtml = (req.headers.get('accept') ?? '').includes('text/html');
       if (isDev && !response.body && req.method === 'GET' && acceptsHtml) {
-        const { generateDev404Page, collectRoutes } = await import('../../plugins/dev-404-page.js');
+        const { generateDev404Page, collectRoutes } = await import('../../dev-tools/404-page.js');
         const routes = collectRoutes(manifest.root);
         const pathname = new URL(req.url).pathname;
         const html = generateDev404Page(pathname, routes);
@@ -358,10 +349,7 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       // route's `401.json` are picked up. Fall back to the root chain when no
       // match is available (e.g. proxy-stage deny before route matching).
       // See TIM-822, design/04-authorization.md, design/10-error-handling.md.
-      type SegNode = import('../route-matcher.js').ManifestSegmentNode;
-      const chain = matchedRoute
-        ? (matchedRoute.segments as unknown as SegNode[])
-        : ([manifest.root] as unknown as SegNode[]);
+      const chain: ManifestSegmentNode[] = matchedRoute ? matchedRoute.segments : [manifest.root];
       const layoutComponents: LayoutEntry[] = [];
       try {
         for (const segment of chain) {
@@ -382,8 +370,8 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       // Reuse the matched route's params/middleware metadata when present so
       // downstream rendering sees the real route shape. Otherwise synthesise
       // a root-only stub (no params, no middleware).
-      const match = matchedRoute ?? {
-        segments: chain as never,
+      const match: RouteMatch = matchedRoute ?? {
+        segments: chain,
         segmentParams: {},
         middlewareChain: [],
       };
@@ -421,9 +409,15 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
 
   const pipeline = createPipeline(pipelineConfig);
 
-  // Wrap the pipeline to intercept server action requests before rendering.
-  // Actions bypass the normal pipeline (no route matching, no middleware)
-  // per design/08-forms-and-actions.md §"Middleware for Server Actions".
+  // Wrap the pipeline to enforce CSRF at the request boundary and intercept
+  // server action requests. By default, the wrapper also runs the matched
+  // route's `middleware.ts` chain on action POSTs, so authentication, rate
+  // limiting, tenant isolation, and request-header injection apply to
+  // actions just like they do to page renders. See TIM-871 and
+  // design/08-forms-and-actions.md §"Middleware for Server Actions".
+  //
+  // CSRF validation lives in the wrapper (not inside the action handler) so
+  // it covers route.ts API handlers as well as server actions. See LOCAL-773.
   const csrfConfig = {
     csrf: runtimeConfig.csrf,
     allowedOrigins: (runtimeConfig as Record<string, unknown>).allowedOrigins as
@@ -431,330 +425,51 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       | undefined,
   };
 
-  return async (req: Request): Promise<Response> => {
-    if (isActionRequest(req)) {
-      const actionResponse = await handleActionRequest(req, {
-        csrf: csrfConfig,
-        bodyLimits: {
-          limits: (runtimeConfig as Record<string, unknown>).limits as BodyLimitsConfig['limits'],
-        },
-        sensitiveFields: formsConfig?.stripSensitiveFields,
-        revalidateRenderer: async (path: string) => {
-          // Build the React element tree for the route at `path`.
-          // Returns the element tree (not serialized) so the action handler can
-          // combine it with the action result in a single renderToReadableStream call.
-          // Forward original request headers (cookies, session IDs, etc.).
-          const revalidateHeaders = new Headers(req.headers);
-          revalidateHeaders.set('Accept', 'text/x-component');
-          const revalidateReq = new Request(new URL(path, req.url), {
-            headers: revalidateHeaders,
-          });
-          const revalidateMatch = matchRoute(new URL(revalidateReq.url).pathname);
-          if (!revalidateMatch) {
-            throw new Error(`revalidatePath('${path}') — no matching route`);
-          }
-          // Coerce segment params (params.ts) before building the element tree.
-          // Without this, components receive raw strings instead of typed values.
-          await coerceSegmentParams(revalidateMatch);
-          // Set coerced params in ALS so getSegmentParams() works during
-          // the revalidation render (AccessGate reads params via ALS).
-          // Without this, AccessGate → getSegmentParams() throws because
-          // segmentParamsPromise is never set. See TIM-667.
-          setSegmentParams(revalidateMatch.segmentParams);
-          const routeResult = await buildRouteElement(revalidateReq, revalidateMatch);
-          return {
-            element: routeResult.element,
-            headElements: routeResult.headElements,
-          };
-        },
+  const actionsConfig = (runtimeConfig as Record<string, unknown>).actions as
+    | { runMiddleware?: boolean }
+    | undefined;
+
+  return wrapPipelineWithActionDispatch(pipeline, {
+    csrfConfig,
+    bodyLimits: (runtimeConfig as Record<string, unknown>).limits as BodyLimitsConfig['limits'],
+    sensitiveFields: formsConfig?.stripSensitiveFields,
+    matchRoute,
+    coerceSegmentParams,
+    renderDenyFallback: pipelineConfig.renderDenyFallback,
+    runMiddleware: actionsConfig?.runMiddleware,
+    // Thread the pipeline's `stripTrailingSlash` setting into the wrapper
+    // so its canonicalization step (applied before `matchRoute` for
+    // action POSTs) matches the page pipeline exactly. Defaults to `true`
+    // both here and inside the wrapper.
+    stripTrailingSlash: pipelineConfig.stripTrailingSlash,
+    buildRevalidateRenderer: (req) => async (path: string) => {
+      // Build the React element tree for the route at `path`.
+      // Returns the element tree (not serialized) so the action handler can
+      // combine it with the action result in a single renderToReadableStream call.
+      // Forward original request headers (cookies, session IDs, etc.).
+      const revalidateHeaders = new Headers(req.headers);
+      revalidateHeaders.set('Accept', 'text/x-component');
+      const revalidateReq = new Request(new URL(path, req.url), {
+        headers: revalidateHeaders,
       });
-      if (actionResponse) {
-        // Check if this is a re-render signal (no-JS validation failure)
-        if ('rerender' in actionResponse) {
-          const formRerender = actionResponse as FormRerender;
-          // Re-render the page with the action result as flash data.
-          // Server components read it via getFormFlash() and pass it to
-          // client form components as the initial useActionState value.
-          //
-          // Build a synthetic GET request for the rerender pipeline:
-          //   - Same URL (so route matching lands on the same page)
-          //   - Cookie header replaced with the post-action RYW snapshot
-          //     so server components see the action's writes (TIM-837)
-          //   - Method GET because the rerender is conceptually a page
-          //     render, not a re-POST. The pipeline doesn't branch on
-          //     method for page rendering, and constructing a POST without
-          //     a body is awkward across Request implementations.
-          const rerenderHeaders = new Headers(req.headers);
-          if (formRerender.cookieHeader) {
-            rerenderHeaders.set('cookie', formRerender.cookieHeader);
-          } else {
-            rerenderHeaders.delete('cookie');
-          }
-          const rerenderReq = new Request(req.url, {
-            method: 'GET',
-            headers: rerenderHeaders,
-          });
-          const response = await runWithFormFlash(formRerender.rerender, () =>
-            pipeline(rerenderReq)
-          );
-          // Apply Set-Cookie headers snapshotted from the action's ALS scope.
-          // The pipeline above runs in its own request context with a fresh
-          // cookie jar, so cookies set inside the action would otherwise be
-          // silently dropped on the no-JS rerender path. See TIM-836
-          // (LOCAL-740).
-          for (const value of formRerender.setCookieHeaders) {
-            response.headers.append('Set-Cookie', value);
-          }
-          return response;
-        }
-        return actionResponse;
+      const revalidateMatch = matchRoute(new URL(revalidateReq.url).pathname);
+      if (!revalidateMatch) {
+        throw new Error(`revalidatePath('${path}') — no matching route`);
       }
-    }
-    return pipeline(req);
-  };
-}
-
-/**
- * Render a matched route to an HTML Response via RSC → SSR pipeline,
- * or return a raw RSC Flight stream for client-side navigation requests.
- *
- * 1. Load page/layout components from the segment chain
- * 2. Resolve metadata
- * 3. Render to RSC Flight stream (serializes "use client" as references)
- * 4. If Accept: text/x-component → return RSC stream directly
- *    Otherwise → pass RSC stream to SSR entry for HTML rendering
- */
-async function renderRoute(
-  _req: Request,
-  match: RouteMatch,
-  responseHeaders: Headers,
-  clientBootstrap: ClientBootstrapConfig,
-  clientJsDisabled: boolean,
-  interception?: InterceptionContext,
-  rootSegment?: ManifestSegmentNode,
-  globalError?: { load: () => Promise<unknown>; filePath: string }
-): Promise<Response> {
-  const segments = match.segments as unknown as ManifestSegmentNode[];
-  const leaf = segments[segments.length - 1];
-
-  // API routes (route.ts) — run access.ts standalone then dispatch to handler.
-  // No React render pass — AccessGate is not used, React.cache is not active.
-  // See design/04-authorization.md §"Auth in API Routes".
-  if (leaf.route && !leaf.page) {
-    return handleApiRoute(_req, match, segments, responseHeaders);
-  }
-
-  // Parse X-Timber-State-Tree for RSC payload requests (client navigation).
-  // The state tree lists sync segments the client has cached — the server
-  // skips re-rendering those layouts for a smaller, faster RSC payload.
-  // Only used for RSC requests — HTML requests always get a full render.
-  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
-  const clientStateTree = isRscPayloadRequest(_req) ? parseClientStateTree(_req) : null;
-
-  // Build the React element tree — loads modules, collects access checks,
-  // resolves metadata. Access checks are NOT run here — they run inside
-  // AccessPreRunner during renderToReadableStream so that access.ts and
-  // render components share the same React.cache scope (TIM-662).
-  //
-  // DenySignal/RedirectSignal from access checks are caught by onError
-  // during stream consumption and handled by renderSsrResponse /
-  // buildRscPayloadResponse.
-  let routeResult;
-  const _buildStart = performance.now();
-  try {
-    routeResult = await buildRouteElement(_req, match, interception, clientStateTree);
-  } catch (error) {
-    // Param coercion failed — render the custom 404 page (status files / not-found).
-    // Previously returned a bare Response(null, { status: 404 }) which bypassed
-    // custom not-found pages. Now routes through renderNoMatchPage so apps with
-    // 404.tsx / not-found status files render their custom page.
-    if (error instanceof ParamCoercionError) {
-      return renderNoMatchPage(_req, rootSegment!, responseHeaders, clientBootstrap);
-    }
-    // No PageComponent found — same treatment as param coercion: render custom 404.
-    if (error instanceof Error && error.message.startsWith('No page component')) {
-      return renderNoMatchPage(_req, rootSegment!, responseHeaders, clientBootstrap);
-    }
-    throw error;
-  }
-
-  const _buildEnd = performance.now();
-  recordTiming({
-    name: 'build',
-    dur: Math.round(_buildEnd - _buildStart),
-    desc: 'build element tree',
-  });
-
-  const { element, headElements, layoutComponents, deferSuspenseFor, skippedSegments } =
-    routeResult;
-
-  // Build head HTML for injection into the SSR output.
-  // Collects CSS, fonts, and modulepreload from the build manifest for matched segments.
-  // In dev mode the manifest is empty — Vite HMR handles CSS/JS.
-  //
-  // Link headers (for 103 Early Hints) are emitted by the earlyHints pipeline
-  // stage before middleware runs. Here we only emit the <head> HTML fallback tags
-  // — these ensure resources load even on platforms without Early Hints support.
-  const typedManifest = buildManifest as BuildManifest;
-  let headHtml = '';
-
-  // CSS is handled by the RSC plugin via ReactDOM.preinit() with
-  // data-precedence attributes. This injects <link rel="stylesheet">
-  // tags during the RSC render phase — before our headHtml injection.
-  // We do NOT emit additional <link rel="stylesheet"> tags here because:
-  // 1. React's Float system deduplicates them, making ours redundant
-  // 2. The duplicate reference confuses React's client-side preload
-  //    deduplication, causing "preload ignored" browser warnings
-  //
-  // CSS URLs are still collected for Early Hints (Link headers) in
-  // buildEarlyHintsHeaders() — those are HTTP headers, not DOM elements,
-  // so they don't conflict with Float.
-
-  // Font CSS is NOT inlined here anymore (TIM-828). The transform hook
-  // injects a side-effect `import 'virtual:timber-font-css/<hash>.css'`
-  // into each file that calls a font function. @vitejs/plugin-rsc's
-  // `collectCss` walks the RSC module graph, finds the virtual CSS
-  // module, and React Float `preinit()`s it as
-  // `<link rel="stylesheet" data-rsc-css-href=...>` — the same path
-  // component CSS rides on. Dev and production share a single path,
-  // with no `globalThis` channel and no dev/prod skew.
-  //
-  // Font preload hints (distinct from the @font-face CSS) still flow
-  // through `BuildManifest.fonts[importer]` and are emitted below plus
-  // as 103 Early Hints via `buildEarlyHintsHeaders()`.
-  const fontEntries = collectRouteFonts(segments, typedManifest);
-  if (fontEntries.length > 0) {
-    headHtml += buildFontPreloadTags(fontEntries);
-  }
-
-  // Skip modulepreload tags when client JavaScript is disabled — no JS to preload.
-  if (!clientJsDisabled) {
-    const preloadUrls = collectRouteModulepreloads(segments, typedManifest);
-    if (preloadUrls.length > 0) {
-      headHtml += buildModulepreloadTags(preloadUrls);
-    }
-  }
-
-  for (const el of headElements) {
-    if (el.tag === 'title' && el.content) {
-      headHtml += `<title>${escapeHtml(el.content)}</title>`;
-    } else if (el.attrs) {
-      const attrs = Object.entries(el.attrs)
-        .filter(([, v]) => v != null)
-        .map(([k, v]) => `${k}="${escapeHtml(v as string)}"`)
-        .join(' ');
-      headHtml += `<${el.tag} ${attrs}>`;
-    }
-  }
-
-  // In dev mode, inject the browser log forwarding script so console
-  // errors/warnings from the browser appear in the server terminal.
-  // Set by timber-dev-browser-logs plugin via globalThis (TIM-575).
-  if (isDevMode()) {
-    const devLogScript = (globalThis as Record<string, unknown>).__timber_dev_browser_log_script as
-      | string
-      | undefined;
-    if (devLogScript) {
-      headHtml += devLogScript;
-    }
-  }
-
-  // Render to RSC Flight stream with signal tracking.
-  const _rscStart = performance.now();
-  const { rscStream, signals, getDebugComponents } = renderRscStream(element, _req);
-
-  // Store the debug components getter in ALS so onPipelineError can
-  // include component tree context for render-phase errors (dev mode only).
-  // Per-request via ALS — no cross-request race. See TIM-557.
-  const alsStore = requestContextAls.getStore();
-  if (alsStore) {
-    alsStore.debugComponentsGetter = getDebugComponents;
-  }
-  recordTiming({
-    name: 'rsc-init',
-    dur: Math.round(performance.now() - _rscStart),
-    desc: 'RSC stream init',
-  });
-
-  // Synchronous redirect — redirect() in access.ts or a non-async component
-  // throws during renderToReadableStream creation. Return HTTP redirect.
-  if (signals.redirectSignal) {
-    return buildRedirectResponse(_req, signals.redirectSignal, responseHeaders);
-  }
-
-  // Synchronous deny — deny() in a non-async component throws during
-  // renderToReadableStream creation, caught in the try/catch above.
-  if (signals.denySignal) {
-    if (isRscPayloadRequest(_req)) {
-      return renderDenyPageAsRsc(
-        signals.denySignal,
-        segments,
-        layoutComponents as LayoutEntry[],
-        responseHeaders,
-        createDebugChannelSink
-      );
-    }
-    return renderDenyPage(
-      signals.denySignal,
-      segments,
-      layoutComponents as LayoutEntry[],
-      _req,
-      match,
-      responseHeaders,
-      clientBootstrap,
-      createDebugChannelSink,
-      callSsr
-    );
-  }
-
-  // Synchronous render error — renderToReadableStream threw before
-  // creating the stream. Render the error page with correct 5xx status.
-  // (Async render errors are tracked in onError and handled after SSR.)
-  if (signals.renderError && !rscStream) {
-    return renderErrorPage(
-      signals.renderError.error,
-      signals.renderError.status,
-      segments,
-      layoutComponents as LayoutEntry[],
-      _req,
-      match,
-      responseHeaders,
-      clientBootstrap,
-      globalError
-    );
-  }
-
-  // For RSC payload requests (client navigation), return the RSC Flight
-  // stream directly — skip SSR HTML rendering entirely.
-  // See design/19-client-navigation.md §"RSC Payload Handling"
-  if (isRscPayloadRequest(_req)) {
-    return buildRscPayloadResponse(
-      _req,
-      rscStream!,
-      signals,
-      segments,
-      layoutComponents,
-      headElements,
-      match,
-      responseHeaders,
-      skippedSegments
-    );
-  }
-
-  // Pipe through SSR for HTML rendering with streaming Suspense support.
-  return renderSsrResponse({
-    req: _req,
-    rscStream: rscStream!,
-    signals,
-    segments,
-    layoutComponents,
-    match,
-    responseHeaders,
-    clientBootstrap,
-    clientJsDisabled,
-    headHtml,
-    deferSuspenseFor,
-    globalError,
+      // Coerce segment params (params.ts) before building the element tree.
+      // Without this, components receive raw strings instead of typed values.
+      await coerceSegmentParams(revalidateMatch);
+      // Set coerced params in ALS so getSegmentParams() works during the
+      // revalidation render (AccessGate reads params via ALS). Without this,
+      // AccessGate → getSegmentParams() throws because segmentParams
+      // is never set. See TIM-667.
+      setSegmentParams(revalidateMatch.segmentParams);
+      const routeResult = await buildRouteElement(revalidateReq, revalidateMatch);
+      return {
+        element: routeResult.element,
+        headElements: routeResult.headElements,
+      };
+    },
   });
 }