@timber-js/app 0.2.0-alpha.8 → 0.2.0-alpha.80

package/src/server/action-handler.ts

@@ -18,7 +18,7 @@ import {
   decodeReply,
   decodeAction,
   renderToReadableStream,
-} from '#/rsc-runtime/rsc.js';
+} from '../rsc-runtime/rsc.js';
 
 import { validateCsrf, type CsrfConfig } from './csrf.js';
 import { executeAction, type RevalidateRenderer } from './actions.js';
@@ -31,6 +31,8 @@ import { handleActionError } from './action-client.js';
 import { enforceBodyLimits, enforceFieldLimit, type BodyLimitsConfig } from './body-limits.js';
 import { parseFormData } from './form-data.js';
 import type { FormFlashData } from './form-flash.js';
+import { checkVersionSkew, applyReloadHeaders } from './version-skew.js';
+import { logActionError } from './logger.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -90,6 +92,21 @@ export async function handleActionRequest(
   req: Request,
   config: ActionDispatchConfig
 ): Promise<Response | FormRerender | null> {
+  // Version skew detection — reject actions from stale clients (TIM-446).
+  // On mismatch, return a structured RSC error response that the client
+  // handles by showing a brief "App updated" message and reloading.
+  const skewCheck = checkVersionSkew(req);
+  if (!skewCheck.ok) {
+    const reloadHeaders = new Headers({
+      'Content-Type': RSC_CONTENT_TYPE,
+    });
+    applyReloadHeaders(reloadHeaders);
+    // Return the reload signal as an RSC stream so createFromFetch can
+    // decode it. The client checks X-Timber-Reload before processing.
+    const rscStream = renderToReadableStream({ _versionSkew: true });
+    return new Response(rscStream, { status: 200, headers: reloadHeaders });
+  }
+
   // CSRF validation — reject cross-origin mutation requests.
   const csrfResult = validateCsrf(req, config.csrf);
   if (!csrfResult.ok) {
@@ -106,7 +123,7 @@ export async function handleActionRequest(
     return new Response(null, { status: limitsResult.status });
   }
 
-  // Run inside request context so headers(), cookies() work in actions.
+  // Run inside request context so getHeaders(), getCookies() work in actions.
   // Actions are a mutable context — they can set cookies (design/29-cookies.md).
   return runWithRequestContext(req, async () => {
     setMutableCookieContext(true);
@@ -177,7 +194,7 @@ async function handleRscAction(
     });
   } catch (error) {
     // Log full error server-side for debugging
-    console.error('[timber] server action error:', error);
+    logActionError({ method: req.method, path: new URL(req.url).pathname, error });
 
     // Return structured error response — ActionError gets its code/data,
     // unexpected errors get sanitized { code: 'INTERNAL_ERROR' }
@@ -293,7 +310,7 @@ async function handleFormAction(
       renderer: config.revalidateRenderer,
     });
   } catch (error) {
-    console.error('[timber] server action error:', error);
+    logActionError({ method: req.method, path: new URL(req.url).pathname, error });
 
     // Return the error as flash data for re-render.
     // handleActionError produces { serverError } for ActionErrors

package/src/server/actions.ts

@@ -3,7 +3,7 @@
  *
  * - revalidatePath(path) re-renders the route at that path and returns the RSC
  *   flight payload for inline reconciliation.
- * - revalidateTag(tag) invalidates cached shells and 'use cache' entries by tag.
+ * - revalidateTag(tag) invalidates timber.cache entries by tag.
  *
  * Both are callable from anywhere on the server — actions, API routes, handlers.
  *
@@ -14,7 +14,7 @@
  * See design/08-forms-and-actions.md
  */
 
-import type { CacheHandler } from '#/cache/index';
+import { getCacheHandler } from '../cache/handler-store';
 import { RedirectSignal } from './primitives';
 import { withSpan } from './tracing';
 import { revalidationAls, type RevalidationState } from './als-registry.js';
@@ -37,8 +37,6 @@ export type { RevalidationState } from './als-registry.js';
 
 /** Options for creating the action handler. */
 export interface ActionHandlerConfig {
-  /** Cache handler for tag invalidation. */
-  cacheHandler?: CacheHandler;
   /** Renderer for producing RSC payloads during revalidation. */
   renderer?: RevalidateRenderer;
 }
@@ -112,8 +110,8 @@ export function revalidatePath(path: string): void {
 }
 
 /**
- * Invalidate all pre-rendered shells and 'use cache' entries tagged with `tag`.
- * Does not return a payload — the next request for an invalidated route re-renders fresh.
+ * Invalidate all timber.cache entries tagged with `tag`.
+ * Does not return a payload — the next request for an invalidated entry re-executes.
  *
  * @param tag - The cache tag to invalidate (e.g. 'products', 'user:123').
  */
@@ -172,9 +170,12 @@ export async function executeAction(
     }
   });
 
