Cache Fallbacks

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

// Multi-tier cache configuration optimized for resilience
interface ResilientCacheConfig {
  // L1: Local in-process cache (fastest, smallest)
  local: {
    maxSize: number;          // e.g., 1000 items
    ttlSeconds: number;       // e.g., 60 seconds
  };
  
  // L2: Distributed cache (Redis/Memcached)
  distributed: {
    ttlSeconds: number;       // e.g., 300 seconds (5 minutes)
    fallbackTtlSeconds: number; // e.g., 3600 seconds (1 hour) - stale but usable
  };
  
  // L3: Persistent fallback cache (database or object storage)
  persistent: {
    ttlSeconds: number;       // e.g., 86400 seconds (24 hours)
    enabled: boolean;         // Enable only for critical paths
  };
}
 
// Example configuration for a product catalog
const productCatalogCache: ResilientCacheConfig = {
  local: {
    maxSize: 10000,     // Hot products cached locally
    ttlSeconds: 30,     // Quick refresh for price changes
  },
  distributed: {
    ttlSeconds: 300,          // 5 minute freshness target
    fallbackTtlSeconds: 7200, // Serve up to 2 hour stale during outage
  },
  persistent: {
    ttlSeconds: 86400,  // 24 hour backup in S3/database
    enabled: true,      // Product data is critical
  }
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

interface SWRCacheEntry<T> {
  data: T;
  cachedAt: number;      // Timestamp when cached
  refreshedAt: number;   // Timestamp of last successful refresh
}
 
interface SWRConfig {
  freshThresholdMs: number;    // Serve without refresh
  staleThresholdMs: number;    // Serve but trigger refresh
  maxStaleMs: number;          // Beyond this, treat as miss
}
 
class SWRCache<T> {
  constructor(
    private cache: Cache,
    private fetcher: () => Promise<T>,
    private config: SWRConfig
  ) {}
 
  async get(key: string): Promise<{ data: T; status: 'fresh' | 'stale' | 'miss' }> {
    const entry = await this.cache.get<SWRCacheEntry<T>>(key);
    const now = Date.now();
 
    // Case 1: Cache miss - fetch synchronously
    if (!entry) {
      const data = await this.fetchAndCache(key);
      return { data, status: 'miss' };
    }
 
    const age = now - entry.refreshedAt;
 
    // Case 2: Fresh - serve immediately
    if (age < this.config.freshThresholdMs) {
      return { data: entry.data, status: 'fresh' };
    }
 
    // Case 3: Stale but usable - serve and refresh
    if (age < this.config.maxStaleMs) {
      // Trigger background refresh (don't await)
      this.backgroundRefresh(key);
      return { data: entry.data, status: 'stale' };
    }
 
    // Case 4: Too stale - treat as miss
    try {
      const data = await this.fetchAndCache(key);
      return { data, status: 'miss' };
    } catch (error) {
      // Even though too stale, if fetch fails, still serve stale
      // This is the fallback power of SWR
      if (entry) {
        logger.warn('Serving very stale cache due to fetch failure', { key, age });
        metrics.increment('cache.very_stale_fallback');
        return { data: entry.data, status: 'stale' };
      }
      throw error;
    }
  }
 
  private async fetchAndCache(key: string): Promise<T> {
    const data = await this.fetcher();
    const now = Date.now();
    await this.cache.set(key, {
      data,
      cachedAt: now,
      refreshedAt: now
    });
    return data;
  }
 
  private backgroundRefresh(key: string): void {
    // Fire and forget - errors are logged but don't affect response
    this.fetchAndCache(key).catch(error => {
      logger.warn('Background refresh failed', { key, error: error.message });
      metrics.increment('cache.background_refresh_failed');
    });
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

interface CachedResponse<T> {
  data: T;
  metadata: {
    source: 'fresh' | 'cache' | 'stale_cache' | 'fallback';
    cachedAt?: Date;
    maxAge?: number;           // Original TTL
    age?: number;              // How old the data is
    staleReason?: string;      // Why we're serving stale
    refreshAttempted?: Date;   // Last refresh attempt time
    nextRefresh?: Date;        // When refresh will be tried
  };
}
 
// Controller returns this structure
async function getProduct(productId: string): Promise<CachedResponse<Product>> {
  const cacheKey = `product:${productId}`;
  const cached = await cache.getWithMetadata<Product>(cacheKey);
 
  // Fresh cache hit
  if (cached && cached.age < cached.maxAge) {
    return {
      data: cached.value,
      metadata: {
        source: 'cache',
        cachedAt: cached.timestamp,
        maxAge: cached.maxAge,
        age: cached.age
      }
    };
  }
 
  // Try to fetch fresh
  try {
    const product = await productService.fetch(productId);
    await cache.set(cacheKey, product, { maxAge: 300 });
    return {
      data: product,
      metadata: { source: 'fresh' }
    };
  } catch (error) {
    // Fetch failed - use stale cache if available
    if (cached) {
      return {
        data: cached.value,
        metadata: {
          source: 'stale_cache',
          cachedAt: cached.timestamp,
          age: cached.age,
          staleReason: 'upstream_unavailable',
          refreshAttempted: new Date()
        }
      };
    }
    throw error; // No cache, no fresh - must fail
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

class CacheWarmer {
  private warmingQueue: Queue;
  
  constructor(
    private cache: Cache,
    private dataSource: DataSource,
    private config: CacheWarmerConfig
  ) {
    this.warmingQueue = new Queue('cache-warming');
    this.schedulePeriodicWarming();
  }
 
  // Warm cache for a specific key
  async warmKey(key: string, fetcher: () => Promise<any>): Promise<void> {
    const existing = await this.cache.get(key);
    const age = existing ? Date.now() - existing.timestamp : Infinity;
 
    // Only warm if approaching staleness threshold
    if (age > this.config.warmingThresholdMs) {
      try {
        const data = await fetcher();
        await this.cache.set(key, data, { maxAge: this.config.ttlSeconds });
        metrics.increment('cache.warmed', { key: this.keyPattern(key) });
      } catch (error) {
        logger.warn('Cache warming failed', { key, error: error.message });
        metrics.increment('cache.warming_failed', { key: this.keyPattern(key) });
      }
    }
  }
 
  // Scheduled warming of critical data
  private schedulePeriodicWarming(): void {
    // Run every minute
    setInterval(async () => {
      // Warm product catalog top 1000 products
      const topProducts = await this.dataSource.getTopProducts(1000);
      for (const product of topProducts) {
        await this.warmingQueue.add('warm-product', { productId: product.id });
      }
 
      // Warm user preferences for recently active users
      const recentUsers = await this.dataSource.getRecentlyActiveUsers(10000);
      for (const user of recentUsers) {
        await this.warmingQueue.add('warm-user-prefs', { userId: user.id });
      }
 
      metrics.gauge('cache.warming_queue_size', this.warmingQueue.length);
    }, 60000);
  }
 
  // Process warming jobs
  async processWarmingJob(job: { type: string; data: any }): Promise<void> {
    switch (job.type) {
      case 'warm-product':
        await this.warmKey(
          `product:${job.data.productId}`,
          () => this.dataSource.getProduct(job.data.productId)
        );
        break;
      case 'warm-user-prefs':
        await this.warmKey(
          `user:prefs:${job.data.userId}`,
          () => this.dataSource.getUserPreferences(job.data.userId)
        );
        break;
    }
  }
 
  private keyPattern(key: string): string {
    return key.replace(/:[a-f0-9-]+/g, ':*');
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

class OutageAwareCache<T> {
  private upstreamHealthy = true;
  private lastHealthCheck = 0;
  private healthCheckIntervalMs = 5000;
 
  constructor(
    private cache: Cache,
    private fetcher: (key: string) => Promise<T>,
    private config: OutageCacheConfig
  ) {}
 
  async get(key: string): Promise<T | null> {
    // Check if we should probe upstream health
    if (!this.upstreamHealthy && this.shouldProbeHealth()) {
      this.probeUpstreamHealth();
    }
 
    // If upstream is healthy, try normal fetch
    if (this.upstreamHealthy) {
      return this.normalFetch(key);
    }
 
    // Upstream unhealthy - fallback mode
    return this.fallbackFetch(key);
  }
 
  private async normalFetch(key: string): Promise<T | null> {
    // First check cache
    const cached = await this.cache.get<CacheEntry<T>>(key);
    if (cached && !this.isStale(cached)) {
      return cached.data;
    }
 
    // Cache miss or stale - fetch from upstream
    try {
      const data = await this.fetcher(key);
      await this.cache.set(key, { data, timestamp: Date.now() });
      return data;
    } catch (error) {
      // Upstream failed - might be start of outage
      this.handleUpstreamFailure(error);
      
      // Return stale cache if available
      if (cached) {
        metrics.increment('cache.stale_fallback');
        return cached.data;
      }
      
      throw error;
    }
  }
 
  private async fallbackFetch(key: string): Promise<T | null> {
    // In fallback mode, only use cache - don't hit upstream
    const cached = await this.cache.get<CacheEntry<T>>(key);
    
    if (cached) {
      const staleness = Date.now() - cached.timestamp;
      
      // Check if within extended fallback threshold
      if (staleness < this.config.fallbackMaxStaleMs) {
        metrics.increment('cache.fallback_hit', {
          staleness_bucket: this.stalenessBucket(staleness)
        });
        return cached.data;
      }
      
      // Beyond fallback threshold - data too old
      metrics.increment('cache.fallback_too_stale');
      // Depending on policy, either return anyway with warning or return null
      if (this.config.serveVeryStale) {
        logger.warn('Serving very stale data', { key, staleness });
        return cached.data;
      }
    }
 
    return null;
  }
 
  private handleUpstreamFailure(error: Error): void {
    this.upstreamHealthy = false;
    this.lastHealthCheck = Date.now();
    logger.warn('Upstream failure detected, entering fallback mode');
    metrics.increment('cache.fallback_mode_entered');
  }
 
  private shouldProbeHealth(): boolean {
    return Date.now() - this.lastHealthCheck > this.healthCheckIntervalMs;
  }
 
  private async probeUpstreamHealth(): Promise<void> {
    this.lastHealthCheck = Date.now();
    try {
      await this.fetcher('__health_probe__');
      this.upstreamHealthy = true;
      logger.info('Upstream recovered, exiting fallback mode');
      metrics.increment('cache.fallback_mode_exited');
    } catch {
      // Still unhealthy
    }
  }
 
  private isStale(entry: CacheEntry<T>): boolean {
    return Date.now() - entry.timestamp > this.config.freshTtlMs;
  }
 
  private stalenessBucket(staleness: number): string {
    if (staleness < 60000) return '<1min';
    if (staleness < 300000) return '1-5min';
    if (staleness < 900000) return '5-15min';
    if (staleness < 3600000) return '15-60min';
    return '>1hour';
  }
}