@rangojs/router 0.0.0-experimental.ce770c9a → 0.0.0-experimental.d5d3070a

package/src/cache/cache-scope.ts

@@ -16,14 +16,38 @@ import {
   getRequestContext,
   _getRequestContext,
 } from "../server/request-context.js";
-import { serializeSegments, deserializeSegments } from "./segment-codec.js";
-import { captureHandles, restoreHandles } from "./handle-snapshot.js";
+import { recordRequestTags } from "./cache-tag.js";
+import { reportCacheError } from "./cache-error.js";
+// segment-codec is the only module on cache-scope's import graph that eagerly
+// pulls @vitejs/plugin-rsc (a virtual: module the plain node/vitest runner cannot
+// resolve). It is imported LAZILY at the two call sites below (deserializeSegments
+// in lookupRoute, serializeSegments in cacheRoute) so that requiring cache-scope —
+// e.g. dispatch's lazy `import("../cache/cache-scope.js")` for the response-route
+// cache path — does not crash a consumer test that never mocks plugin-rsc. Behavior
+// is unchanged: both methods are async and already awaited the codec.
+import {
+  captureHandles,
+  restoreHandles,
+  encodeHandles,
+  decodeHandles,
+} from "./handle-snapshot.js";
 import { sortedSearchString, sortedRouteParams } from "./cache-key-utils.js";
 import {
   DEFAULT_ROUTE_TTL,
+  isFiniteNonNegativeSeconds,
   resolveCacheKey,
   resolveCacheStore,
+  resolveTagsOption,
 } from "./cache-policy.js";
