@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/src/cache/timber-cache.ts

@@ -1,17 +1,56 @@
-import { createHash } from 'node:crypto';
-import type { CacheHandler, CacheOptions } from './index';
-import { stableStringify } from './stable-stringify';
-import { createSingleflight } from './singleflight';
-import { addSpanEvent } from '#/server/tracing.js';
+import type { CacheHandler, CacheOptions } from './index.ts';
+import { stableStringify } from './stable-stringify.ts';
+import { createSingleflight } from './singleflight.ts';
+import {
+  currentInvalidationEpoch,
+  lastInvalidationEpochFor,
+  wasInvalidatedSince,
+} from './invalidation-epoch.ts';
+import { addSpanEventSync } from '../server/tracing.ts';
+import { logSwrRefetchFailed, swallow } from '../server/logger.ts';
+import { getWaitUntil } from '../server/waituntil-bridge.ts';
+import { fnv1aHash } from './fast-hash.ts';
 
-const singleflight = createSingleflight();
+let defaultSingleflight = createSingleflight();
 
 /**
- * Generate a SHA-256 cache key from function identity and serialized args.
+ * 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.
+ *
+ * Uses FNV-1a (fast non-crypto hash) instead of SHA-256. Cache keys don't
+ * need collision resistance — they need speed. The fnId prefix provides
+ * namespace isolation; the hash covers the args.
+ *
+ * See TIM-370 for perf motivation.
  */
 function defaultKeyGenerator(fnId: string, args: unknown[]): string {
   const raw = fnId + ':' + stableStringify(args);
-  return createHash('sha256').update(raw).digest('hex');
+  return fnId + ':' + fnv1aHash(raw);
 }
 
 /**
@@ -27,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.
@@ -46,71 +130,119 @@ 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)
-      await addSpanEvent('timber.cache.hit', {
+      // Record as OTEL span event on enclosing span (not a child span).
+      // Fire-and-forget — no microtask overhead on the cache hot path.
+      addSpanEventSync('timber.cache.hit', {
         key,
         duration_ms: Math.round(performance.now() - cacheStart),
       });
       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
-      await addSpanEvent('timber.cache.hit', {
+      // Record stale cache hit as OTEL span event (fire-and-forget).
+      addSpanEventSync('timber.cache.hit', {
         key,
         duration_ms: Math.round(performance.now() - cacheStart),
         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
-    await addSpanEvent('timber.cache.miss', {
+    // Record cache miss as OTEL span event (fire-and-forget).
+    addSpanEventSync('timber.cache.miss', {
       key,
       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.ts';
+
+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.ts';
+
+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('; ')}`
+      );
+    }
+  }
+}

package/src/cdn/headers.ts

@@ -0,0 +1,153 @@
+/**
+ * CDN header helpers — pure functions that build Cache-Control,
+ * CDN-Cache-Control, Surrogate-Control, and Surrogate-Key header values.
+ *
+ * These are developer-elected utilities for wiring CDN caching in
+ * proxy.ts / middleware.ts. The framework never sets these automatically.
+ * See design/25-production-deployments.md §Layer 2.
+ */
+
+export interface CacheControlOptions {
+  /** Mark the response as publicly cacheable (CDN, shared caches). */
+  public?: boolean;
+  /** Mark the response as private (browser cache only, not CDN). */
+  private?: boolean;
+  /** Max freshness in seconds for the browser/client. */
+  maxAge?: number;
+  /** Max freshness in seconds for shared caches (CDN, proxy). Overrides maxAge for CDNs. */
+  sMaxAge?: number;
+  /** Serve stale while revalidating in the background (seconds). */
+  staleWhileRevalidate?: number;
+  /** Serve stale on upstream error (seconds). */
+  staleIfError?: number;
+  /** Response must not be stored by any cache. */
+  noStore?: boolean;
+  /** Caches must revalidate before using a stored response. */
+  noCache?: boolean;
+  /** Caches must revalidate once stale — no serving stale without checking origin. */
+  mustRevalidate?: boolean;
+  /** Response will not change — allows aggressive caching. Pair with hashed URLs. */
+  immutable?: boolean;
+}
+
+/**
+ * Build a `Cache-Control` header value.
+ *
+ * ```ts
+ * ctx.headers.set('Cache-Control', cacheControl({
+ *   public: true,
+ *   maxAge: 300,
+ *   staleWhileRevalidate: 60,
+ * }));
+ * ```
+ */
+export function cacheControl(opts: CacheControlOptions): string {
+  if (opts.public && opts.private) {
+    throw new Error('cacheControl: public and private are mutually exclusive');
+  }
+  if (opts.noStore && opts.maxAge !== undefined) {
+    throw new Error('cacheControl: noStore makes maxAge meaningless — remove one');
+  }
+
+  const parts: string[] = [];
+
+  parts.push(opts.public ? 'public' : 'private');
+
+  if (opts.noStore) parts.push('no-store');
+  if (opts.noCache) parts.push('no-cache');
+  if (opts.maxAge !== undefined) parts.push(`max-age=${opts.maxAge}`);
+  if (opts.sMaxAge !== undefined) parts.push(`s-maxage=${opts.sMaxAge}`);
+  if (opts.staleWhileRevalidate !== undefined)
+    parts.push(`stale-while-revalidate=${opts.staleWhileRevalidate}`);
+  if (opts.staleIfError !== undefined) parts.push(`stale-if-error=${opts.staleIfError}`);
+  if (opts.mustRevalidate) parts.push('must-revalidate');
+  if (opts.immutable) parts.push('immutable');
+
+  return parts.join(', ');
+}
+
+export interface SurrogateControlOptions {
+  /** Max freshness in seconds for the surrogate (CDN). */
+  maxAge?: number;
+  /** Do not store in surrogate cache. */
+  noStore?: boolean;
+  /** Serve stale while revalidating (seconds). */
+  staleWhileRevalidate?: number;
+  /** Serve stale on error (seconds). */
+  staleIfError?: number;
+}
+
+/**
+ * Build a `Surrogate-Control` header value (Fastly, Akamai, Varnish).
+ *
+ * ```ts
+ * ctx.headers.set('Surrogate-Control', surrogateControl({ maxAge: 3600 }));
+ * ```
+ */
+export function surrogateControl(opts: SurrogateControlOptions): string {
+  const parts: string[] = [];
+  if (opts.noStore) parts.push('no-store');
+  if (opts.maxAge !== undefined) parts.push(`max-age=${opts.maxAge}`);
+  if (opts.staleWhileRevalidate !== undefined)
+    parts.push(`stale-while-revalidate=${opts.staleWhileRevalidate}`);
+  if (opts.staleIfError !== undefined) parts.push(`stale-if-error=${opts.staleIfError}`);
+  return parts.join(', ');
+}
+
+/**
+ * Build a `CDN-Cache-Control` header value (Cloudflare).
+ * Same directive syntax as Surrogate-Control but recognized by Cloudflare.
+ *
+ * ```ts
+ * ctx.headers.set('CDN-Cache-Control', cdnCacheControl({ maxAge: 3600 }));
+ * ```
+ */
+export function cdnCacheControl(opts: SurrogateControlOptions): string {
+  return surrogateControl(opts);
+}
+
+/**
+ * Build a `Surrogate-Key` header value — space-separated tags for CDN
+ * tag-based purging (Fastly, Cloudflare Enterprise, Akamai).
+ *
+ * Tags are deduplicated. Tags must not contain spaces or double quotes
+ * (these are separators/delimiters in the header format).
+ *
+ * ```ts
+ * ctx.headers.set('Surrogate-Key', surrogateKey(['products', `product:${id}`]));
+ * ```
+ */
+export function surrogateKey(tags: string[]): string {
+  for (const tag of tags) {
+    if (tag.includes(' ') || tag.includes('"')) {
+      throw new Error(`surrogateKey: tag "${tag}" must not contain spaces or double quotes`);
+    }
+  }
+  return [...new Set(tags)].join(' ');
+}
+
+/**
+ * Build a `Cache-Tag` header value — comma-separated tags for Cloudflare
+ * Workers Cache tag-based purging. Available on ALL Cloudflare plans.
+ *
+ * Tags are deduplicated. Tags must not contain commas (the delimiter).
+ * Maximum tag length is 1024 characters per Cloudflare's limits.
+ *
+ * Use this instead of `surrogateKey()` when using Cloudflare Workers Cache
+ * (ctx.cache.purge). Workers Cache reads `Cache-Tag`, not `Surrogate-Key`.
+ *
+ * ```ts
+ * ctx.headers.set('Cache-Tag', cacheTag(['products', `product:${id}`]));
+ * ```
+ */
+export function cacheTag(tags: string[]): string {
+  for (const tag of tags) {
+    if (tag.includes(',')) {
+      throw new Error(`cacheTag: tag "${tag}" must not contain commas`);
+    }
+    if (tag.length > 1024) {
+      throw new Error(`cacheTag: tag "${tag}" exceeds 1024-character limit`);
+    }
+  }
+  return [...new Set(tags)].join(',');
+}

