@rangojs/router 0.0.0-experimental.e16b7c00 → 0.0.0-experimental.e9c0b2f2

package/src/cache/handle-snapshot.ts

@@ -9,6 +9,76 @@
 import type { ResolvedSegment } from "../types.js";
 import type { HandleStore } from "../server/handle-store.js";
 import type { SegmentHandleData } from "./types.js";
+// segment-codec eagerly pulls @vitejs/plugin-rsc (a virtual: module unresolvable
+// in plain node/vitest). It is imported LAZILY inside the two async encode/decode
+// helpers below so that modules which import handle-snapshot only for the
+// plugin-rsc-free captureHandles/restoreHandles (e.g. cache-scope, on dispatch's
+// lazy response-route cache path) do not pull plugin-rsc at module load. Behavior
+// is unchanged: both helpers are async and already awaited the codec.
+
+const HANDLE_ENCODE_TIMEOUT_MS = 5000;
+
+type HandleRecord = Record<string, SegmentHandleData>;
+
+function hasHandleData(handles: HandleRecord): boolean {
+  for (const segId in handles) {
+    for (const _ in handles[segId]) return true;
+  }
+  return false;
+}
+
+function withTimeout<T>(p: Promise<T>, ms: number, onTimeout: T): Promise<T> {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeout = new Promise<T>((resolve) => {
+    timer = setTimeout(() => resolve(onTimeout), ms);
+  });
+  return Promise.race([
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        return v;
+      },
+      (e) => {
+        clearTimeout(timer);
+        throw e;
+      },
+    ),
+    timeout,
+  ]);
+}
+
+export async function encodeHandles(handles: HandleRecord): Promise<string> {
+  if (!hasHandleData(handles)) return "";
+  return encodeHandleValue(handles);
+}
+
+export function decodeHandles(encoded: string): Promise<HandleRecord | null> {
+  return decodeHandleValue<HandleRecord>(encoded);
+}
+
+export async function encodeHandleValue(value: unknown): Promise<string> {
+  const { serializeResult } = await import("./segment-codec.js");
+  const encoded = await withTimeout(
+    serializeResult(value),
+    HANDLE_ENCODE_TIMEOUT_MS,
+    null,
+  );
+  return encoded ?? "";
+}
+
+/**
+ * Decode a Flight-encoded handle-data string. Returns null on any decode
+ * failure so the caller can skip handle restore without discarding valid
+ * cached/prerendered segments.
+ */
+export async function decodeHandleValue<T>(encoded: string): Promise<T | null> {
+  try {
+    const { deserializeResult } = await import("./segment-codec.js");
+    return await deserializeResult<T>(encoded);
+  } catch {
+    return null;
+  }
+}
 
 /**
  * Capture handle data for a set of segments from the handle store.

package/src/cache/index.ts

@@ -1,50 +1,46 @@
-/**
- * Cache Store
- *
- * Server-side caching for RSC segments and loader data.
- *
- * Main exports for users:
- * - SegmentCacheStore - Interface for implementing custom cache stores
- * - MemorySegmentCacheStore - In-memory cache for development/testing
- * - CFCacheStore - Cloudflare edge cache store for production
- * - CacheScope / createCacheScope - Request-scoped cache provider
- */
-
-// Segment cache store types and implementations
 export type {
   SegmentCacheStore,
-  SegmentCacheProvider,
   CachedEntryData,
-  CachedEntryResult,
   CacheGetResult,
+  CacheItemResult,
+  CacheItemOptions,
   SerializedSegmentData,
   SegmentHandleData,
-  CacheConfig,
-  CacheConfigOrFactory,
 } from "./types.js";
 
 export { MemorySegmentCacheStore } from "./memory-segment-store.js";
 
-// Cloudflare cache store
 export {
   CFCacheStore,
   type CFCacheStoreOptions,
+  type CFCacheDebug,
+  type CFCacheReadDebugEvent,
   type KVNamespace,
   CACHE_STALE_AT_HEADER,
   CACHE_STATUS_HEADER,
+  CACHE_REVALIDATING_AT_HEADER,
+  EDGE_LOOKUP_TIMEOUT_MS,
+  EDGE_READ_TIMEOUT_MS,
+  KV_READ_TIMEOUT_MS,
 } from "./cf/index.js";
 
-// Cache scope
+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/index.js";
+
 export { CacheScope, createCacheScope } from "./cache-scope.js";
 
