Cache Invalidation Strategies

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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

/**
 * Staleness Metrics Collector
 * 
 * Instruments cache reads to measure staleness across dimensions.
 */
 
interface StalenessMetrics {
    /** Age of the cached entry in milliseconds */
    ageMs: number;
    
    /** Lag between source update and cache (if detectable) */
    lagMs?: number;
    
    /** Whether this read was stale (if verifiable) */
    isStale?: boolean;
    
    /** Cache entry metadata */
    cacheKey: string;
    entityType: string;
}
 
class StalenessMonitor {
    private metrics: MetricsClient;
    
    constructor(metricsClient: MetricsClient) {
        this.metrics = metricsClient;
    }
 
    /**
     * Record staleness metrics for a cache read
     */
    recordRead(metrics: StalenessMetrics): void {
        // Age histogram - understand age distribution
        this.metrics.histogram('cache.staleness.age_ms', metrics.ageMs, {
            entityType: metrics.entityType,
        });
 
        // Lag histogram - if we can measure it
        if (metrics.lagMs !== undefined) {
            this.metrics.histogram('cache.staleness.lag_ms', metrics.lagMs, {
                entityType: metrics.entityType,
            });
        }
 
        // Staleness rate counter
        if (metrics.isStale !== undefined) {
            this.metrics.increment(
                metrics.isStale ? 'cache.reads.stale' : 'cache.reads.fresh',
                { entityType: metrics.entityType }
            );
        }
    }
 
    /**
     * Calculate P50/P95/P99 staleness from recent data
     */
    async geStalenessPercentiles(entityType: string, window: string): Promise<{
        p50: number;
        p95: number;
        p99: number;
    }> {
        return this.metrics.queryHistogramPercentiles(
            'cache.staleness.age_ms',
            { entityType },
            window,
            [50, 95, 99]
        );
    }
}
 
/**
 * Enhanced cache entry with staleness tracking metadata
 */
interface TrackedCacheEntry<T> {
    value: T;
    cachedAt: number;
    sourceUpdatedAt?: number;  // When source was last updated (if known)
    sourceVersion?: string;    // Version/ETag from source
}
 
class StalenessAwareCache {
    constructor(
        private cache: CacheClient,
        private monitor: StalenessMonitor,
    ) {}
 
    async get<T>(
        key: string,
        entityType: string
    ): Promise<{ value: T | null; staleness: StalenessMetrics | null }> {
        const raw = await this.cache.get(key);
        
        if (!raw) {
            return { value: null, staleness: null };
        }
 
        const entry = JSON.parse(raw) as TrackedCacheEntry<T>;
        const now = Date.now();
        
        const staleness: StalenessMetrics = {
            ageMs: now - entry.cachedAt,
            lagMs: entry.sourceUpdatedAt 
                ? entry.cachedAt - entry.sourceUpdatedAt 
                : undefined,
            cacheKey: key,
            entityType,
        };
 
        this.monitor.recordRead(staleness);
 
        return { value: entry.value, staleness };
    }
 
    async set<T>(
        key: string,
        value: T,
        ttlSeconds: number,
        sourceMetadata?: { updatedAt: number; version?: string }
    ): Promise<void> {
        const entry: TrackedCacheEntry<T> = {
            value,
            cachedAt: Date.now(),
            sourceUpdatedAt: sourceMetadata?.updatedAt,
            sourceVersion: sourceMetadata?.version,
        };
 
        await this.cache.setex(key, ttlSeconds, JSON.stringify(entry));
    }
}
 
interface MetricsClient {
    histogram(metric: string, value: number, tags: Record<string, string>): void;
    increment(metric: string, tags: Record<string, string>): void;
    queryHistogramPercentiles(
        metric: string, 
        tags: Record<string, string>, 
        window: string, 
        percentiles: number[]
    ): Promise<{ [key: string]: number }>;
}

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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

/**
 * Stale-While-Revalidate Implementation
 * 
 * Serves stale data immediately while refreshing in background.
 * Configurable freshness and staleness windows.
 */
 
interface SWRConfig {
    /** Time in seconds during which data is considered fresh */
    freshTtlSeconds: number;
    
    /** Additional time during which stale data can be served while revalidating */
    staleWhileRevalidateSeconds: number;
    
    /** Maximum age before data is considered too stale to serve */
    maxStaleSeconds: number;
}
 
interface SWREntry<T> {
    value: T;
    cachedAt: number;
    revalidating?: boolean;
}
 
enum FreshnessState {
    FRESH = 'FRESH',                        // Within freshTtl
    STALE_BUT_USABLE = 'STALE_BUT_USABLE', // Within staleWhileRevalidate window
    TOO_STALE = 'TOO_STALE',               // Beyond maxStale
}
 
