@timber-js/app 0.2.0-alpha.17 → 0.2.0-alpha.170

package/src/server/request-context.ts

@@ -1,230 +1,220 @@
 /**
- * Request Context — per-request ALS store for headers() and cookies().
+ * Request Context — per-request ALS store for headers, search params,
+ * segment params, and request scope lifecycle.
  *
  * Follows the same pattern as tracing.ts: a module-level AsyncLocalStorage
  * instance, public accessor functions that throw outside request scope,
  * and a framework-internal `runWithRequestContext()` to establish scope.
  *
+ * Cookie state lives in `cookie-context.ts` (split out in TIM-853). The
+ * scope set up here owns the cookie jar / parsedCookies fields on the
+ * store, but the cookie API and helpers are in the cookie module.
+ *
  * See design/04-authorization.md §"AccessContext does not include cookies or headers"
  * and design/11-platform.md §"AsyncLocalStorage".
- * See design/29-cookies.md for cookie mutation semantics.
  */
 
-import { createHmac, timingSafeEqual } from 'node:crypto';
-import type { Routes } from '#/index.js';
-import { requestContextAls, type RequestContextStore, type CookieEntry } from './als-registry.js';
+import { requestContextAls, type RequestContextStore } from './als-registry.js';
+import { _setGetSearchParamsFn } from '../search-params/define.js';
+import { _setGetSegmentParamsFn } from '../segment-params/define.js';
+import { consumeSeededCookies } from './cookie-context.js';
 import { isDebug } from './debug.js';
 
 // Re-export the ALS for framework-internal consumers that need direct access.
 export { requestContextAls };
 
-// No fallback needed — we use enterWith() instead of run() to ensure
-// the ALS context persists for the entire request lifecycle including
-// async stream consumption by React's renderToReadableStream.
-
-// ─── Cookie Signing Secrets ──────────────────────────────────────────────
+// ─── Public API ───────────────────────────────────────────────────────────
 
 /**
- * Module-level cookie signing secrets. Index 0 is the newest (used for signing).
- * All entries are tried for verification (key rotation support).
+ * Returns a read-only view of the current request's headers.
  *
- * Set by the framework at startup via `setCookieSecrets()`.
- * See design/29-cookies.md §"Signed Cookies"
+ * Available in middleware, access checks, server components, and server actions.
+ * Throws if called outside a request context (security principle #2: no global fallback).
  */
-let _cookieSecrets: string[] = [];
+export function getHeaders(): ReadonlyHeaders {
+  const store = requestContextAls.getStore();
+  if (!store) {
+    throw new Error(
+      '[timber] getHeaders() called outside of a request context. ' +
+        'It can only be used in middleware, access checks, server components, and server actions.'
+    );
+  }
+  return store.headers;
+}
 
 /**
- * Configure the cookie signing secrets.
+ * Returns the value of a single request header, or undefined if absent.
  *
- * Called by the framework during server initialization with values from
- * `cookies.secret` or `cookies.secrets` in timber.config.ts.
+ * Thin wrapper over `getHeaders().get(name)` for the common case where
+ * you need exactly one header.
  *
- * The first secret (index 0) is used for signing new cookies.
- * All secrets are tried for verification (supports key rotation).
+ * @internal — not part of the public API. Use `getHeaders().get(name)` instead.
  */
