@timber-js/app 0.2.0-alpha.6 → 0.2.0-alpha.61

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

@@ -24,36 +24,38 @@ import buildManifest from 'virtual:timber-build-manifest';
 // @ts-expect-error — virtual module provided by timber-entries plugin
 import loadUserInstrumentation from 'virtual:timber-instrumentation';
 
-import type { FormRerender } from '#/server/action-handler.js';
-import { handleActionRequest, isActionRequest } from '#/server/action-handler.js';
-import type { BodyLimitsConfig } from '#/server/body-limits.js';
-import type { BuildManifest } from '#/server/build-manifest.js';
+import type { FormRerender } from '../action-handler.js';
+import { handleActionRequest, isActionRequest } from '../action-handler.js';
+import type { BodyLimitsConfig } from '../body-limits.js';
+import type { BuildManifest } from '../build-manifest.js';
 import {
-  buildCssLinkTags,
   buildFontPreloadTags,
   buildModulepreloadTags,
-  collectRouteCss,
   collectRouteFonts,
   collectRouteModulepreloads,
-} from '#/server/build-manifest.js';
-import type { LayoutEntry } from '#/server/deny-renderer.js';
-import { renderDenyPage, renderDenyPageAsRsc } from '#/server/deny-renderer.js';
-import { resolveLogMode } from '#/server/dev-logger.js';
-import { sendEarlyHints103 } from '#/server/early-hints-sender.js';
-import { collectEarlyHintHeaders } from '#/server/early-hints.js';
-import { runWithFormFlash } from '#/server/form-flash.js';
-import type { ClientBootstrapConfig } from '#/server/html-injectors.js';
-import { buildClientScripts } from '#/server/html-injectors.js';
-import type { InterceptionContext, PipelineConfig, RouteMatch } from '#/server/pipeline.js';
-import { createPipeline } from '#/server/pipeline.js';
-import { DenySignal, RedirectSignal } from '#/server/primitives.js';
-import { buildRouteElement, RouteSignalWithContext } from '#/server/route-element-builder.js';
-import type { ManifestSegmentNode } from '#/server/route-matcher.js';
-import { createMetadataRouteMatcher, createRouteMatcher } from '#/server/route-matcher.js';
-import { initDevTracing } from '#/server/tracing.js';
-
-import { renderFallbackError as renderFallback } from '#/server/fallback-error.js';
-import { loadInstrumentation } from '#/server/instrumentation.js';
+} 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 { 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 { DenySignal, RedirectSignal } from '../primitives.js';
+import {
+  buildRouteElement,
+  RouteSignalWithContext,
+  ParamCoercionError,
+} from '../route-element-builder.js';
+import type { ManifestSegmentNode } from '../route-matcher.js';
+import { createMetadataRouteMatcher, createRouteMatcher } from '../route-matcher.js';
+import { initDevTracing } from '../tracing.js';
+
+import { renderFallbackError as renderFallback } from '../fallback-error.js';
+import { loadInstrumentation } from '../instrumentation.js';
 import { handleApiRoute } from './api-handler.js';
 import { renderErrorPage, renderNoMatchPage } from './error-renderer.js';
 import {
@@ -61,33 +63,61 @@ import {
   createDebugChannelSink,
   escapeHtml,
   isRscPayloadRequest,
+  type DebugComponentEntry,
 } from './helpers.js';
-import { parseClientStateTree } from '#/server/state-tree-diff.js';
-import {
-  createResponseCache,
-  resolveResponseCacheConfig,
-  type ResponseCache,
-} from '#/server/response-cache.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 { callSsr } from './ssr-bridge.js';
-import { isDebug, isDevMode, setDebugFromConfig } from '#/server/debug.js';
+import { isDebug, isDevMode, setDebugFromConfig } from '../debug.js';
+import { recordTiming } from '../server-timing.js';
+import { requestContextAls } from '../als-registry.js';
+
+/**
+ * Resolve the Server-Timing mode from timber.config.ts.
+ *
+ * If the user set `serverTiming` explicitly, use that value.
+ * Otherwise: `'detailed'` in dev, `'total'` in production.
+ */
+function resolveServerTimingMode(
+  config: Record<string, unknown>,
+  isDev: boolean
+): 'detailed' | 'total' | false {
+  const userValue = config.serverTiming as 'detailed' | 'total' | false | undefined;
+  if (userValue !== undefined) return userValue;
+  return isDev ? 'detailed' : 'total';
+}
 
 // Dev-only pipeline error handler, set by the dev server after import.
 // In production this is always undefined — no overhead.
-let _devPipelineErrorHandler: ((error: Error, phase: string) => void) | undefined;
+// The third argument provides RSC debug component data (from the Flight
+// debug channel) when available — used by the error overlay to show the
+// server component tree context for render errors.
+let _devPipelineErrorHandler:
+  | ((error: Error, phase: string, debugComponents?: DebugComponentEntry[]) => void)
+  | undefined;
 
 /**
  * Set the dev pipeline error handler.
  *
  * Called by the dev server after importing this module to wire pipeline
  * errors into the Vite browser error overlay. No-op in production.
+ *
+ * The handler receives an optional third argument with RSC debug component
+ * info — component names, environments, and stack frames from the Flight
+ * debug channel. This is only populated for render-phase errors.
  */
-export function setDevPipelineErrorHandler(handler: (error: Error, phase: string) => void): void {
+export function setDevPipelineErrorHandler(
+  handler: (error: Error, phase: string, debugComponents?: DebugComponentEntry[]) => void
+): void {
   _devPipelineErrorHandler = handler;
 }
 
+// Dev-only: debug components getter is stored per-request in ALS
+// (RequestContextStore.debugComponentsGetter) to avoid cross-request
+// race conditions. See TIM-557.
+
 /**
  * Create the RSC request handler from the route manifest.
  *
@@ -101,13 +131,15 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
   // See design/17-logging.md §"register() — Server Startup"
   await loadInstrumentation(loadUserInstrumentation);
 
-  // Initialize cookie signing secrets from config (design/29-cookies.md §"Signed Cookies")
-  const cookieSecrets = (runtimeConfig as Record<string, unknown>).cookieSecrets as
-    | string[]
+  // Initialize deployment ID for version skew detection (TIM-446).
+  // The manifest init module sets globalThis.__TIMBER_DEPLOYMENT_ID__ at startup.
+  // In dev mode this is undefined — skew checks are skipped.
+  const deploymentId = (globalThis as Record<string, unknown>).__TIMBER_DEPLOYMENT_ID__ as
+    | string
     | undefined;
-  if (cookieSecrets?.length) {
-    const { setCookieSecrets } = await import('#/server/request-context.js');
-    setCookieSecrets(cookieSecrets);
+  if (deploymentId) {
+    const { setDeploymentId } = await import('../version-skew.js');
+    setDeploymentId(deploymentId);
   }
 
   const matchRoute = createRouteMatcher(manifest);
@@ -164,17 +196,6 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
 
   const typedBuildManifest = buildManifest as BuildManifest;
 
-  // Initialize response-level caching and singleflight deduplication.
-  // See design/31-benchmarking.md for performance motivation.
-  const responseCacheRaw = (runtimeConfig as Record<string, unknown>).responseCache as
-    | { maxSize?: number; ttlMs?: number; publicOnly?: boolean }
-    | false
-    | undefined;
-  const responseCacheConfig = resolveResponseCacheConfig(responseCacheRaw);
-  const responseCache: ResponseCache | null = responseCacheConfig
-    ? createResponseCache(responseCacheConfig)
-    : null;
-
   const pipelineConfig: PipelineConfig = {
     proxyLoader: manifest.proxy?.load,
     matchRoute,
@@ -205,17 +226,16 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       _requestHeaderOverlay: Headers,
       interception?: InterceptionContext
     ) => {
-      const doRender = () =>
-        renderRoute(req, match, responseHeaders, clientBootstrap, clientJsDisabled, interception);
-
-      // Response cache wraps the render with singleflight + LRU.
-      // Interception requests (modals) are excluded — they depend on
-      // X-Timber-URL which makes caching semantics ambiguous.
-      if (responseCache && !interception) {
-        const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
-        return responseCache.getOrRender(req, isRsc, doRender);
-      }
-      return doRender();
+      return renderRoute(
+        req,
+        match,
+        responseHeaders,
+        clientBootstrap,
+        clientJsDisabled,
+        interception,
+        manifest.root,
+        manifest.globalError
+      );
     },
     renderNoMatch: async (req: Request, responseHeaders: Headers) => {
       return renderNoMatchPage(req, manifest.root, responseHeaders, clientBootstrap);
@@ -224,14 +244,31 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
     // Slow request threshold from timber.config.ts. Default 3000ms, 0 to disable.
     // See design/17-logging.md §"slowRequestMs"
     slowRequestMs: (runtimeConfig as Record<string, unknown>).slowRequestMs as number | undefined,
-    enableServerTiming: isDev,
+    serverTiming: resolveServerTimingMode(runtimeConfig, isDev),
     onPipelineError: isDev
       ? (error: Error, phase: string) => {
-          if (_devPipelineErrorHandler) _devPipelineErrorHandler(error, phase);
+          if (_devPipelineErrorHandler) {
+            // For render-phase errors, include RSC debug component data
+            // from the Flight debug channel (if available from the current request).
+            const store = requestContextAls.getStore();
+            const debugComponents =
+              phase === 'render' && store?.debugComponentsGetter
+                ? store.debugComponentsGetter()
+                : undefined;
+            _devPipelineErrorHandler(error, phase, debugComponents);
+          }
         }
       : undefined,
     renderFallbackError: (error, req, responseHeaders) =>
-      renderFallback(error, req, responseHeaders, isDev, manifest.root, clientBootstrap),
+      renderFallback(
+        error,
+        req,
+        responseHeaders,
+        isDev,
+        manifest.root,
+        clientBootstrap,
+        manifest.globalError
+      ),
   };
 
   const pipeline = createPipeline(pipelineConfig);
@@ -267,6 +304,9 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
           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);
           const routeResult = await buildRouteElement(revalidateReq, revalidateMatch);
           return {
             element: routeResult.element,
@@ -307,7 +347,9 @@ async function renderRoute(
   responseHeaders: Headers,
   clientBootstrap: ClientBootstrapConfig,
   clientJsDisabled: boolean,
-  interception?: InterceptionContext
+  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];
@@ -329,6 +371,7 @@ async function renderRoute(
   // Build the React element tree — loads modules, runs access checks,
   // resolves metadata. DenySignal/RedirectSignal propagate for HTTP handling.
   let routeResult;
+  const _buildStart = performance.now();
   try {
     routeResult = await buildRouteElement(_req, match, interception, clientStateTree);
   } catch (error) {
@@ -361,14 +404,29 @@ async function renderRoute(
         return buildRedirectResponse(_req, signal, responseHeaders);
       }
     }
-    // No PageComponent found
+    // 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 new Response(null, { status: 404 });
+      return renderNoMatchPage(_req, rootSegment!, responseHeaders, clientBootstrap);
     }
     throw error;
   }
 
-  const { element, headElements, layoutComponents, deferSuspenseFor, skippedSegments } = routeResult;
+  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.
@@ -380,9 +438,24 @@ async function renderRoute(
   const typedManifest = buildManifest as BuildManifest;
   let headHtml = '';
 
-  const cssUrls = collectRouteCss(segments, typedManifest);
-  if (cssUrls.length > 0) {
-    headHtml += buildCssLinkTags(cssUrls);
+  // 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.
+
+  // Inline font CSS as a <style> tag — @font-face rules and scoped classes.
+  // The font CSS is set on globalThis by the transformed font file's
+  // side-effect import of virtual:timber-font-css-register.
+  const fontCss = (globalThis as Record<string, unknown>).__timber_font_css as string | undefined;
+  if (fontCss) {
+    headHtml += `<style data-timber-fonts>${fontCss}</style>`;
   }
 
   const fontEntries = collectRouteFonts(segments, typedManifest);
@@ -410,8 +483,34 @@ async function renderRoute(
     }
   }
 
+  // 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 { rscStream, signals } = renderRscStream(element, _req);
+  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.
@@ -456,7 +555,8 @@ async function renderRoute(
       _req,
       match,
       responseHeaders,
-      clientBootstrap
+      clientBootstrap,
+      globalError
     );
   }
 
@@ -490,15 +590,16 @@ async function renderRoute(
     clientJsDisabled,
     headHtml,
     deferSuspenseFor,
+    globalError,
   });
 }
 
 // Re-export for generated entry points (e.g., Nitro node-server/bun) to wrap
 // the handler with per-request 103 Early Hints sender via ALS.
-export { runWithEarlyHintsSender } from '#/server/early-hints-sender.js';
+export { runWithEarlyHintsSender } from '../early-hints-sender.js';
 
 // Re-export for generated entry points to wrap the handler with per-request
 // waitUntil support via ALS. See design/11-platform.md §"waitUntil()".
-export { runWithWaitUntil } from '#/server/waituntil-bridge.js';
+export { runWithWaitUntil } from '../waituntil-bridge.js';
 
 export default await createRequestHandler(routeManifest, config);

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

@@ -9,12 +9,12 @@
  *              16-metadata.md §"Head Elements"
  */
 
-import type { LayoutEntry } from '#/server/deny-renderer.js';
-import { renderDenyPageAsRsc } from '#/server/deny-renderer.js';
-import type { RouteMatch } from '#/server/pipeline.js';
-import type { RedirectSignal } from '#/server/primitives.js';
-import type { HeadElement, LayoutComponentEntry } from '#/server/route-element-builder.js';
-import type { ManifestSegmentNode } from '#/server/route-matcher.js';
+import type { LayoutEntry } from '../deny-renderer.js';
+import { renderDenyPageAsRsc } from '../deny-renderer.js';
+import type { RouteMatch } from '../pipeline.js';
+import type { RedirectSignal } from '../primitives.js';
+import type { HeadElement, LayoutComponentEntry } from '../route-element-builder.js';
+import type { ManifestSegmentNode } from '../route-matcher.js';
 
 import {
   buildRedirectResponse,
@@ -45,18 +45,60 @@ export async function buildRscPayloadResponse(
   skippedSegments?: string[]
 ): Promise<Response> {
   // Read the first chunk from the RSC stream before committing headers.
+  // Race the first read against signal detection — if an async component
+  // throws a RedirectSignal or DenySignal, the onError callback fires
+  // signals.onSignal() and we can react immediately without waiting for
+  // the full macrotask queue.
+  //
+  // The rejection chain for an async-wrapped page component:
+  //   1. PageComponent throws RedirectSignal
+  //   2. withSpan catches and re-throws (microtask 1)
+  //   3. TracedPage promise rejects (microtask 2)
+  //   4. React Flight rejection handler → onError (microtask 3+)
+  //
+  // Promise.race reacts the instant onError fires, eliminating the
+  // per-request setTimeout(0) macrotask delay for the common case
+  // (no signal). A 50ms ceiling timeout guards against edge cases
+  // where onError never fires.
   const reader = rscStream.getReader();
-  const firstRead = await reader.read();
+  const signalDetected = new Promise<void>((resolve) => {
+    signals.onSignal = resolve;
+  });
 
-  // Yield to the microtask queue so that async component rejections
-  // (e.g. an async-wrapped page component that throws redirect())
-  // propagate to the onError callback before we check the signals.
-  // The rejected Promise from an async component resolves in the next
-  // microtask after read(), so we need at least one tick.
-  //
-  // Uses queueMicrotask instead of setTimeout(0) to stay within the
-  // same tick — no full event loop round-trip needed.
-  await new Promise<void>((r) => queueMicrotask(r));
+  type RaceResult =
+    | { type: 'data'; chunk: ReadableStreamReadResult<Uint8Array> }
+    | { type: 'signal' };
+
+  let first: RaceResult;
+  try {
+    first = await Promise.race([
+      reader.read().then((chunk) => ({ type: 'data' as const, chunk })),
+      signalDetected.then(() => ({ type: 'signal' as const })),
+    ]);
+  } catch (_readError) {
+    // RSC stream failed on first read — unhandled error in the page component.
+    // Return an error response so the client can hard-navigate for the
+    // SSR-rendered error page. See design/10-error-handling.md.
+    reader.cancel().catch(() => {});
+    signals.onSignal = undefined;
+    responseHeaders.set('X-Timber-Error', '1');
+    responseHeaders.set('content-type', 'application/json; charset=utf-8');
+    return new Response(JSON.stringify({ error: true, status: 500 }), {
+      status: 500,
+      headers: responseHeaders,
+    });
+  }
+
+  // If data arrived first, still check signals — they may have fired
+  // concurrently. Also do a final ceiling timeout check for edge cases
+  // where the signal fires just after the first read resolves.
+  if (first.type === 'data' && !signals.redirectSignal && !signals.denySignal) {
+    // Brief yield to let any in-flight microtask rejections complete.
+    await new Promise<void>((r) => setTimeout(r, 0));
+  }
+
+  // Detach the callback — no longer needed after this point.
+  signals.onSignal = undefined;
 
   // Check for redirect/deny signals detected during initial rendering
   const trackedRedirect = signals.redirectSignal as RedirectSignal | null;
@@ -75,6 +117,37 @@ export async function buildRscPayloadResponse(
     );
   }
 
+  // Check for unhandled errors (RenderError or plain Error).
+  // These aren't redirect/deny signals but the RSC stream will be broken.
+  // Return an error response so the client can hard-navigate for the
+  // SSR-rendered error page. See design/10-error-handling.md
+  // §"Error Page Rendering for Client Navigation".
+  if (signals.renderError) {
+    reader.cancel().catch(() => {});
+    responseHeaders.set('X-Timber-Error', '1');
+    responseHeaders.set('content-type', 'application/json; charset=utf-8');
+    return new Response(
+      JSON.stringify({
+        error: true,
+        status: signals.renderError.status,
+      }),
+      { status: signals.renderError.status, headers: responseHeaders }
+    );
+  }
+
+  // Extract the first chunk from the race result.
+  // If the signal won the race but neither redirect nor deny was detected
+  // (edge case), cancel the reader immediately rather than issuing a bare
+  // read() that could hang forever if the RSC stream has stalled.
+  // See TIM-519.
+  let firstRead: ReadableStreamReadResult<Uint8Array>;
+  if (first.type === 'data') {
+    firstRead = first.chunk;
+  } else {
+    await reader.cancel();
+    firstRead = { done: true, value: undefined };
+  }
+
   // Reconstruct the stream: prepend the buffered first chunk,
   // then continue piping from the original reader.
   const patchedStream = new ReadableStream<Uint8Array>({
@@ -123,8 +196,8 @@ export async function buildRscPayloadResponse(
     responseHeaders.set('X-Timber-Skipped-Segments', JSON.stringify(skippedSegments));
   }
 
-  // Send route params so the client can populate useParams() after
-  // SPA navigation. Without this, useParams() returns {}.
+  // Send route params so the client can populate useSegmentParams() after
+  // SPA navigation. Without this, useSegmentParams() returns {}.
   if (Object.keys(match.params).length > 0) {
     responseHeaders.set('X-Timber-Params', JSON.stringify(match.params));
   }