class StaleWhileRevalidateCache<T> {
    private revalidationInProgress = new Set<string>();
 
    constructor(
        private cache: CacheClient,
        private fetcher: (key: string) => Promise<T>,
        private config: SWRConfig,
    ) {}
 
    async get(key: string): Promise<{ value: T | null; freshness: FreshnessState }> {
        const raw = await this.cache.get(key);
        
        if (!raw) {
            // Cache miss - fetch synchronously
            return this.fetchAndCache(key);
        }
 
        const entry = JSON.parse(raw) as SWREntry<T>;
        const freshness = this.determineFreshness(entry);
 
        switch (freshness) {
            case FreshnessState.FRESH:
                // Data is fresh, return immediately
                return { value: entry.value, freshness };
 
            case FreshnessState.STALE_BUT_USABLE:
                // Return stale data immediately, revalidate in background
                this.triggerBackgroundRevalidation(key);
                return { value: entry.value, freshness };
 
            case FreshnessState.TOO_STALE:
                // Data too old, fetch synchronously
                return this.fetchAndCache(key);
        }
    }
 
    private determineFreshness(entry: SWREntry<T>): FreshnessState {
        const ageSeconds = (Date.now() - entry.cachedAt) / 1000;
 
        if (ageSeconds <= this.config.freshTtlSeconds) {
            return FreshnessState.FRESH;
        }
 
        if (ageSeconds <= this.config.freshTtlSeconds + this.config.staleWhileRevalidateSeconds) {
            return FreshnessState.STALE_BUT_USABLE;
        }
 
        if (ageSeconds <= this.config.maxStaleSeconds) {
            return FreshnessState.STALE_BUT_USABLE; // Still serve, but flag as stale
        }
 
        return FreshnessState.TOO_STALE;
    }
 
    private async triggerBackgroundRevalidation(key: string): Promise<void> {
        // Prevent concurrent revalidations for same key
        if (this.revalidationInProgress.has(key)) {
            return;
        }
 
        this.revalidationInProgress.add(key);
 
        // Fire-and-forget background refresh
        setImmediate(async () => {
            try {
                const freshValue = await this.fetcher(key);
                await this.cacheValue(key, freshValue);
            } catch (error) {
                console.error(`Background revalidation failed for ${key}:`, error);
                // Keep serving stale data, don't delete cache entry
            } finally {
                this.revalidationInProgress.delete(key);
            }
        });
    }
 
    private async fetchAndCache(key: string): Promise<{ value: T | null; freshness: FreshnessState }> {
        try {
            const value = await this.fetcher(key);
            await this.cacheValue(key, value);
            return { value, freshness: FreshnessState.FRESH };
        } catch (error) {
            console.error(`Fetch failed for ${key}:`, error);
            return { value: null, freshness: FreshnessState.TOO_STALE };
        }
    }
 
    private async cacheValue(key: string, value: T): Promise<void> {
        const entry: SWREntry<T> = {
            value,
            cachedAt: Date.now(),
        };
 
        // Cache for the total possible lifetime
        const totalTtl = this.config.maxStaleSeconds + 60; // Buffer for clock drift
        await this.cache.setex(key, totalTtl, JSON.stringify(entry));
    }
}
 
// Example usage for product catalog
const productCache = new StaleWhileRevalidateCache<Product>(
    redis,
    async (key) => {
        const productId = key.split(':')[1];
        return await productService.getProduct(productId);
    },
    {
        freshTtlSeconds: 60,              // Fresh for 1 minute
        staleWhileRevalidateSeconds: 300, // Serve stale for 5 more minutes
        maxStaleSeconds: 3600,            // Absolute max 1 hour
    }
);
 
// Usage
const { value: product, freshness } = await productCache.get('product:123');
 
if (freshness === FreshnessState.STALE_BUT_USABLE) {
    // Optionally indicate to user that data might not be current
    console.log('Showing cached product data, refreshing in background...');
}

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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175

/**
 * Graceful Degradation with Stale-If-Error
 * 
 * When fetching fails, fall back to stale cached data
 * rather than returning an error to the user.
 */
 
interface DegradationConfig {
    /** Normal TTL for fresh data */
    normalTtlSeconds: number;
    
    /** Extended TTL for fallback during errors */
    errorFallbackTtlSeconds: number;
    
    /** Static fallback if no cache available */
    staticFallback?: unknown;
}
 
class GracefulDegradationCache<T> {
    constructor(
        private cache: CacheClient,
        private fetcher: (key: string) => Promise<T>,
        private config: DegradationConfig,
        private circuitBreaker: CircuitBreaker,
    ) {}
 
