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

package/src/cache/cache-error.ts

@@ -0,0 +1,104 @@
+/**
+ * Cache error reporting.
+ *
+ * Caches are best-effort: a read failure degrades to a miss (render fresh) and a
+ * write failure degrades to a no-op - they MUST NOT throw up and fail the
+ * request. But the failure must still be LOUD: it is logged to the console (so
+ * it is visible even in a background waitUntil task or when no hook is wired)
+ * AND routed through the router's onError callback (via the request context's
+ * deduped _reportBackgroundError) so consumers can observe cache degradation in
+ * their own telemetry.
+ *
+ * The one deliberate exception is the invalidation WRITE verb (updateTag ->
+ * store.invalidateTags): a failed durable marker write is rejected so an awaited
+ * updateTag() surfaces it (read-your-own-writes honesty). That is not a data
+ * read/write and does not go through this helper's swallow-and-degrade path.
+ */
+
+import { _getRequestContext } from "../server/request-context.js";
+
+/**
+ * Minimal shape of a request context for error reporting. Passed explicitly by
+ * background tasks (waitUntil) where the ALS context is already gone, so the
+ * error can still reach the router's onError. Structural to avoid importing the
+ * full RequestContext type (request-context.ts imports CacheErrorCategory from
+ * here - a mutual type-only reference).
+ */
+export interface CacheErrorReporter {
+  _reportBackgroundError?: (
+    error: unknown,
+    category: CacheErrorCategory,
+  ) => void;
+}
+
+export type CacheErrorCategory =
+  /** A read failed (transient infra: KV/Cache API error). Degrade to a miss. */
+  | "cache-read"
+  /** A write failed. Degrade to a no-op (entry simply not cached). */
+  | "cache-write"
+  /** A delete/eviction failed. Best-effort. */
+  | "cache-delete"
+  /**
+   * A STORED entry could not be parsed/deserialized (partial KV read, truncated
+   * Cache API body, malformed envelope/RSC payload). The entry is faulty and is
+   * evicted so subsequent reads do not keep failing on it. Distinct from
+   * cache-read so consumers can tell corruption from a transient outage.
+   */
+  | "cache-corrupt"
+  /** A tag-invalidation side effect failed (e.g. the eager CDN purge hook). */
+  | "cache-invalidate"
+  /**
+   * A background stale-while-revalidate refresh failed (the `"use cache"`
+   * read-through path). The stale value was already served; the refresh that
+   * would have replaced it errored.
+   */
+  | "stale-revalidation";
+
+/**
+ * Report a non-fatal cache error loudly without failing the request: always logs
+ * (label + error) and, when a request context is available, routes the error
+ * through the router's onError callback. Never throws.
+ *
+ * `ctx` is for callers running in a detached background task (waitUntil), where
+ * the ALS request context is already gone (so `_getRequestContext()` is null):
+ * they capture the context up front and pass it here so onError still fires.
+ * Foreground callers omit it and fall back to the ALS context.
+ */
+export function reportCacheError(
+  error: unknown,
+  category: CacheErrorCategory,
+  label: string,
+  ctx?: CacheErrorReporter,
+): void {
+  console.error(`${label}:`, error);
+  try {
+    const target = ctx ?? _getRequestContext();
+    target?._reportBackgroundError?.(error, category);
+  } catch {
+    // Reporting must never itself break the cache path.
+  }
+}
+
+/**
+ * Run a best-effort async cache task (typically scheduled via waitUntil), catching
+ * any rejection and routing it through reportCacheError so background cache work
+ * (non-blocking L1 writes, KV persistence, L1 promotion) reports failures via
+ * onError instead of throwing or silently swallowing. Never rejects.
+ *
+ * Pass `ctx` when the task runs detached (the ALS context is gone) and the
+ * failure should still reach onError; omit it to fall back to the ALS context.
+ *
+ * @example this.waitUntil(() => reportingAsync(() => cache.put(req, res), "cache-write", "[CFCacheStore] L1 write"))
+ */
+export async function reportingAsync(
+  task: () => Promise<unknown>,
+  category: CacheErrorCategory,
+  label: string,
+  ctx?: CacheErrorReporter,
+): Promise<void> {
+  try {
+    await task();
+  } catch (error) {
+    reportCacheError(error, category, label, ctx);
+  }
+}

package/src/cache/cache-key-utils.ts

@@ -6,24 +6,45 @@
  * document-cache, and loader-cache.
  */
 
+import { encodeKV } from "../encode-kv.js";
+
+/**
+ * Reserved URL query params that the router owns and must never key the cache
+ * on. `_rsc*` is the router's internal navigation/action/loader prefix (matched
+ * by prefix). `__no_cache` is the single `__`-prefixed param the router reads
+ * (handler.ts / testing dispatch.ts use it to bypass the store); it and the
+ * other router-internal `__`-prefixed request params are matched by an EXACT
+ * allowlist, not a blanket `__` prefix. A blanket `__` filter would silently
+ * collapse consumer params like `__variant=a` vs `__variant=b` onto one cache
+ * slot; an allowlist keeps the router's own params out of the key while leaving
+ * consumer `__` params intact.
+ */
+const RESERVED_SEARCH_PARAMS = new Set([
+  "__no_cache",
+  "__rsc",
+  "__html",
+  "__debug_manifest",
+  "__prerender_collect",
+]);
+
+function isReservedSearchParam(key: string): boolean {
+  return key.startsWith("_rsc") || RESERVED_SEARCH_PARAMS.has(key);
+}
+
 /**
  * Build a sorted, deterministic query string from URLSearchParams,
- * excluding internal _rsc* and __* params.
+ * excluding the router's reserved params (see isReservedSearchParam).
  *
  * Returns empty string when no user-facing params exist.
  */
 export function sortedSearchString(searchParams: URLSearchParams): string {
   const pairs: [string, string][] = [];
   for (const [k, v] of searchParams) {
-    if (!k.startsWith("_rsc") && !k.startsWith("__")) {
+    if (!isReservedSearchParam(k)) {
       pairs.push([k, v]);
     }
   }
-  if (pairs.length === 0) return "";
-  pairs.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-  return pairs
-    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
-    .join("&");
+  return encodeKV(pairs, { sort: true });
 }
 
 /**
@@ -35,10 +56,5 @@ export function sortedRouteParams(
   params: Record<string, string> | undefined,
 ): string {
   if (!params) return "";
-  const entries = Object.entries(params);
-  if (entries.length === 0) return "";
-  return entries
-    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
-    .join("&");
+  return encodeKV(Object.entries(params), { sort: true });
 }

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);
+  }
+}