@timber-js/app 0.2.0-alpha.157 → 0.2.0-alpha.159

package/src/cache/handler-store.ts

@@ -16,9 +16,17 @@ interface CacheHandlerLike {
 
 let handler: CacheHandlerLike | null = null;
 
+let explicitlyConfigured = false;
+
 /** Replace the active cache handler. Called by the framework at boot. */
 export function setCacheHandler(h: CacheHandlerLike): void {
   handler = h;
+  explicitlyConfigured = true;
+}
+
+/** Whether the handler was explicitly configured (vs the default in-memory fallback). */
+export function isCacheHandlerConfigured(): boolean {
+  return explicitlyConfigured;
 }
 
 /**

package/src/cache/index.ts

@@ -151,6 +151,10 @@ export { setDefaultSingleflightTimeout } from './timber-cache';
 // NOTE: registerCachedFunction (runtime for 'use cache' directive) removed.
 // Future feature pending design doc. See design/06-caching.md.
 export { estimateByteSize } from './sizeof';
+
+// --- Cache Store layering (design/46) ---
+export { TagAwareCacheHandler } from './tag-aware-handler';
+export type { CacheStore } from './store';
 // stableStringify, createSingleflight, and SingleflightTimeoutError are
 // internal utilities used by the cache implementation. They are not
 // re-exported here — import directly from the source files if needed

package/src/cache/redis-handler.ts

@@ -20,7 +20,8 @@ import type { CacheHandler } from './index';
  * const client: RedisClient = {
  *   get: (k) => redis.get(k),
  *   set: (k, v, ttl) => redis.set(k, v, 'EX', ttl),
- *   expire: (k, s) => redis.expire(k, s),
+ *   expireNX: (k, s) => redis.expire(k, s, 'NX'),
+ *   expireGT: (k, s) => redis.expire(k, s, 'GT'),
  *   del: (k) => redis.del(k),
  *   sadd: (k, ...m) => redis.sadd(k, ...m),
  *   srem: (k, ...m) => redis.srem(k, ...m),
@@ -37,7 +38,8 @@ import type { CacheHandler } from './index';
  * const client: RedisClient = {
  *   get: (k) => redis.get(k),
  *   set: (k, v, ttl) => redis.set(k, v, { EX: ttl }),
- *   expire: (k, s) => redis.expire(k, s),
+ *   expireNX: (k, s) => redis.expire(k, s, 'NX'),
+ *   expireGT: (k, s) => redis.expire(k, s, 'GT'),
  *   del: (k) => redis.del(k),
  *   sadd: (k, ...m) => redis.sAdd(k, m),
  *   srem: (k, ...m) => redis.sRem(k, m),
@@ -55,7 +57,8 @@ import type { CacheHandler } from './index';
  * const client: RedisClient = {
  *   get: (k) => redis.get(k),
  *   set: (k, v, ttl) => redis.set(k, v, { ex: ttl }),
- *   expire: (k, s) => redis.expire(k, s),
+ *   expireNX: (k, s) => redis.expire(k, s, 'NX'),
+ *   expireGT: (k, s) => redis.expire(k, s, 'GT'),
  *   del: (k) => redis.del(k),
  *   sadd: (k, ...m) => redis.sadd(k, m[0], ...m.slice(1)),
  *   srem: (k, ...m) => redis.srem(k, m[0], ...m.slice(1)),
@@ -72,8 +75,17 @@ export interface RedisClient {
    * required positional argument so no adapter can forget it.
    */
   set(key: string, value: string, ttlSeconds: number): Promise<unknown>;
-  /** `EXPIRE key seconds` — set/refresh a key's TTL (used for tag sets). */
-  expire(key: string, seconds: number): Promise<unknown>;
+  /**
+   * `EXPIRE key seconds NX` — set the TTL only if the key has no existing
+   * expiry (Redis 7.0+). Used to set the initial TTL on new tag sets.
+   */
+  expireNX(key: string, seconds: number): Promise<unknown>;
+  /**
+   * `EXPIRE key seconds GT` — update the TTL only if the new value is greater
+   * than the current one (Redis 7.0+). Used to extend tag set TTLs without
+   * allowing a short-TTL writer to shrink them.
+   */
+  expireGT(key: string, seconds: number): Promise<unknown>;
   /** `DEL key` — delete a single key. Multi-key deletes loop per key. */
   del(key: string): Promise<unknown>;
   /** `SADD key member [member ...]` — add members to a set. */
@@ -147,14 +159,14 @@ export class RedisCacheHandler implements CacheHandler {
     // otherwise invalidate({tag}) would miss the long-lived entries.
     for (const tag of opts.tags) {
       await this.client.sadd(this.tagKey(tag), key);
-      const currentTtl = await this.client.ttl(this.tagKey(tag));
-      // Only extend, never shorten. -2 = key doesn't exist (rare race after
-      // sadd), -1 = no expiry (new set or legacy — set initial TTL), positive
-      // but shorter = extend. A longer current TTL means a longer-lived entry
-      // set it first — don't shorten.
-      if (currentTtl < redisTtlSeconds) {
-        await this.client.expire(this.tagKey(tag), redisTtlSeconds);
-      }
+      // Two atomic EXPIRE calls cover both the initial-set and extend cases:
+      // - NX: sets the TTL only if the key has no expiry (new tag set from SADD)
+      // - GT: extends the TTL only if the new value is greater than current
+      // Together they close the race where concurrent workers could shrink the
+      // tag set lifetime (TIM-1093), while ensuring new tag sets always get an
+      // initial expiry (without NX, GT is a no-op on non-volatile keys).
+      await this.client.expireNX(this.tagKey(tag), redisTtlSeconds);
+      await this.client.expireGT(this.tagKey(tag), redisTtlSeconds);
     }
   }
 

package/src/cache/singleflight.ts

@@ -17,7 +17,7 @@ export interface SingleflightOptions {
 }
 
 export interface Singleflight {
-  do<T>(key: string, fn: () => Promise<T>): Promise<T>;
+  do<T>(key: string, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
 }
 
 /**
@@ -36,25 +36,25 @@ export function createSingleflight(opts?: SingleflightOptions): Singleflight {
   const timeoutMs = opts?.timeoutMs;
 
   return {
-    do<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    do<T>(key: string, fn: (signal: AbortSignal) => Promise<T>): Promise<T> {
       const existing = inflight.get(key);
       if (existing) return existing as Promise<T>;
 
+      const ac = new AbortController();
       let promise: Promise<T>;
 
       if (timeoutMs != null && timeoutMs > 0) {
         // Race fn() against a timeout to prevent hung calls from
         // permanently blocking the key. See TIM-518.
+        // Abort the signal on timeout so the callback can skip
+        // side effects (e.g. cache writes). See TIM-1092.
         promise = new Promise<T>((resolve, reject) => {
-          const timer = setTimeout(
-            () => reject(new SingleflightTimeoutError(key, timeoutMs)),
-            timeoutMs
-          );
-          // Wrap in try/catch so a synchronous throw from fn()
-          // (e.g. argument validation) still clears the timer.
-          // Without this, the timer leaks until expiry.
+          const timer = setTimeout(() => {
+            ac.abort();
+            reject(new SingleflightTimeoutError(key, timeoutMs));
+          }, timeoutMs);
           try {
-            fn().then(
+            fn(ac.signal).then(
               (value) => {
                 clearTimeout(timer);
                 resolve(value);
@@ -70,7 +70,7 @@ export function createSingleflight(opts?: SingleflightOptions): Singleflight {
           }
         });
       } else {
-        promise = fn();
+        promise = fn(ac.signal);
       }
 
       const tracked = promise.finally(() => {

package/src/cache/store.ts

@@ -0,0 +1,71 @@
+/**
+ * CacheStore — the contract cache backends implement.
+ *
+ * Three tiers of tag capability, auto-detected by TagAwareCacheHandler:
+ *
+ * 1. **Native tags** (store implements setWithTags + invalidateTag): The store
+ *    handles tag indexing and invalidation internally. The handler delegates
+ *    directly. Examples: Vercel Runtime Cache, Durable Object–backed stores.
+ *
+ * 2. **Set primitives** (store implements sadd/smembers/srem/sdel): The handler
+ *    maintains an inverted index using the store's atomic set operations.
+ *    Eager invalidation — enumerate and delete. Example: Redis.
+ *
+ * 3. **Bare KV** (only get/set/del): The handler uses version-stamping. Entries
+ *    record tag versions at write time; reads validate against current versions.
+ *    Invalidation bumps a counter — O(1), race-free. Example: Cloudflare KV.
+ *
+ * Implementors pick their tier by which methods they provide. The handler
+ * selects the best available strategy automatically.
+ */
+
+export interface CacheStore {
+  // --- Required: every store must implement these ---
+
+  /** Read a key. Returns null if absent or physically expired. */
+  get(key: string): Promise<string | null>;
+
+  /** Write a key with a physical TTL in seconds. Overwrites if exists. */
+  set(key: string, value: string, ttlSeconds: number): Promise<void>;
+
+  /** Delete a key. No-op if absent. */
+  del(key: string): Promise<void>;
+
+  // --- Tier 1: Native tag support ---
+  // If implemented, the handler delegates tag operations entirely to the store.
+
+  /**
+   * Write a value with associated tags. The store handles tag indexing
+   * internally. If provided, the handler will call this instead of plain
+   * set() for tagged entries.
+   */
+  setWithTags?(key: string, value: string, ttlSeconds: number, tags: string[]): Promise<void>;
+
+  /**
+   * Invalidate all entries associated with a tag. The store handles
+   * the lookup and deletion/marking internally.
+   */
+  invalidateTag?(tag: string): Promise<void>;
+
+  // --- Tier 2: Set primitives (enables eager inverted-index strategy) ---
+
+  /**
+   * Atomically add members to a named set and ensure the set has at least
+   * the given TTL.
+   */
+  sadd?(key: string, members: string[], ttlSeconds: number): Promise<void>;
+
+  /** Remove members from a named set. */
+  srem?(key: string, members: string[]): Promise<void>;
+
+  /** Return all members of a named set. */
+  smembers?(key: string): Promise<string[]>;
+
+  /** Delete a named set entirely. */
+  sdel?(key: string): Promise<void>;
+
+  // --- Metadata ---
+
+  /** Consistency model — used for framework build diagnostics. */
+  readonly consistency: 'strong' | 'eventual' | 'local';
+}

package/src/cache/stores/cloudflare-kv.ts

@@ -0,0 +1,52 @@
+/**
+ * Cloudflare Workers KV CacheStore — eventually-consistent, no set operations.
+ *
+ * The TagAwareCacheHandler uses the lazy (version-stamp) strategy for this
+ * store: tag invalidation bumps a version counter (O(1) write), and reads
+ * validate stored tag versions against current. No enumeration, no
+ * read-modify-write races, correct under eventual consistency.
+ *
+ * Consistency: KV propagates writes in ~60s. A tag version bump propagates
+ * like any other write — during the window, some reads may still validate
+ * against the old version and serve stale data. This is acceptable for KV's
+ * consistency model (use short TTLs for security-critical invalidation).
+ */
+
+import type { CacheStore } from '../store';
+
+export interface CloudflareKVNamespace {
+  get(key: string, options?: { type?: string }): Promise<string | null>;
+  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+export class CloudflareKVStore implements CacheStore {
+  private kv: CloudflareKVNamespace | (() => CloudflareKVNamespace);
+  readonly consistency = 'eventual' as const;
+
+  /**
+   * @param kv - Either a KVNamespace instance or a factory function that
+   * resolves it from the current request context (for Workers where bindings
+   * are per-request).
+   */
+  constructor(kv: CloudflareKVNamespace | (() => CloudflareKVNamespace)) {
+    this.kv = kv;
+  }
+
+  private getKV(): CloudflareKVNamespace {
+    return typeof this.kv === 'function' ? this.kv() : this.kv;
+  }
+
+  async get(key: string): Promise<string | null> {
+    return this.getKV().get(key);
+  }
+
+  async set(key: string, value: string, ttlSeconds: number): Promise<void> {
+    // KV expirationTtl minimum is 60s
+    await this.getKV().put(key, value, { expirationTtl: Math.max(ttlSeconds, 60) });
+  }
+
+  async del(key: string): Promise<void> {
+    await this.getKV().delete(key);
+  }
+}

package/src/cache/stores/memory.ts

@@ -0,0 +1,125 @@
+/**
+ * In-memory CacheStore — local consistency only.
+ *
+ * LRU eviction by entry count and optional byte budget. The TagAwareCacheHandler
+ * uses the Set-based strategy here (we implement sadd/smembers/srem/sdel with
+ * plain Maps — atomic within a single process).
+ *
+ * Tag sets may accumulate stale memberships when data entries expire via TTL or
+ * LRU eviction (the store layer cannot know which sets reference a given key).
+ * This is harmless: TagAwareCacheHandler's eager invalidation path reads each
+ * member before deleting and prunes stale entries. The cost is proportional to
+ * set size on invalidation, not to memory — stale memberships are just strings.
+ */
+
+import type { CacheStore } from '../store';
+import { estimateByteSize } from '../sizeof.js';
+
+export interface MemoryStoreOptions {
+  maxEntries?: number;
+  maxBytes?: number;
+  maxEntryBytes?: number;
+}
+
+export class MemoryCacheStore implements CacheStore {
+  private store = new Map<string, { value: string; expiresAt: number; byteSize: number }>();
+  private sets = new Map<string, Set<string>>();
+  private maxEntries: number;
+  private maxBytes: number | undefined;
+  private maxEntryBytes: number | undefined;
+  private currentBytes = 0;
+  private readonly trackBytes: boolean;
+  readonly consistency = 'local' as const;
+
+  constructor(opts?: MemoryStoreOptions) {
+    this.maxEntries = Math.max(opts?.maxEntries ?? 1000, 1);
+    this.maxBytes = opts?.maxBytes;
+    this.maxEntryBytes = opts?.maxEntryBytes;
+    this.trackBytes = this.maxBytes !== undefined || this.maxEntryBytes !== undefined;
+  }
+
+  async get(key: string): Promise<string | null> {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    if (Date.now() > entry.expiresAt) {
+      this.removeEntry(key);
+      return null;
+    }
+    // LRU: move to end
+    this.store.delete(key);
+    this.store.set(key, entry);
+    return entry.value;
+  }
+
+  async set(key: string, value: string, ttlSeconds: number): Promise<void> {
+    const byteSize = this.trackBytes ? estimateByteSize(value) : 0;
+
+    if (this.maxEntryBytes !== undefined && byteSize > this.maxEntryBytes) return;
+
+    if (this.store.has(key)) this.removeEntry(key);
+
+    while (this.store.size >= this.maxEntries) this.evictOldest();
+
+    if (this.maxBytes !== undefined) {
+      while (this.currentBytes + byteSize > this.maxBytes && this.store.size > 0) {
+        this.evictOldest();
+      }
+      if (this.currentBytes + byteSize > this.maxBytes) return;
+    }
+
+    this.store.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000, byteSize });
+    this.currentBytes += byteSize;
+  }
+
+  async del(key: string): Promise<void> {
+    this.removeEntry(key);
+  }
+
+  // Set operations — trivial in-process implementations.
+
+  async sadd(key: string, members: string[], _ttlSeconds: number): Promise<void> {
+    let set = this.sets.get(key);
+    if (!set) {
+      set = new Set();
+      this.sets.set(key, set);
+    }
+    for (const m of members) set.add(m);
+  }
+
+  async srem(key: string, members: string[]): Promise<void> {
+    const set = this.sets.get(key);
+    if (!set) return;
+    for (const m of members) set.delete(m);
+    if (set.size === 0) this.sets.delete(key);
+  }
+
+  async smembers(key: string): Promise<string[]> {
+    const set = this.sets.get(key);
+    return set ? [...set] : [];
+  }
+
+  async sdel(key: string): Promise<void> {
+    this.sets.delete(key);
+  }
+
+  get size(): number {
+    return this.store.size;
+  }
+
+  get bytes(): number {
+    return this.currentBytes;
+  }
+
+  private removeEntry(key: string): void {
+    const entry = this.store.get(key);
+    if (entry) {
+      this.currentBytes -= entry.byteSize;
+      this.store.delete(key);
+    }
+  }
+
+  private evictOldest(): void {
+    const oldest = this.store.keys().next().value;
+    if (oldest !== undefined) this.removeEntry(oldest);
+  }
+}

package/src/cache/stores/redis.ts

@@ -0,0 +1,97 @@
+/**
+ * Redis CacheStore — strongly-consistent, supports native Set operations.
+ *
+ * The TagAwareCacheHandler will use the Set-based strategy automatically
+ * because this store provides sadd/smembers/srem/sdel.
+ */
+
+import type { CacheStore } from '../store';
+
+/**
+ * Minimal Redis client contract. Same philosophy as the old RedisClient
+ * interface — deliberately NOT the native shape of any library. TTL is a
+ * required positional argument so no adapter can forget it.
+ *
+ * @example ioredis
+ * ```ts
+ * import Redis from 'ioredis';
+ * const redis = new Redis(process.env.REDIS_URL);
+ * const client: RedisStoreClient = {
+ *   get: (k) => redis.get(k),
+ *   set: (k, v, ttl) => redis.set(k, v, 'EX', ttl),
+ *   del: (k) => redis.del(k).then(() => {}),
+ *   sadd: (k, ...m) => redis.sadd(k, ...m).then(() => {}),
+ *   srem: (k, ...m) => redis.srem(k, ...m).then(() => {}),
+ *   smembers: (k) => redis.smembers(k),
+ *   expireNX: (k, s) => redis.expire(k, s, 'NX').then(() => {}),
+ *   expireGT: (k, s) => redis.expire(k, s, 'GT').then(() => {}),
+ * };
+ * ```
+ *
+ * @example @upstash/redis
+ * ```ts
+ * import { Redis } from '@upstash/redis';
+ * const redis = new Redis({ url, token, automaticDeserialization: false });
+ * const client: RedisStoreClient = {
+ *   get: (k) => redis.get(k),
+ *   set: (k, v, ttl) => redis.set(k, v, { ex: ttl }).then(() => {}),
+ *   del: (k) => redis.del(k).then(() => {}),
+ *   sadd: (k, ...m) => redis.sadd(k, ...m).then(() => {}),
+ *   srem: (k, ...m) => redis.srem(k, ...m).then(() => {}),
+ *   smembers: (k) => redis.smembers(k),
+ *   expireNX: (k, s) => redis.expire(k, s, 'NX').then(() => {}),
+ *   expireGT: (k, s) => redis.expire(k, s, 'GT').then(() => {}),
+ * };
+ * ```
+ */
+export interface RedisStoreClient {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ttlSeconds: number): Promise<unknown>;
+  del(key: string): Promise<unknown>;
+  sadd(key: string, ...members: string[]): Promise<unknown>;
+  srem(key: string, ...members: string[]): Promise<unknown>;
+  smembers(key: string): Promise<string[]>;
+  /** `EXPIRE key seconds NX` — set TTL only if the key has no existing expiry (Redis 7.0+). */
+  expireNX(key: string, seconds: number): Promise<unknown>;
+  /** `EXPIRE key seconds GT` — extend TTL only if new value is greater (Redis 7.0+). */
+  expireGT(key: string, seconds: number): Promise<unknown>;
+}
+
+export class RedisCacheStore implements CacheStore {
+  private client: RedisStoreClient;
+  readonly consistency = 'strong' as const;
+
+  constructor(client: RedisStoreClient) {
+    this.client = client;
+  }
+
+  async get(key: string): Promise<string | null> {
+    return this.client.get(key);
+  }
+
+  async set(key: string, value: string, ttlSeconds: number): Promise<void> {
+    await this.client.set(key, value, ttlSeconds);
+  }
+
+  async del(key: string): Promise<void> {
+    await this.client.del(key);
+  }
+
+  async sadd(key: string, members: string[], ttlSeconds: number): Promise<void> {
+    await this.client.sadd(key, ...members);
+    await this.client.expireNX(key, ttlSeconds);
+    await this.client.expireGT(key, ttlSeconds);
+  }
+
+  async srem(key: string, members: string[]): Promise<void> {
+    await this.client.srem(key, ...members);
+  }
+
+  async smembers(key: string): Promise<string[]> {
+    return this.client.smembers(key);
+  }
+
+  async sdel(key: string): Promise<void> {
+    await this.client.del(key);
+  }
+}