-export function setCookieSecrets(secrets: string[]): void {
-  _cookieSecrets = secrets.filter(Boolean);
+export function getHeader(name: string): string | undefined {
+  const headers = getHeaders();
+  return headers.get(name) ?? undefined;
 }
 
-// ─── Public API ───────────────────────────────────────────────────────────
-
 /**
- * Returns a read-only view of the current request's headers.
+ * Returns the current request's raw URLSearchParams.
  *
- * Available in middleware, access checks, server components, and server actions.
- * Throws if called outside a request context (security principle #2: no global fallback).
+ * @internal — not part of the public API. Use `defineSearchParams().get()` instead.
  */
-export function headers(): ReadonlyHeaders {
+export function getSearchParams(): URLSearchParams {
   const store = requestContextAls.getStore();
   if (!store) {
     throw new Error(
-      '[timber] headers() called outside of a request context. ' +
+      '[timber] getSearchParams() called outside of a request context. ' +
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
-  return store.headers;
+  return store.searchParams;
 }
 
+// Eagerly register getSearchParams with the search-params module so
+// searchParams.get() can call it without a dynamic import.
+// Dynamic imports lose ALS context in React's RSC Flight renderer,
+// breaking getSearchParams() in parallel slot pages. See TIM-523.
+_setGetSearchParamsFn(getSearchParams);
+
+// Eagerly register getSegmentParams with the segment-params module so
+// segmentParams.get() can call it without a dynamic import.
+// Same pattern as search params — dynamic imports lose ALS context. See TIM-523.
+_setGetSegmentParamsFn(getSegmentParams);
+
 /**
- * Returns a cookie accessor for the current request.
- *
- * Available in middleware, access checks, server components, and server actions.
- * Throws if called outside a request context (security principle #2: no global fallback).
+ * Returns the current request's coerced segment params.
  *
- * Read methods (.get, .has, .getAll) are always available and reflect
- * read-your-own-writes from .set() calls in the same request.
+ * The optional `segmentPath` argument exists only for TypeScript narrowing —
+ * it does not affect the runtime return value. Pass a segment path
+ * (e.g. `'/(browse)/[artistSlug]/[year]'`) to narrow the return type to the
+ * exact params shape for that segment.
  *
- * Mutation methods (.set, .delete, .clear) are only available in mutable
- * contexts (middleware.ts, server actions, route.ts handlers). Calling them
- * in read-only contexts (access.ts, server components) throws.
+ * Without an argument, returns all coerced params with optional types.
  *
- * See design/29-cookies.md
+ * See design/41-global-params.md §Function Signatures
  */
-export function cookies(): RequestCookies {
+export function getSegmentParams(segmentPath?: string): Record<string, string | string[]> {
   const store = requestContextAls.getStore();
   if (!store) {
     throw new Error(
-      '[timber] cookies() called outside of a request context. ' +
+      '[timber] getSegmentParams() called outside of a request context. ' +
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
-
-  // Parse cookies lazily on first access
-  if (!store.parsedCookies) {
-    store.parsedCookies = parseCookieHeader(store.cookieHeader);
+  if (!store.segmentParams) {
+    throw new Error(
+      '[timber] getSegmentParams() called before route matching completed. ' +
+        'Segment params are not available until after the route is matched.'
+    );
   }
 
-  const map = store.parsedCookies;
-  return {
-    get(name: string): string | undefined {
-      return map.get(name);
-    },
-    has(name: string): boolean {
-      return map.has(name);
-    },
-    getAll(): Array<{ name: string; value: string }> {
-      return Array.from(map.entries()).map(([name, value]) => ({ name, value }));
-    },
-    get size(): number {
-      return map.size;
-    },
-
-    getSigned(name: string): string | undefined {
-      const raw = map.get(name);
-      if (!raw || _cookieSecrets.length === 0) return undefined;
-      return verifySignedCookie(raw, _cookieSecrets);
-    },
-
-    set(name: string, value: string, options?: CookieOptions): void {
-      assertMutable(store, 'set');
-      if (store.flushed) {
-        if (isDebug()) {
-          console.warn(
-            `[timber] warn: cookies().set('${name}') called after response headers were committed.\n` +
-              `  The cookie will NOT be sent. Move cookie mutations to middleware.ts, a server action,\n` +
-              `  or a route.ts handler.`
-          );
-        }
-        return;
-      }
-      let storedValue = value;
-      if (options?.signed) {
-        if (_cookieSecrets.length === 0) {
-          throw new Error(
-            `[timber] cookies().set('${name}', ..., { signed: true }) requires ` +
-              `cookies.secret or cookies.secrets in timber.config.ts.`
-          );
-        }
-        storedValue = signCookieValue(value, _cookieSecrets[0]);
-      }
-      const opts = { ...DEFAULT_COOKIE_OPTIONS, ...options };
-      store.cookieJar.set(name, { name, value: storedValue, options: opts });
-      // Read-your-own-writes: update the parsed cookies map with the signed value
-      // so getSigned() can verify it in the same request
-      map.set(name, storedValue);
-    },
-
-    delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void {
-      assertMutable(store, 'delete');
-      if (store.flushed) {
-        if (isDebug()) {
-          console.warn(
-            `[timber] warn: cookies().delete('${name}') called after response headers were committed.\n` +
-              `  The cookie will NOT be deleted. Move cookie mutations to middleware.ts, a server action,\n` +
-              `  or a route.ts handler.`
-          );
-        }
-        return;
-      }
-      const opts: CookieOptions = {
-        ...DEFAULT_COOKIE_OPTIONS,
-        ...options,
-        maxAge: 0,
-        expires: new Date(0),
-      };
-      store.cookieJar.set(name, { name, value: '', options: opts });
-      // Remove from read view
-      map.delete(name);
-    },
+  // Check slot params map first — parallel slots may have different param
+  // types than the main route (e.g. catch-all [..year] → string[] vs
+  // dynamic [year] → string). If the requested segment path matches a
+  // stored slot, return its params merged with the main route's.
+  if (segmentPath && store.slotParamsMap?.has(segmentPath)) {
+    const slotParams = store.slotParamsMap.get(segmentPath)!;
+    // Merge: main params as base, slot-specific params override.
+    // This ensures params from segments above the slot (that the slot
+    // doesn't re-derive) are still available.
+    return { ...store.segmentParams, ...slotParams };
+  }
 
-    clear(): void {
-      assertMutable(store, 'clear');
-      if (store.flushed) return;
-      // Delete every incoming cookie
-      for (const name of Array.from(map.keys())) {
-        store.cookieJar.set(name, {
-          name,
-          value: '',
-          options: { ...DEFAULT_COOKIE_OPTIONS, maxAge: 0, expires: new Date(0) },
-        });
-      }
-      map.clear();
-    },
+  // Dev-mode validation: warn when the segment path expects dynamic
+  // segments that don't exist on the actual matched segment. This catches
+  // bugs like passing a child segment's $segment to a parent layout.
+  // Skip for slot paths — they're validated against their own chain.
+  // See design/41-global-params.md §Runtime Validation
+  if (segmentPath && isDebug() && store.matchedSegmentPath) {
+    const expected = extractDynamicSegments(segmentPath);
+    const actual = extractDynamicSegments(store.matchedSegmentPath);
+    const missing = expected.filter((s) => !actual.includes(s));
+
+    if (missing.length > 0) {
+      console.warn(
+        `[timber] getSegmentParams('${segmentPath}') called but current segment is '${store.matchedSegmentPath}'\n` +
+          `  Missing params: ${missing.join(', ')}\n` +
+          `  These will be undefined at runtime despite the type annotation.`
+      );
+    }
+  }
 
-    toString(): string {
-      return Array.from(map.entries())
-        .map(([name, value]) => `${name}=${value}`)
-        .join('; ');
-    },
-  };
+  return store.segmentParams;
 }
 
 /**
- * Returns a Promise resolving to the current request's search params.
+ * Set the segment params on the current request context.
+ * Called by the pipeline after route matching and param coercion.
  *
- * In `page.tsx`, `middleware.ts`, and `access.ts` the framework pre-parses the
- * route's `search-params.ts` definition and the Promise resolves to the typed
- * object. In all other server component contexts it resolves to raw
- * `URLSearchParams`.
- *
- * Returned as a Promise to match the `params` prop convention and to allow
- * future partial pre-rendering support where param resolution may be deferred.
- *
- * Throws if called outside a request context.
+ * @internal — framework use only
  */
-export function searchParams<R extends keyof Routes>(): Promise<Routes[R]['searchParams']>;
-export function searchParams(): Promise<URLSearchParams | Record<string, unknown>>;
-export function searchParams(): Promise<URLSearchParams | Record<string, unknown>> {
+export function setSegmentParams(params: Record<string, string | string[]>): void {
   const store = requestContextAls.getStore();
   if (!store) {
-    throw new Error(
-      '[timber] searchParams() called outside of a request context. ' +
-        'It can only be used in middleware, access checks, server components, and server actions.'
-    );
+    throw new Error('[timber] setSegmentParams() called outside of a request context.');
   }
-  return store.searchParamsPromise;
+  store.segmentParams = params;
 }
 
 /**
- * Replace the search params Promise for the current request with one that
- * resolves to the typed parsed result from the route's search-params.ts.
- * Called by the framework before rendering the page — not for app code.
+ * Store per-slot coerced segment params in the current request context.
+ * Called by the route element builder when resolving parallel slots.
+ *
+ * @param segmentPath — The slot's full tree path (e.g. '/(browse)/@shows/[artistSlug]/[...year]')
+ * @param params — The slot's coerced segment params
+ * @internal — framework use only
  */
-export function setParsedSearchParams(parsed: Record<string, unknown>): void {
+export function setSlotParams(
+  segmentPath: string,
+  params: Record<string, string | string[]>
+): void {
   const store = requestContextAls.getStore();
-  if (store) {
-    store.searchParamsPromise = Promise.resolve(parsed);
+  if (!store) return; // non-throwing — optional diagnostic
+  if (!store.slotParamsMap) store.slotParamsMap = new Map();
+  store.slotParamsMap.set(segmentPath, params);
+}
+
+/**
+ * Store the matched segment path (e.g. '/(browse)/[artistSlug]/[year]') for
+ * dev-mode validation in getSegmentParams().
+ *
+ * @internal — framework use only
+ */
+export function setMatchedSegmentPath(segmentPath: string): void {
+  const store = requestContextAls.getStore();
+  if (!store) return; // non-throwing — optional diagnostic
+  store.matchedSegmentPath = segmentPath;
+}
+
+/**
+ * Extract dynamic segment names from a route pattern.
+ * '/[artistSlug]/[year]' → ['artistSlug', 'year']
+ * '/docs/[...slug]'      → ['slug']
+ */
+function extractDynamicSegments(route: string): string[] {
+  const segments: string[] = [];
+  // Match [paramName], [...paramName], [[...paramName]]
+  const re = /\[{1,2}\.{0,3}(\w+)\]{1,2}/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(route)) !== null) {
+    segments.push(m[1]);
   }
+  return segments;
+}
+
+/**
+ * Returns the raw search string from the current request URL (e.g. "?foo=bar").
+ * Synchronous — safe for use in `redirect()` which throws synchronously.
+ *
+ * Returns empty string if called outside a request context (non-throwing for
+ * use in redirect's optional preserveSearchParams path).
+ *
+ * @internal — used by redirect() for preserveSearchParams support.
+ */
+export function getRequestSearchString(): string {
+  const store = requestContextAls.getStore();
+  return store?.searchString ?? '';
 }
 
 // ─── Types ────────────────────────────────────────────────────────────────
@@ -239,88 +229,34 @@ export type ReadonlyHeaders = Pick<
   'get' | 'has' | 'entries' | 'keys' | 'values' | 'forEach' | typeof Symbol.iterator
 >;
 
-/** Options for setting a cookie. See design/29-cookies.md. */
-export interface CookieOptions {
-  /** Domain scope. Default: omitted (current domain only). */
-  domain?: string;
-  /** URL path scope. Default: '/'. */
-  path?: string;
-  /** Expiration date. Mutually exclusive with maxAge. */
-  expires?: Date;
-  /** Max age in seconds. Mutually exclusive with expires. */
-  maxAge?: number;
-  /** Prevent client-side JS access. Default: true. */
-  httpOnly?: boolean;
-  /** Only send over HTTPS. Default: true. */
-  secure?: boolean;
-  /** Cross-site request policy. Default: 'lax'. */
-  sameSite?: 'strict' | 'lax' | 'none';
-  /** Partitioned (CHIPS) — isolate cookie per top-level site. Default: false. */
-  partitioned?: boolean;
-  /**
-   * Sign the cookie value with HMAC-SHA256 for integrity verification.
-   * Requires `cookies.secret` or `cookies.secrets` in timber.config.ts.
-   * See design/29-cookies.md §"Signed Cookies".
-   */
-  signed?: boolean;
-}
-
-const DEFAULT_COOKIE_OPTIONS: CookieOptions = {
-  path: '/',
-  httpOnly: true,
-  secure: true,
-  sameSite: 'lax',
-};
-
-/**
- * Cookie accessor returned by `cookies()`.
- *
- * Read methods are always available. Mutation methods throw in read-only
- * contexts (access.ts, server components).
- */
-export interface RequestCookies {
-  /** Get a cookie value by name. Returns undefined if not present. */
-  get(name: string): string | undefined;
-  /** Check if a cookie exists. */
-  has(name: string): boolean;
-  /** Get all cookies as an array of { name, value } pairs. */
-  getAll(): Array<{ name: string; value: string }>;
-  /** Number of cookies. */
-  readonly size: number;
-  /**
-   * Get a signed cookie value, verifying its HMAC-SHA256 signature.
-   * Returns undefined if the cookie is missing, the signature is invalid,
-   * or no secrets are configured. Never throws.
-   *
-   * See design/29-cookies.md §"Signed Cookies"
-   */
-  getSigned(name: string): string | undefined;
-  /** Set a cookie. Only available in mutable contexts (middleware, actions, route handlers). */
-  set(name: string, value: string, options?: CookieOptions): void;
-  /** Delete a cookie. Only available in mutable contexts. */
-  delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void;
-  /** Delete all cookies. Only available in mutable contexts. */
-  clear(): void;
-  /** Serialize cookies as a Cookie header string. */
-  toString(): string;
-}
-
 // ─── Framework-Internal Helpers ───────────────────────────────────────────
 
 /**
  * Run a callback within a request context. Used by the pipeline to establish
- * per-request ALS scope so that `headers()` and `cookies()` work.
+ * per-request ALS scope so that `getHeaders()` and `getCookies()` work.
+ *
+ * If the request was previously registered via `seedRequestCookies`, the
+ * resulting context's `parsedCookies` map is initialized from the seed and
+ * the raw `cookieHeader` is left empty — `parseCookieHeader` is never called
+ * for that request. This is the no-JS form-rerender path. See TIM-868.
  *
  * @param req - The incoming Request object.
  * @param fn - The function to run within the request context.
  */
 export function runWithRequestContext<T>(req: Request, fn: () => T): T {
   const originalCopy = new Headers(req.headers);
+  const parsedUrl = new URL(req.url);
+  const seed = consumeSeededCookies(req);
   const store: RequestContextStore = {
     headers: freezeHeaders(req.headers),
     originalHeaders: originalCopy,
-    cookieHeader: req.headers.get('cookie') ?? '',
-    searchParamsPromise: Promise.resolve(new URL(req.url).searchParams),
+    // When seeded, leave the raw header empty — parseCookieHeader is the
+    // exact code path the smuggling primitive abused, and lazy parsing is
+    // gated on `parsedCookies` being undefined.
+    cookieHeader: seed ? '' : (req.headers.get('cookie') ?? ''),
+    parsedCookies: seed,
+    searchParams: parsedUrl.searchParams,
+    searchString: parsedUrl.search,
     cookieJar: new Map(),
     flushed: false,
     mutableContext: false,
@@ -354,24 +290,12 @@ export function markResponseFlushed(): void {
   }
 }
 
-/**
- * Collect all Set-Cookie headers from the cookie jar.
- * Called by the framework at flush time to apply cookies to the response.
- *
- * Returns an array of serialized Set-Cookie header values.
- */
-export function getSetCookieHeaders(): string[] {
-  const store = requestContextAls.getStore();
-  if (!store) return [];
-  return Array.from(store.cookieJar.values()).map(serializeCookieEntry);
-}
-
 /**
  * Apply middleware-injected request headers to the current request context.
  *
  * Called by the pipeline after middleware.ts runs. Merges overlay headers
  * on top of the original request headers so downstream code (access.ts,
- * server components, server actions) sees them via `headers()`.
+ * server components, server actions) sees them via `getHeaders()`.
  *
  * The original request headers are never mutated — a new frozen Headers
  * object is created with the overlay applied on top.
@@ -418,7 +342,7 @@ function freezeHeaders(source: Headers): Headers {
       if (typeof prop === 'string' && MUTATING_METHODS.has(prop)) {
         return () => {
           throw new Error(
-            `[timber] headers() returns a read-only Headers object. ` +
+            `[timber] getHeaders() returns a read-only Headers object. ` +
               `Calling .${prop}() is not allowed. ` +
               `Use ctx.requestHeaders in middleware to inject headers for downstream components.`
           );
@@ -433,96 +357,3 @@ function freezeHeaders(source: Headers): Headers {
     },
   });
 }
-
-// ─── Cookie Helpers ───────────────────────────────────────────────────────
-
-/** Throw if cookie mutation is attempted in a read-only context. */
-function assertMutable(store: RequestContextStore, method: string): void {
-  if (!store.mutableContext) {
-    throw new Error(
-      `[timber] cookies().${method}() cannot be called in this context.\n` +
-        `  Set cookies in middleware.ts, server actions, or route.ts handlers.`
-    );
-  }
-}
-
-/**
- * Parse a Cookie header string into a Map of name → value pairs.
- * Follows RFC 6265 §4.2.1: cookies are semicolon-separated key=value pairs.
- */
-function parseCookieHeader(header: string): Map<string, string> {
-  const map = new Map<string, string>();
-  if (!header) return map;
-
-  for (const pair of header.split(';')) {
-    const eqIndex = pair.indexOf('=');
-    if (eqIndex === -1) continue;
-    const name = pair.slice(0, eqIndex).trim();
-    const value = pair.slice(eqIndex + 1).trim();
-    if (name) {
-      map.set(name, value);
-    }
-  }
-
-  return map;
-}
-
-// ─── Cookie Signing ──────────────────────────────────────────────────────
-
-/**
- * Sign a cookie value with HMAC-SHA256.
- * Returns `value.hex_signature`.
- */
-function signCookieValue(value: string, secret: string): string {
-  const signature = createHmac('sha256', secret).update(value).digest('hex');
-  return `${value}.${signature}`;
-}
-
-/**
- * Verify a signed cookie value against an array of secrets.
- * Returns the original value if any secret produces a matching signature,
- * or undefined if none match. Uses timing-safe comparison.
- *
- * The signed format is `value.hex_signature` — split at the last `.`.
- */
-function verifySignedCookie(raw: string, secrets: string[]): string | undefined {
-  const lastDot = raw.lastIndexOf('.');
-  if (lastDot <= 0 || lastDot === raw.length - 1) return undefined;
-
-  const value = raw.slice(0, lastDot);
-  const signature = raw.slice(lastDot + 1);
-
-  // Hex-encoded SHA-256 is always 64 chars
-  if (signature.length !== 64) return undefined;
-
-  const signatureBuffer = Buffer.from(signature, 'hex');
-  // If the hex decode produced fewer bytes, the signature was not valid hex
-  if (signatureBuffer.length !== 32) return undefined;
-
-  for (const secret of secrets) {
-    const expected = createHmac('sha256', secret).update(value).digest();
-    if (timingSafeEqual(expected, signatureBuffer)) {
-      return value;
-    }
-  }
-  return undefined;
-}
-
-/** Serialize a CookieEntry into a Set-Cookie header value. */
-function serializeCookieEntry(entry: CookieEntry): string {
-  const parts = [`${entry.name}=${entry.value}`];
-  const opts = entry.options;
-
-  if (opts.domain) parts.push(`Domain=${opts.domain}`);
-  if (opts.path) parts.push(`Path=${opts.path}`);
-  if (opts.expires) parts.push(`Expires=${opts.expires.toUTCString()}`);
-  if (opts.maxAge !== undefined) parts.push(`Max-Age=${opts.maxAge}`);
-  if (opts.httpOnly) parts.push('HttpOnly');
-  if (opts.secure) parts.push('Secure');
-  if (opts.sameSite) {
-    parts.push(`SameSite=${opts.sameSite.charAt(0).toUpperCase()}${opts.sameSite.slice(1)}`);
-  }
-  if (opts.partitioned) parts.push('Partitioned');
-
-  return parts.join('; ');
-}