@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.141

package/src/cache/taint.ts

@@ -0,0 +1,153 @@
+/**
+ * Taint symbol for request-scoped objects.
+ *
+ * Objects branded with NOCACHE_SYMBOL (ctx, env, req) are excluded from
+ * "use cache" cache keys and trigger handle capture mode so that side
+ * effects (breadcrumbs, metadata) are recorded and replayed on cache hit.
+ */
+
+export const NOCACHE_SYMBOL: unique symbol = Symbol.for("rango:nocache") as any;
+
+/**
+ * Check if a value is tainted (request-scoped, should not be in cache key).
+ */
+export function isTainted(value: unknown): boolean {
+  return (
+    value !== null &&
+    value !== undefined &&
+    typeof value === "object" &&
+    (NOCACHE_SYMBOL as symbol) in (value as Record<symbol, unknown>)
+  );
+}
+
+/**
+ * Symbol stamped on tainted ctx during "use cache" function execution.
+ * cookies(), headers(), ctx.set(), ctx.header(), etc. check this flag and
+ * throw if present — reads would cache per-request data under a shared key,
+ * and side effects would be lost on cache hit.
+ *
+ * The value is a numeric reference count, not a boolean. Multiple concurrent
+ * cached functions sharing the same ctx/requestCtx each increment on entry
+ * and decrement on exit. Guards fire when count > 0.
+ */
+export const INSIDE_CACHE_EXEC: unique symbol = Symbol.for(
+  "rango:inside-cache-exec",
+) as any;
+
+/**
+ * Increment the INSIDE_CACHE_EXEC ref count on an object.
+ */
+export function stampCacheExec(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_EXEC] ?? 0;
+  (obj as any)[INSIDE_CACHE_EXEC] = current + 1;
+}
+
+/**
+ * Decrement the INSIDE_CACHE_EXEC ref count on an object.
+ * Deletes the symbol when the count reaches zero so the `in` check
+ * used by guards no longer fires.
+ */
+export function unstampCacheExec(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_EXEC] ?? 0;
+  if (current <= 1) {
+    delete (obj as any)[INSIDE_CACHE_EXEC];
+  } else {
+    (obj as any)[INSIDE_CACHE_EXEC] = current - 1;
+  }
+}
+
+/**
+ * Throw if ctx is inside a "use cache" execution.
+ * Call from side-effecting ctx methods (set, header, etc.) and cookie mutations.
+ */
+export function assertNotInsideCacheExec(
+  ctx: unknown,
+  methodName: string,
+): void {
+  if (
+    ctx !== null &&
+    ctx !== undefined &&
+    typeof ctx === "object" &&
+    (INSIDE_CACHE_EXEC as symbol) in (ctx as Record<symbol, unknown>)
+  ) {
+    throw new Error(
+      `ctx.${methodName}() cannot be called inside a "use cache" function. ` +
+        `Side effects on the request context are lost on cache hit because ` +
+        `the function body is skipped. Extract the data fetch into a separate ` +
+        `cached function and call ctx.${methodName}() outside it, or use the ` +
+        `route-level cache() DSL which caches all segments (handler + children) ` +
+        `together.`,
+    );
+  }
+}
+
+/**
+ * Symbol stamped on ctx when resolving handlers inside a cache() DSL boundary.
+ * Separate from INSIDE_CACHE_EXEC ("use cache") because cache() allows
+ * ctx.set() (children are also cached) but blocks response-level side effects
+ * (headers, cookies, status) which are lost on cache hit.
+ */
+export const INSIDE_CACHE_SCOPE: unique symbol = Symbol.for(
+  "rango:inside-cache-scope",
+) as any;
+
+/**
+ * Mark ctx as inside a cache() scope. Must be paired with unstampCacheScope.
+ */
+export function stampCacheScope(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_SCOPE] ?? 0;
+  (obj as any)[INSIDE_CACHE_SCOPE] = current + 1;
+}
+
+/**
+ * Remove cache() scope mark.
+ */
+export function unstampCacheScope(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_SCOPE] ?? 0;
+  if (current <= 1) {
+    delete (obj as any)[INSIDE_CACHE_SCOPE];
+  } else {
+    (obj as any)[INSIDE_CACHE_SCOPE] = current - 1;
+  }
+}
+
+/**
+ * Throw if ctx is inside a cache() DSL boundary.
+ * Call from response-level side effects (header, setCookie, setStatus, etc.)
+ * which are lost on cache hit because the handler body is skipped.
+ * ctx.set() is allowed inside cache() — children are also cached and can
+ * read the value.
+ */
+export function assertNotInsideCacheScope(
+  ctx: unknown,
+  methodName: string,
+): void {
+  if (
+    ctx !== null &&
+    ctx !== undefined &&
+    typeof ctx === "object" &&
+    (INSIDE_CACHE_SCOPE as symbol) in (ctx as Record<symbol, unknown>)
+  ) {
+    throw new Error(
+      `ctx.${methodName}() cannot be called inside a cache() boundary. ` +
+        `On cache hit the handler is skipped, so this side effect would be lost. ` +
+        `Move ctx.${methodName}() to a middleware or layout outside the cache() scope.`,
+    );
+  }
+}
+
+/**
+ * Brand symbol for functions wrapped by registerCachedFunction().
+ * Used at runtime to detect when a "use cache" function is misused
+ * (e.g., passed as middleware).
+ */
+export const CACHED_FN_SYMBOL: unique symbol = Symbol.for(
+  "rango:cached-fn",
+) as any;
+
+/**
+ * Check if a value is a "use cache" wrapped function.
+ */
+export function isCachedFunction(value: unknown): boolean {
+  return typeof value === "function" && (CACHED_FN_SYMBOL as symbol) in value;
+}