-  // Process tag invalidation
-  if (state.tags.length > 0 && config.cacheHandler) {
-    await Promise.all(state.tags.map((tag) => config.cacheHandler!.invalidate({ tag })));
+  // Process tag invalidation via the module-level cache handler singleton.
+  // setCacheHandler() is called at boot from rsc-entry when timber.config.ts
+  // provides a cacheHandler; otherwise falls back to in-memory LRU (TIM-599).
+  if (state.tags.length > 0) {
+    const handler = getCacheHandler();
+    await Promise.all(state.tags.map((tag) => handler.invalidate({ tag })));
   }
 
   // Process path revalidation — build element tree (not yet serialized)

package/src/server/als-registry.ts

@@ -21,9 +21,10 @@
  */
 
 import { AsyncLocalStorage } from 'node:async_hooks';
+import type { DebugComponentEntry } from './rsc-entry/helpers.js';
 
 // ─── Request Context ──────────────────────────────────────────────────────
-// Used by: request-context.ts (headers(), cookies(), searchParams())
+// Used by: request-context.ts (getHeaders(), getCookies(), getSearchParams())
 // Design doc: design/04-authorization.md
 
 /** @internal — import via request-context.ts public API */
@@ -39,17 +40,44 @@ export interface RequestContextStore {
   /** Original (pre-overlay) frozen headers, kept for overlay merging. */
   originalHeaders: Headers;
   /**
-   * Promise resolving to the route's typed search params (when search-params.ts
-   * exists) or to the raw URLSearchParams. Stored as a Promise so the framework
-   * can later support partial pre-rendering where param resolution is deferred.
+   * Promise resolving to the raw URLSearchParams for the current request.
+   * To get typed parsed params, import a search params definition and
+   * call `.parse(searchParams())`.
    */
-  searchParamsPromise: Promise<URLSearchParams | Record<string, unknown>>;
+  searchParamsPromise: Promise<URLSearchParams>;
+  /**
+   * Raw search string from the request URL (e.g. "?foo=bar&baz=1").
+   * Available synchronously for use in `redirect()` with `preserveSearchParams`.
+   */
+  searchString: string;
+  /**
+   * Promise resolving to the coerced segment params for the current request.
+   * Set by the pipeline after route matching and param coercion, before
+   * middleware and rendering. Pages and layouts read params via
+   * `getSegmentParams()` instead of receiving them as a prop.
+   *
+   * See design/07-routing.md §"params.ts — Convention File for Typed Params"
+   */
+  segmentParamsPromise?: Promise<Record<string, string | string[]>>;
   /** Outgoing Set-Cookie entries (name → serialized value + options). Last write wins. */
   cookieJar: Map<string, CookieEntry>;
   /** Whether the response has flushed (headers committed). */
   flushed: boolean;
   /** Whether the current context allows cookie mutation. */
   mutableContext: boolean;
+  /**
+   * Set by AccessGate or PageDenyBoundary when a DenySignal is caught
+   * server-side (inside the React tree, before React Flight sees it).
+   * The pipeline reads this after render to set the HTTP status code.
+   * See TIM-666.
+   */
+  denyStatus?: number;
+  /**
+   * Dev-only: getter for the current request's RSC debug components.
+   * Set by renderRoute() so onPipelineError can include component tree
+   * context for render-phase errors without module-level shared state.
+   */
+  debugComponentsGetter?: () => DebugComponentEntry[];
 }
 
 /** A single outgoing cookie entry in the cookie jar. */
@@ -60,7 +88,7 @@ export interface CookieEntry {
 }
 
 // ─── Tracing ──────────────────────────────────────────────────────────────
-// Used by: tracing.ts (traceId(), spanId())
+// Used by: tracing.ts (getTraceId(), getSpanId())
 // Design doc: design/17-logging.md
 
 export interface TraceStore {

package/src/server/build-manifest.ts

@@ -85,6 +85,12 @@ export function collectRouteCss(segments: SegmentWithFiles[], manifest: BuildMan
  * via injectHead() before </head>.
  */
 export function buildCssLinkTags(cssUrls: string[]): string {
+  // Emit <link rel="stylesheet"> tags as a fallback for platforms where
+  // React's Float system (via @vitejs/plugin-rsc preinit with
+  // data-precedence) doesn't handle CSS injection. In practice, Float
+  // deduplicates and these may be dropped. No preload hints — Float
+  // already starts the fetch via preinit(), and redundant preloads
+  // cause "ignored due to unknown as/type" browser warnings.
   return cssUrls.map((url) => `<link rel="stylesheet" href="${url}">`).join('');
 }
 
@@ -95,10 +101,10 @@ export function buildCssLinkTags(cssUrls: string[]): string {
  * into 103 Early Hints responses. This avoids platform-specific 103
  * sending code.
  *
- * Example output: `</assets/root.css>; rel=preload; as=style, </assets/page.css>; rel=preload; as=style`
+ * Example output: `</assets/root.css>; as=style; rel=preload, </assets/page.css>; as=style; rel=preload`
  */
 export function buildLinkHeaders(cssUrls: string[]): string {
-  return cssUrls.map((url) => `<${url}>; rel=preload; as=style`).join(', ');
+  return cssUrls.map((url) => `<${url}>; as=style; rel=preload`).join(', ');
 }
 
 // ─── Font utilities ──────────────────────────────────────────────────────
@@ -153,10 +159,10 @@ export function buildFontPreloadTags(fonts: ManifestFontEntry[]): string {
  *
  * Cloudflare CDN converts Link headers with rel=preload into 103 Early Hints.
  *
- * Example: `</fonts/inter.woff2>; rel=preload; as=font; crossorigin`
+ * Example: `</fonts/inter.woff2>; as=font; rel=preload; crossorigin`
  */
 export function buildFontLinkHeaders(fonts: ManifestFontEntry[]): string {
-  return fonts.map((f) => `<${f.href}>; rel=preload; as=font; crossorigin`).join(', ');
+  return fonts.map((f) => `<${f.href}>; as=font; rel=preload; crossorigin`).join(', ');
 }
 
 // ─── JS chunk utilities ──────────────────────────────────────────────────

package/src/server/compress.ts

@@ -160,15 +160,33 @@ export function compressResponse(request: Request, response: Response): Response
   });
 }
 
-// ─── Gzip (CompressionStream API) ────────────────────────────────────────
+// ─── Gzip (node:zlib with Z_SYNC_FLUSH) ──────────────────────────────────
+//
+// Uses node:zlib's createGzip with Z_SYNC_FLUSH so each chunk is flushed
+// to the output immediately. The Web Platform CompressionStream API buffers
+// internally and does NOT flush per-chunk — this kills streaming because
+// the browser doesn't receive the HTML shell until the gzip stream closes
+// (i.e. after all Suspense boundaries resolve).
+//
+// Z_SYNC_FLUSH adds ~2–5% size overhead vs Z_NO_FLUSH but preserves
+// correct streaming behavior: the shell renders instantly, Suspense
+// fallbacks are visible immediately, and streamed content appears
+// progressively.
+
+import { createGzip, constants } from 'node:zlib';
+import { Readable } from 'node:stream';
 
 /**
- * Compress a ReadableStream with gzip using the Web Platform CompressionStream API.
- * Available in Node 18+, Bun, and Deno — no npm dependency needed.
+ * Compress a ReadableStream with gzip, flushing each chunk immediately.
+ *
+ * Uses node:zlib's createGzip with Z_SYNC_FLUSH to ensure each HTML chunk
+ * (shell, Suspense resolution, RSC payload) is delivered to the browser
+ * as soon as it's available — preserving streaming semantics.
  */
 function compressWithGzip(body: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
-  const compressionStream = new CompressionStream('gzip');
-  // Cast needed: CompressionStream's WritableStream<BufferSource> type is wider
-  // than ReadableStream's Uint8Array, but Uint8Array is a valid BufferSource.
-  return body.pipeThrough(compressionStream as unknown as TransformStream<Uint8Array, Uint8Array>);
+  const gzip = createGzip({ flush: constants.Z_SYNC_FLUSH });
+  const nodeInput = Readable.fromWeb(body as import('stream/web').ReadableStream);
+  nodeInput.pipe(gzip);
+
+  return Readable.toWeb(gzip) as ReadableStream<Uint8Array>;
 }

package/src/server/debug.ts

@@ -48,7 +48,7 @@
  *
  * This is the ONLY function that should gate client-visible dev behavior:
  * - Dev error pages with stack traces
- * - Detailed Server-Timing response headers
+ * - Server-Timing mode default (`'detailed'` in dev, `'total'` in prod)
  * - Error messages in action `INTERNAL_ERROR` payloads
  * - Pipeline error handler wiring (Vite overlay)
  *

package/src/server/default-logger.ts

@@ -0,0 +1,99 @@
+/**
+ * DefaultLogger — human-readable stderr logging when no custom logger is configured.
+ *
+ * Ships as the fallback so production deployments always have error visibility,
+ * even without an `instrumentation.ts` logger export. Output is one line per
+ * event, designed for `fly logs`, `kubectl logs`, Cloudflare dashboard tails, etc.
+ *
+ * Format:
+ *   [timber] ERROR  message  key=value key=value  trace_id=4bf92f35
+ *   [timber] WARN   message  key=value key=value  trace_id=4bf92f35
+ *   [timber] INFO   message  method=GET path=/dashboard status=200 durationMs=43  trace_id=4bf92f35
+ *
+ * Behavior:
+ * - Suppressed entirely in dev mode (dev logging handles all output)
+ * - `debug` suppressed unless TIMBER_DEBUG is set
+ * - Replaced entirely when a custom logger is set via `setLogger()`
+ *
+ * See design/17-logging.md §"DefaultLogger"
+ */
+
+import { isDevMode, isDebug } from './debug.js';
+import { formatSsrError } from './error-formatter.js';
+import type { TimberLogger } from './logger.js';
+
+/**
+ * Format data fields as `key=value` pairs for human-readable output.
+ * - `error` key is serialized via formatSsrError for stack trace cleanup
+ * - `trace_id` is truncated to 8 chars for readability (full ID in OTEL)
+ * - Other values are stringified inline
+ */
+function formatDataFields(data?: Record<string, unknown>): string {
+  if (!data) return '';
+
+  const parts: string[] = [];
+  let traceId: string | undefined;
+
+  for (const [key, value] of Object.entries(data)) {
+    if (key === 'trace_id') {
+      // Defer trace_id to the end
+      traceId = typeof value === 'string' ? value : String(value);
+      continue;
+    }
+    if (key === 'error') {
+      // Serialize errors with formatSsrError for clean output
+      parts.push(`error=${formatSsrError(value)}`);
+      continue;
+    }
+    if (value === undefined || value === null) continue;
+    parts.push(`${key}=${value}`);
+  }
+
+  // trace_id always last, truncated to 8 chars for readability
+  if (traceId) {
+    parts.push(`trace_id=${traceId.slice(0, 8)}`);
+  }
+
+  return parts.length > 0 ? '  ' + parts.join('  ') : '';
+}
+
+/** Pad level string to fixed width for alignment. */
+function padLevel(level: string): string {
+  return level.padEnd(5);
+}
+
+export function createDefaultLogger(): TimberLogger {
+  return {
+    error(msg: string, data?: Record<string, unknown>): void {
+      // Errors are ALWAYS logged, including dev mode. Suppressing errors
+      // in dev causes silent 500s with no stack trace, making route.ts
+      // and render errors impossible to debug. See TIM-555.
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('ERROR')}  ${msg}${fields}\n`);
+    },
+
+    warn(msg: string, data?: Record<string, unknown>): void {
+      // Warnings are always logged — same rationale as errors.
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('WARN')}  ${msg}${fields}\n`);
+    },
+
+    info(msg: string, data?: Record<string, unknown>): void {
+      // info is suppressed by default — per-request lines are too noisy
+      // without a custom logger. Enable with TIMBER_DEBUG.
+      if (isDevMode()) return;
+      if (!isDebug()) return;
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('INFO')}  ${msg}${fields}\n`);
+    },
+
+    debug(msg: string, data?: Record<string, unknown>): void {
+      // debug is suppressed in dev (dev logger handles it) and in
+      // production unless TIMBER_DEBUG is explicitly set.
+      if (isDevMode()) return;
+      if (!isDebug()) return;
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('DEBUG')}  ${msg}${fields}\n`);
+    },
+  };
+}

