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

package/src/server/stream-utils.ts

@@ -0,0 +1,213 @@
+/**
+ * Stream utilities for the RSC rendering pipeline.
+ *
+ * teeWithErrorPropagation — wraps native ReadableStream.tee() with:
+ * 1. Cross-branch error propagation (error on one branch cancels the other)
+ * 2. Buffer divergence monitoring (warns + cancels when threshold exceeded)
+ *
+ * This prevents two classes of bugs:
+ * - Silent stalls when one tee branch errors and the other hangs indefinitely
+ * - Unbounded memory growth when one consumer (SSR) is much slower than the other
+ *
+ * Design doc: 02-rendering-pipeline.md §"RSC → SSR → Client Hydration"
+ */
+
+/** Default maximum buffer divergence before cancellation (5MB). */
+const DEFAULT_MAX_BUFFER_BYTES = 5 * 1024 * 1024;
+
+export interface TeeOptions {
+  /**
+   * Maximum byte divergence between the two branches before both are
+   * cancelled. When one branch has consumed this many more bytes than
+   * the other, the tee's internal buffer is at least this large.
+   *
+   * Default: 5MB.
+   */
+  maxBufferBytes?: number;
+}
+
+/**
+ * Tee a ReadableStream with error propagation and buffer monitoring.
+ *
+ * Delegates to the native `stream.tee()` for the actual forking, then wraps
+ * each branch in a ReadableStream that:
+ * - Tracks bytes consumed per branch
+ * - Cancels both branches if byte divergence exceeds `maxBufferBytes`
+ * - Cancels the other branch if either branch is cancelled or errors
+ *
+ * The returned streams are drop-in replacements for the native tee branches.
+ */
+export function teeWithErrorPropagation(
+  stream: ReadableStream<Uint8Array>,
+  options?: TeeOptions
+): [ReadableStream<Uint8Array>, ReadableStream<Uint8Array>] {
+  const maxBuffer = options?.maxBufferBytes ?? DEFAULT_MAX_BUFFER_BYTES;
+  const [rawBranch1, rawBranch2] = stream.tee();
+
+  // Shared state for cross-branch coordination
+  let consumed1 = 0;
+  let consumed2 = 0;
+  let cancelled = false;
+
+  // Readers and controllers are assigned when wrapBranch creates the wrapped
+  // streams. We store them so cancelBoth can cancel raw tee branches AND
+  // error the wrapped stream controllers for cross-branch propagation.
+  let rawReader1: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  let rawReader2: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  let controller1: ReadableStreamDefaultController<Uint8Array> | undefined;
+  let controller2: ReadableStreamDefaultController<Uint8Array> | undefined;
+
+  /**
+   * Cancel both tee branches. `initiator` is the branch index (0 or 1)
+   * that triggered the cancellation — its controller is already being
+   * closed/errored by the pull/cancel that triggered this, so we skip it.
+   * Pass -1 to cancel+error both (e.g., from the buffer divergence guard).
+   *
+   * Both raw readers are always canceled regardless of initiator, because
+   * the tee source stream is only released when both branches are canceled.
+   * ReadableStreamDefaultReader.cancel() is idempotent, so double-cancel
+   * is safe.
+   */
+  function cancelBoth(reason: unknown, initiator: number = -1): void {
+    if (cancelled) return;
+    cancelled = true;
+    // Cancel both raw readers — tee source requires both branches canceled.
+    rawReader1?.cancel(reason).catch(() => {});
+    rawReader2?.cancel(reason).catch(() => {});
+    // Error wrapped controllers so consumers see the failure.
+    // Skip the initiator's controller — it's already being closed/errored.
+    if (initiator !== 0) {
+      try {
+        controller1?.error(reason);
+      } catch {
+        /* already closed/errored */
+      }
+    }
+    if (initiator !== 1) {
+      try {
+        controller2?.error(reason);
+      } catch {
+        /* already closed/errored */
+      }
+    }
+  }
+
+  function wrapBranch(
+    branchIndex: number,
+    rawBranch: ReadableStream<Uint8Array>,
+    assignReader: (r: ReadableStreamDefaultReader<Uint8Array>) => void,
+    assignController: (c: ReadableStreamDefaultController<Uint8Array>) => void,
+    addConsumed: (n: number) => void,
+    getSelfConsumed: () => number,
+    getOtherConsumed: () => number
+  ): ReadableStream<Uint8Array> {
+    const reader = rawBranch.getReader();
+    assignReader(reader);
+
+    return new ReadableStream<Uint8Array>({
+      start(controller) {
+        assignController(controller);
+      },
+
+      async pull(controller) {
+        if (cancelled) {
+          return;
+        }
+
+        try {
+          const { done, value } = await reader.read();
+
+          // Re-check after await — cancelBoth may have fired while we
+          // were waiting on the raw reader.
+          if (cancelled) return;
+
+          if (done) {
+            try {
+              controller.close();
+            } catch {
+              /* controller already errored by cancelBoth */
+            }
+            return;
+          }
+
+          addConsumed(value.byteLength);
+
+          // Check buffer divergence: the difference in consumed bytes
+          // approximates the tee's internal buffer size.
+          const divergence = getSelfConsumed() - getOtherConsumed();
+          if (divergence > maxBuffer) {
+            const error = new Error(
+              `RSC stream tee buffer exceeded ${formatBytes(maxBuffer)} ` +
+                `(divergence: ${formatBytes(divergence)}). ` +
+                `This usually means SSR is much slower than the inline stream consumer. ` +
+                `Consider reducing RSC payload size or increasing the tee buffer limit.`
+            );
+            console.warn(`[timber] ${error.message}`);
+            cancelBoth(error);
+            return;
+          }
+
+          controller.enqueue(value);
+        } catch (err) {
+          if (!cancelled) {
+            // Source stream errored — propagate to both branches.
+            // cancelBoth with initiator skips our own controller,
+            // so we error it explicitly here.
+            cancelBoth(err, branchIndex);
+            try {
+              controller.error(err);
+            } catch {
+              /* already closed/errored */
+            }
+          }
+        }
+      },
+
+      cancel(reason) {
+        // Consumer cancelled this branch — propagate to the other
+        cancelBoth(reason, branchIndex);
+      },
+    });
+  }
+
+  const wrapped1 = wrapBranch(
+    0,
+    rawBranch1,
+    (r) => {
+      rawReader1 = r;
+    },
+    (c) => {
+      controller1 = c;
+    },
+    (n) => {
+      consumed1 += n;
+    },
+    () => consumed1,
+    () => consumed2
+  );
+
+  const wrapped2 = wrapBranch(
+    1,
+    rawBranch2,
+    (r) => {
+      rawReader2 = r;
+    },
+    (c) => {
+      controller2 = c;
+    },
+    (n) => {
+      consumed2 += n;
+    },
+    () => consumed2,
+    () => consumed1
+  );
+
+  return [wrapped1, wrapped2];
+}
+
+/** Format bytes as human-readable string (e.g., "5.00 MB"). */
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}

