@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/src/cache/tag-aware-handler.ts

@@ -0,0 +1,237 @@
+/**
+ * TagAwareCacheHandler — wraps any CacheStore and adds tag-based invalidation.
+ *
+ * Three strategies, selected by store capabilities (best available wins):
+ *
+ * 1. **Native** (store has setWithTags + invalidateTag): Delegates entirely.
+ *    The store owns tag indexing. Used for Vercel Runtime Cache, DO-backed
+ *    stores, or any platform with first-class tag support.
+ *
+ * 2. **Eager** (store has sadd/smembers/srem/sdel): Maintains an inverted
+ *    index via atomic set operations. Invalidation enumerates the set and
+ *    deletes entries. Used for Redis.
+ *
+ * 3. **Lazy** (bare get/set/del only): Version-stamps entries with tag
+ *    counters. Invalidation bumps a counter (O(1)). Reads validate stored
+ *    versions against current. Race-free, correct under eventual consistency.
+ *    Used for Cloudflare KV.
+ *
+ * Implements the CacheHandler interface consumed by timber-cache.ts.
+ */
+
+import type { CacheHandler } from './index';
+import type { CacheStore } from './store';
+
+const DATA_PREFIX = 'd:';
+const TAG_SET_PREFIX = 'ts:';
+const TAG_VERSION_PREFIX = 'tv:';
+
+type Strategy = 'native' | 'eager' | 'lazy';
+
+/** Stored entry format for eager strategy. */
+interface EagerEntry {
+  value: unknown;
+  expiresAt: number;
+  tags: string[];
+}
+
+/** Stored entry format for lazy (version-stamp) strategy. */
+interface LazyEntry {
+  value: unknown;
+  expiresAt: number;
+  tags: string[];
+  tagVersions: Record<string, number>;
+}
+
+function detectStrategy(store: CacheStore): Strategy {
+  if (store.setWithTags && store.invalidateTag) return 'native';
+  if (store.sadd && store.smembers && store.srem && store.sdel) return 'eager';
+  return 'lazy';
+}
+
+export class TagAwareCacheHandler implements CacheHandler {
+  private store: CacheStore;
+  private prefix: string;
+  private strategy: Strategy;
+
+  constructor(store: CacheStore, opts?: { prefix?: string }) {
+    this.store = store;
+    this.prefix = opts?.prefix ?? 'timber:';
+    this.strategy = detectStrategy(store);
+  }
+
+  get consistency(): 'strong' | 'eventual' | 'local' {
+    return this.store.consistency;
+  }
+
+  private dataKey(key: string): string {
+    return `${this.prefix}${DATA_PREFIX}${key}`;
+  }
+
+  /** Namespace tags for native stores so prefix isolates shared stores. */
+  private prefixTags(tags: string[]): string[] {
+    return tags.map((t) => `${this.prefix}${t}`);
+  }
+
+  private tagSetKey(tag: string): string {
+    return `${this.prefix}${TAG_SET_PREFIX}${tag}`;
+  }
+
+  private tagVersionKey(tag: string): string {
+    return `${this.prefix}${TAG_VERSION_PREFIX}${tag}`;
+  }
+
+  async get(key: string): Promise<{ value: unknown; stale: boolean } | null> {
+    const raw = await this.store.get(this.dataKey(key));
+    if (raw === null) return null;
+
+    if (this.strategy === 'native' || this.strategy === 'eager') {
+      const entry = JSON.parse(raw) as EagerEntry;
+      const stale = Date.now() > entry.expiresAt;
+      return { value: entry.value, stale };
+    }
+
+    // Lazy: validate tag versions before returning
+    const entry = JSON.parse(raw) as LazyEntry;
+    if (entry.tags.length > 0) {
+      const currentVersions = await this.getTagVersions(entry.tags);
+      for (const tag of entry.tags) {
+        const stored = entry.tagVersions[tag] ?? 0;
+        const current = currentVersions[tag] ?? 0;
+        if (current > stored) return null;
+      }
+    }
+    const stale = Date.now() > entry.expiresAt;
+    return { value: entry.value, stale };
+  }
+
+  async set(
+    key: string,
+    value: unknown,
+    opts: { ttl: number; tags: string[]; generation?: number }
+  ): Promise<void> {
+    const physicalTtl = Math.max(opts.ttl * 2 + 60, 120);
+
+    if (this.strategy === 'native') {
+      const entry: EagerEntry = {
+        value,
+        expiresAt: Date.now() + opts.ttl * 1000,
+        tags: opts.tags,
+      };
+      const payload = JSON.stringify(entry);
+      if (opts.tags.length > 0) {
+        await this.store.setWithTags!(
+          this.dataKey(key),
+          payload,
+          physicalTtl,
+          this.prefixTags(opts.tags)
+        );
+      } else {
+        await this.store.set(this.dataKey(key), payload, physicalTtl);
+      }
+      return;
+    }
+
+    if (this.strategy === 'eager') {
+      const entry: EagerEntry = {
+        value,
+        expiresAt: Date.now() + opts.ttl * 1000,
+        tags: opts.tags,
+      };
+      await this.store.set(this.dataKey(key), JSON.stringify(entry), physicalTtl);
+      if (opts.tags.length > 0) {
+        await Promise.all(
+          opts.tags.map((tag) => this.store.sadd!(this.tagSetKey(tag), [key], physicalTtl))
+        );
+      }
+      return;
+    }
+
+    // Lazy: snapshot current tag versions into the entry
+    const tagVersions = opts.tags.length > 0 ? await this.getTagVersions(opts.tags) : {};
+    const entry: LazyEntry = {
+      value,
+      expiresAt: Date.now() + opts.ttl * 1000,
+      tags: opts.tags,
+      tagVersions,
+    };
+    await this.store.set(this.dataKey(key), JSON.stringify(entry), physicalTtl);
+  }
+
+  async invalidate(opts: { key?: string; tag?: string }): Promise<void> {
+    if (opts.key) {
+      if (this.strategy === 'eager') {
+        const raw = await this.store.get(this.dataKey(opts.key));
+        if (raw !== null) {
+          const entry = JSON.parse(raw) as EagerEntry;
+          if (entry.tags.length > 0) {
+            await Promise.all(
+              entry.tags.map((tag) => this.store.srem!(this.tagSetKey(tag), [opts.key!]))
+            );
+          }
+        }
+      }
+      await this.store.del(this.dataKey(opts.key));
+    }
+
+    if (opts.tag) {
+      const tag = opts.tag;
+      if (this.strategy === 'native') {
+        await this.store.invalidateTag!(`${this.prefix}${tag}`);
+      } else if (this.strategy === 'eager') {
+        const members = await this.store.smembers!(this.tagSetKey(tag));
+        // Verify each member still carries the tag before deleting — the set
+        // can contain stale memberships from overwritten entries or LRU eviction.
+        // Remove only the snapshot members (via srem, not sdel) so concurrent
+        // writes that add new members between smembers() and cleanup are preserved.
+        await Promise.all(
+          members.map(async (k) => {
+            const raw = await this.store.get(this.dataKey(k));
+            if (raw === null) {
+              await this.store.srem!(this.tagSetKey(tag), [k]);
+              return;
+            }
+            const entry = JSON.parse(raw) as EagerEntry;
+            if (entry.tags.includes(tag)) {
+              await this.store.del(this.dataKey(k));
+              await this.store.srem!(this.tagSetKey(tag), [k]);
+            } else {
+              await this.store.srem!(this.tagSetKey(tag), [k]);
+            }
+          })
+        );
+      } else {
+        await this.bumpTagVersion(opts.tag);
+      }
+    }
+  }
+
+  // --- Lazy strategy helpers ---
+
+  private async getTagVersions(tags: string[]): Promise<Record<string, number>> {
+    const versions: Record<string, number> = {};
+    await Promise.all(
+      tags.map(async (tag) => {
+        const raw = await this.store.get(this.tagVersionKey(tag));
+        versions[tag] = raw !== null ? parseInt(raw, 10) : 0;
+      })
+    );
+    return versions;
+  }
+
+  private async bumpTagVersion(tag: string): Promise<void> {
+    const key = this.tagVersionKey(tag);
+    const raw = await this.store.get(key);
+    const stored = raw !== null ? parseInt(raw, 10) : 0;
+    // max(stored, now) + 1: strictly advancing even within the same
+    // millisecond (two bumps in 1ms produce N, N+1 not N, N). On
+    // eventually-consistent stores the read can be stale, but Date.now()
+    // provides a floor — regression only if BOTH the read is stale AND the
+    // clock is behind, bounded by the store's propagation window (~60s).
+    const version = Math.max(stored, Date.now()) + 1;
+    // Version keys must outlive all data entries stamped with them. Data
+    // entries use physical TTL of max(ttl*2+60, 120); 365 days exceeds any
+    // practical cache lifetime.
+    await this.store.set(key, String(version), 365 * 86400);
+  }
+}