package/src/cdn/index.ts

@@ -0,0 +1,23 @@
+// @timber-js/app/cdn — CDN integration helpers
+//
+// Header utilities and purge handler for CDN caching. Developer-elected,
+// never automatic. See design/25-production-deployments.md §Layer 2.
+
+export {
+  cacheControl,
+  surrogateKey,
+  surrogateControl,
+  cdnCacheControl,
+  cacheTag,
+} from './headers.ts';
+export type { CacheControlOptions, SurrogateControlOptions } from './headers.ts';
+
+export { setCdnPurgeHandler, getCdnPurgeHandler } from './purge-store.ts';
+export type { CdnPurgeHandler } from './purge-store.ts';
+
+// Platform-specific purge handlers are at their own entry points:
+//   @timber-js/app/cdn/cloudflare         → CloudflarePurge (REST API, Enterprise)
+//   @timber-js/app/cdn/cloudflare-workers → WorkersCachePurge (ctx.cache, all plans)
+//   @timber-js/app/cdn/fastly             → FastlyPurge
+// Same pattern as @timber-js/app/cache/stores/* — keeps platform
+// dependencies out of the main CDN import.

package/src/cdn/purge-store.ts

@@ -0,0 +1,34 @@
+/**
+ * CDN purge handler singleton — same pattern as cache/handler-store.ts.
+ *
+ * Set via timber.config.ts or setCdnPurgeHandler() at boot. When set,
+ * cache.invalidate({ tag }) also triggers CDN purge for the invalidated
+ * tags, so revalidateTag() composes with CDN caching out of the box.
+ *
+ * See design/25-production-deployments.md §Layer 2.
+ */
+
+export interface CdnPurgeHandler {
+  /**
+   * Purge the given cache tags from the CDN.
+   * Called by cache.invalidate when a tag is invalidated.
+   */
+  purgeTags(tags: string[]): Promise<void>;
+}
+
+let handler: CdnPurgeHandler | undefined;
+
+/** Install a CDN purge handler. Called by the framework at boot from timber.config.ts. */
+export function setCdnPurgeHandler(h: CdnPurgeHandler): void {
+  handler = h;
+}
+
+/** Get the current CDN purge handler, if configured. */
+export function getCdnPurgeHandler(): CdnPurgeHandler | undefined {
+  return handler;
+}
+
+/** @internal — reset for tests only. */
+export function _resetCdnPurgeHandler(): void {
+  handler = undefined;
+}