-// Document-level cache middleware
 export {
   createDocumentCacheMiddleware,
   type DocumentCacheOptions,
 } from "./document-cache.js";
 
-// Cache error reporting. CacheErrorCategory is the discriminator surfaced to a
-// router's onError callback as `metadata.category` for the `cache` phase, so
-// consumers can branch on the failure kind (e.g. distinguish a transient
-// cache-read outage from cache-corrupt self-heal).
 export type { CacheErrorCategory } from "./cache-error.js";

package/src/cache/memory-segment-store.ts

@@ -12,9 +12,9 @@ import type {
   CacheGetResult,
   CacheItemResult,
   CacheItemOptions,
-  SegmentHandleData,
 } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
+import { isPerClientSignalHeader } from "../browser/cookie-name.js";
 import {
   resolveTtl,
   resolveSwrWindow,
@@ -59,7 +59,7 @@ interface CachedResponseEntry {
 
 interface CachedItemEntry {
   value: string;
-  handles?: Record<string, SegmentHandleData>;
+  handles?: string;
   expiresAt: number;
   staleAt: number;
   tags?: string[];
@@ -169,8 +169,6 @@ export class MemorySegmentCacheStore<
 
   constructor(options?: MemorySegmentCacheStoreOptions<TEnv>) {
     if (options?.name != null) {
-      // Named stores use the globalThis registry so data survives HMR.
-      // Each name gets its own isolated Map.
       this.cache = getNamedMap<CachedEntryData>(
         CACHE_REGISTRY_KEY,
         options.name,
@@ -192,7 +190,6 @@ export class MemorySegmentCacheStore<
         options.name,
       );
     } else {
-      // Unnamed stores get a plain instance-level Map (no globalThis sharing).
       this.cache = new Map<string, CachedEntryData>();
       this.responseCache = new Map<string, CachedResponseEntry>();
       this.itemCache = new Map<string, CachedItemEntry>();
@@ -227,15 +224,11 @@ export class MemorySegmentCacheStore<
     ttl: number,
     _swr?: number,
   ): Promise<void> {
-    // Note: Memory store doesn't implement SWR - entries just expire at TTL
-    // For SWR support, use CFCacheStore or similar distributed cache
     const entry: CachedEntryData = {
       ...data,
       expiresAt: Date.now() + ttl * 1000,
     };
     const prefixedKey = `seg:${key}`;
-    // Always drop stale tag mappings before writing so an overwrite with
-    // different (or no) tags cannot leave the previous tags pointing here.
     this.unregisterTags(prefixedKey);
     this.cache.set(key, entry);
     if (data.tags && data.tags.length > 0) {
@@ -287,12 +280,10 @@ export class MemorySegmentCacheStore<
     tags?: string[],
   ): Promise<void> {
     try {
-      // arrayBuffer() can reject (e.g. an already-consumed body). A write
-      // failure must degrade to a no-op (entry simply not cached), never throw
-      // up and fail the request.
       const body = await response.clone().arrayBuffer();
       const headers: [string, string][] = [];
       response.headers.forEach((value, name) => {
+        if (isPerClientSignalHeader(name)) return;
         headers.push([name, value]);
       });
 
@@ -362,19 +353,11 @@ export class MemorySegmentCacheStore<
     }
   }
 
-  /**
-   * Invalidate every cache entry (segment, response, item) tagged with any of
-   * `tags`. Entries are dropped immediately; the next read is a miss and
-   * re-renders fresh. This is the store-level primitive both updateTag() and
-   * revalidateTag() delegate to. (In-process, so there is nothing to batch
-   * beyond looping the tags.)
-   */
   async invalidateTags(tags: string[]): Promise<void> {
     for (const tag of tags) {
       const keys = this.tagIndex.get(tag);
       if (!keys || keys.size === 0) continue;
 
-      // Snapshot the keys before mutating the index inside the loop.
       const prefixedKeys = [...keys];
 
       for (const prefixedKey of prefixedKeys) {
@@ -390,18 +373,11 @@ export class MemorySegmentCacheStore<
           this.itemCache.delete(rawKey);
         }
 
-        // Drop this key from every tag set it belonged to, not just `tag`.
         this.unregisterTags(prefixedKey);
       }
     }
   }
 
-  /**
-   * Register `tags` for a prefixed cache key in both the forward
-   * (tag -> keys) and reverse (key -> tags) indexes.
-   * Callers must call unregisterTags() first to clear stale mappings.
-   * @internal
-   */
   private registerTags(tags: string[], prefixedKey: string): void {
     let tagSet = this.keyTags.get(prefixedKey);
     if (!tagSet) {
@@ -419,11 +395,6 @@ export class MemorySegmentCacheStore<
     }
   }
 
-  /**
-   * Remove a prefixed cache key from every tag set it belongs to.
-   * Uses the reverse index so this is O(tags-per-key), not O(total-tags).
-   * @internal
-   */
   private unregisterTags(prefixedKey: string): void {
     const tagSet = this.keyTags.get(prefixedKey);
     if (!tagSet) return;
@@ -439,10 +410,6 @@ export class MemorySegmentCacheStore<
     this.keyTags.delete(prefixedKey);
   }
 
-  /**
-   * Get cache statistics for debugging purposes.
-   * @internal
-   */
   getStats(): { size: number; keys: string[] } {
     return {
       size: this.cache.size,
@@ -450,18 +417,6 @@ export class MemorySegmentCacheStore<
     };
   }
 
-  /**
-   * Reset the global cache registry.
-   * Useful for test isolation - call this in beforeEach to ensure
-   * tests don't share cache state via globalThis.
-   *
-   * @example
-   * ```typescript
-   * beforeEach(() => {
-   *   MemorySegmentCacheStore.resetGlobalCache();
-   * });
-   * ```
-   */
   static resetGlobalCache(): void {
     delete (globalThis as any)[CACHE_REGISTRY_KEY];
     delete (globalThis as any)[RESPONSE_CACHE_REGISTRY_KEY];

package/src/cache/profile-registry.ts

@@ -1,9 +1,11 @@
 /**
- * Cache Profile Registry
+ * Cache profile resolution.
  *
- * Named cache profiles for "use cache" directive.
- * Profiles define TTL, SWR, and optional default tags.
- * Set by createRouter() at startup, read by registerCachedFunction() at runtime.
+ * Named cache profiles for the "use cache" directive define TTL, SWR, and
+ * optional default tags. createRouter() resolves the user's profiles once via
+ * resolveCacheProfiles() and threads the resulting map onto each request
+ * context; the "use cache: <profile>" runtime path reads it from there
+ * (request-scoped) — there is no global registry.
  */
 
 export interface CacheProfile {
@@ -17,10 +19,6 @@ export interface CacheProfile {
 
 const DEFAULT_PROFILE: CacheProfile = { ttl: 900, swr: 1800 };
 
-let _profiles: Record<string, CacheProfile> = {
-  default: DEFAULT_PROFILE,
-};
-
 const PROFILE_NAME_RE = /^[a-zA-Z0-9_-]+$/;
 
 /**
@@ -44,30 +42,32 @@ export function resolveCacheProfiles(
             `Profile names must match [a-zA-Z0-9_-]+.`,
         );
       }
-      merged[name] = profiles[name];
+      const profile = profiles[name];
+      // Validate ttl/swr VALUES, not just the name. An unvalidated NaN/Infinity
+      // ttl flows into computeExpiration -> staleAt/expiresAt = NaN, and every
+      // expiry check (`now > NaN`) is false, so the entry never evicts and never
+      // revalidates: it is served fresh forever and accumulates unbounded. A
+      // negative ttl makes every read a guaranteed miss. This guard's policy is
+      // to FAIL FAST at config time on any non-finite/negative ttl — distinct
+      // from prefetch-cache-ttl.ts (falls back to the default) and defer.ts
+      // (treats Infinity as an intentional disable). Do not conflate them.
+      if (!Number.isFinite(profile.ttl) || profile.ttl < 0) {
+        throw new Error(
+          `Invalid cache profile "${name}": ttl must be a finite non-negative ` +
+            `number (got ${profile.ttl}).`,
+        );
+      }
+      if (
+        profile.swr !== undefined &&
+        (!Number.isFinite(profile.swr) || profile.swr < 0)
+      ) {
+        throw new Error(
+          `Invalid cache profile "${name}": swr must be a finite non-negative ` +
+            `number (got ${profile.swr}).`,
+        );
+      }
+      merged[name] = profile;
     }
   }
   return merged;
 }
-
-/**
- * Set all cache profiles in the global registry.
- * Called by createRouter() at startup for DSL-time resolution
- * (cache("profileName") reads from this during route definition).
- *
- * WARNING: This is global mutable state. It exists only for DSL-time
- * reads. Runtime resolution (registerCachedFunction) uses request-scoped
- * profiles and does NOT read from this registry.
- */
-export function setCacheProfiles(profiles: Record<string, CacheProfile>): void {
-  _profiles = resolveCacheProfiles(profiles);
-}
-
-/**
- * Get a cache profile by name from the global registry.
- * Used only at DSL-time (cache("profileName") inside urls() evaluation).
- * Runtime code uses request-scoped profiles instead.
- */
-export function getCacheProfile(name: string): CacheProfile | undefined {
-  return _profiles[name];
-}

package/src/cache/read-through-swr.ts

@@ -13,10 +13,15 @@
 
 import type { CacheItemResult, CacheItemOptions } from "./types.js";
 import { runBackground } from "./background-task.js";
+import { reportCacheError } from "./cache-error.js";
+import type { CacheErrorReporter } from "./cache-error.js";
 
-interface WaitUntilHost {
+// The host carries both the optional waitUntil (for background scheduling) and
+// the CacheErrorReporter seam (for routing degradation errors through onError).
+// loader-cache.ts passes the request context, which provides both.
+type WaitUntilHost = {
   waitUntil?: (fn: () => Promise<void>) => void;
-}
+} & CacheErrorReporter;
 
 export interface ReadThroughItemConfig<T> {
   /** Retrieve a cached item by key */
@@ -74,11 +79,20 @@ export async function readThroughItem<T>(
     host,
   } = config;
 
-  // Cache lookup
+  // Cache lookup. An infra read failure (getItem) is reported by the store
+  // itself, so here we just degrade to a miss. A deserialize failure is a
+  // corrupt/truncated stored entry, which this layer owns: report it LOUD as
+  // cache-corrupt, then fall through to a fresh execution (the miss-path write
+  // self-heals the bad entry).
+  let cached: CacheItemResult | null = null;
   try {
-    const cached = await getItem(key);
+    cached = await getItem(key);
+  } catch {
+    cached = null;
+  }
 
-    if (cached) {
+  if (cached) {
+    try {
       const data = await deserialize(cached.value);
 
       if (!cached.shouldRevalidate) {
@@ -97,16 +111,27 @@ export async function readThroughItem<T>(
             if (serialized !== null) {
               await setItem(key, serialized, storeOptions);
             }
-          } catch {
-            // Background revalidation failed silently
+          } catch (error) {
+            reportCacheError(
+              error,
+              "stale-revalidation",
+              "[read-through] background revalidation",
+              host ?? undefined,
+            );
           }
         },
         true,
       );
       return data;
+    } catch (error) {
+      reportCacheError(
+        error,
+        "cache-corrupt",
+        "[read-through] deserialize stored entry",
+        host ?? undefined,
+      );
+      // fall through to fresh execution
     }
-  } catch {
-    // Cache lookup failed, fall through to fresh execution
   }
 
   // Cache miss
@@ -123,8 +148,13 @@ export async function readThroughItem<T>(
           await setItem(key, serialized, storeOptions);
           onCached?.();
         }
-      } catch {
-        // Cache write failed silently
+      } catch (error) {
+        reportCacheError(
+          error,
+          "cache-write",
+          "[read-through] cache write",
+          host ?? undefined,
+        );
       }
     },
     true,

package/src/cache/segment-codec.ts

@@ -10,16 +10,13 @@
 
 import type { ResolvedSegment } from "../types.js";
 import type { SerializedSegmentData } from "./types.js";
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import {
   renderToReadableStream,
   createTemporaryReferenceSet,
 } from "@vitejs/plugin-rsc/rsc";
 import { createFromReadableStream } from "@vitejs/plugin-rsc/rsc";
 
-// ============================================================================
-// Stream Utilities (internal)
-// ============================================================================
-
 /**
  * Convert a ReadableStream to a string.
  */
@@ -55,10 +52,6 @@ export function stringToStream(str: string): ReadableStream<Uint8Array> {
   });
 }
 
-// ============================================================================
-// RSC Serialization Primitives (internal)
-// ============================================================================
-
 /**
  * RSC-serialize a value using React Server Components stream.
  * Used for serializing loaderData, layout, loading components etc.
@@ -90,10 +83,6 @@ export async function rscDeserialize<T>(
   return createFromReadableStream<T>(stream, { temporaryReferences });
 }
 
-// ============================================================================
-// Null-Preserving RSC Serialization (for caching)
-// ============================================================================
-
 /**
  * RSC-serialize any value including null.
  * Unlike rscSerialize(), this does NOT skip null — it serializes it through
@@ -107,7 +96,14 @@ export async function serializeResult(value: unknown): Promise<string | null> {
     const temporaryReferences = createTemporaryReferenceSet();
     const stream = renderToReadableStream(value, { temporaryReferences });
     return await streamToString(stream);
-  } catch {
+  } catch (error) {
+    // Returning null silently turns a non-serializable cache value into a
+    // permanent miss with no trace. Surface it on the internal debug channel so
+    // a failed serialize is diagnosable on wrangler tail, but keep returning
+    // null so the caller falls through to an uncached render rather than throws.
+    if (INTERNAL_RANGO_DEBUG) {
+      console.warn("[segment-codec] serializeResult failed:", error);
+    }
     return null;
   }
 }
@@ -122,10 +118,6 @@ export async function deserializeResult<T>(encoded: string): Promise<T> {
   return createFromReadableStream<T>(stream, { temporaryReferences });
 }
 
-// ============================================================================
-// Public API
-// ============================================================================
-
 /**
  * RSC-deserialize a single encoded component string back to a React element.
  * Used by the static handler runtime to revive pre-rendered components.

package/src/cache/tag-invalidation.ts

@@ -33,10 +33,16 @@ import type { SegmentCacheStore } from "./types.js";
  * the app-level store plus all explicit per-scope stores (deduplicated). Splits
  * them into tag-capable (implement invalidateTags()) and not, so callers can
  * warn about configured stores whose tagged entries will NOT be invalidated.
+ *
+ * `hasContext` reports whether an ALS request context existed at all. Without one
+ * (e.g. a queue consumer or cron job calling updateTag/revalidateTag) no stores
+ * are reachable, and the empty-capable case is a missing-context problem, not a
+ * store-config problem - callers branch on this to warn about the right cause.
  */
 function collectStores(): {
   capable: SegmentCacheStore[];
   incapable: number;
+  hasContext: boolean;
 } {
   const ctx = _getRequestContext();
   const stores = new Set<SegmentCacheStore>();
@@ -50,7 +56,7 @@ function collectStores(): {
     if (typeof store.invalidateTags === "function") capable.push(store);
     else incapable++;
   }
-  return { capable, incapable };
+  return { capable, incapable, hasContext: ctx != null };
 }
 
 /**
@@ -67,6 +73,22 @@ function warnNoTagStore(fn: string, tags: string[]): void {
   );
 }
 
+/**
+ * Production-visible warning for the no-request-context case. Distinct from
+ * warnNoTagStore: the stores are not unreachable because they are misconfigured,
+ * but because there is no ALS request context to reach them through (e.g. a queue
+ * consumer or scheduled job). Naming the real cause keeps consumers from chasing
+ * a store-config red herring.
+ */
+function warnNoRequestContext(fn: string, tags: string[]): void {
+  console.warn(
+    `[${fn}] Called outside a request context (e.g. from a queue consumer or ` +
+      `scheduled job); no cache stores are reachable and tags ` +
+      `[${tags.join(", ")}] were not invalidated. Invoke it within a request ` +
+      `(Server Action or route handler).`,
+  );
+}
+
 /**
  * Production-visible warning for mixed-store configs: at least one configured
  * store does not support tag invalidation, so its tagged entries (if any) are
@@ -132,9 +154,10 @@ export async function updateTag(...tags: string[]): Promise<void> {
   const valid = normalizeTags(tags);
   if (valid.length === 0) return;
 
-  const { capable, incapable } = collectStores();
+  const { capable, incapable, hasContext } = collectStores();
   if (capable.length === 0) {
-    warnNoTagStore("updateTag", valid);
+    if (hasContext) warnNoTagStore("updateTag", valid);
+    else warnNoRequestContext("updateTag", valid);
     return;
   }
   if (incapable > 0) warnPartialTagStore("updateTag", incapable);
@@ -177,9 +200,10 @@ export function revalidateTag(...tags: string[]): void {
   const valid = normalizeTags(tags);
   if (valid.length === 0) return;
 
-  const { capable, incapable } = collectStores();
+  const { capable, incapable, hasContext } = collectStores();
   if (capable.length === 0) {
-    warnNoTagStore("revalidateTag", valid);
+    if (hasContext) warnNoTagStore("revalidateTag", valid);
+    else warnNoRequestContext("revalidateTag", valid);
     return;
   }
   if (incapable > 0) warnPartialTagStore("revalidateTag", incapable);