@timber-js/app 0.2.0-alpha.4 → 0.2.0-alpha.40

package/src/server/primitives.ts

@@ -6,6 +6,8 @@
 import type { JsonSerializable } from './types.js';
 import { getWaitUntil as _getWaitUntil } from './waituntil-bridge.js';
 import { isDebug } from './debug.js';
+import { getRequestSearchString } from './request-context.js';
+import { mergePreservedSearchParams } from '#/shared/merge-search-params.js';
 
 // ─── Dev-mode validation ────────────────────────────────────────────────────
 
@@ -209,14 +211,46 @@ export class RedirectSignal extends Error {
 /** Pattern matching absolute URLs: http(s):// or protocol-relative // */
 const ABSOLUTE_URL_RE = /^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/\/)/;
 
+/**
+ * Options for redirect() — alternative to passing a bare status code.
+ */
+export interface RedirectOptions {
+  /** HTTP redirect status code (3xx). Defaults to 302. */
+  status?: number;
+  /**
+   * Preserve search params from the current request URL on the redirect target.
+   *
+   * - `true` — preserve ALL current search params (target params take precedence)
+   * - `string[]` — preserve only the named params (e.g. `['private', 'token']`)
+   *
+   * Target path's own query params always take precedence over preserved ones.
+   */
+  preserveSearchParams?: true | string[];
+}
+
 /**
  * Redirect to a relative path. Rejects absolute and protocol-relative URLs.
  * Use `redirectExternal()` for external redirects with an allow-list.
  *
  * @param path - Relative path (e.g. '/login', 'settings', '/login?returnTo=/dash')
- * @param status - HTTP redirect status code (3xx). Defaults to 302.
+ * @param statusOrOptions - HTTP status code (3xx, default 302) or options object.
+ *
+ * @example
+ * // Simple redirect
+ * redirect('/login');
+ *
+ * // With status code
+ * redirect('/login', 301);
+ *
+ * // With preserved search params
+ * redirect(`/docs/${version}/${slug}`, { preserveSearchParams: ['foo'] });
  */
-export function redirect(path: string, status: number = 302): never {
+export function redirect(path: string, statusOrOptions?: number | RedirectOptions): never {
+  const status =
+    typeof statusOrOptions === 'number' ? statusOrOptions : (statusOrOptions?.status ?? 302);
+  const preserveSearchParams =
+    typeof statusOrOptions === 'object' ? statusOrOptions.preserveSearchParams : undefined;
+
   if (status < 300 || status > 399) {
     throw new Error(`redirect() requires a 3xx status code, got ${status}.`);
   }
@@ -226,7 +260,14 @@ export function redirect(path: string, status: number = 302): never {
         'Use redirectExternal(url, allowList) for external redirects.'
     );
   }
-  throw new RedirectSignal(path, status);
+
+  let resolvedPath = path;
+  if (preserveSearchParams) {
+    const currentSearch = getRequestSearchString();
+    resolvedPath = mergePreservedSearchParams(path, currentSearch, preserveSearchParams);
+  }
+
+  throw new RedirectSignal(resolvedPath, status);
 }
 
 /**
@@ -236,9 +277,10 @@ export function redirect(path: string, status: number = 302): never {
  * will replay POST requests to the new location. This matches Next.js behavior.
  *
  * @param path - Relative path (e.g. '/new-page', '/dashboard')
+ * @param options - Optional redirect options (e.g. preserveSearchParams).
  */