package/src/cache/timber-cache.ts

@@ -1,10 +1,43 @@
 import type { CacheHandler, CacheOptions } from './index';
 import { stableStringify } from './stable-stringify';
 import { createSingleflight } from './singleflight';
-import { addSpanEventSync } from '#/server/tracing.js';
+import {
+  currentInvalidationEpoch,
+  lastInvalidationEpochFor,
+  wasInvalidatedSince,
+} from './invalidation-epoch';
+import { addSpanEventSync } from '../server/tracing.js';
+import { logSwrRefetchFailed, swallow } from '../server/logger.js';
+import { getWaitUntil } from '../server/waituntil-bridge.js';
 import { fnv1aHash } from './fast-hash.js';
 
-const singleflight = createSingleflight();
+let defaultSingleflight = createSingleflight();
+
+/**
+ * Per-key monotonic generation counter for CAS writes (TIM-1158).
+ *
+ * Unbounded, like the singleflight map — the key space is the same set of
+ * cache keys the handler already tracks. Pruning was removed because it
+ * desyncs from MemoryCacheHandler.generations: a pruned key restarts at 1
+ * while the handler still holds the old higher generation, causing fresh
+ * writes to be rejected as stale.
+ */
+const writeGenerations = new Map<string, number>();
+function nextGeneration(key: string): number {
+  const gen = (writeGenerations.get(key) ?? 0) + 1;
+  writeGenerations.set(key, gen);
+  return gen;
+}
+
+/**
+ * Set the timeout for the module-level default singleflight.
+ * Called at framework boot with renderTimeoutMs from timber.config.ts so that
+ * cache calls without a per-call timeoutMs still get deadlock protection.
+ * See design/06-caching.md §"Singleflight Timeout — Deadlock Risk".
+ */
+export function setDefaultSingleflightTimeout(timeoutMs: number): void {
+  defaultSingleflight = createSingleflight({ timeoutMs });
+}
 
 /**
  * Generate a cache key from function identity and serialized args.
@@ -33,17 +66,62 @@ function resolveTags<Fn extends (...args: any[]) => any>(
   return opts.tags(...args);
 }
 
-// Counter for generating unique function IDs when no explicit key is provided.
-let fnIdCounter = 0;
+/** Per-process count of byte-identical fn sources seen by deriveFallbackFnId. */
+const fallbackIdOccurrences = new Map<string, number>();
+let hasWarnedFallbackId = false;
+
+/**
+ * Derive a fallback fnId for callsites the timber-cache-transform Vite plugin
+ * could not statically detect (aliased bindings, user re-export wrappers).
+ *
+ * The base is fnv1a(fn.toString()) — deterministic across instances and cold
+ * starts of the same build, so two *different* functions can never swap fnIds
+ * by module-evaluation order (the TIM-997 poisoning scenario that the old
+ * process-local counter allowed; see TIM-1054). A per-process occurrence
+ * suffix disambiguates byte-identical duplicate sources. That residue is the
+ * one remaining hazard: closures produced by the same factory share source
+ * text but capture different values, and their occurrence order may differ
+ * across instances — such callsites need an explicit `key` option.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function deriveFallbackFnId(fn: (...args: any[]) => any): string {
+  const sourceHash = fnv1aHash(fn.toString());
+  const occurrence = fallbackIdOccurrences.get(sourceHash) ?? 0;
+  fallbackIdOccurrences.set(sourceHash, occurrence + 1);
+
+  if (!hasWarnedFallbackId && typeof process !== 'undefined' && process.env?.NODE_ENV !== 'test') {
+    hasWarnedFallbackId = true;
+    console.warn(
+      '[timber] cache() callsite has no build-time stable ID and no explicit `key` option — ' +
+        'the call is not statically visible to the timber Vite plugin (e.g. an aliased ' +
+        'binding like `const c = cache` or a re-export wrapper module). Falling back to a ' +
+        'function-source hash for the cache key. With a shared CacheHandler (Redis/KV) this ' +
+        'is safe for distinct functions, but byte-identical closures from a factory can swap ' +
+        'cache entries across instances. Provide an explicit `key` option to make the cache ' +
+        'key contract stable and auditable.'
+    );
+  }
+
+  return `timber-cache:fn:${sourceHash}:${occurrence}`;
+}
 
 /**
  * Creates a cached wrapper around an async function.
  *
- * - SHA-256 default keys with normalized JSON args
- * - Singleflight: concurrent misses → single execution
+ * - FNV-1a default keys with normalized JSON args
+ * - Singleflight: concurrent misses → single execution AND single
+ *   handler.set — the write happens inside the coalesced callback (TIM-1028)
+ * - Writes are skipped when the key/tags were invalidated while fn was in
+ *   flight, so explicit invalidation is never silently undone (TIM-1028)
  * - SWR: serve stale immediately, background refetch
  * - Tags as string[] or function of args
- * - No ALS dependency
+ * - The handler is resolved per invocation via `getHandler`, never captured
+ *   at wrapper-creation time — module-scope cache() wrappers created before
+ *   the framework's boot wiring calls setCacheHandler() still use the
+ *   configured handler once it arrives (TIM-1029)
+ * - No ALS dependency for correctness — cache() works outside a request
+ *   context. The waitUntil ALS bridge is read optionally so the SWR
+ *   background refetch survives handler return on Workers/Lambda.
  *
  * Cache hits/misses are recorded as OTEL span events on the enclosing
  * span (not child spans). The DevSpanProcessor reads these for dev log output.
@@ -52,15 +130,30 @@ let fnIdCounter = 0;
 export function createCache<Fn extends (...args: any[]) => Promise<any>>(
   fn: Fn,
   opts: CacheOptions<Fn>,
-  handler: CacheHandler
-): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>> {
-  const fnId = `timber-cache:${fnIdCounter++}`;
+  getHandler: () => CacheHandler,
+  stableId?: string
+): Fn {
+  // With an explicit `key` option the fnId never reaches key generation, so
+  // no fallback derivation (or warning) is needed in that case.
+  const fnId = stableId ?? (opts.key ? undefined : deriveFallbackFnId(fn));
+
+  // Per-call timeoutMs gets a dedicated singleflight instance. Otherwise
+  // resolve defaultSingleflight per invocation (not captured at creation
+  // time) so wrappers created before boot pick up the timeout once
+  // setDefaultSingleflightTimeout is called (TIM-1032, same rationale as
+  // getCacheHandler for TIM-1029).
+  const perCallSf =
+    opts.timeoutMs !== undefined ? createSingleflight({ timeoutMs: opts.timeoutMs }) : undefined;
 
-  return async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {
-    const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId, args);
+  // Cast to Fn to preserve the original function's generic call signature.
+  // Without this, generic type parameters (e.g. <T> in apiFetch<T>) are
+  // erased and callers lose type safety on the return type.
+  return (async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {
+    const sf = perCallSf ?? defaultSingleflight;
+    const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId as string, args);
 
     const cacheStart = performance.now();
-    const cached = await handler.get(key);
+    const cached = await getHandler().get(key);
 
     if (cached && !cached.stale) {
       // Record as OTEL span event on enclosing span (not a child span).
@@ -72,6 +165,43 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
       return cached.value as Awaited<ReturnType<Fn>>;
     }
 
+    // From here fn() will execute (SWR refetch or miss). Scope the
+    // singleflight key by the last invalidation epoch affecting this
+    // key/tags: a caller arriving after an invalidation must not coalesce
+    // onto a flight that started before it — it would receive the
+    // pre-invalidation result the invalidation was issued to discard.
+    // NUL separator: cannot collide with user-provided key strings.
+    const tags = resolveTags(opts, args);
+    const flightKey = `${key}\u0000${lastInvalidationEpochFor(key, tags)}`;
+
+    /**
+     * Run fn and store the result — exactly once per coalesced execution,
+     * inside the singleflight callback. The write is skipped when:
+     * - the key/tags were invalidated after fn started (TIM-1028), or
+     * - the singleflight timed out (signal aborted) — the timed-out
+     *   flight's write could overwrite a newer value from a subsequent
+     *   flight (TIM-1092), or
+     * - the handler rejects the write because a newer generation has
+     *   already been stored (TIM-1158 CAS guard).
+     */
+    const executeAndStore = async (signal: AbortSignal): Promise<Awaited<ReturnType<Fn>>> => {
+      const startEpoch = currentInvalidationEpoch();
+      const generation = nextGeneration(key);
+      const result = await fn(...args);
+      if (!signal.aborted && !wasInvalidatedSince(startEpoch, key, tags)) {
+        try {
+          await getHandler().set(key, result, { ttl: opts.ttl, tags, generation });
+        } catch (err) {
+          // Cache-write failure must not fail the request (TIM-1046).
+          // JSON-serializing handlers (Redis, KV) throw on BigInt; network
+          // errors can surface from any shared handler. The result is valid
+          // — serve it uncached rather than rejecting a successful fn().
+          swallow(err, `cache set failed for key "${key}"`);
+        }
+      }
+      return result;
+    };
+
     if (cached && cached.stale && opts.staleWhileRevalidate) {
       // Record stale cache hit as OTEL span event (fire-and-forget).
       addSpanEventSync('timber.cache.hit', {
@@ -80,27 +210,32 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
         stale: true,
       });
       // Serve stale immediately, trigger background refetch
-      singleflight
-        .do(`swr:${key}`, async () => {
+      const refetch = sf
+        .do(`swr:${flightKey}`, async (signal) => {
           try {
-            const fresh = await fn(...args);
-            const tags = resolveTags(opts, args);
-            await handler.set(key, fresh, { ttl: opts.ttl, tags });
-          } catch {
+            await executeAndStore(signal);
+          } catch (err) {
             // Failed refetch — stale entry continues to be served.
-            // Error is swallowed per design doc: "Error is logged."
+            logSwrRefetchFailed({ cacheKey: key, error: err });
           }
         })
         .catch(() => {
           // Singleflight promise rejection handled — stale continues.
         });
+      // Platforms that cancel work when the handler returns (Cloudflare
+      // Workers, Lambda) would otherwise kill the refetch mid-flight —
+      // stale data re-served forever. Register the (never-rejecting)
+      // refetch with the request's waitUntil; undefined outside a request
+      // context or on platforms without lifecycle extension (Node servers
+      // keep floating promises alive, so behavior there is unchanged).
+      getWaitUntil()?.(refetch);
       return cached.value as Awaited<ReturnType<Fn>>;
     }
 
-    // Cache miss (or stale without SWR) — execute with singleflight
-    const result = await singleflight.do(key, () => fn(...args));
-    const tags = resolveTags(opts, args);
-    await handler.set(key, result, { ttl: opts.ttl, tags });
+    // Cache miss (or stale without SWR) — execute with singleflight.
+    // The handler.set lives inside the coalesced callback, so N concurrent
+    // misses produce exactly one write (TIM-1028).
+    const result = await sf.do(flightKey, executeAndStore);
 
     // Record cache miss as OTEL span event (fire-and-forget).
     addSpanEventSync('timber.cache.miss', {
@@ -108,16 +243,6 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
       duration_ms: Math.round(performance.now() - cacheStart),
     });
 
-    return result as Awaited<ReturnType<Fn>>;
-  };
+    return result;
+  }) as unknown as Fn;
 }
