@rangojs/router 0.0.0-experimental.121 → 0.0.0-experimental.124

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,
@@ -28,7 +30,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) {
@@ -253,8 +271,32 @@ 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;
+      }
+
+      // 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. An empty string means the route pushed no handles —
       // skip the decode entirely (the common case). Otherwise decode the
@@ -279,7 +321,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;
     }
   }
@@ -322,6 +364,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");
 
@@ -390,6 +436,7 @@ export class CacheScope {
           segments: serializedSegments,
           handles: encodedHandles,
           expiresAt: Date.now() + ttl * 1000,
+          tags,
         };
 
         if (INTERNAL_RANGO_DEBUG) {
@@ -407,7 +454,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 };
+}