-export function permanentRedirect(path: string): never {
-  redirect(path, 308);
+export function permanentRedirect(path: string, options?: Omit<RedirectOptions, 'status'>): never {
+  redirect(path, { status: 308, ...options });
 }
 
 /**

package/src/server/render-timeout.ts

@@ -0,0 +1,108 @@
+/**
+ * Render timeout utilities for SSR streaming pipeline.
+ *
+ * Provides a RenderTimeoutError class and a helper to create
+ * timeout-guarded AbortSignals. Used to defend against hung RSC
+ * streams and infinite SSR renders.
+ *
+ * Design doc: 02-rendering-pipeline.md §"Streaming Constraints"
+ */
+
+/**
+ * Error thrown when an SSR render or RSC stream read exceeds the
+ * configured timeout. Callers can check `instanceof RenderTimeoutError`
+ * to distinguish timeout from other errors and return a 504 or close
+ * the connection cleanly.
+ */
+export class RenderTimeoutError extends Error {
+  readonly timeoutMs: number;
+
+  constructor(timeoutMs: number, context?: string) {
+    const message = context
+      ? `Render timeout after ${timeoutMs}ms: ${context}`
+      : `Render timeout after ${timeoutMs}ms`;
+    super(message);
+    this.name = 'RenderTimeoutError';
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+/**
+ * Result of createRenderTimeout — an AbortSignal that fires after
+ * the given duration, plus a cancel function to clear the timer
+ * when the render completes normally.
+ */
+export interface RenderTimeout {
+  /** AbortSignal that aborts after timeoutMs. */
+  signal: AbortSignal;
+  /** Cancel the timeout timer. Call this when the render completes. */
+  cancel: () => void;
+}
+
+/**
+ * Create a render timeout that aborts after the given duration.
+ *
+ * Returns an AbortSignal and a cancel function. The signal fires
+ * with a RenderTimeoutError as the abort reason after `timeoutMs`.
+ * Call `cancel()` when the render completes to prevent the timeout
+ * from firing.
+ *
+ * If an existing `parentSignal` is provided, the returned signal
+ * aborts when either the parent signal or the timeout fires —
+ * whichever comes first.
+ */
+export function createRenderTimeout(timeoutMs: number, parentSignal?: AbortSignal): RenderTimeout {
+  const controller = new AbortController();
+  const reason = new RenderTimeoutError(timeoutMs, 'RSC stream read timed out');
+
+  const timer = setTimeout(() => {
+    controller.abort(reason);
+  }, timeoutMs);
+
+  // If there's a parent signal (e.g. request abort), chain it
+  if (parentSignal) {
+    if (parentSignal.aborted) {
+      clearTimeout(timer);
+      controller.abort(parentSignal.reason);
+    } else {
+      parentSignal.addEventListener(
+        'abort',
+        () => {
+          clearTimeout(timer);
+          controller.abort(parentSignal.reason);
+        },
+        { once: true }
+      );
+    }
+  }
+
+  return {
+    signal: controller.signal,
+    cancel: () => {
+      clearTimeout(timer);
+    },
+  };
+}
+
+/**
+ * Race a promise against a timeout. Rejects with RenderTimeoutError
+ * if the promise does not resolve within `timeoutMs`.
+ *
+ * Used to guard individual `rscReader.read()` calls inside pullLoop.
+ */
+export function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  context?: string
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeoutPromise = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(new RenderTimeoutError(timeoutMs, context));
+    }, timeoutMs);
+  });
+
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    clearTimeout(timer!);
+  });
+}

package/src/server/request-context.ts

@@ -10,8 +10,6 @@
  * 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 { isDebug } from './debug.js';
 
@@ -22,30 +20,6 @@ export { requestContextAls };
 // the ALS context persists for the entire request lifecycle including
 // async stream consumption by React's renderToReadableStream.
 
-// ─── Cookie Signing Secrets ──────────────────────────────────────────────
-
-/**
- * Module-level cookie signing secrets. Index 0 is the newest (used for signing).
- * All entries are tried for verification (key rotation support).
- *
- * Set by the framework at startup via `setCookieSecrets()`.
- * See design/29-cookies.md §"Signed Cookies"
- */
-let _cookieSecrets: string[] = [];
-
-/**
- * Configure the cookie signing secrets.
- *
- * Called by the framework during server initialization with values from
- * `cookies.secret` or `cookies.secrets` in timber.config.ts.
- *
- * The first secret (index 0) is used for signing new cookies.
- * All secrets are tried for verification (supports key rotation).
- */
-export function setCookieSecrets(secrets: string[]): void {
-  _cookieSecrets = secrets.filter(Boolean);
-}
-
 // ─── Public API ───────────────────────────────────────────────────────────
 
 /**
@@ -109,12 +83,6 @@ export function cookies(): RequestCookies {
       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) {
@@ -127,21 +95,10 @@ export function cookies(): RequestCookies {
         }
         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);
+      store.cookieJar.set(name, { name, value, options: opts });
+      // Read-your-own-writes: update the parsed cookies map
+      map.set(name, value);
     },
 
     delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void {
@@ -190,25 +147,31 @@ export function cookies(): RequestCookies {
 }
 
 /**
- * Returns a Promise resolving to the current request's search params.
+ * 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.load()
+ * ```
  *
- * 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`.
+ * Or explicitly:
  *
- * Returned as a Promise to match the `params` prop convention and to allow
- * future partial pre-rendering support where param resolution may be deferred.
+ * ```ts
+ * import { rawSearchParams } from '@timber-js/app/server'
+ * import { searchParams } from './params'
+ * const parsed = searchParams.parse(await rawSearchParams())
+ * ```
  *
  * Throws if called outside a request context.
  */