-
-/**
- * Invalidate cache entries by tag or key.
- */
-createCache.invalidate = async function invalidate(
-  handler: CacheHandler,
-  opts: { key?: string; tag?: string }
-): Promise<void> {
-  await handler.invalidate(opts);
-};

package/src/cdn/cloudflare-purge.ts

@@ -0,0 +1,50 @@
+/**
+ * Cloudflare CDN purge handler — purges by cache tag via the Cloudflare API.
+ *
+ * Requires Cloudflare Enterprise for tag-based purging.
+ * See https://developers.cloudflare.com/cache/how-to/purge-cache/purge-by-tags/
+ */
+
+import type { CdnPurgeHandler } from './purge-store';
+
+export interface CloudflarePurgeOptions {
+  /** Cloudflare zone ID. */
+  zoneId: string;
+  /** API token with Cache Purge permission. */
+  apiToken: string;
+  /** Override fetch for testing. */
+  fetch?: typeof globalThis.fetch;
+}
+
+export class CloudflarePurge implements CdnPurgeHandler {
+  private readonly zoneId: string;
+  private readonly apiToken: string;
+  private readonly _fetch: typeof globalThis.fetch;
+
+  constructor(opts: CloudflarePurgeOptions) {
+    this.zoneId = opts.zoneId;
+    this.apiToken = opts.apiToken;
+    this._fetch = opts.fetch ?? globalThis.fetch;
+  }
+
+  async purgeTags(tags: string[]): Promise<void> {
+    if (tags.length === 0) return;
+
+    const res = await this._fetch(
+      `https://api.cloudflare.com/client/v4/zones/${this.zoneId}/purge_cache`,
+      {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${this.apiToken}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ tags }),
+      }
+    );
+
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`Cloudflare purge failed (${res.status}): ${body}`);
+    }
+  }
+}