+import type { RequestContext } from "../server/request-context.js";
+
+export function resolveCacheTags(
+  config: PartialCacheOptions | false,
+  ctx: RequestContext | undefined,
+): string[] | undefined {
+  if (config === false) return undefined;
+  return resolveTagsOption(config.tags, ctx, "CacheScope");
+}
 
 function debugCacheLog(message: string): void {
   if (INTERNAL_RANGO_DEBUG) {
@@ -31,17 +55,36 @@ function debugCacheLog(message: string): void {
   }
 }
 
-// ============================================================================
-// Key Generation (internal)
-// ============================================================================
-
 /**
- * Generate cache key base from host, pathname, route params, and search params.
- * Host is included to prevent cross-host cache collisions on shared stores.
- * Route params and search params are sorted alphabetically for deterministic keys.
- * Internal _rsc* and __* query params are excluded.
- * @internal
+ * A finite, non-negative seconds value? A NaN/Infinity ttl/swr (from a bad
+ * cache() option or store defaults) flows into computeExpiration ->
+ * staleAt/expiresAt = NaN, where every `now > NaN` is false so the entry never
+ * evicts and is served fresh forever; a negative value makes every read a miss.
+ * Mirror profile-registry.ts's Number.isFinite + >= 0 check, but the callers
+ * degrade to a default (warning in dev) rather than throw — this runs on the
+ * foreground render.
  */
+function isValidCacheSeconds(value: number, label: string): boolean {
+  if (isFiniteNonNegativeSeconds(value)) return true;
+  if (process.env.NODE_ENV !== "production") {
+    console.warn(
+      `[CacheScope] Invalid ${label} ${value}; falling back to default`,
+    );
+  }
+  return false;
+}
+
+/** Coerce a resolved ttl to a finite, non-negative number (default on invalid). */
+function validatedTtl(value: number): number {
+  return isValidCacheSeconds(value, "ttl") ? value : DEFAULT_ROUTE_TTL;
+}
+
+/** Coerce a resolved swr to a finite, non-negative number, or undefined (no SWR window). */
+function validatedSwr(value: number | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  return isValidCacheSeconds(value, "swr") ? value : undefined;
+}
+
 function getCacheKeyBase(
   host: string,
   pathname: string,
@@ -57,16 +100,6 @@ function getCacheKeyBase(
   return key;
 }
 
-/**
- * Generate default cache key for a route request.
- * Includes pathname, route params, and user-facing search params for
- * correct scoping. Internal _rsc* params are excluded.
- * Includes request type prefix since they produce different segment sets:
- * - doc: document requests (full page load)
- * - partial: navigation requests (client-side navigation)
- * - intercept: intercept navigation (modal/overlay routes)
- * @internal
- */
 function getDefaultRouteCacheKey(
   pathname: string,
   params?: Record<string, string>,
@@ -128,20 +161,26 @@ export class CacheScope {
   }
 
   /**
-   * Get effective TTL from config or store defaults
+   * Get effective TTL from config or store defaults.
+   *
+   * Unlike profile-registry.ts (which fails fast at config time), the render
+   * path must DEGRADE: a non-finite/negative ttl (NaN/Infinity from a bad
+   * defaults config) would make computeExpiration produce NaN deadlines so the
+   * entry never evicts, or a guaranteed miss for a negative value. Fall back to
+   * DEFAULT_ROUTE_TTL instead of throwing in the foreground render.
    */
   get ttl(): number {
     if (this.config === false) return 0;
 
     // Explicit TTL in cache() options
     if (this.config.ttl !== undefined) {
-      return this.config.ttl;
+      return validatedTtl(this.config.ttl);
     }
 
     // Fall back to store defaults (explicit store first, then app-level)
     const store = this.getStore();
     if (store?.defaults?.ttl !== undefined) {
-      return store.defaults.ttl;
+      return validatedTtl(store.defaults.ttl);
     }
 
     // Hardcoded fallback
@@ -149,19 +188,22 @@ export class CacheScope {
   }
 
   /**
-   * Get SWR window from config or store defaults
+   * Get SWR window from config or store defaults.
+   *
+   * A non-finite/negative swr is degraded to undefined (no SWR window) rather
+   * than fed into expiry math; see the ttl getter for the rationale.
    */
   get swr(): number | undefined {
     if (this.config === false) return undefined;
 
     // Explicit SWR in cache() options
     if (this.config.swr !== undefined) {
-      return this.config.swr;
+      return validatedSwr(this.config.swr);
     }
 
     // Fall back to store defaults
     const store = this.getStore();
-    return store?.defaults?.swr;
+    return validatedSwr(store?.defaults?.swr);
   }
 
   /**
@@ -187,6 +229,32 @@ export class CacheScope {
     return resolveCacheKey(keyFn, this.getStore(), defaultKey, "CacheScope");
   }
 
+  /**
+   * Evaluate the cache `condition` predicate. Returns false (skip the cache
+   * operation) when the predicate returns false or throws; returns true when
+   * there is no condition or no request context to evaluate it against.
+   */
+  private conditionAllows(op: "read" | "write"): boolean {
+    if (this.config === false || !this.config.condition) return true;
+    const requestCtx = getRequestContext();
+    if (!requestCtx) return true;
+    try {
+      if (!this.config.condition(requestCtx)) {
+        debugCacheLog(
+          `[CacheScope] condition returned false, skipping cache ${op}`,
+        );
+        return false;
+      }
+      return true;
+    } catch (error) {
+      console.error(
+        `[CacheScope] condition function threw, skipping cache ${op}:`,
+        error,
+      );
+      return false;
+    }
+  }
+
   /**
    * Lookup cached segments for a route (single cache entry per request).
    * Returns { segments, shouldRevalidate } or null if cache miss.
@@ -204,35 +272,21 @@ export class CacheScope {
     shouldRevalidate: boolean;
   } | null> {
     if (!this.enabled) return null;
-
-    // Evaluate condition — skip cache read when condition returns false
-    if (this.config !== false && this.config.condition) {
-      const requestCtx = getRequestContext();
-      if (requestCtx) {
-        try {
-          if (!this.config.condition(requestCtx)) {
-            debugCacheLog(
-              `[CacheScope] condition returned false, skipping cache read`,
-            );
-            return null;
-          }
-        } catch (error) {
-          console.error(
-            `[CacheScope] condition function threw, skipping cache read:`,
-            error,
-          );
-          return null;
-        }
-      }
-    }
+    if (!this.conditionAllows("read")) return null;
 
     const store = this.getStore();
     if (!store) return null;
 
-    // Resolve cache key (may use custom key functions)
-    const key = await this.resolveKey(pathname, params, isIntercept);
-
+    // Resolve cache key INSIDE the try so a throwing consumer key() (or a
+    // store.keyGenerator) degrades to a cache miss (return null -> render
+    // uncached) instead of crashing the foreground render. resolveCacheKey
+    // itself keeps its hard-fail/no-fallback-to-default contract (a throw must
+    // not silently collide onto the default slot); the graceful degradation
+    // happens here, where a miss is a safe outcome.
+    let key: string | undefined;
     try {
+      key = await this.resolveKey(pathname, params, isIntercept);
+
       const result = await store.get(key);
 
       if (!result) {
@@ -242,13 +296,44 @@ export class CacheScope {
 
       const { data: cached, shouldRevalidate } = result;
 
-      // Deserialize segments
-      const segments = await deserializeSegments(cached.segments);
+      // Deserialize segments. A failure means the cached segments are corrupt/
+      // partial: evict the entry (self-heal - the re-render re-caches under the
+      // same key) and report it as corruption, distinct from a transient infra
+      // error (handled by the outer catch).
+      let segments: ResolvedSegment[];
+      try {
+        const { deserializeSegments } = await import("./segment-codec.js");
+        segments = await deserializeSegments(cached.segments);
+      } catch (error) {
+        reportCacheError(
+          error,
+          "cache-corrupt",
+          `[CacheScope] ${key}: corrupt cached segments, evicting`,
+        );
+        await store
+          .delete(key)
+          .catch((e) =>
+            reportCacheError(e, "cache-delete", `[CacheScope] ${key}: evict`),
+          );
+        return null;
+      }
+
+      // A hit serves content that was tagged at write time, so the document
+      // tag union must include this entry's tags for updateTag()/revalidateTag()
+      // to invalidate any full-page entry built on top of it. The write path
+      // records via cacheRoute (resolveCacheTags); the hit path records here.
+      recordRequestTags(cached.tags);
 
-      // Replay handle data
+      // Replay handle data. An empty string means the route pushed no handles —
+      // skip the decode entirely (the common case). Otherwise decode the
+      // Flight-encoded blob; a decode failure skips handle restore but keeps the
+      // valid cached segments.
       const handleStore = _getRequestContext()?._handleStore;
-      if (handleStore) {
-        restoreHandles(cached.handles, handleStore);
+      if (handleStore && cached.handles) {
+        const handlesRecord = await decodeHandles(cached.handles);
+        if (handlesRecord) {
+          restoreHandles(handlesRecord, handleStore);
+        }
       }
 
       if (INTERNAL_RANGO_DEBUG) {
@@ -262,11 +347,37 @@ export class CacheScope {
 
       return { segments, shouldRevalidate };
     } catch (error) {
-      console.error(`[CacheScope] Failed to lookup ${key}:`, error);
+      // Covers a store.get() failure AND a throwing consumer key()/keyGenerator
+      // (resolveKey). Either way degrade to a cache miss so the render proceeds.
+      reportCacheError(
+        error,
+        "cache-read",
+        `[CacheScope] lookup ${key ?? "(key resolution failed)"}`,
+      );
       return null;
     }
   }
 
+  /**
+   * Record this scope's segment-DSL cache({ tags }) into the request tag union
+   * synchronously, under the same gate cacheRoute() uses for a write.
+   *
+   * cacheRoute() already records these tags, but it is invoked inside
+   * requestCtx.waitUntil() by the cache-store middleware (and the proactive path
+   * re-resolves the whole tree before calling it), so its recording is deferred
+   * and RACES the document cache's post-body-drain snapshot of _requestTags. On a
+   * first-write (segment-cache miss) the document tag union could miss these
+   * tags, and updateTag()/revalidateTag() would then fail to invalidate the
+   * cached document until a later write reseeded it. Calling this synchronously
+   * in the request pipeline (before the snapshot) closes that window. Idempotent
+   * (the tag union is a Set), so the duplicate record in cacheRoute is harmless.
+   */
+  recordTags(requestCtx: RequestContext | undefined): void {
+    if (!this.enabled) return;
+    if (!this.conditionAllows("write")) return;
+    recordRequestTags(resolveCacheTags(this.config, requestCtx), requestCtx);
+  }
+
   /**
    * Cache all segments for a route (non-blocking via waitUntil)
    * Single cache entry per route request.
@@ -284,27 +395,7 @@ export class CacheScope {
     isIntercept?: boolean,
   ): Promise<void> {
     if (!this.enabled || segments.length === 0) return;
-
-    // Evaluate condition — skip cache write when condition returns false
-    if (this.config !== false && this.config.condition) {
-      const conditionCtx = getRequestContext();
-      if (conditionCtx) {
-        try {
-          if (!this.config.condition(conditionCtx)) {
-            debugCacheLog(
-              `[CacheScope] condition returned false, skipping cache write`,
-            );
-            return;
-          }
-        } catch (error) {
-          console.error(
-            `[CacheScope] condition function threw, skipping cache write:`,
-            error,
-          );
-          return;
-        }
-      }
-    }
+    if (!this.conditionAllows("write")) return;
 
     const store = this.getStore();
     if (!store) return;
@@ -325,34 +416,86 @@ export class CacheScope {
     // Resolve cache key early (while request context is available)
     const key = await this.resolveKey(pathname, params, isIntercept);
 
+    // Resolve tags early (while request context is available, before waitUntil)
+    const tags = resolveCacheTags(this.config, requestCtx);
+    recordRequestTags(tags, requestCtx);
+
     // Check if this is a partial request (navigation) vs document request
     const isPartial = requestCtx.originalUrl.searchParams.has("_rsc_partial");
 
+    if (INTERNAL_RANGO_DEBUG) {
+      debugCacheLog(
+        `[CacheScope] cacheRoute: scheduling waitUntil for ${key} (${nonLoaderSegments.length} segments, isPartial=${isPartial})`,
+      );
+    }
+
     requestCtx.waitUntil(async () => {
+      if (INTERNAL_RANGO_DEBUG) {
+        debugCacheLog(
+          `[CacheScope] waitUntil: awaiting handleStore.settled for ${key}`,
+        );
+      }
+
       await handleStore.settled;
 
-      // For document requests: only cache if ALL segments have components (complete render)
-      // For partial requests: null components are expected (client already has them)
+      if (INTERNAL_RANGO_DEBUG) {
+        debugCacheLog(`[CacheScope] waitUntil: handleStore settled for ${key}`);
+      }
+
+      // For document requests: only cache if layout segments have components
+      // (complete render). Parallel and route segments may legitimately have
+      // null components — UI-less @meta parallels return null, and void route
+      // handlers produce null when the UI lives in parallel slots/layouts.
+      // Partial requests always allow null components (client already has them).
       if (!isPartial) {
-        const hasAllComponents = nonLoaderSegments.every(
-          (s) => s.component !== null,
+        const hasIncompleteLayouts = nonLoaderSegments.some(
+          (s) => s.component === null && s.type === "layout",
         );
-        if (!hasAllComponents) return;
+        if (hasIncompleteLayouts) {
+          const nullSegments = nonLoaderSegments
+            .filter((s) => s.component === null && s.type === "layout")
+            .map((s) => s.id);
+          const error = new Error(
+            `[CacheScope] Cache write skipped: layout segments have null components ` +
+              `(${nullSegments.join(", ")}). This indicates an incomplete render — ` +
+              `layout handlers must return JSX for document requests to be cacheable.`,
+          );
+          error.name = "CacheScopeInvariantError";
+          console.error(error.message);
+          return;
+        }
       }
 
       // Collect handle data for non-loader segments only
       const handles = captureHandles(nonLoaderSegments, handleStore);
 
       try {
-        // Serialize non-loader segments only
-        const serializedSegments = await serializeSegments(nonLoaderSegments);
+        if (INTERNAL_RANGO_DEBUG) {
+          debugCacheLog(
+            `[CacheScope] waitUntil: serializing ${nonLoaderSegments.length} segments for ${key}`,
+          );
+        }
+
+        // Serialize segments and Flight-encode handles in parallel. Handles go
+        // through the codec (not raw into the entry) so Promise/ReactNode handle
+        // values survive a JSON-serializing store — see encodeHandles.
+        const { serializeSegments } = await import("./segment-codec.js");
+        const [serializedSegments, encodedHandles] = await Promise.all([
+          serializeSegments(nonLoaderSegments),
+          encodeHandles(handles),
+        ]);
 
         const data: CachedEntryData = {
           segments: serializedSegments,
-          handles,
+          handles: encodedHandles,
           expiresAt: Date.now() + ttl * 1000,
+          tags,
         };
 
+        if (INTERNAL_RANGO_DEBUG) {
+          debugCacheLog(`[CacheScope] waitUntil: calling store.set for ${key}`);
+        }
+
         await store.set(key, data, ttl, swr);
 
         if (INTERNAL_RANGO_DEBUG) {
@@ -364,7 +507,11 @@ export class CacheScope {
           );
         }
       } catch (error) {
-        console.error(`[CacheScope] Failed to cache ${key}:`, error);
+        reportCacheError(
+          error,
+          "cache-write",
+          `[CacheScope] Failed to cache ${key}`,
+        );
       }
     });
   }

package/src/cache/cache-tag.ts

@@ -0,0 +1,103 @@
+/**
+ * Cache Tag API
+ *
+ * Provides cacheTag() for tagging cached entries at runtime inside "use cache"
+ * functions. Tags are scoped via AsyncLocalStorage; calling cacheTag() outside
+ * a "use cache" execution throws.
+ *
+ * The runtime (cache-runtime.ts) wraps "use cache" execution in
+ * runWithCacheTagScope(), collects the runtime tags, and merges them with the
+ * profile/DSL tags before storing.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import {
+  _getRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
+
+const cacheTagStorage = new AsyncLocalStorage<Set<string>>();
+
+export function normalizeTag(tag: string): string | null {
+  // Trim and return the canonical (trimmed) form, not the raw tag. Both the
+  // write path (cacheTag) and the invalidate path (updateTag/revalidateTag)
+  // route through here, and matching is exact-string: returning the untrimmed
+  // tag made cacheTag(" products ") and updateTag("products") two different
+  // logical tags, a silent failure-to-invalidate (stale data served forever).
+  const trimmed = tag?.trim();
+  return trimmed ? trimmed : null;
+}
+
+export function normalizeTags(tags: Iterable<string>): string[] {
+  const out: string[] = [];
+  for (const tag of tags) {
+    const normalized = normalizeTag(tag);
+    if (normalized !== null) out.push(normalized);
+  }
+  return out;
+}
+
+/**
+ * Tag the current "use cache" entry for later invalidation via
+ * updateTag() / revalidateTag().
+ *
+ * Must be called inside a function marked with "use cache".
+ * Tags are additive - multiple calls accumulate.
+ *
+ * @example
+ * ```typescript
+ * async function getProduct(ctx) {
+ *   "use cache";
+ *   cacheTag(`product:${ctx.params.id}`, "products");
+ *   return db.getProduct(ctx.params.id);
+ * }
+ * ```
+ */
+export function cacheTag(...tags: string[]): void {
+  const store = cacheTagStorage.getStore();
+  if (!store) {
+    throw new Error('cacheTag() must be called inside a "use cache" function.');
+  }
+  for (const tag of tags) {
+    const normalized = normalizeTag(tag);
+    if (normalized === null) {
+      if (process.env.NODE_ENV !== "production") {
+        console.warn(`[cacheTag] Ignoring empty or whitespace-only tag.`);
+      }
+      continue;
+    }
+    store.add(normalized);
+  }
+}
+
+export function recordRequestTags(
+  tags: Iterable<string> | undefined,
+  ctx: RequestContext | undefined = _getRequestContext(),
+): void {
+  if (!tags) return;
+  const set = ctx?._requestTags;
+  if (!set) return;
+  for (const tag of tags) {
+    const normalized = normalizeTag(tag);
+    if (normalized !== null) set.add(normalized);
+  }
+}
+
+/**
+ * Run a function within a cache tag scope. Any cacheTag() calls inside `fn`
+ * accumulate into the returned Set.
+ *
+ * The returned Set is the LIVE reference - the caller must await `result`
+ * before reading `tags`, because an async cached function may call cacheTag()
+ * after an await boundary.
+ *
+ * @internal Used by cache-runtime.ts to wrap "use cache" execution.
+ */
+export function runWithCacheTagScope<T>(fn: () => T): {
+  result: T;
+  tags: Set<string>;
+} {
+  const tagSet = new Set<string>();
+  const result = cacheTagStorage.run(tagSet, fn);
+  return { result, tags: tagSet };
+}

package/src/cache/cf/cf-base64.ts

@@ -0,0 +1,33 @@
+// ============================================================================
+// Base64 Helpers (binary-safe response body encoding for KV)
+// ============================================================================
+
+// Chunk size for String.fromCharCode.apply: large enough to amortize the call
+// overhead, small enough to stay well under the JS engine argument-count limit
+// (~65k). 8192 turns a per-byte concat loop into O(n/8192) apply calls.
+const FROM_CHARCODE_CHUNK = 8192;
+
+/** Encode ArrayBuffer to base64 string. */
+export function bufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  // Build the binary (latin1) string in fixed-size chunks instead of one
+  // String.fromCharCode per byte. Identical output to the per-byte loop (each
+  // byte maps to the same code unit); just far fewer string concatenations for
+  // large document payloads.
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += FROM_CHARCODE_CHUNK) {
+    const chunk = bytes.subarray(i, i + FROM_CHARCODE_CHUNK);
+    binary += String.fromCharCode.apply(null, chunk as unknown as number[]);
+  }
+  return btoa(binary);
+}
+
+/** Decode base64 string to ArrayBuffer. */
+export function base64ToBuffer(base64: string): ArrayBuffer {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
+}