package/src/cache/stores/vercel.ts

@@ -0,0 +1,59 @@
+/**
+ * Vercel Runtime Cache CacheStore — native tag support.
+ *
+ * Delegates tag operations to Vercel's infrastructure via their Runtime Cache
+ * API (getCache/expireTag). The TagAwareCacheHandler detects setWithTags +
+ * invalidateTag and delegates entirely — no inverted index, no version stamps.
+ *
+ * Vercel handles tag purging across CDN, Runtime Cache, and Data Cache layers
+ * simultaneously. Available on all plans.
+ */
+
+import type { CacheStore } from '../store';
+
+/**
+ * Vercel Runtime Cache contract — the subset we depend on.
+ * Resolved from `@vercel/functions` at runtime.
+ */
+export interface VercelCache {
+  get(key: string): Promise<string | undefined>;
+  set(key: string, value: string, options: { ttl: number; tags?: string[] }): Promise<void>;
+  delete(key: string): Promise<void>;
+  expireTag(tag: string): Promise<void>;
+}
+
+export class VercelCacheStore implements CacheStore {
+  private cache: VercelCache | (() => VercelCache);
+  readonly consistency = 'strong' as const;
+
+  constructor(cache: VercelCache | (() => VercelCache)) {
+    this.cache = cache;
+  }
+
+  private getCache(): VercelCache {
+    return typeof this.cache === 'function' ? this.cache() : this.cache;
+  }
+
+  async get(key: string): Promise<string | null> {
+    const result = await this.getCache().get(key);
+    return result ?? null;
+  }
+
+  async set(key: string, value: string, ttlSeconds: number): Promise<void> {
+    await this.getCache().set(key, value, { ttl: ttlSeconds });
+  }
+
+  async del(key: string): Promise<void> {
+    await this.getCache().delete(key);
+  }
+
+  // --- Native tag support ---
+
+  async setWithTags(key: string, value: string, ttlSeconds: number, tags: string[]): Promise<void> {
+    await this.getCache().set(key, value, { ttl: ttlSeconds, tags });
+  }
+
+  async invalidateTag(tag: string): Promise<void> {
+    await this.getCache().expireTag(tag);
+  }
+}