package/src/server/tracing.ts

@@ -1,7 +1,7 @@
 /**
  * Tracing — per-request trace ID via AsyncLocalStorage, OTEL span helpers.
  *
- * traceId() is always available in server code (middleware, access, components, actions).
+ * getTraceId() is always available in server code (middleware, access, components, actions).
  * Returns a 32-char lowercase hex string — the OTEL trace ID when an SDK is active,
  * or a crypto.randomUUID()-derived fallback otherwise.
  *
@@ -24,11 +24,11 @@ export type { TraceStore } from './als-registry.js';
  *
  * Throws if called outside a request context (no ALS store).
  */
-export function traceId(): string {
+export function getTraceId(): string {
   const store = traceAls.getStore();
   if (!store) {
     throw new Error(
-      '[timber] traceId() called outside of a request context. ' +
+      '[timber] getTraceId() called outside of a request context. ' +
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
@@ -38,7 +38,7 @@ export function traceId(): string {
 /**
  * Returns the current OTEL span ID if available, undefined otherwise.
  */
-export function spanId(): string | undefined {
+export function getSpanId(): string | undefined {
   return traceAls.getStore()?.spanId;
 }
 
@@ -86,7 +86,7 @@ export function updateSpanId(newSpanId: string | undefined): void {
 
 /**
  * Get the current trace store, or undefined if outside a request context.
- * Framework-internal — use traceId()/spanId() in user code.
+ * Framework-internal — use getTraceId()/getSpanId() in user code.
  */
 export function getTraceStore(): TraceStore | undefined {
   return traceAls.getStore();
@@ -110,9 +110,20 @@ export async function initDevTracing(
   const api = await getOtelApi();
   if (!api) return;
 
-  const { DevSpanProcessor } = await import('./dev-span-processor.js');
-  const { BasicTracerProvider } = await import('@opentelemetry/sdk-trace-base');
-  const { AsyncLocalStorageContextManager } = await import('@opentelemetry/context-async-hooks');
+  let DevSpanProcessor: typeof import('./dev-span-processor.js').DevSpanProcessor;
+  let BasicTracerProvider: typeof import('@opentelemetry/sdk-trace-base').BasicTracerProvider;
+  let AsyncLocalStorageContextManager: typeof import('@opentelemetry/context-async-hooks').AsyncLocalStorageContextManager;
+
+  try {
+    ({ DevSpanProcessor } = await import('./dev-span-processor.js'));
+    ({ BasicTracerProvider } = await import('@opentelemetry/sdk-trace-base'));
+    ({ AsyncLocalStorageContextManager } = await import('@opentelemetry/context-async-hooks'));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(`[timber] Dev tracing disabled — failed to load OTEL packages:\n  ${msg}`);
+    return;
+  }
+
   const processor = new DevSpanProcessor(config);
 
   // Register a context manager so OTEL can propagate the active span
@@ -199,7 +210,7 @@ export async function withSpan<T>(
 
   const api = (await getOtelApi())!;
   return tracer.startActiveSpan(name, { attributes }, async (span) => {
-    const prevSpanId = spanId();
+    const prevSpanId = getSpanId();
     updateSpanId(span.spanContext().spanId);
     try {
       const result = await fn();

package/src/server/tree-builder.ts

@@ -10,7 +10,7 @@
  * See design/02-rendering-pipeline.md §"Element Tree Construction"
  */
 
-import type { SegmentNode, RouteFile } from '#/routing/types.js';
+import type { SegmentNode, RouteFile } from '../routing/types.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -46,10 +46,6 @@ export type SlotElements = Map<string, ReactElement>;
 export interface TreeBuilderConfig {
   /** The matched segment chain from root to leaf. */
   segments: SegmentNode[];
-  /** Route params extracted by the matcher (catch-all segments produce string[]). */
-  params: Record<string, string | string[]>;
-  /** Parsed search params (typed or URLSearchParams). */
-  searchParams: unknown;
   /** Loads a route file's module. */
   loadModule: ModuleLoader;
   /** React.createElement or equivalent. */
@@ -77,9 +73,7 @@ export interface TreeBuilderConfig {
  * (backward compat for tree-builder.ts which doesn't run a pre-render pass).
  */
 export interface AccessGateProps {
-  accessFn: (ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown;
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
+  accessFn: () => unknown;
   /** Segment name for dev logging (e.g. "authenticated", "dashboard"). */
   segmentName?: string;
   /**
@@ -92,18 +86,32 @@ export interface AccessGateProps {
     | 'pass'
     | import('./primitives.js').DenySignal
     | import('./primitives.js').RedirectSignal;
+  /**
+   * Deny page fallback chain. When provided and a DenySignal is caught,
+   * AccessGate renders the matching deny page in-tree instead of throwing.
+   * This prevents the error from reaching React Flight, eliminating the
+   * second render pass. See TIM-666.
+   */
+  denyPages?: import('./deny-page-resolver.js').DenyPageEntry[];
   children: ReactElement;
 }
 
 /**
  * Framework-injected slot access gate component.
  * On denial, renders denied.tsx → default.tsx → null instead of failing the page.
+ *
+ * DeniedComponent is passed instead of a pre-built element so that
+ * SlotAccessGate can forward DenySignal.data as dangerouslyPassData
+ * and slotName as the slot prop after catching the signal.
  */
 export interface SlotAccessGateProps {
-  accessFn: (ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown;
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
-  deniedFallback: ReactElement | null;
+  accessFn: () => unknown;
+  /** The denied.tsx component (not a pre-built element). null if no denied.tsx exists. */
+  DeniedComponent: ((...args: unknown[]) => unknown) | null;
+  /** Slot directory name without @ prefix (e.g. "admin", "sidebar"). */
+  slotName: string;
+  /** createElement function for building elements dynamically. */
+  createElement: CreateElement;
   defaultFallback: ReactElement | null;
   children: ReactElement;
 }
@@ -113,7 +121,8 @@ export interface SlotAccessGateProps {
  * Wraps content with status-code error boundary handling.
  */
 export interface ErrorBoundaryProps {
-  fallbackComponent: ReactElement | null;
+  fallbackComponent?: ReactElement | null;
+  fallbackElement?: ReactElement | null;
   status?: number;
   children: ReactElement;
 }
@@ -143,8 +152,7 @@ export interface TreeBuildResult {
  * Parallel slots are resolved at each layout level and composed as named props.
  */
 export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeBuildResult> {
-  const { segments, params, searchParams, loadModule, createElement, errorBoundaryComponent } =
-    config;
+  const { segments, loadModule, createElement, errorBoundaryComponent } = config;
 
   if (segments.length === 0) {
     throw new Error('[timber] buildElementTree: empty segment chain');
@@ -168,8 +176,8 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
     );
   }
 
-  // Build the page element with params and searchParams props
-  let element: ReactElement = createElement(PageComponent, { params, searchParams });
+  // Build the page element — params are accessed via getSegmentParams() from ALS
+  let element: ReactElement = createElement(PageComponent, {});
 
   // Build tree bottom-up: wrap page, then walk segments from leaf to root
   for (let i = segments.length - 1; i >= 0; i--) {
@@ -190,8 +198,6 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
       const accessFn = accessModule.default as AccessGateProps['accessFn'];
       element = createElement('timber:access-gate', {
         accessFn,
-        params,
-        searchParams,
         segmentName: segment.segmentName,
         children: element,
       } satisfies AccessGateProps);
@@ -211,8 +217,6 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
           for (const [slotName, slotNode] of segment.slots) {
             slotProps[slotName] = await buildSlotElement(
               slotNode,
-              params,
-              searchParams,
               loadModule,
               createElement,
               errorBoundaryComponent
@@ -222,8 +226,6 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
 
         element = createElement(LayoutComponent, {
           ...slotProps,
-          params,
-          searchParams,
           children: element,
         });
       }
@@ -243,8 +245,6 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
  */
 async function buildSlotElement(
   slotNode: SegmentNode,
-  params: Record<string, string | string[]>,
-  searchParams: unknown,
   loadModule: ModuleLoader,
   createElement: CreateElement,
   errorBoundaryComponent: unknown
@@ -261,10 +261,10 @@ async function buildSlotElement(
 
   // If no page, render default.tsx or null
   if (!PageComponent) {
-    return DefaultComponent ? createElement(DefaultComponent, { params, searchParams }) : null;
+    return DefaultComponent ? createElement(DefaultComponent, {}) : null;
   }
 
-  let element: ReactElement = createElement(PageComponent, { params, searchParams });
+  let element: ReactElement = createElement(PageComponent, {});
 
   // Wrap in error boundaries
   element = await wrapWithErrorBoundaries(
@@ -280,27 +280,19 @@ async function buildSlotElement(
     const accessModule = await loadModule(slotNode.access);
     const accessFn = accessModule.default as SlotAccessGateProps['accessFn'];
 
-    // Load denied.tsx
+    // Load denied.tsx — pass component (not pre-built element) so
+    // SlotAccessGate can forward DenySignal.data dynamically. See TIM-488.
     const deniedModule = slotNode.denied ? await loadModule(slotNode.denied) : null;
-    const DeniedComponent = deniedModule?.default as
-      | ((...args: unknown[]) => ReactElement)
-      | undefined;
-
-    const deniedFallback = DeniedComponent
-      ? createElement(DeniedComponent, {
-          slot: slotNode.segmentName.replace(/^@/, ''),
-          dangerouslyPassData: undefined,
-        })
-      : null;
-    const defaultFallback = DefaultComponent
-      ? createElement(DefaultComponent, { params, searchParams })
-      : null;
+    const DeniedComponent =
+      (deniedModule?.default as ((...args: unknown[]) => ReactElement) | undefined) ?? null;
+
+    const defaultFallback = DefaultComponent ? createElement(DefaultComponent, {}) : null;
 
     element = createElement('timber:slot-access-gate', {
       accessFn,
-      params,
-      searchParams,
-      deniedFallback,
+      DeniedComponent,
+      slotName: slotNode.segmentName.replace(/^@/, ''),
+      createElement,
       defaultFallback,
       children: element,
     } satisfies SlotAccessGateProps);
@@ -311,6 +303,19 @@ async function buildSlotElement(
 
 // ─── Error Boundary Wrapping ─────────────────────────────────────────────────
 
+/** MDX/markdown extensions — these are server components that cannot be passed as function props. */
+const MDX_EXTENSIONS = new Set(['mdx', 'md']);
+
+/**
+ * Check if a route file is an MDX/markdown file based on its extension.
+ * MDX components are server components by default and cannot cross the
+ * RSC→client boundary as function props. They must be pre-rendered as
+ * elements and passed as fallbackElement instead of fallbackComponent.
+ */
+function isMdxFile(file: RouteFile): boolean {
+  return MDX_EXTENSIONS.has(file.extension);
+}
+
 /**
  * Wrap an element with error boundaries from a segment's status-code files.
  *
@@ -320,6 +325,12 @@ async function buildSlotElement(
  *   3. error.tsx (general error boundary)
  *
  * This creates the fallback chain described in design/10-error-handling.md.
+ *
+ * MDX status files are server components and cannot be passed as function
+ * props to TimberErrorBoundary (a 'use client' component). Instead, they
+ * are pre-rendered as elements and passed as fallbackElement. The error
+ * boundary renders the element directly when an error is caught.
+ * See TIM-503.
  */
 async function wrapWithErrorBoundaries(
   segment: SegmentNode,
@@ -340,11 +351,18 @@ async function wrapWithErrorBoundaries(
           const mod = await loadModule(file);
           const Component = mod.default;
           if (Component) {
-            element = createElement(errorBoundaryComponent, {
-              fallbackComponent: Component,
-              status,
-              children: element,
-            } satisfies ErrorBoundaryProps);
+            const boundaryProps = isMdxFile(file)
+              ? ({
+                  fallbackElement: createElement(Component, { status }),
+                  status,
+                  children: element,
+                } satisfies ErrorBoundaryProps)
+              : ({
+                  fallbackComponent: Component,
+                  status,
+                  children: element,
+                } satisfies ErrorBoundaryProps);
+            element = createElement(errorBoundaryComponent, boundaryProps);
           }
         }
       }
@@ -356,25 +374,41 @@ async function wrapWithErrorBoundaries(
         const mod = await loadModule(file);
         const Component = mod.default;
         if (Component) {
-          element = createElement(errorBoundaryComponent, {
-            fallbackComponent: Component,
-            status: key === '4xx' ? 400 : 500, // category marker
-            children: element,
-          } satisfies ErrorBoundaryProps);
+          const categoryStatus = key === '4xx' ? 400 : 500;
+          const boundaryProps = isMdxFile(file)
+            ? ({
+                fallbackElement: createElement(Component, {}),
+                status: categoryStatus,
+                children: element,
+              } satisfies ErrorBoundaryProps)
+            : ({
+                fallbackComponent: Component,
+                status: categoryStatus,
+                children: element,
+              } satisfies ErrorBoundaryProps);
+          element = createElement(errorBoundaryComponent, boundaryProps);
         }
       }
     }
   }
 
   // Wrap with error.tsx (outermost — catches anything not matched by status files)
+  // Note: error.tsx/error.mdx receives { error, digest, reset } props.
+  // MDX error files are pre-rendered without those props (they're static content).
   if (segment.error) {
     const errorModule = await loadModule(segment.error);
     const ErrorComponent = errorModule.default;
     if (ErrorComponent) {
-      element = createElement(errorBoundaryComponent, {
-        fallbackComponent: ErrorComponent,
-        children: element,
-      } satisfies ErrorBoundaryProps);
+      const boundaryProps = isMdxFile(segment.error)
+        ? ({
+            fallbackElement: createElement(ErrorComponent, {}),
+            children: element,
+          } satisfies ErrorBoundaryProps)
+        : ({
+            fallbackComponent: ErrorComponent,
+            children: element,
+          } satisfies ErrorBoundaryProps);
+      element = createElement(errorBoundaryComponent, boundaryProps);
     }
   }
 

package/src/server/types.ts

@@ -22,8 +22,7 @@ export interface MiddlewareContext {
   req: Request;
   requestHeaders: Headers;
   headers: Headers;
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
+  segmentParams: Record<string, string | string[]>;
   /** Declare early hints for critical resources. Appends Link headers. */
   earlyHints: (hints: EarlyHint[]) => void;
 }
@@ -35,10 +34,8 @@ export interface RouteContext {
   headers: Headers;
 }
 
-export interface AccessContext {
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
-}
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface AccessContext {}
 
 export interface Metadata {
   title?: string | { default?: string; template?: string; absolute?: string };