package/src/cdn/workers-cache-purge.ts

@@ -0,0 +1,34 @@
+/**
+ * Cloudflare Workers Cache purge handler — purges by cache tag via
+ * ctx.cache.purge() on the ExecutionContext.
+ *
+ * Available on ALL Cloudflare plans (no Enterprise requirement).
+ * No API token needed — uses the Workers runtime's built-in cache API.
+ *
+ * ctx.cache.purge() operates on the same underlying Cloudflare CDN cache
+ * as caches.default — entries stored via cache.put() with matching
+ * Cache-Tag headers are purged (TIM-1172). See design/25 §TIM-1172.
+ *
+ * Auto-wired by the Cloudflare adapter when no user-configured CDN
+ * purge handler is set. Uses the Workers Cache ALS bridge to access
+ * ctx.cache from within the request context.
+ */
+
+import type { CdnPurgeHandler } from './purge-store.ts';
+import { getWorkersCachePurgeCtx } from '../server/workers-cache-bridge.ts';
+
+export class WorkersCachePurge implements CdnPurgeHandler {
+  async purgeTags(tags: string[]): Promise<void> {
+    if (tags.length === 0) return;
+
+    const ctx = getWorkersCachePurgeCtx();
+    if (!ctx) {
+      throw new Error(
+        'WorkersCachePurge: no Workers Cache context available. ' +
+          'This handler can only be used within a Cloudflare Workers request context.'
+      );
+    }
+
+    await ctx.purge({ tags });
+  }
+}