@timber-js/app 0.1.38 → 0.1.39

package/src/server/compress.ts

@@ -0,0 +1,200 @@
+// Response compression for self-hosted deployments (dev server, Nitro preview).
+//
+// Uses CompressionStream (Web Platform API) for gzip and node:zlib for
+// brotli (CompressionStream doesn't support brotli). Cloudflare Workers
+// auto-compress at the edge — this module is only used on Node.js/Bun.
+//
+// See design/25-production-deployments.md.
+
+import { createBrotliCompress, constants as zlibConstants } from 'node:zlib';
+import { Readable } from 'node:stream';
+
+// ─── Constants ────────────────────────────────────────────────────────────
+
+/**
+ * MIME types that benefit from compression.
+ * text/* is handled via prefix matching; these are the specific
+ * application/* and image/* types that are compressible.
+ */
+export const COMPRESSIBLE_TYPES = new Set([
+  'text/html',
+  'text/css',
+  'text/plain',
+  'text/xml',
+  'text/javascript',
+  'text/x-component',
+  'application/json',
+  'application/javascript',
+  'application/xml',
+  'application/xhtml+xml',
+  'application/rss+xml',
+  'application/atom+xml',
+  'image/svg+xml',
+]);
+
+/**
+ * Status codes that should never be compressed (no body or special semantics).
+ */
+const NO_COMPRESS_STATUSES = new Set([204, 304]);
+
+// ─── Encoding Negotiation ─────────────────────────────────────────────────
+
+/**
+ * Parse Accept-Encoding and return the best supported encoding.
+ * Prefers brotli (br) over gzip. Returns null if no supported encoding.
+ *
+ * We always prefer brotli regardless of quality values because:
+ * 1. Brotli achieves better compression ratios than gzip
+ * 2. All modern browsers that send br in Accept-Encoding support it well
+ * 3. Respecting q-values for br vs gzip adds complexity with no real benefit
+ */
+export function negotiateEncoding(acceptEncoding: string): 'br' | 'gzip' | null {
+  if (!acceptEncoding) return null;
+
+  // Parse tokens from the Accept-Encoding header (ignore quality values).
+  // e.g. "gzip;q=1.0, br;q=0.8, deflate" → ['gzip', 'br', 'deflate']
+  const tokens = acceptEncoding.split(',').map((s) => s.split(';')[0].trim().toLowerCase());
+
+  if (tokens.includes('br')) return 'br';
+  if (tokens.includes('gzip')) return 'gzip';
+  return null;
+}
+
+// ─── Compressibility Check ────────────────────────────────────────────────
+
+/**
+ * Determine if a response should be compressed.
+ *
+ * Returns false for:
+ * - Responses without a body (204, 304, null body)
+ * - Already-encoded responses (Content-Encoding set)
+ * - Non-compressible content types (images, binary)
+ * - SSE streams (text/event-stream — must not be buffered)
+ */
+export function shouldCompress(response: Response): boolean {
+  // No body to compress
+  if (!response.body) return false;
+  if (NO_COMPRESS_STATUSES.has(response.status)) return false;
+
+  // Already compressed
+  if (response.headers.has('Content-Encoding')) return false;
+
+  // Check content type
+  const contentType = response.headers.get('Content-Type');
+  if (!contentType) return false;
+
+  // Extract the MIME type (strip charset and other parameters)
+  const mimeType = contentType.split(';')[0].trim().toLowerCase();
+
+  // SSE must not be compressed — it relies on chunk-by-chunk delivery
+  if (mimeType === 'text/event-stream') return false;
+
+  return COMPRESSIBLE_TYPES.has(mimeType);
+}
+
+// ─── Compression ──────────────────────────────────────────────────────────
+
+/**
+ * Compress a Web Response if the client supports it and the content is compressible.
+ *
+ * Returns the original response unchanged if compression is not applicable.
+ * Returns a new Response with the compressed body, Content-Encoding, and Vary headers.
+ *
+ * The body is piped through a compression stream — no buffering of the full response.
+ * This preserves streaming behavior for HTML shell + deferred Suspense chunks.
+ */
+export function compressResponse(request: Request, response: Response): Response {
+  // Check if response is compressible
+  if (!shouldCompress(response)) return response;
+
+  // Negotiate encoding with the client
+  const acceptEncoding = request.headers.get('Accept-Encoding') ?? '';
+  const encoding = negotiateEncoding(acceptEncoding);
+  if (!encoding) return response;
+
+  // Compress the body stream
+  const compressedBody = encoding === 'br'
+    ? compressWithBrotli(response.body!)
+    : compressWithGzip(response.body!);
+
+  // Build new headers: copy originals, add compression headers, remove Content-Length
+  // (compressed size is unknown until streaming completes).
+  const headers = new Headers(response.headers);
+  headers.set('Content-Encoding', encoding);
+  headers.delete('Content-Length');
+
+  // Append to Vary header (preserve existing Vary values)
+  const existingVary = headers.get('Vary');
+  if (existingVary) {
+    if (!existingVary.toLowerCase().includes('accept-encoding')) {
+      headers.set('Vary', `${existingVary}, Accept-Encoding`);
+    }
+  } else {
+    headers.set('Vary', 'Accept-Encoding');
+  }
+
+  return new Response(compressedBody, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+// ─── Gzip (CompressionStream API) ────────────────────────────────────────
+
+/**
+ * Compress a ReadableStream with gzip using the Web Platform CompressionStream API.
+ * Available in Node 18+, Bun, and Deno — no npm dependency needed.
+ */
+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>);
+}
+
+// ─── Brotli (node:zlib) ──────────────────────────────────────────────────
+
+/**
+ * Compress a ReadableStream with brotli using node:zlib.
+ *
+ * CompressionStream doesn't support brotli — it only handles gzip and deflate.
+ * We use node:zlib's createBrotliCompress() and bridge between Web streams
+ * and Node streams.
+ */
+function compressWithBrotli(body: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
+  const brotli = createBrotliCompress({
+    params: {
+      // Quality 4 balances compression ratio and CPU time for streaming.
+      // Default (11) is too slow for real-time responses.
+      [zlibConstants.BROTLI_PARAM_QUALITY]: 4,
+    },
+  });
+
+  // Pipe the Web ReadableStream into the Node brotli transform.
+  const reader = body.getReader();
+
+  // Pump chunks from the Web ReadableStream into the Node transform.
+  const pump = async (): Promise<void> => {
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          brotli.end();
+          return;
+        }
+        // Write to brotli, wait for drain if buffer is full
+        if (!brotli.write(value)) {
+          await new Promise<void>((resolve) => brotli.once('drain', resolve));
+        }
+      }
+    } catch (err) {
+      brotli.destroy(err instanceof Error ? err : new Error(String(err)));
+    }
+  };
+  // Start pumping (fire and forget — errors propagate via brotli stream)
+  pump();
+
+  // Convert the Node readable (brotli output) to a Web ReadableStream.
+  return Readable.toWeb(brotli) as ReadableStream<Uint8Array>;
+}