package/src/cdn/fastly-purge.ts

@@ -0,0 +1,63 @@
+/**
+ * Fastly CDN purge handler — purges by surrogate key via the Fastly API.
+ *
+ * See https://www.fastly.com/documentation/reference/api/purging/
+ */
+
+import type { CdnPurgeHandler } from './purge-store';
+
+export interface FastlyPurgeOptions {
+  /** Fastly service ID. */
+  serviceId: string;
+  /** Fastly API token with purge permission. */
+  apiToken: string;
+  /** Use soft purge (marks as stale instead of immediate delete). Default: false. */
+  softPurge?: boolean;
+  /** Override fetch for testing. */
+  fetch?: typeof globalThis.fetch;
+}
+
+export class FastlyPurge implements CdnPurgeHandler {
+  private readonly serviceId: string;
+  private readonly apiToken: string;
+  private readonly softPurge: boolean;
+  private readonly _fetch: typeof globalThis.fetch;
+
+  constructor(opts: FastlyPurgeOptions) {
+    this.serviceId = opts.serviceId;
+    this.apiToken = opts.apiToken;
+    this.softPurge = opts.softPurge ?? false;
+    this._fetch = opts.fetch ?? globalThis.fetch;
+  }
+
+  async purgeTags(tags: string[]): Promise<void> {
+    if (tags.length === 0) return;
+
+    const results = await Promise.allSettled(
+      tags.map((tag) =>
+        this._fetch(
+          `https://api.fastly.com/service/${this.serviceId}/purge/${encodeURIComponent(tag)}`,
+          {
+            method: 'POST',
+            headers: {
+              'Fastly-Key': this.apiToken,
+              ...(this.softPurge ? { 'Fastly-Soft-Purge': '1' } : {}),
+            },
+          }
+        ).then(async (res) => {
+          if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`Fastly purge failed for tag "${tag}" (${res.status}): ${body}`);
+          }
+        })
+      )
+    );
+
+    const failures = results.filter((r): r is PromiseRejectedResult => r.status === 'rejected');
+    if (failures.length > 0) {
+      throw new Error(
+        `Fastly purge failed for ${failures.length}/${tags.length} tags: ${failures.map((f) => f.reason?.message).join('; ')}`
+      );
+    }
+  }
+}