@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/src/cache/cache-policy.ts

@@ -9,6 +9,8 @@
 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";
+import { reportCacheError } from "./cache-error.js";
 
 /**
  * Default TTL for route-level cache() DSL and loader cache.
@@ -22,31 +24,62 @@ export const DEFAULT_ROUTE_TTL = 60;
  */
 export const DEFAULT_FUNCTION_TTL = 900;
 
+/**
+ * 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.
+ * Shared with cache-scope.ts (the segment getters) so every cache path validates
+ * the same way. profile-registry.ts uses the same predicate but fails fast at
+ * config time; the resolvers here degrade because they run on the live path.
+ */
+export function isFiniteNonNegativeSeconds(value: number): boolean {
+  return Number.isFinite(value) && value >= 0;
+}
+
+function warnInvalidSeconds(label: string, value: number): void {
+  if (process.env.NODE_ENV !== "production") {
+    console.warn(`[cache] Invalid ${label} ${value}; falling back to default`);
+  }
+}
+
 /**
  * Resolve effective TTL from the 3-tier cascade:
- * explicit → store defaults → fallback.
+ * explicit → store defaults → fallback. A non-finite/negative resolved value
+ * degrades to the fallback (loader cache and "use cache" setItem both resolve
+ * ttl here, so this is where those paths are guarded; the segment cache is
+ * guarded in cache-scope.ts).
  */
 export function resolveTtl(
   explicit: number | undefined,
   defaults: CacheDefaults | undefined,
   fallback: number,
 ): number {
-  if (explicit !== undefined) return explicit;
-  if (defaults?.ttl !== undefined) return defaults.ttl;
+  let value: number;
+  if (explicit !== undefined) value = explicit;
+  else if (defaults?.ttl !== undefined) value = defaults.ttl;
+  else return fallback;
+  if (isFiniteNonNegativeSeconds(value)) return value;
+  warnInvalidSeconds("ttl", value);
   return fallback;
 }
 
 /**
  * Resolve effective SWR window from the 2-tier cascade:
  * explicit → store defaults.
- * Returns 0 when unset (no SWR window).
+ * Returns 0 when unset (no SWR window) or when the resolved value is
+ * non-finite/negative (degrade rather than feed bad math into expiry).
  */
 export function resolveSwrWindow(
   explicit: number | undefined,
   defaults: CacheDefaults | undefined,
 ): number {
-  if (explicit !== undefined) return explicit;
-  if (defaults?.swr !== undefined) return defaults.swr;
+  let value: number;
+  if (explicit !== undefined) value = explicit;
+  else if (defaults?.swr !== undefined) value = defaults.swr;
+  else return 0;
+  if (isFiniteNonNegativeSeconds(value)) return value;
+  warnInvalidSeconds("swr", value);
   return 0;
 }
 
@@ -68,24 +101,6 @@ export function computeExpiration(
   return { staleAt, expiresAt };
 }
 
-// ============================================================================
-// Cache Key Resolution
-// ============================================================================
-
-/**
- * Resolve cache key using the 3-tier priority:
- * 1. keyFn (full override from route/loader cache options)
- * 2. store.keyGenerator (modifies default key)
- * 3. defaultKey (used when neither keyFn nor keyGenerator is provided)
- *
- * Errors from keyFn and store.keyGenerator propagate to the caller.
- * Cache identity is correctness-critical: if explicit key logic throws,
- * silently remapping to a different key could cause cache collisions or
- * serve stale/wrong data. Callers must handle the error or let it surface.
- *
- * Uses _getRequestContext (non-throwing) so that calls outside ALS
- * (e.g. build-time) gracefully fall back to defaultKey.
- */
 export async function resolveCacheKey(
   keyFn: ((ctx: RequestContext) => string | Promise<string>) | undefined,
   store: SegmentCacheStore | null,
@@ -94,32 +109,91 @@ export async function resolveCacheKey(
 ): Promise<string> {
   const requestCtx = _getRequestContext();
 
-  // Priority 1: Route/loader-level key function (full override)
   if (keyFn && requestCtx) {
     return await keyFn(requestCtx);
   }
 
-  // Priority 2: Store-level keyGenerator (modifies default key)
   if (store?.keyGenerator && requestCtx) {
     return await store.keyGenerator(requestCtx, defaultKey);
   }
 
-  // Priority 3: Default key (no custom key logic provided)
   return defaultKey;
 }
 
-// ============================================================================
-// Cache Store Resolution
-// ============================================================================
+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) {
+      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) {
+      reportCacheError(
+        error,
+        "cache-write",
+        `[${label}] Tags function failed, caching without tags`,
+        ctx,
+      );
+      return undefined;
+    }
+  }
+  return normalizeTagList(tags);
+}
 
 /**
- * Resolve cache store from the 2-tier priority:
- * 1. Explicit store from cache options
- * 2. App-level store from request context
+ * 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;
+}
+
 export function resolveCacheStore(
   explicitStore: SegmentCacheStore | undefined,
 ): SegmentCacheStore | null {
-  if (explicitStore) return explicitStore;
+  if (explicitStore) {
+    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);
+  }
+}