    async get(key: string): Promise<{
        value: T | null;
        source: 'fresh' | 'stale' | 'fallback' | 'error';
        staleness?: number;
    }> {
        // Try to fetch fresh data first
        if (this.circuitBreaker.isOpen()) {
            // Backend known to be down, skip to stale
            return this.getFromStaleCache(key, 'circuit_open');
        }
 
        try {
            const freshValue = await this.fetcher(key);
            await this.cacheValue(key, freshValue);
            return { value: freshValue, source: 'fresh' };
        } catch (error) {
            // Fetch failed, try to serve stale
            this.circuitBreaker.recordFailure();
            return this.getFromStaleCache(key, 'fetch_failed');
        }
    }
 
    private async getFromStaleCache(
        key: string,
        reason: string
    ): Promise<{
        value: T | null;
        source: 'stale' | 'fallback' | 'error';
        staleness?: number;
    }> {
        // Check if we have any cached value (even if expired)
        const raw = await this.cache.get(key);
 
        if (raw) {
            const { value, cachedAt } = JSON.parse(raw);
            const staleness = (Date.now() - cachedAt) / 1000;
 
            // Check if within extended fallback TTL
            if (staleness <= this.config.errorFallbackTtlSeconds) {
                console.warn(
                    `Serving stale data for ${key} (${reason}), age: ${staleness}s`
                );
                return { value, source: 'stale', staleness };
            }
        }
 
        // No valid cache, try static fallback
        if (this.config.staticFallback !== undefined) {
            console.warn(`Serving static fallback for ${key} (${reason})`);
            return { 
                value: this.config.staticFallback as T, 
                source: 'fallback' 
            };
        }
 
        // Complete failure
        return { value: null, source: 'error' };
    }
 
    private async cacheValue(key: string, value: T): Promise<void> {
        const entry = {
            value,
            cachedAt: Date.now(),
        };
        
        // Cache with extended TTL for error fallback
        const totalTtl = this.config.errorFallbackTtlSeconds + 60;
        await this.cache.setex(key, totalTtl, JSON.stringify(entry));
    }
}
 
/**
 * Simple circuit breaker for backend health
 */
class CircuitBreaker {
    private failures = 0;
    private lastFailure = 0;
    private state: 'closed' | 'open' | 'half-open' = 'closed';
 
    constructor(
        private failureThreshold: number = 5,
        private resetTimeMs: number = 30000,
    ) {}
 
    isOpen(): boolean {
        if (this.state === 'open') {
            // Check if reset time has passed
            if (Date.now() - this.lastFailure > this.resetTimeMs) {
                this.state = 'half-open';
                return false; // Allow one request through
            }
            return true;
        }
        return false;
    }
 
    recordFailure(): void {
        this.failures++;
        this.lastFailure = Date.now();
        
        if (this.failures >= this.failureThreshold) {
            this.state = 'open';
            console.error('Circuit breaker opened: backend unavailable');
        }
    }
 
    recordSuccess(): void {
        this.failures = 0;
        this.state = 'closed';
    }
}
 
// Example: Product catalog with graceful degradation
const productCache = new GracefulDegradationCache<Product>(
    redis,
    async (key) => await productAPI.fetch(key),
    {
        normalTtlSeconds: 300,           // 5 minutes normal
        errorFallbackTtlSeconds: 3600,   // Serve up to 1 hour old during outage
        staticFallback: {                // Last resort
            id: 'unknown',
            name: 'Product Temporarily Unavailable',
            price: 0,
            available: false,
        },
    },
    new CircuitBreaker(5, 30000), // Open after 5 failures, reset after 30s
);
 
// Usage in request handler
async function handleProductRequest(productId: string): Promise<Response> {
    const result = await productCache.get(`product:${productId}`);
 
    if (result.source === 'error') {
        return new Response('Service unavailable', { status: 503 });
    }
 
    // Include freshness metadata in response headers
    const headers = new Headers({
        'Content-Type': 'application/json',
        'X-Data-Source': result.source,
    });
 
    if (result.staleness) {
        headers.set('X-Data-Staleness-Seconds', result.staleness.toString());
    }
 
    return new Response(JSON.stringify(result.value), { headers });
}

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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197

/**
 * Staleness Communication Patterns
 * 
 * Multiple approaches for informing clients about data freshness.
 */
 
// ============================================
// 1. HTTP Headers (API Responses)
// ============================================
 
interface CacheMetadata {
    cachedAt: number;
    source: 'fresh' | 'stale' | 'fallback';
    age: number;  // Seconds since caching
    maxAge?: number; // Expected freshness duration
}
 