package/src/server/deny-page-resolver.ts

@@ -0,0 +1,154 @@
+/**
+ * Deny Page Resolver — resolves status-code file components for in-tree deny handling.
+ *
+ * When AccessGate or PageDenyBoundary catches a DenySignal, they need to
+ * render the matching deny page (403.tsx, 4xx.tsx, error.tsx) as a normal
+ * element in the React tree. This module resolves the deny page chain from
+ * the segment chain — a list of fallback components ordered by specificity.
+ *
+ * The chain is built during buildRouteElement and passed as a prop to
+ * AccessGate and PageDenyBoundary. At catch time, the first matching
+ * component is rendered.
+ *
+ * See design/10-error-handling.md §"Status-Code Files", TIM-666.
+ */
+
+import { createElement } from 'react';
+
+import type { ManifestSegmentNode } from './route-matcher.js';
+import { loadModule } from './safe-load.js';
+import { requestContextAls } from './als-registry.js';
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+/** A single entry in the deny page fallback chain. */
+export interface DenyPageEntry {
+  /** Status code filter: specific (403), category (400 = any 4xx), or null (catch-all). */
+  status: number | null;
+  /** The component to render (server or client — both work). */
+  component: (...args: unknown[]) => unknown;
+}
+
+// ─── Resolver ─────────────────────────────────────────────────────────────
+
+/**
+ * Build the deny page fallback chain from the segment chain.
+ *
+ * Walks segments from `startIndex` outward (toward root) and collects
+ * status-code file components in fallback order:
+ * 1. Specific status files (403.tsx, 404.tsx) — exact match
+ * 2. Category catch-alls (4xx.tsx) — matches any 4xx
+ * 3. error.tsx — catches everything
+ *
+ * Each segment is checked in this order. The chain is ordered so the
+ * FIRST match wins at catch time.
+ */
+export async function buildDenyPageChain(
+  segments: ManifestSegmentNode[],
+  startIndex: number
+): Promise<DenyPageEntry[]> {
+  const chain: DenyPageEntry[] = [];
+
+  // Pass 1: Status files (specific + category) across ALL segments.
+  // These have higher priority than error.tsx — a root 4xx.tsx should
+  // match before a leaf error.tsx. Walking inner → outer ensures the
+  // nearest match wins within each priority tier.
+  for (let i = startIndex; i >= 0; i--) {
+    const segment = segments[i];
+    if (!segment.statusFiles) continue;
+
+    // Specific status files (403.tsx, 404.tsx, etc.)
+    for (const [key, file] of Object.entries(segment.statusFiles)) {
+      if (key !== '4xx' && key !== '5xx') {
+        const status = parseInt(key, 10);
+        if (!isNaN(status)) {
+          const mod = await loadModule(file).catch(() => null);
+          if (mod?.default) {
+            chain.push({ status, component: mod.default as (...args: unknown[]) => unknown });
+          }
+        }
+      }
+    }
+
+    // Category catch-alls (4xx.tsx, 5xx.tsx)
+    for (const [key, file] of Object.entries(segment.statusFiles)) {
+      if (key === '4xx' || key === '5xx') {
+        const mod = await loadModule(file).catch(() => null);
+        if (mod?.default) {
+          const categoryStatus = key === '4xx' ? 400 : 500;
+          chain.push({
+            status: categoryStatus,
+            component: mod.default as (...args: unknown[]) => unknown,
+          });
+        }
+      }
+    }
+  }
+
+  // Pass 2: error.tsx files — lowest priority catch-all.
+  // Only added AFTER all status files so they never shadow a specific
+  // or category status file from an ancestor segment.
+  for (let i = startIndex; i >= 0; i--) {
+    const segment = segments[i];
+    if (segment.error) {
+      const mod = await loadModule(segment.error).catch(() => null);
+      if (mod?.default) {
+        chain.push({ status: null, component: mod.default as (...args: unknown[]) => unknown });
+      }
+    }
+  }
+
+  return chain;
+}
+
+// ─── Matcher ──────────────────────────────────────────────────────────────
+
+/**
+ * Find the first deny page in the chain that matches the given status code.
+ * Returns a React element for the matching component, or null if no match.
+ */
+export function renderMatchingDenyPage(
+  chain: DenyPageEntry[],
+  status: number,
+  data: unknown
+): React.ReactElement | null {
+  const h = createElement as (...args: unknown[]) => React.ReactElement;
+
+  for (const entry of chain) {
+    if (entry.status === status) {
+      return h(entry.component, { status, dangerouslyPassData: data });
+    }
+    if (entry.status === 400 && status >= 400 && status <= 499) {
+      return h(entry.component, { status, dangerouslyPassData: data });
+    }
+    if (entry.status === 500 && status >= 500 && status <= 599) {
+      return h(entry.component, { status, dangerouslyPassData: data });
+    }
+    if (entry.status === null) {
+      return h(entry.component, { status, dangerouslyPassData: data });
+    }
+  }
+  return null;
+}
+
+// ─── ALS Helper ───────────────────────────────────────────────────────────
+
+/**
+ * Set the deny status in the request context ALS.
+ * Called from AccessGate / PageDenyBoundary when a DenySignal is caught.
+ * The pipeline reads this after render to set the HTTP status code.
+ */
+export function setDenyStatus(status: number): void {
+  const store = requestContextAls.getStore();
+  if (store) {
+    store.denyStatus = status;
+  }
+}
+
+/**
+ * Read the deny status from the request context ALS.
+ * Returns undefined if no deny was caught during render.
+ */
+export function getDenyStatus(): number | undefined {
+  return requestContextAls.getStore()?.denyStatus;
+}