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

package/src/cache/cache-policy.ts

@@ -9,6 +9,7 @@
 import type { CacheDefaults, SegmentCacheStore } from "./types.js";
 import { _getRequestContext } from "../server/request-context.js";
 import type { RequestContext } from "../server/request-context.js";
+import { normalizeTags } from "./cache-tag.js";
 
 /**
  * Default TTL for route-level cache() DSL and loader cache.
@@ -108,6 +109,64 @@ export async function resolveCacheKey(
   return defaultKey;
 }
 
+// ============================================================================
+// Cache Tag Resolution
+// ============================================================================
+
+/**
+ * Resolve cache tags from a tags option (static array or function of ctx).
+ *
+ * Fails open: a thrown tag callback falls back to no tags rather than
+ * aborting the request. Tags are additive metadata (not identity), so a
+ * missing tag does not cause cache collisions, only a missed invalidation.
+ *
+ * Shared by the cache() DSL (cache-scope) and loader caching (loader-cache)
+ * so tag resolution behaves identically across every cache axis.
+ */
+export function resolveTagsOption<TEnv>(
+  tags: string[] | ((ctx: RequestContext<TEnv>) => string[]) | undefined,
+  ctx: RequestContext<TEnv> | undefined,
+  label: string,
+): string[] | undefined {
+  if (!tags) return undefined;
+  if (typeof tags === "function") {
+    if (!ctx) {
+      // A dynamic tags function needs the request context to run. Without it
+      // (e.g. resolved outside a request, at build/prerender time) the entry is
+      // cached UNTAGGED and can never be invalidated - surface that rather than
+      // silently dropping the tags, matching the thrown-callback branch below.
+      console.warn(
+        `[${label}] Dynamic tags function present but no request context; ` +
+          `caching without tags (this entry will not be tag-invalidatable).`,
+      );
+      return undefined;
+    }
+    try {
+      return normalizeTagList(tags(ctx));
+    } catch (error) {
+      console.error(
+        `[${label}] Tags function failed, caching without tags:`,
+        error,
+      );
+      return undefined;
+    }
+  }
+  return normalizeTagList(tags);
+}
+
+/**
+ * Normalize a resolved tags array so the WRITE path matches the invalidate path:
+ * updateTag()/revalidateTag()/cacheTag() all drop empty/whitespace-only tags via
+ * normalizeTag(). Without this, an empty tag attached at write time would enter
+ * the store index but could never be invalidated (the verbs normalize it away),
+ * and on CFCacheStore would also cost a wasted KV marker read per request.
+ * Returns undefined when nothing usable remains, keeping the entry header-free.
+ */
+function normalizeTagList(tags: string[]): string[] | undefined {
+  const out = normalizeTags(tags);
+  return out.length > 0 ? out : undefined;
+}
+
 // ============================================================================
 // Cache Store Resolution
 // ============================================================================