package/src/cache/types.ts

@@ -12,10 +12,6 @@
 import type { ResolvedSegment } from "../types.js";
 import type { RequestContext } from "../server/request-context.js";
 
-// ============================================================================
-// Segment Cache Store (low-level storage interface)
-// ============================================================================
-
 /**
  * Result from cache get() including data and revalidation status
  */
@@ -75,14 +71,14 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * @example Using cookies for locale
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
-   *   const locale = ctx.cookie('locale') || 'en';
+   *   const locale = cookies().get('locale')?.value || 'en';
    *   return `${locale}:${defaultKey}`;
    * }
    * ```
    */
   readonly keyGenerator?: (
     ctx: RequestContext<TEnv>,
-    defaultKey: string
+    defaultKey: string,
   ) => string | Promise<string>;
 
   /**
@@ -98,7 +94,12 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * @param ttl - Time-to-live in seconds
    * @param swr - Optional stale-while-revalidate window in seconds
    */
-  set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
+  set(
+    key: string,
+    data: CachedEntryData,
+    ttl: number,
+    swr?: number,
+  ): Promise<void>;
 
   /**
    * Delete a cached entry
@@ -111,17 +112,13 @@ export interface SegmentCacheStore<TEnv = unknown> {
    */
   clear?(): Promise<void>;
 
-  // ============================================================================
-  // Document Cache Methods (optional)
-  // ============================================================================
-  // These methods are for caching full HTTP responses (document-level caching).
-  // Stores that support response caching should implement these methods.
-
   /**
    * Get a cached Response by key.
    * Returns the response and whether it should be revalidated (SWR).
    */
-  getResponse?(key: string): Promise<{ response: Response; shouldRevalidate: boolean } | null>;
+  getResponse?(
+    key: string,
+  ): Promise<{ response: Response; shouldRevalidate: boolean } | null>;
 
   /**
    * Store a Response with TTL and optional SWR window.
@@ -129,8 +126,202 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * @param response - Response to cache (will be cloned)
    * @param ttl - Time-to-live in seconds
    * @param swr - Optional stale-while-revalidate window in seconds
+   * @param tags - Optional cache tags for invalidation
+   */
+  putResponse?(
+    key: string,
+    response: Response,
+    ttl: number,
+    swr?: number,
+    tags?: string[],
+  ): Promise<void>;
+
+  /**
+   * Get a cached PPR shell entry by key.
+   * Returns the stored prelude/postponed pair (see ShellCacheEntry) and whether
+   * it should be revalidated (SWR). Used by the shell-cache middleware to serve
+   * a cached HTML shell and resume fizz for just the live holes.
+   *
+   * Optional: a store that does not implement the shell family disables the
+   * shell-cache middleware (it fails open to the normal HTML render path).
+   */
+  getShell?(
+    key: string,
+  ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null>;
+
+  /**
+   * Store a PPR shell entry with TTL and optional SWR window.
+   * The prelude bytes and postponed state are version- and generation-coupled
+   * and travel together in a single entry (they must never mix across a React
+   * upgrade — the reactVersion field on the entry gates that at read time).
+   * @param key - Cache key
+   * @param entry - The shell prelude/postponed/version/createdAt bundle
+   * @param ttlSeconds - Time-to-live in seconds
+   * @param swrSeconds - Optional stale-while-revalidate window in seconds
+   * @param tags - Optional cache tags for invalidation (participates in
+   *   invalidateTags via the same tag machinery as the item family)
+   */
+  putShell?(
+    key: string,
+    entry: ShellCacheEntry,
+    ttlSeconds?: number,
+    swrSeconds?: number,
+    tags?: string[],
+  ): Promise<void>;
+
+  /**
+   * Get a cached function result by key.
+   * Returns the serialized value, optional handle data, and staleness flag.
+   */
+  getItem?(key: string): Promise<CacheItemResult | null>;
+
+  /**
+   * Store a function result with TTL and optional SWR window.
+   * @param key - Cache key (format: use-cache:{functionId}:{serializedArgs})
+   * @param value - RSC-serialized return value
+   * @param options - TTL, SWR, handle data, and tags
+   */
+  setItem?(
+    key: string,
+    value: string,
+    options?: CacheItemOptions,
+  ): Promise<void>;
+
+  /**
+   * Invalidate every cache entry (segment, response, item) tagged with any of
+   * `tags`. Store-level primitive that the public updateTag()/revalidateTag()
+   * APIs delegate to. Receives ALL of one invalidation call's tags at once so
+   * stores can batch their work (e.g. a single CDN purge request rather than
+   * one per tag). Stores that do not support tags simply omit this method.
+   * @param tags - The cache tags to invalidate
    */
-  putResponse?(key: string, response: Response, ttl: number, swr?: number): Promise<void>;
+  invalidateTags?(tags: string[]): Promise<void>;
+}
+
+/**
+ * Result from getItem() for function-level caching ("use cache").
+ */
+export interface CacheItemResult {
+  /** RSC-serialized return value */
+  value: string;
+  /** RSC-encoded handle data captured during execution (breadcrumbs, metadata,
+   *  etc.). Encoded via the Flight codec so Promise/ReactNode handle values
+   *  survive JSON-serializing stores — see handle-snapshot.ts encodeHandles. */
+  handles?: string;
+  /** Whether the entry is stale and should be revalidated */
+  shouldRevalidate: boolean;
+  /**
+   * The entry's cache tags (including runtime cacheTag() tags), surfaced on read
+   * so a "use cache" HIT can still contribute its tags to the request-scoped tag
+   * set used by document-level caching. On a hit the cached function is not
+   * re-run, so its runtime tags are only available here, not from re-execution.
+   */
+  tags?: string[];
+}
+
+/**
+ * A cached PPR (Partial Pre-rendering) shell entry.
+ *
+ * One entry carries BOTH artifacts a resume needs — the rendered HTML prelude
+ * and React's postponed state — because the pair is version- and
+ * generation-coupled and must never be mixed across a React upgrade or a build
+ * change. The reactVersion field is the read-time gate that enforces that: the
+ * shell-cache middleware treats an entry whose reactVersion differs from the
+ * running React as a miss (the postponed blob is build-coupled and cannot be
+ * resumed by a different React).
+ */
+export interface ShellCacheEntry {
+  /** Rendered HTML prelude bytes, base64-encoded (stores are JSON-serializing). */
+  prelude: string;
+  /**
+   * JSON.stringify of React's postponed state, or null when the shell settled
+   * with no holes (the DATA variant — served without a fizz resume).
+   */
+  postponed: string | null;
+  /** React.version captured at prerender time; the read-time invalidation gate. */
+  reactVersion: string;
+  /**
+   * The initialTheme the CAPTURE render was built with (the derived context's
+   * reqCtx.theme). The resume tail must render ThemeProvider with the SAME
+   * initialTheme the frozen prelude was rendered with: React resume requires the
+   * tree above the holes to match the prerendered tree, and initialTheme is
+   * per-request METADATA, not part of the cached segments — a visitor whose
+   * theme differs from the capturer's would otherwise produce a divergent resume
+   * tree (broken stitching/hydration). The visitor's real theme is applied
+   * pre-paint by the FOUC script and re-synced from the cookie post-mount by
+   * ThemeProvider.
+   */
+  initialTheme?: string;
+  /**
+   * The CAPTURE DATA SNAPSHOT: every cache-store read-hit and write the capture
+   * render performed, in stored/serialized form. Replaying these on a HIT (via
+   * the SeededShellStore overlay, for the tail render only) reproduces the
+   * shell's cached content byte-identically, so the freshly rendered hydration
+   * payload matches the frozen prelude even after the underlying cache entries
+   * have drifted (expired, been recomputed, or been tag-invalidated).
+   *
+   * Optional: an entry captured before this field existed simply has no
+   * snapshot and keeps the pre-snapshot behavior (the tail reads live, so any
+   * shell-baked cached value that drifted mismatches the prelude). Recapture
+   * heals it. See docs/design/ppr-shell-resume.md ("the capture data snapshot").
+   */
+  snapshot?: ShellSnapshotRecord[];
+  /** Epoch ms when the shell was captured. */
+  createdAt: number;
+}
+
+/**
+ * The cache-store families a shell snapshot pins. Excludes the shell family
+ * itself (getShell/putShell) — the snapshot rides INSIDE a shell entry, so
+ * recording it would be self-referential.
+ */
+export type ShellSnapshotFamily = "item" | "segment" | "response";
+
+/** A serialized cached Response for the response family of a shell snapshot. */
+export interface ShellSnapshotResponseValue {
+  status: number;
+  /** Client-facing header pairs (per-client signal headers excluded at record). */
+  headers: [string, string][];
+  /** base64-encoded response body (binary-safe, JSON-serializable). */
+  body: string;
+}
+
+/** The stored form of an item-family (use cache / loader cache) snapshot value. */
+export interface ShellSnapshotItemValue {
+  /** RSC-serialized return value. */
+  value: string;
+  /** RSC-encoded handle data, if any. */
+  handles?: string;
+  /** The entry's cache tags. */
+  tags?: string[];
+}
+
+/**
+ * One recorded cache-store read-hit or write from the capture render. `value`
+ * carries the entry in its stored/serialized shape so it round-trips through a
+ * JSON-serializing store (KV, CF, Vercel) with the rest of the ShellCacheEntry:
+ * - `item`    -> {@link ShellSnapshotItemValue}
+ * - `segment` -> {@link CachedEntryData} (already JSON-able)
+ * - `response`-> {@link ShellSnapshotResponseValue}
+ */
+export interface ShellSnapshotRecord {
+  family: ShellSnapshotFamily;
+  key: string;
+  value: ShellSnapshotItemValue | CachedEntryData | ShellSnapshotResponseValue;
+}
+
+/**
+ * Options for setItem() for function-level caching ("use cache").
+ */
+export interface CacheItemOptions {
+  /** RSC-encoded handle data to store alongside the value (see encodeHandles). */
+  handles?: string;
+  /** Time-to-live in seconds */
+  ttl?: number;
+  /** Stale-while-revalidate window in seconds */
+  swr?: number;
+  /** Cache tags for invalidation */
+  tags?: string[];
 }
 
 /**
@@ -151,7 +342,10 @@ export interface SerializedSegmentData {
   /** RSC-encoded loaderDataPromise (if present) */
   encodedLoaderDataPromise?: string;
   /** Segment metadata (everything except component, layout, loading, and loader data) */
-  metadata: Omit<ResolvedSegment, "component" | "layout" | "loading" | "loaderData" | "loaderDataPromise">;
+  metadata: Omit<
+    ResolvedSegment,
+    "component" | "layout" | "loading" | "loaderData" | "loaderDataPromise"
+  >;
 }
 
 /**
@@ -162,16 +356,18 @@ export interface SerializedSegmentData {
 export interface CachedEntryData {
   /** Serialized segments for this entry */
   segments: SerializedSegmentData[];
-  /** Handle data keyed by segment ID */
-  handles: Record<string, SegmentHandleData>;
+  /** RSC-encoded handle data keyed by segment ID. Encoded via the Flight codec
+   *  (see handle-snapshot.ts encodeHandles) so Promise/ReactNode handle values
+   *  round-trip through JSON-serializing stores instead of being flattened. */
+  handles: string;
   /** Expiration timestamp (ms since epoch) */
   expiresAt: number;
+  /** Cache tags for invalidation */
+  tags?: string[];
+  /** Timestamp (ms since epoch) when tags were attached, for distributed invalidation */
+  taggedAt?: number;
 }
 
-// ============================================================================
-// Cache Configuration
-// ============================================================================
-
 /**
  * Default cache options applied to all cache() boundaries.
  * Individual cache() calls can override any of these values.
@@ -187,206 +383,21 @@ export interface CacheDefaults {
   /**
    * Default time-to-live in seconds.
    * After TTL expires, cached entry is considered stale.
+   * Must be a finite, non-negative number; an invalid value (NaN/Infinity/
+   * negative) falls back to the default at read time.
    */
   ttl?: number;
   /**
    * Default stale-while-revalidate window in seconds.
    * During SWR window, stale content is served while revalidating in background.
+   * Must be a finite, non-negative number; an invalid value (NaN/Infinity/
+   * negative) falls back to the default at read time.
    */
   swr?: number;
 }
 
-/**
- * Cache configuration for RSC handler
- */
-export interface CacheConfig {
-  /** Cache store implementation (includes defaults) */
-  store: SegmentCacheStore;
-  /** Enable/disable caching (default: true) */
-  enabled?: boolean;
-}
-
-/**
- * Cache configuration - can be static or a function receiving env
- */
-export type CacheConfigOrFactory<TEnv> =
-  | CacheConfig
-  | ((env: TEnv) => CacheConfig);
-
-// ============================================================================
-// Segment Cache Provider (request-level interface)
-// ============================================================================
-
 /**
  * Handle data for a single segment
  * Structure: { handleName: [values...] }
  */
 export type SegmentHandleData = Record<string, unknown[]>;
-
-/**
- * Result from cache get() including segments and their handle data
- * Each entry can produce multiple segments (main + parallels)
- */
-export interface CachedEntryResult {
-  /** All segments for this entry (main segment + parallels) */
-  segments: ResolvedSegment[];
-  /** Handle data keyed by segment ID */
-  handles: Record<string, SegmentHandleData>;
-}
-
-
-/**
- * Segment cache provider interface
- *
- * Used by router to check/store segment cache during matching.
- * Accessed via request context - if not present, caching is disabled.
- *
- * @internal Not currently implemented - CacheScope is used directly.
- * Reserved for future extensibility.
- */
-export interface SegmentCacheProvider {
-  /** Whether caching is enabled for this request */
-  readonly enabled: boolean;
-
-  /**
-   * Get cached segments and restore handles/loaders.
-   *
-   * Combines cache get with handle replay and loader data restoration.
-   * Returns tuple of [segments, segmentIds] if cache hit, null if miss or disabled.
-   *
-   * @param cacheKey - Cache key to look up
-   * @param params - Route params for cache key generation
-   * @param loaderPromises - Map to restore loader data into
-   * @returns Tuple of [segments, segmentIds] or null if miss
-   */
-  restore(
-    cacheKey: string,
-    params: Record<string, string>,
-    loaderPromises: Map<string, Promise<any>>
-  ): Promise<[ResolvedSegment[], string[]] | null>;
-
-  /**
-   * Cache entry with automatic handle collection (non-blocking).
-   *
-   * Schedules caching via waitUntil - handles are collected after they settle.
-   * Validates segments have actual components before caching.
-   *
-   * @param cacheKey - The cache key to store under
-   * @param segments - All resolved segments for this entry
-   */
-  cacheEntry(cacheKey: string, segments: ResolvedSegment[]): void;
-}
-
-// ============================================================================
-// Generic Cache Store (for future extensibility)
-// ============================================================================
-// These types support a general-purpose cache interface that can be used
-// for caching arbitrary values (responses, streams, objects). Currently,
-// the segment caching system uses SegmentCacheStore directly, but these
-// types enable future use cases like response caching or data caching.
-
-/**
- * Supported cache value types for the generic CacheStore interface.
- * @internal Reserved for future extensibility
- */
-export type CacheValue =
-  | ReadableStream<Uint8Array>
-  | Response
-  | ArrayBuffer
-  | string
-  | unknown[] // JSON-serializable array
-  | Record<string, unknown>; // JSON-serializable object
-
-/**
- * Cache entry returned by match().
- * @internal Reserved for future extensibility
- */
-export interface CacheEntry<T = CacheValue> {
-  /** The cached value */
-  value: T;
-  /** Optional metadata stored with the entry */
-  metadata?: CacheMetadata;
-}
-
-/**
- * Original value type for reconstruction.
- * @internal Reserved for future extensibility
- */
-export type CacheValueType =
-  | "stream"
-  | "response"
-  | "arraybuffer"
-  | "string"
-  | "object";
-
-/**
- * Metadata associated with a cache entry.
- * @internal Reserved for future extensibility
- */
-export interface CacheMetadata {
-  /** Timestamp when entry expires (ms since epoch) */
-  expiresAt?: number;
-  /** Tags for bulk invalidation */
-  tags?: string[];
-  /** Original value type for reconstruction on read */
-  valueType?: CacheValueType;
-  /** Response headers (preserved when caching Response) */
-  responseHeaders?: Record<string, string>;
-  /** Response status (preserved when caching Response) */
-  responseStatus?: number;
-  /** Custom metadata */
-  [key: string]: unknown;
-}
-
-/**
- * Options for put().
- * @internal Reserved for future extensibility
- */
-export interface CachePutOptions {
-  /** Time-to-live in seconds */
-  ttl?: number;
-  /** Metadata to store with entry */
-  metadata?: Omit<CacheMetadata, "expiresAt">;
-}
-
-/**
- * Generic cache store interface for arbitrary value types.
- *
- * This interface is designed for future extensibility to support caching
- * responses, streams, and other values. Currently, segment caching uses
- * the SegmentCacheStore interface directly.
- *
- * Implementations must handle:
- * - Stream values (clone before storing, streams can only be read once)
- * - Promise values (await before storing)
- * - Expiration/TTL
- *
- * @internal Reserved for future extensibility
- */
-export interface CacheStore {
-  /**
-   * Retrieve a cached entry by key.
-   * @param key - Cache key
-   * @returns The cached entry or undefined if not found/expired
-   */
-  match<T = CacheValue>(key: string): Promise<CacheEntry<T> | undefined>;
-
-  /**
-   * Store a value in the cache.
-   * @param key - Cache key
-   * @param value - Value to cache (stream, response, string, object, etc.)
-   * @param options - TTL, metadata, etc.
-   */
-  put<T extends CacheValue>(
-    key: string,
-    value: T,
-    options?: CachePutOptions
-  ): Promise<void>;
-
-  /**
-   * Delete a cached entry.
-   * @param key - Cache key
-   * @returns true if entry was deleted, false if not found
-   */
-  delete(key: string): Promise<boolean>;
-}

package/src/cache/vercel/index.ts

@@ -0,0 +1,11 @@
+export {
+  VercelCacheStore,
+  type VercelCacheStoreOptions,
+  type VercelRuntimeCache,
+  type VercelCacheDebug,
+  type VercelCacheReadDebugEvent,
+  type VercelCacheReadOutcome,
+  VERCEL_MAX_ITEM_BYTES,
+  VERCEL_MAX_TAGS_PER_ITEM,
+  VERCEL_MAX_TAG_BYTES,
+} from "./vercel-cache-store.js";