-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 rawSearchParams(): Promise<URLSearchParams> {
   const store = requestContextAls.getStore();
   if (!store) {
     throw new Error(
-      '[timber] searchParams() called outside of a request context. ' +
+      '[timber] rawSearchParams() called outside of a request context. ' +
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
@@ -216,15 +179,69 @@ export function searchParams(): Promise<URLSearchParams | Record<string, unknown
 }
 
 /**
- * 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.
+ * 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:
+ *
+ * ```ts
+ * import { rawSegmentParams } from '@timber-js/app/server'
+ *
+ * export default async function Page() {
+ *   const { slug } = await rawSegmentParams()
+ *   // ...
+ * }
+ * ```
+ *
+ * Throws if called outside a request context.
  */
-export function setParsedSearchParams(parsed: Record<string, unknown>): void {
+export function rawSegmentParams(): Promise<Record<string, string | string[]>> {
   const store = requestContextAls.getStore();
-  if (store) {
-    store.searchParamsPromise = Promise.resolve(parsed);
+  if (!store) {
+    throw new Error(
+      '[timber] rawSegmentParams() called outside of a request context. ' +
+        'It can only be used in middleware, access checks, server components, and server actions.'
+    );
+  }
+  if (!store.segmentParamsPromise) {
+    throw new Error(
+      '[timber] rawSegmentParams() called before route matching completed. ' +
+        'Segment params are not available until after the route is matched.'
+    );
+  }
+  return store.segmentParamsPromise;
+}
+
+/**
+ * Set the segment params promise on the current request context.
+ * Called by the pipeline after route matching and param coercion.
+ *
+ * @internal — framework use only
+ */
+export function setSegmentParams(params: Record<string, string | string[]>): void {
+  const store = requestContextAls.getStore();
+  if (!store) {
+    throw new Error('[timber] setSegmentParams() called outside of a request context.');
   }
+  store.segmentParamsPromise = Promise.resolve(params);
+}
+
+/**
+ * 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 ────────────────────────────────────────────────────────────────
@@ -257,12 +274,6 @@ export interface CookieOptions {
   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 = {
@@ -287,14 +298,6 @@ export interface RequestCookies {
   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. */
@@ -316,11 +319,13 @@ export interface RequestCookies {
  */
 export function runWithRequestContext<T>(req: Request, fn: () => T): T {
   const originalCopy = new Headers(req.headers);
+  const parsedUrl = new URL(req.url);
   const store: RequestContextStore = {
     headers: freezeHeaders(req.headers),
     originalHeaders: originalCopy,
     cookieHeader: req.headers.get('cookie') ?? '',
-    searchParamsPromise: Promise.resolve(new URL(req.url).searchParams),
+    searchParamsPromise: Promise.resolve(parsedUrl.searchParams),
+    searchString: parsedUrl.search,
     cookieJar: new Map(),
     flushed: false,
     mutableContext: false,
@@ -354,6 +359,35 @@ 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 cookies().set() / cookies().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:
+  // - cookies().set() updates the map via map.set(name, value)
+  // - cookies().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.
@@ -467,47 +501,6 @@ function parseCookieHeader(header: string): Map<string, string> {
   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}`];