@@ -120,6 +179,41 @@ export async function resolveCacheKey(
 export function resolveCacheStore(
   explicitStore: SegmentCacheStore | undefined,
 ): SegmentCacheStore | null {
-  if (explicitStore) return explicitStore;
+  if (explicitStore) {
+    // Register explicit per-scope stores so updateTag()/revalidateTag() can
+    // reach them. This is the single chokepoint every cache axis (segment,
+    // response, loader) resolves through, so registering here covers them all
+    // eagerly - no dependence on whether a tagged write has happened yet. The
+    // app-level store is intentionally not registered (always reachable via
+    // ctx._cacheStore).
+    registerExplicitTaggedStore(explicitStore);
+    return explicitStore;
+  }
   return _getRequestContext()?._cacheStore ?? null;
 }
+
+/**
+ * Upper bound on the per-handler explicit-store registry. A module-singleton
+ * store (the recommended pattern) dedupes to a single entry and never approaches
+ * this. The cap bounds the niche case of an explicit store constructed PER
+ * request/boundary (e.g. a ctx-bound CFCacheStore, which must take a per-request
+ * ctx): without it the registry - which intentionally persists across requests so
+ * a server action's updateTag() can reach stores a prior render registered -
+ * would accumulate one dead instance per request and fan invalidation out to
+ * finished execution contexts. LRU-touch on re-resolution keeps a live, re-used
+ * store from being evicted by that churn.
+ */
+const EXPLICIT_STORE_REGISTRY_CAP = 64;
+
+function registerExplicitTaggedStore(store: SegmentCacheStore): void {
+  const set = _getRequestContext()?._explicitTaggedStores;
+  if (!set) return;
+  // LRU touch: move an already-present store to the most-recent position (Set
+  // preserves insertion order) so a store re-resolved every request stays live.
+  set.delete(store);
+  set.add(store);
+  if (set.size > EXPLICIT_STORE_REGISTRY_CAP) {
+    const oldest = set.values().next().value;
+    if (oldest !== undefined) set.delete(oldest);
+  }
+}

package/src/cache/cache-runtime.ts

@@ -36,6 +36,12 @@ import { restoreHandles } from "./handle-snapshot.js";
 import { startHandleCapture, type HandleCapture } from "./handle-capture.js";
 import { sortedSearchString } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
+import {
+  normalizeTags,
+  recordRequestTags,
+  runWithCacheTagScope,
+} from "./cache-tag.js";
+import { reportCacheError } from "./cache-error.js";
 
 /**
  * Convert encodeReply result to a stable string key.
@@ -70,9 +76,17 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     const store = requestCtx?._cacheStore;
     const resolvedProfileName = profileName || "default";
 
-    // Bypass: no store or no getItem support
+    // Bypass: no store or no getItem support. Still run inside a tag scope so a
+    // cacheTag() call inside the function degrades to a no-op rather than
+    // throwing "must be called inside a use cache function" - adopting cacheTag()
+    // must not hard-fail in apps/tests without an item-capable cache configured.
     if (!store?.getItem) {
-      return fn.apply(this, args);
+      const scoped = runWithCacheTagScope(() => fn.apply(this, args));
+      const result = await scoped.result;
+      // Still record the runtime tags into the request set so a cacheTag() in an
+      // uncached function tags the document, even with no item-capable store.
+      recordRequestTags(scoped.tags, requestCtx);
+      return result;
     }
 
     // Resolve profile strictly from request-scoped config (set by the
@@ -155,8 +169,13 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         cacheKey = `use-cache:${id}`;
       }
     } catch {
-      // Non-serializable args: run uncached
-      return fn.apply(this, args);
+      // Non-serializable args: run uncached (within a tag scope so cacheTag()
+      // still does not throw). Record runtime tags so the document union still
+      // sees them even though this call is not itself cached.
+      const scoped = runWithCacheTagScope(() => fn.apply(this, args));
+      const result = await scoped.result;
+      recordRequestTags(scoped.tags, requestCtx);
+      return result;
     }
 
     // Cache lookup
@@ -173,9 +192,20 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             restoreHandles(cached.handles, handleStore);
           }
         }
+        // Surface the hit's tags to the request set so a document built from a
+        // cached item is still tagged (the function did not re-run, so its
+        // runtime cacheTag() tags are only available from the stored entry).
+        recordRequestTags(cached.tags, requestCtx);
         return result;
-      } catch {
-        // Deserialization failed, fall through to fresh execution
+      } catch (error) {
+        // The stored value is corrupt/partial (failed RSC deserialize). Report
+        // it, then fall through to fresh execution - the miss path below re-runs
+        // and setItem() overwrites the faulty entry under the same key (self-heal).
+        reportCacheError(
+          error,
+          "cache-corrupt",
+          `[use cache] "${id}" fresh-hit`,
+        );
       }
     }
 
@@ -189,6 +219,8 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             restoreHandles(cached.handles, handleStore);
           }
         }
+        // Tag the request with the stale entry's tags (see fresh-hit note).
+        recordRequestTags(cached.tags, requestCtx);
         // Background revalidation — must capture handles if tainted args present.
         // Use an isolated handle store so background pushes don't pollute the
         // live response or throw LateHandlePushError on the completed store.
@@ -238,20 +270,38 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           }
 
           try {
-            const freshResult = await fn.apply(this, args);
+            const scoped = runWithCacheTagScope(() => fn.apply(this, args));
+            const freshResult = await scoped.result;
             bgStopCapture?.();
+            // Merge profile/DSL tags with runtime cacheTag() tags, read after
+            // awaiting so post-await cacheTag() calls are included. Normalize
+            // (drops empty profile tags, matching the invalidate path) + dedupe.
+            const freshTags = [
+              ...new Set(
+                normalizeTags([...(profile.tags ?? []), ...scoped.tags]),
+              ),
+            ];
+            recordRequestTags(freshTags, requestCtx);
             const serialized = await serializeResult(freshResult);
             if (serialized !== null) {
               await store.setItem!(cacheKey, serialized, {
                 handles: bgCapture?.data,
                 ttl: profile.ttl,
                 swr: profile.swr,
-                tags: profile.tags,
+                tags: freshTags.length > 0 ? freshTags : undefined,
               });
             }
           } catch (bgError) {
             bgStopCapture?.();
-            requestCtx?._reportBackgroundError?.(bgError, "stale-revalidation");
+            // Pass requestCtx explicitly: this runs in a detached background
+            // task where the ALS context is gone, so onError can only fire if
+            // we hand it the context captured up front.
+            reportCacheError(
+              bgError,
+              "stale-revalidation",
+              "[use cache] background revalidation failed",
+              requestCtx,
+            );
           } finally {
             for (const arg of bgTaintedArgs) {
               unstampCacheExec(arg as object);
@@ -263,8 +313,14 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           }
         });
         return result;
-      } catch {
-        // Deserialization of stale value failed, fall through
+      } catch (error) {
+        // Stale value is corrupt/partial; report and fall through to a fresh
+        // execution, which overwrites the faulty entry under the same key.
+        reportCacheError(
+          error,
+          "cache-corrupt",
+          `[use cache] "${id}" stale-hit`,
+        );
       }
     }
 
@@ -297,8 +353,10 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     }
 
     let result: any;
+    let scoped: ReturnType<typeof runWithCacheTagScope>;
     try {
-      result = await fn.apply(this, args);
+      scoped = runWithCacheTagScope(() => fn.apply(this, args));
+      result = await scoped.result;
     } finally {
       // Decrement ref count; symbol is deleted when it reaches zero
       for (const arg of taintedArgs) {
@@ -311,6 +369,14 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       stopCapture?.();
     }
 
+    // Merge profile/DSL tags with runtime cacheTag() tags. Read scoped.tags
+    // after awaiting result so post-await cacheTag() calls are included.
+    // Normalize (drops empty profile tags, matching the invalidate path) + dedupe.
+    const allTags = [
+      ...new Set(normalizeTags([...(profile.tags ?? []), ...scoped!.tags])),
+    ];
+    recordRequestTags(allTags, requestCtx);
+
     // Serialize and store — fully non-blocking when waitUntil is available.
     // The response does not need to wait for serialization or the store write.
     const cacheWrite = async () => {
@@ -321,7 +387,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             handles: capture?.data,
             ttl: profile.ttl,
             swr: profile.swr,
-            tags: profile.tags,
+            tags: allTags.length > 0 ? allTags : undefined,
           });
         }
       } catch (writeError) {

package/src/cache/cache-scope.ts

@@ -16,6 +16,8 @@ import {
   getRequestContext,
   _getRequestContext,
 } from "../server/request-context.js";
+import { recordRequestTags } from "./cache-tag.js";
+import { reportCacheError } from "./cache-error.js";
 import { serializeSegments, deserializeSegments } from "./segment-codec.js";
 import { captureHandles, restoreHandles } from "./handle-snapshot.js";
 import { sortedSearchString, sortedRouteParams } from "./cache-key-utils.js";
@@ -23,7 +25,23 @@ import {
   DEFAULT_ROUTE_TTL,
   resolveCacheKey,
   resolveCacheStore,
+  resolveTagsOption,
 } from "./cache-policy.js";
+import type { RequestContext } from "../server/request-context.js";
+
+/**
+ * Resolve tags for a cache() boundary from its config (static array or
+ * function of ctx). Thin wrapper over the shared resolveTagsOption so the
+ * cache() DSL and loader caching resolve tags identically.
+ * @internal
+ */
+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) {
@@ -187,6 +205,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,27 +248,7 @@ 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;
@@ -242,8 +266,26 @@ 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 {
+        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;
+      }
 
       // Replay handle data
       const handleStore = _getRequestContext()?._handleStore;
@@ -262,7 +304,7 @@ export class CacheScope {
 
       return { segments, shouldRevalidate };
     } catch (error) {
-      console.error(`[CacheScope] Failed to lookup ${key}:`, error);
+      reportCacheError(error, "cache-read", `[CacheScope] lookup ${key}`);
       return null;
     }
   }