package/src/server/route-element-builder.ts

@@ -32,6 +32,7 @@ import { setParsedSearchParams } from './request-context.js';
 import type { SearchParamsDefinition } from '#/search-params/create.js';
 import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.js';
 import type { InterceptionContext } from './pipeline.js';
+import { shouldSkipSegment } from './state-tree-diff.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -91,7 +92,8 @@ export class RouteSignalWithContext extends Error {
 export async function buildRouteElement(
   req: Request,
   match: RouteMatch,
-  interception?: InterceptionContext
+  interception?: InterceptionContext,
+  clientStateTree?: Set<string> | null
 ): Promise<RouteElementResult> {
   const segments = match.segments as unknown as ManifestSegmentNode[];
 
@@ -308,8 +310,32 @@ export async function buildRouteElement(
   //   1. Error boundaries (status files + error.tsx)
   //   2. Layout component — wraps children + parallel slots
   //   3. SegmentProvider — records position for useSelectedLayoutSegment
+  //
+  // When clientStateTree is provided (from X-Timber-State-Tree header on
+  // client navigation), sync layouts the client already has are skipped.
+  // Access.ts already ran for ALL segments in the pre-render loop above.
+  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
   for (let i = segments.length - 1; i >= 0; i--) {
     const segment = segments[i];
+    const isLeaf = i === segments.length - 1;
+    const layoutComponent = layoutBySegment.get(segment);
+
+    // Check if this segment's layout can be skipped for partial rendering.
+    // Skipped segments: no layout wrapping, no error boundaries, no slots,
+    // no AccessGate in element tree (access already ran pre-render).
+    const skip = shouldSkipSegment(
+      segment.urlPath,
+      layoutComponent,
+      isLeaf,
+      clientStateTree ?? null
+    );
+
+    if (skip) {
+      // Skip this segment entirely — the client uses its cached version.
+      // Access.ts already ran in the pre-render loop (security guarantee).
+      // Metadata was already resolved above (head elements are correct).
+      continue;
+    }
 
     // Wrap with error boundaries from this segment (inside layout).
     element = await wrapSegmentWithErrorBoundaries(segment, element, h);
@@ -335,7 +361,6 @@ export async function buildRouteElement(
     }
 
     // Wrap with layout if this segment has one — traced with OTEL span
-    const layoutComponent = layoutBySegment.get(segment);
     if (layoutComponent) {
       // Resolve parallel slots for this layout
       const slotProps: Record<string, unknown> = {};

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

@@ -59,6 +59,7 @@ import {
   escapeHtml,
   isRscPayloadRequest,
 } from './helpers.js';
+import { parseClientStateTree } from '#/server/state-tree-diff.js';
 import { buildRscPayloadResponse } from './rsc-payload.js';
 import { renderRscStream } from './rsc-stream.js';
 import { renderSsrResponse } from './ssr-renderer.js';
@@ -268,11 +269,18 @@ async function renderRoute(
     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, runs access checks,
   // resolves metadata. DenySignal/RedirectSignal propagate for HTTP handling.
   let routeResult;
   try {
-    routeResult = await buildRouteElement(_req, match, interception);
+    routeResult = await buildRouteElement(_req, match, interception, clientStateTree);
   } catch (error) {
     // RouteSignalWithContext wraps DenySignal/RedirectSignal with layout context
     if (error instanceof RouteSignalWithContext) {

package/src/server/state-tree-diff.ts

@@ -0,0 +1,77 @@
+/**
+ * State Tree Diffing — Server-side parsing and diffing of X-Timber-State-Tree.
+ *
+ * The client sends X-Timber-State-Tree on navigation requests, listing
+ * the sync segments it has cached. The server diffs this against the
+ * target route's segments to skip re-rendering unchanged sync layouts.
+ *
+ * This is a performance optimization only — NOT a security boundary.
+ * All access.ts files run regardless of the state tree content.
+ * A fabricated state tree can only cause extra rendering work or stale
+ * layouts — never auth bypass.
+ *
+ * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+ * See design/13-security.md §"State tree manipulation"
+ */
+
+/**
+ * Parse the X-Timber-State-Tree header from a request.
+ *
+ * Returns a Set of segment paths the client has cached, or null if
+ * the header is missing, malformed, or empty. Parsing happens before
+ * renderToReadableStream — not inside the React render pass.
+ *
+ * @returns Set of sync segment paths, or null if no valid state tree
+ */
+export function parseClientStateTree(req: Request): Set<string> | null {
+  const header = req.headers.get('X-Timber-State-Tree');
+  if (!header) return null;
+
+  try {
+    const parsed = JSON.parse(header) as { segments?: unknown };
+    if (!Array.isArray(parsed.segments) || parsed.segments.length === 0) {
+      return null;
+    }
+    return new Set(parsed.segments as string[]);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Determine whether a segment's layout rendering can be skipped.
+ *
+ * A segment is skipped when ALL of the following are true:
+ * 1. The client has the segment in its state tree (clientSegments contains urlPath)
+ * 2. The layout is sync (not an async function — async layouts always re-render)
+ * 3. The segment is NOT the leaf (pages are never cached across navigations)
+ *
+ * Access.ts still runs for skipped segments — this is enforced by the caller
+ * (buildRouteElement) which runs all access checks before building the tree.
+ *
+ * @param urlPath - The segment's URL path (e.g., "/", "/dashboard")
+ * @param layoutComponent - The loaded layout component function
+ * @param isLeaf - Whether this is the leaf segment (page segment)
+ * @param clientSegments - Set of paths from X-Timber-State-Tree, or null
+ */
+export function shouldSkipSegment(
+  urlPath: string,
+  layoutComponent: ((...args: unknown[]) => unknown) | undefined,
+  isLeaf: boolean,
+  clientSegments: Set<string> | null
+): boolean {
+  // No state tree → full render (initial load, refresh, etc.)
+  if (!clientSegments) return false;
+
+  // Leaf segments (pages) are never skipped
+  if (isLeaf) return false;
+
+  // No layout → nothing to skip
+  if (!layoutComponent) return false;
+
+  // Async layouts always re-render (they may depend on request context)
+  if (layoutComponent.constructor?.name === 'AsyncFunction') return false;
+
+  // Skip if the client already has this segment cached
+  return clientSegments.has(urlPath);
+}