function addCacheHeaders(
    response: Response, 
    metadata: CacheMetadata
): Response {
    const headers = new Headers(response.headers);
    
    // Standard HTTP headers
    headers.set('Age', metadata.age.toString());
    headers.set('Date', new Date(metadata.cachedAt).toUTCString());
    
    // Custom headers for detailed staleness info
    headers.set('X-Cache-Status', metadata.source);
    headers.set('X-Cache-Age-Seconds', metadata.age.toString());
    
    if (metadata.source !== 'fresh') {
        // Indicate data may not be current
        headers.set('Warning', '110 - "Response is stale"');
    }
 
    if (metadata.maxAge) {
        // Suggest when client should refetch
        const remainingFreshness = Math.max(0, metadata.maxAge - metadata.age);
        headers.set(
            'Cache-Control', 
            `max-age=${remainingFreshness}, stale-while-revalidate=300`
        );
    }
 
    return new Response(response.body, {
        status: response.status,
        headers,
    });
}
 
 
// ============================================
// 2. Response Envelope (API JSON)
// ============================================
 
interface EnvelopedResponse<T> {
    data: T;
    meta: {
        cached: boolean;
        cachedAt: string;
        ageSeconds: number;
        freshness: 'fresh' | 'stale-ok' | 'stale-degraded';
        nextRefresh?: string;
    };
}
 
function envelopeResponse<T>(
    data: T,
    cacheMetadata: CacheMetadata
): EnvelopedResponse<T> {
    return {
        data,
        meta: {
            cached: cacheMetadata.source !== 'fresh',
            cachedAt: new Date(cacheMetadata.cachedAt).toISOString(),
            ageSeconds: cacheMetadata.age,
            freshness: mapToFreshness(cacheMetadata),
            nextRefresh: cacheMetadata.maxAge 
                ? new Date(cacheMetadata.cachedAt + cacheMetadata.maxAge * 1000).toISOString()
                : undefined,
        },
    };
}
 
function mapToFreshness(metadata: CacheMetadata): 'fresh' | 'stale-ok' | 'stale-degraded' {
    if (metadata.source === 'fresh') return 'fresh';
    if (metadata.source === 'stale') return 'stale-ok';
    return 'stale-degraded';
}
 
 
// ============================================
// 3. GraphQL Extensions
// ============================================
 
interface GraphQLResponse<T> {
    data: T;
    extensions?: {
        cacheControl?: {
            version: number;
            hints: Array<{
                path: string[];
                maxAge: number;
                scope: 'PUBLIC' | 'PRIVATE';
            }>;
        };
        staleness?: {
            staleFields: string[];
            ageByField: Record<string, number>;
        };
    };
}
 
 
// ============================================
// 4. UI Components (Frontend)
// ============================================
 
/**
 * React component for displaying staleness indicators
 */
const StalenessIndicatorExample = `
// React component
function DataCard({ data, staleness }) {
    const getIndicator = () => {
        if (staleness.freshness === 'fresh') return null;
        
        if (staleness.freshness === 'stale-ok') {
            return (
                <div className="text-yellow-600 text-sm">
                    Data from {formatTimeAgo(staleness.cachedAt)}
                    <button onClick={onRefresh}>Refresh</button>
                </div>
            );
        }
        
        return (
            <div className="text-orange-600 text-sm bg-orange-50 p-2">
                ⚠️ Showing cached data (service temporarily unavailable)
                <span>Data from {formatTimeAgo(staleness.cachedAt)}</span>
            </div>
        );
    };
 
    return (
        <div>
            {getIndicator()}
            <DataContent data={data} />
        </div>
    );
}
`;
 
 
// ============================================
// 5. Event Stream Updates
// ============================================
 
/**
 * For real-time apps, notify clients when fresher data is available
 */
class StalenessEventEmitter {
    private clients = new Map<string, Set<(event: StalenessEvent) => void>>();
 
    subscribe(
        entityId: string, 
        callback: (event: StalenessEvent) => void
    ): () => void {
        if (!this.clients.has(entityId)) {
            this.clients.set(entityId, new Set());
        }
        this.clients.get(entityId)!.add(callback);
        
        return () => this.clients.get(entityId)?.delete(callback);
    }
 
    notifyRefreshed(entityId: string, newVersion: string): void {
        const subscribers = this.clients.get(entityId);
        if (subscribers) {
            const event: StalenessEvent = {
                type: 'data_refreshed',
                entityId,
                newVersion,
                timestamp: Date.now(),
            };
            subscribers.forEach(callback => callback(event));
        }
    }
}
 
interface StalenessEvent {
    type: 'data_refreshed' | 'data_stale';
    entityId: string;
    newVersion?: string;
    timestamp: number;
}