@@ -284,27 +326,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,6 +347,10 @@ 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");
 
@@ -388,6 +414,7 @@ export class CacheScope {
           segments: serializedSegments,
           handles,
           expiresAt: Date.now() + ttl * 1000,
+          tags,
         };
 
         if (INTERNAL_RANGO_DEBUG) {
@@ -405,7 +432,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,135 @@
+/**
+ * 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>>();
+
+/**
+ * Normalize a tag for storage.
+ *
+ * Returns the tag unchanged if usable, or null if it is empty/whitespace-only
+ * (dropped consistently in every environment - an empty tag matches nothing).
+ *
+ * Backend-specific constraints are intentionally NOT enforced here so the tag
+ * primitive stays backend-agnostic. In particular, the CFCacheStore
+ * encodeURIComponent's tags at serialization time so commas/spaces/non-Latin1
+ * characters cannot corrupt the comma-delimited Cloudflare Cache-Tag header or
+ * the HTTP marker header (it does not reject them). Keep tags short and
+ * low-cardinality: a tag's KV marker key must stay under Cloudflare's 512-byte
+ * limit, and a Cache-Tag value under 1024 bytes. The in-memory store has no
+ * such limitations.
+ *
+ * @internal
+ */
+export function normalizeTag(tag: string): string | null {
+  if (!tag || !tag.trim()) return null;
+  return tag;
+}
+
+/**
+ * Normalize a tag collection: drop empty/whitespace-only tags so the WRITE path
+ * matches the invalidate path (updateTag/revalidateTag/cacheTag all normalize).
+ * Does not deduplicate - callers that need that wrap with a Set.
+ *
+ * @internal
+ */
+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);
+  }
+}
+
+/**
+ * Record `tags` into the request-scoped tag set (ctx._requestTags), the union of
+ * every cache tag resolved while producing the response. The document cache reads
+ * this after the render settles so a full-page entry is tagged with everything its
+ * content used, making it invalidatable by updateTag()/revalidateTag().
+ *
+ * Called at the tag-resolution sites: "use cache" stores (cache-runtime, both the
+ * miss and read/hit paths), loader cache (cache-policy/loader-cache), and segment
+ * cache() (cache-scope). Writes the field directly (not via ctx.set()) so it does
+ * not trip the cache-scope side-effect guard, mirroring cacheTag() itself.
+ *
+ * @internal
+ */
+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 };
+}