cache-utils.ts•10.6 kB
/**
* Cache utilities for flexible instance configuration
* Provides hash creation, metrics tracking, and cache configuration
*/
import { createHash } from 'crypto';
import { LRUCache } from 'lru-cache';
import { logger } from './logger';
/**
* Cache metrics for monitoring and optimization
*/
export interface CacheMetrics {
hits: number;
misses: number;
evictions: number;
sets: number;
deletes: number;
clears: number;
size: number;
maxSize: number;
avgHitRate: number;
createdAt: Date;
lastResetAt: Date;
}
/**
* Cache configuration options
*/
export interface CacheConfig {
max: number;
ttlMinutes: number;
}
/**
* Simple memoization cache for hash results
* Limited size to prevent memory growth
*/
const hashMemoCache = new Map<string, string>();
const MAX_MEMO_SIZE = 1000;
/**
* Metrics tracking for cache operations
*/
class CacheMetricsTracker {
private metrics!: CacheMetrics;
private startTime: Date;
constructor() {
this.startTime = new Date();
this.reset();
}
/**
* Reset all metrics to initial state
*/
reset(): void {
this.metrics = {
hits: 0,
misses: 0,
evictions: 0,
sets: 0,
deletes: 0,
clears: 0,
size: 0,
maxSize: 0,
avgHitRate: 0,
createdAt: this.startTime,
lastResetAt: new Date()
};
}
/**
* Record a cache hit
*/
recordHit(): void {
this.metrics.hits++;
this.updateHitRate();
}
/**
* Record a cache miss
*/
recordMiss(): void {
this.metrics.misses++;
this.updateHitRate();
}
/**
* Record a cache eviction
*/
recordEviction(): void {
this.metrics.evictions++;
}
/**
* Record a cache set operation
*/
recordSet(): void {
this.metrics.sets++;
}
/**
* Record a cache delete operation
*/
recordDelete(): void {
this.metrics.deletes++;
}
/**
* Record a cache clear operation
*/
recordClear(): void {
this.metrics.clears++;
}
/**
* Update cache size metrics
*/
updateSize(current: number, max: number): void {
this.metrics.size = current;
this.metrics.maxSize = max;
}
/**
* Update average hit rate
*/
private updateHitRate(): void {
const total = this.metrics.hits + this.metrics.misses;
if (total > 0) {
this.metrics.avgHitRate = this.metrics.hits / total;
}
}
/**
* Get current metrics snapshot
*/
getMetrics(): CacheMetrics {
return { ...this.metrics };
}
/**
* Get formatted metrics for logging
*/
getFormattedMetrics(): string {
const { hits, misses, evictions, avgHitRate, size, maxSize } = this.metrics;
return `Cache Metrics: Hits=${hits}, Misses=${misses}, HitRate=${(avgHitRate * 100).toFixed(2)}%, Size=${size}/${maxSize}, Evictions=${evictions}`;
}
}
// Global metrics tracker instance
export const cacheMetrics = new CacheMetricsTracker();
/**
* Get cache configuration from environment variables or defaults
* @returns Cache configuration with max size and TTL
*/
export function getCacheConfig(): CacheConfig {
const max = parseInt(process.env.INSTANCE_CACHE_MAX || '100', 10);
const ttlMinutes = parseInt(process.env.INSTANCE_CACHE_TTL_MINUTES || '30', 10);
// Validate configuration bounds
const validatedMax = Math.max(1, Math.min(10000, max)) || 100;
const validatedTtl = Math.max(1, Math.min(1440, ttlMinutes)) || 30; // Max 24 hours
if (validatedMax !== max || validatedTtl !== ttlMinutes) {
logger.warn('Cache configuration adjusted to valid bounds', {
requestedMax: max,
requestedTtl: ttlMinutes,
actualMax: validatedMax,
actualTtl: validatedTtl
});
}
return {
max: validatedMax,
ttlMinutes: validatedTtl
};
}
/**
* Create a secure hash for cache key with memoization
* @param input - The input string to hash
* @returns SHA-256 hash as hex string
*/
export function createCacheKey(input: string): string {
// Check memoization cache first
if (hashMemoCache.has(input)) {
return hashMemoCache.get(input)!;
}
// Create hash
const hash = createHash('sha256').update(input).digest('hex');
// Add to memoization cache with size limit
if (hashMemoCache.size >= MAX_MEMO_SIZE) {
// Remove oldest entries (simple FIFO)
const firstKey = hashMemoCache.keys().next().value;
if (firstKey) {
hashMemoCache.delete(firstKey);
}
}
hashMemoCache.set(input, hash);
return hash;
}
/**
* Create LRU cache with metrics tracking
* @param onDispose - Optional callback for when items are evicted
* @returns Configured LRU cache instance
*/
export function createInstanceCache<T extends {}>(
onDispose?: (value: T, key: string) => void
): LRUCache<string, T> {
const config = getCacheConfig();
return new LRUCache<string, T>({
max: config.max,
ttl: config.ttlMinutes * 60 * 1000, // Convert to milliseconds
updateAgeOnGet: true,
dispose: (value, key) => {
cacheMetrics.recordEviction();
if (onDispose) {
onDispose(value, key);
}
logger.debug('Cache eviction', {
cacheKey: key.substring(0, 8) + '...',
metrics: cacheMetrics.getFormattedMetrics()
});
}
});
}
/**
* Mutex implementation for cache operations
* Prevents race conditions during concurrent access
*/
export class CacheMutex {
private locks: Map<string, Promise<void>> = new Map();
private lockTimeouts: Map<string, NodeJS.Timeout> = new Map();
private readonly timeout: number = 5000; // 5 second timeout
/**
* Acquire a lock for the given key
* @param key - The cache key to lock
* @returns Promise that resolves when lock is acquired
*/
async acquire(key: string): Promise<() => void> {
while (this.locks.has(key)) {
try {
await this.locks.get(key);
} catch {
// Previous lock failed, we can proceed
}
}
let releaseLock: () => void;
const lockPromise = new Promise<void>((resolve) => {
releaseLock = () => {
resolve();
this.locks.delete(key);
const timeout = this.lockTimeouts.get(key);
if (timeout) {
clearTimeout(timeout);
this.lockTimeouts.delete(key);
}
};
});
this.locks.set(key, lockPromise);
// Set timeout to prevent stuck locks
const timeout = setTimeout(() => {
logger.warn('Cache lock timeout, forcefully releasing', { key: key.substring(0, 8) + '...' });
releaseLock!();
}, this.timeout);
this.lockTimeouts.set(key, timeout);
return releaseLock!;
}
/**
* Check if a key is currently locked
* @param key - The cache key to check
* @returns True if the key is locked
*/
isLocked(key: string): boolean {
return this.locks.has(key);
}
/**
* Clear all locks (use with caution)
*/
clearAll(): void {
this.lockTimeouts.forEach(timeout => clearTimeout(timeout));
this.locks.clear();
this.lockTimeouts.clear();
}
}
/**
* Retry configuration for API operations
*/
export interface RetryConfig {
maxAttempts: number;
baseDelayMs: number;
maxDelayMs: number;
jitterFactor: number;
}
/**
* Default retry configuration
*/
export const DEFAULT_RETRY_CONFIG: RetryConfig = {
maxAttempts: 3,
baseDelayMs: 1000,
maxDelayMs: 10000,
jitterFactor: 0.3
};
/**
* Calculate exponential backoff delay with jitter
* @param attempt - Current attempt number (0-based)
* @param config - Retry configuration
* @returns Delay in milliseconds
*/
export function calculateBackoffDelay(attempt: number, config: RetryConfig = DEFAULT_RETRY_CONFIG): number {
const exponentialDelay = Math.min(
config.baseDelayMs * Math.pow(2, attempt),
config.maxDelayMs
);
// Add jitter to prevent thundering herd
const jitter = exponentialDelay * config.jitterFactor * Math.random();
return Math.floor(exponentialDelay + jitter);
}
/**
* Execute function with retry logic
* @param fn - Function to execute
* @param config - Retry configuration
* @param context - Optional context for logging
* @returns Result of the function
*/
export async function withRetry<T>(
fn: () => Promise<T>,
config: RetryConfig = DEFAULT_RETRY_CONFIG,
context?: string
): Promise<T> {
let lastError: Error;
for (let attempt = 0; attempt < config.maxAttempts; attempt++) {
try {
return await fn();
} catch (error) {
lastError = error as Error;
// Check if error is retryable
if (!isRetryableError(error)) {
throw error;
}
if (attempt < config.maxAttempts - 1) {
const delay = calculateBackoffDelay(attempt, config);
logger.debug('Retrying operation after delay', {
context,
attempt: attempt + 1,
maxAttempts: config.maxAttempts,
delayMs: delay,
error: lastError.message
});
await new Promise(resolve => setTimeout(resolve, delay));
}
}
}
logger.error('All retry attempts exhausted', {
context,
attempts: config.maxAttempts,
lastError: lastError!.message
});
throw lastError!;
}
/**
* Check if an error is retryable
* @param error - The error to check
* @returns True if the error is retryable
*/
function isRetryableError(error: any): boolean {
// Network errors
if (error.code === 'ECONNREFUSED' ||
error.code === 'ECONNRESET' ||
error.code === 'ETIMEDOUT' ||
error.code === 'ENOTFOUND') {
return true;
}
// HTTP status codes that are retryable
if (error.response?.status) {
const status = error.response.status;
return status === 429 || // Too Many Requests
status === 503 || // Service Unavailable
status === 504 || // Gateway Timeout
(status >= 500 && status < 600); // Server errors
}
// Timeout errors
if (error.message && error.message.toLowerCase().includes('timeout')) {
return true;
}
return false;
}
/**
* Format cache statistics for logging or display
* @returns Formatted statistics string
*/
export function getCacheStatistics(): string {
const metrics = cacheMetrics.getMetrics();
const runtime = Date.now() - metrics.createdAt.getTime();
const runtimeMinutes = Math.floor(runtime / 60000);
return `
Cache Statistics:
Runtime: ${runtimeMinutes} minutes
Total Operations: ${metrics.hits + metrics.misses}
Hit Rate: ${(metrics.avgHitRate * 100).toFixed(2)}%
Current Size: ${metrics.size}/${metrics.maxSize}
Total Evictions: ${metrics.evictions}
Sets: ${metrics.sets}, Deletes: ${metrics.deletes}, Clears: ${metrics.clears}
`.trim();
}