cloud-server/docs/cache-kv-usage.md

Cache Service - KV Index Usage Guide

Quick Start

Initialization

With KV Index (Recommended):

import { CacheService } from './services/cache';
import { CACHE_TTL } from './constants';

const cache = new CacheService(CACHE_TTL.INSTANCES, env.RATE_LIMIT_KV);

Without KV Index (Backward Compatible):

const cache = new CacheService(CACHE_TTL.INSTANCES);

Common Operations

Pattern-Based Invalidation

// Invalidate all instance caches
const count = await cache.invalidatePattern('*instances*');
console.log(`Invalidated ${count} entries`);

// Invalidate specific provider caches
await cache.invalidatePattern('*provider=linode*');

// Invalidate pricing caches
await cache.invalidatePattern('*pricing*');

// Invalidate with exact pattern
await cache.invalidatePattern('https://cache.internal/instances?provider=vultr*');

Clear All Caches

// Clear all cache entries
const totalCleared = await cache.clearAll();

// Clear with prefix filter
const instancesCleared = await cache.clearAll('https://cache.internal/instances');

Cache Statistics

const stats = await cache.getStats();

if (stats.supported) {
  console.log(`Cache has ${stats.indexed_keys} entries`);
} else {
  console.log('KV index not available');
}

Use Cases

After Data Sync

// Clear all cached instance data after sync
const invalidated = await cache.invalidatePattern('*instances*');
logger.info(`Invalidated ${invalidated} instance cache entries after sync`);

Provider-Specific Updates

// Update only Linode data, invalidate Linode caches
await syncLinodeData();
await cache.invalidatePattern('*provider=linode*');

Cache Cleanup

// Daily cache cleanup (optional, caches auto-expire)
const cleared = await cache.clearAll();
logger.info(`Cache cleanup: ${cleared} entries cleared`);

Pattern Syntax

Wildcards:

• * - Matches any characters
• Case-insensitive by default

Examples:

// Match all
'*'

// Match endpoint
'*instances*'
'*pricing*'

// Match specific parameter
'*provider=linode*'
'*region_code=us-east*'

// Match exact URL
'https://cache.internal/instances?provider=linode'

// Match with prefix
'https://cache.internal/instances*'

Performance

Operation Costs:

• invalidatePattern(): 1 KV list + N cache deletes + N KV deletes
• clearAll(): 1 KV list + N cache deletes + N KV deletes
• getStats(): 1 KV list

KV List Performance:

• ~100ms for <1000 keys
• Pagination handled automatically
• Results cached during operation

Error Handling

All KV operations use graceful degradation:

// KV failures don't break cache operations
await cache.set(key, data); // Succeeds even if KV registration fails
await cache.delete(key);    // Succeeds even if KV unregistration fails

// Pattern operations return 0 on KV failures
const count = await cache.invalidatePattern('*pattern*');
// Returns 0 if KV list fails, logs error

Monitoring

Log Levels:

• DEBUG: Cache hits/misses, KV operations
• INFO: Pattern invalidation results, clear operations
• WARN: KV not available, unsupported operations
• ERROR: KV failures (non-blocking)

Key Metrics:

const stats = await cache.getStats();
// { supported: true, indexed_keys: 42 }

Best Practices

1. Enable KV Index in Production: Pass env.RATE_LIMIT_KV for full functionality
2. Use Pattern Invalidation: Prefer invalidatePattern() over individual delete() calls
3. Monitor Stats: Use getStats() to track cache size
4. Prefix Organization: Use consistent URL prefixes for easy filtering
5. Handle Failures: Always check return values from invalidation operations

Limitations

• KV Eventual Consistency: Recent writes may not appear immediately in list operations
• Pattern Matching: Done in-memory after KV list (not server-side)
• Large Caches: >1000 keys may have higher latency for pattern operations
• No Dedicated Namespace: Currently reuses RATE_LIMIT_KV (future: add CACHE_INDEX_KV)

Future Enhancements

• Dedicated CACHE_INDEX_KV namespace
• Server-side pattern filtering
• Batch invalidation optimization
• Cache warming strategies
• Advanced statistics (hit rate, size, etc.)