@timber-js/app 0.2.0-alpha.97 → 0.2.0-alpha.99

package/src/server/request-context.ts

@@ -1,19 +1,25 @@
 /**
- * Request Context — per-request ALS store for getHeaders() and getCookies().
+ * 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 { requestContextAls, type RequestContextStore, type CookieEntry } from './als-registry.js';
-import { isDebug } from './debug.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, getCookieJar } from './cookie-context.js';
+import { _registerServerCookieImpl, _registerFromSchema } from '../cookies/define-cookie.js';
+import { fromSchema } from '../schema-bridge.js';
 
 // Re-export the ALS for framework-internal consumers that need direct access.
 export { requestContextAls };
@@ -30,7 +36,7 @@ export { requestContextAls };
  * Available in middleware, access checks, server components, and server actions.
  * Throws if called outside a request context (security principle #2: no global fallback).
  */
-export function getHeaders(): Promise<ReadonlyHeaders> {
+export function getHeaders(): ReadonlyHeaders {
   const store = requestContextAls.getStore();
   if (!store) {
     throw new Error(
@@ -38,199 +44,28 @@ export function getHeaders(): Promise<ReadonlyHeaders> {
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
-  return Promise.resolve(store.headers);
+  return store.headers;
 }
 
 /**
  * Returns the value of a single request header, or undefined if absent.
  *
- * Thin wrapper over `(await getHeaders()).get(name)` for the common
- * case where you need exactly one header.
- *
- * ```ts
- * import { getHeader } from '@timber-js/app/server'
+ * Thin wrapper over `getHeaders().get(name)` for the common case where
+ * you need exactly one header.
  *
- * export default async function Page() {
- *   const auth = await getHeader('authorization');
- * }
- * ```
+ * @internal — not part of the public API. Use `getHeaders().get(name)` instead.
  */
-export async function getHeader(name: string): Promise<string | undefined> {
-  const headers = await getHeaders();
+export function getHeader(name: string): string | undefined {
+  const headers = getHeaders();
   return headers.get(name) ?? undefined;
 }
 
 /**
- * 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).
- *
- * Read methods (.get, .has, .getAll) are always available and reflect
- * read-your-own-writes from .set() calls in the same request.
- *
- * 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.
- *
- * See design/29-cookies.md
- */
-export function getCookies(): Promise<RequestCookies> {
-  const store = requestContextAls.getStore();
-  if (!store) {
-    throw new Error(
-      '[timber] getCookies() 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);
-  }
-
-  const map = store.parsedCookies;
-  return Promise.resolve({
-    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;
-    },
-
-    set(name: string, value: string, options?: CookieOptions): void {
-      assertMutable(store, 'set');
-      if (store.flushed) {
-        if (isDebug()) {
-          console.warn(
-            `[timber] warn: getCookies().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;
-      }
-      const opts = { ...DEFAULT_COOKIE_OPTIONS, ...options };
-      store.cookieJar.set(name, { name, value, options: opts });
-      // Read-your-own-writes: update the parsed cookies map
-      map.set(name, value);
-    },
-
-    setFromHeaders(headers: Headers): void {
-      assertMutable(store, 'setFromHeaders');
-      if (store.flushed) {
-        console.warn(
-          `[timber] warn: getCookies().setFromHeaders() called after response headers were committed.\n` +
-            `  The cookies will NOT be sent. Move cookie mutations to middleware.ts, a server action,\n` +
-            `  or a route.ts handler.`
-        );
-        return;
-      }
-      // Headers.getSetCookie() returns individual Set-Cookie strings,
-      // avoiding the fragile comma-splitting that raw .get() requires.
-      for (const raw of headers.getSetCookie()) {
-        const parsed = parseSetCookie(raw);
-        if (parsed) {
-          // Use setRaw to preserve the original header's attributes without
-          // merging DEFAULT_COOKIE_OPTIONS (parseSetCookie intentionally
-          // does not apply defaults — see its doc comment).
-          setRaw(store, map, parsed.name, parsed.value, parsed.options);
-        }
-      }
-    },
-
-    delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void {
-      assertMutable(store, 'delete');
-      if (store.flushed) {
-        if (isDebug()) {
-          console.warn(
-            `[timber] warn: getCookies().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);
-    },
-
-    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();
-    },
-
-    toString(): string {
-      return Array.from(map.entries())
-        .map(([name, value]) => `${name}=${value}`)
-        .join('; ');
-    },
-  });
-}
-
-/**
- * Returns the value of a single cookie, or undefined if absent.
- *
- * Thin wrapper over `(await getCookies()).get(name)` for the common
- * case where you need exactly one cookie.
- *
- * ```ts
- * import { getCookie } from '@timber-js/app/server'
- *
- * export default async function Page() {
- *   const session = await getCookie('session_id');
- * }
- * ```
- */
-export async function getCookie(name: string): Promise<string | undefined> {
-  const cookies = await getCookies();
-  return cookies.get(name);
-}
-
-/**
- * Returns a Promise resolving to the current request's raw URLSearchParams.
- *
- * For typed, parsed search params, import the definition from params.ts
- * and call `.load()` or `.parse()`:
- *
- * ```ts
- * import { searchParams } from './params'
- * const parsed = await searchParams.get()
- * ```
- *
- * Or explicitly:
+ * Returns the current request's raw URLSearchParams.
  *
- * ```ts
- * import { getSearchParams } from '@timber-js/app/server'
- * import { searchParams } from './params'
- * const parsed = searchParams.parse(await getSearchParams())
- * ```
- *
- * Throws if called outside a request context.
+ * @internal — not part of the public API. Use `defineSearchParams().get()` instead.
  */
-export function getSearchParams(): Promise<URLSearchParams> {
+export function getSearchParams(): URLSearchParams {
   const store = requestContextAls.getStore();
   if (!store) {
     throw new Error(
@@ -238,42 +73,31 @@ export function getSearchParams(): Promise<URLSearchParams> {
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
-  return store.searchParamsPromise;
+  return store.searchParams;
 }
 
 // Eagerly register getSearchParams with the search-params module so
-// searchParams.get() can call it synchronously without a dynamic import.
+// 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 synchronously without a dynamic import.
+// segmentParams.get() can call it without a dynamic import.
 // Same pattern as search params — dynamic imports lose ALS context. See TIM-523.
 _setGetSegmentParamsFn(getSegmentParams);
 
+// Eagerly register the server cookie impl with defineCookie so
+// .get()/.set()/.delete() are sync without dynamic imports.
+_registerServerCookieImpl({ getCookieJar });
+_registerFromSchema(fromSchema);
+
 /**
- * Returns a Promise resolving to the current request's coerced segment params.
- *
- * Segment params are set by the pipeline after route matching and param
- * coercion (via params.ts codecs). When no params.ts exists, values are
- * raw strings. When codecs are defined, values are already coerced
- * (e.g., `id` is a `number` if `defineSegmentParams({ id: z.coerce.number() })`).
- *
- * This is the primary way page and layout components access route params:
+ * Returns the current request's coerced segment params.
  *
- * ```ts
- * import { getSegmentParams } from '@timber-js/app/server'
- *
- * export default async function Page() {
- *   const { slug } = await getSegmentParams()
- *   // ...
- * }
- * ```
- *
- * Throws if called outside a request context.
+ * @internal — not part of the public API. Use `defineSegmentParams().get()` instead.
  */
-export function getSegmentParams(): Promise<Record<string, string | string[]>> {
+export function getSegmentParams(): Record<string, string | string[]> {
   const store = requestContextAls.getStore();
   if (!store) {
     throw new Error(
@@ -281,13 +105,13 @@ export function getSegmentParams(): Promise<Record<string, string | string[]>> {
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
-  if (!store.segmentParamsPromise) {
+  if (!store.segmentParams) {
     throw new Error(
       '[timber] getSegmentParams() called before route matching completed. ' +
         'Segment params are not available until after the route is matched.'
     );
   }
-  return store.segmentParamsPromise;
+  return store.segmentParams;
 }
 
 /**
@@ -301,7 +125,7 @@ export function setSegmentParams(params: Record<string, string | string[]>): voi
   if (!store) {
     throw new Error('[timber] setSegmentParams() called outside of a request context.');
   }
-  store.segmentParamsPromise = Promise.resolve(params);
+  store.segmentParams = params;
 }
 
 /**
@@ -330,169 +154,33 @@ 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;
-}
-
-const DEFAULT_COOKIE_OPTIONS: CookieOptions = {
-  path: '/',
-  httpOnly: true,
-  secure: true,
-  sameSite: 'lax',
-};
-
-/**
- * Write a cookie to the jar WITHOUT merging DEFAULT_COOKIE_OPTIONS.
- * Used by setFromHeaders to preserve the original header's attributes exactly.
- *
- * For deletion cookies (maxAge=0), the jar entry is still created so the
- * Set-Cookie header is emitted, but the cookie is NOT added to the read map
- * (it would be misleading — the cookie is being deleted).
- */
-function setRaw(
-  store: RequestContextStore,
-  readMap: Map<string, string>,
-  name: string,
-  value: string,
-  options: CookieOptions
-): void {
-  store.cookieJar.set(name, { name, value, options });
-  // Deletion cookies (Max-Age=0) should not appear in the read map
-  if (options.maxAge === 0) {
-    readMap.delete(name);
-  } else {
-    readMap.set(name, value);
-  }
-}
-
-/**
- * Parse a raw `Set-Cookie` header string into name, value, and options.
- * Handles all standard attributes: Path, Domain, Max-Age, Expires,
- * SameSite, Secure, HttpOnly, Partitioned.
- *
- * Does NOT apply DEFAULT_COOKIE_OPTIONS — the caller decides whether
- * to merge defaults (e.g. `set()` does, but `setRaw()` should preserve
- * the original header's intent).
- */
-function parseSetCookie(
-  header: string
-): { name: string; value: string; options: CookieOptions } | null {
-  const segments = header.split(';');
-  const nameValue = segments[0];
-  const eqIdx = nameValue.indexOf('=');
-  if (eqIdx <= 0) return null;
-
-  const name = nameValue.slice(0, eqIdx).trim();
-  const value = nameValue.slice(eqIdx + 1).trim();
-  const options: CookieOptions = {};
-
-  for (let i = 1; i < segments.length; i++) {
-    const seg = segments[i].trim();
-    if (!seg) continue;
-    const [attrName, ...rest] = seg.split('=');
-    const key = attrName.trim().toLowerCase();
-    const val = rest.join('=').trim();
-    switch (key) {
-      case 'path':
-        options.path = val || '/';
-        break;
-      case 'domain':
-        options.domain = val;
-        break;
-      case 'max-age':
-        options.maxAge = Number(val);
-        break;
-      case 'expires':
-        options.expires = new Date(val);
-        break;
-      case 'samesite':
-        options.sameSite = val.toLowerCase() as 'strict' | 'lax' | 'none';
-        break;
-      case 'secure':
-        options.secure = true;
-        break;
-      case 'httponly':
-        options.httpOnly = true;
-        break;
-      case 'partitioned':
-        options.partitioned = true;
-        break;
-    }
-  }
-
-  return { name, value, options };
-}
-
-/**
- * Cookie accessor returned by `getCookies()`.
- *
- * 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;
-  /** Set a cookie. Only available in mutable contexts (middleware, actions, route handlers). */
-  set(name: string, value: string, options?: CookieOptions): void;
-  /**
-   * Copy all `Set-Cookie` headers from a `Headers` object.
-   * Parses each header and forwards name, value, and all attributes
-   * (path, domain, max-age, expires, sameSite, secure, httpOnly, partitioned).
-   *
-   * Useful when forwarding cookies from an internal `fetch()` or auth handler:
-   * ```ts
-   * const response = await auth.handler(req);
-   * getCookies().then(c => c.setFromHeaders(response.headers));
-   * ```
-   */
-  setFromHeaders(headers: Headers): 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 `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(parsedUrl.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,
@@ -527,47 +215,6 @@ export function markResponseFlushed(): void {
   }
 }
 
-/**
- * Build a Map of cookie name → value reflecting the current request's
- * read-your-own-writes state. Includes incoming cookies plus any
- * mutations from getCookies().set() / getCookies().delete() in the same request.
- *
- * Used by SSR renderers to populate NavContext.cookies so that
- * useCookie()'s server snapshot matches the actual response state.
- *
- * See design/29-cookies.md §"Read-Your-Own-Writes"
- * See design/triage/TIM-441-cookie-api-triage.md §4
- */
-export function getCookiesForSsr(): Map<string, string> {
-  const store = requestContextAls.getStore();
-  if (!store) {
-    throw new Error('[timber] getCookiesForSsr() called outside of a request context.');
-  }
-
-  // Trigger lazy parsing if not yet done
-  if (!store.parsedCookies) {
-    store.parsedCookies = parseCookieHeader(store.cookieHeader);
-  }
-
-  // The parsedCookies map already reflects read-your-own-writes:
-  // - getCookies().set() updates the map via map.set(name, value)
-  // - getCookies().delete() removes from the map via map.delete(name)
-  // Return a copy so callers can't mutate the internal map.
-  return new Map(store.parsedCookies);
-}
-
-/**
- * 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.
  *
@@ -635,55 +282,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] getCookies().${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;
-}
-
-/** 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('; ');
-}

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

@@ -27,9 +27,13 @@ import type { Metadata } from './types.js';
 import { METADATA_ROUTE_CONVENTIONS, getMetadataRouteAutoLink } from './metadata-routes.js';
 import { DenySignal, RedirectSignal } from './primitives.js';
 import { AccessGate } from './access-gate.js';
-import { PageDenyBoundary } from './page-deny-boundary.js';
-import { buildDenyPageChain, renderMatchingDenyPage, setDenyStatus } from './deny-page-resolver.js';
-import type { DenyPageEntry } from './deny-page-resolver.js';
+import {
+  PageDenyBoundary,
+  buildDenyPageChain,
+  renderMatchingDenyPage,
+  setDenyStatus,
+} from './deny-boundary.js';
+import type { DenyPageEntry } from './deny-boundary.js';
 import { resolveSlotElement } from './slot-resolver.js';
 import { SegmentProvider } from '../client/segment-context.js';
 
@@ -213,7 +217,7 @@ export async function buildRouteElement(
   interception?: InterceptionContext,
   clientStateTree?: Set<string> | null
 ): Promise<RouteElementResult> {
-  const segments = match.segments as unknown as ManifestSegmentNode[];
+  const segments = match.segments;
 
   // Load all modules along the segment chain
   const metadataEntries: Array<{ metadata: Metadata; isPage: boolean }> = [];