bunsane 0.1.4 → 0.2.0

package/core/cache/CacheWarmer.ts

@@ -0,0 +1,157 @@
+import { CacheManager } from './CacheManager.js';
+import { SchedulerManager } from '../SchedulerManager.js';
+
+/**
+ * CacheWarmer preloads frequently accessed data into the cache to improve
+ * application startup performance and reduce initial request latency.
+ *
+ * Features:
+ * - Preloading of frequently accessed entities
+ * - Scheduled cache warming with cron support
+ * - Configurable warming strategies
+ * - Performance monitoring during warming
+ */
+export class CacheWarmer {
+  private cacheManager: CacheManager;
+  private scheduler: SchedulerManager;
+  private warmingJobs: Map<string, { cancel: () => void }> = new Map();
+
+  constructor(cacheManager: CacheManager, scheduler: SchedulerManager) {
+    this.cacheManager = cacheManager;
+    this.scheduler = scheduler;
+  }
+
+  /**
+   * Warms the cache by preloading frequently accessed entities
+   */
+  async warmEntityCache(entityIds: string[], entityType: string): Promise<{
+    success: boolean;
+    warmed: number;
+    failed: number;
+    duration: number;
+  }> {
+    const startTime = Date.now();
+    let warmed = 0;
+    let failed = 0;
+
+    console.log(`Starting entity cache warming for ${entityIds.length} ${entityType} entities`);
+
+    // Process entities in batches to avoid overwhelming the database
+    const batchSize = 10;
+    for (let i = 0; i < entityIds.length; i += batchSize) {
+      const batch = entityIds.slice(i, i + batchSize);
+
+      try {
+        // Load entities (this will populate the cache via write-through strategy)
+        const entities = await this.loadEntitiesBatch(batch, entityType);
+        warmed += entities.length;
+      } catch (error) {
+        console.warn(`Failed to warm batch of entities:`, error);
+        failed += batch.length;
+      }
+
+      // Small delay between batches to prevent database overload
+      await new Promise(resolve => setTimeout(resolve, 50));
+    }
+
+    const duration = Date.now() - startTime;
+    console.log(`Entity cache warming completed: ${warmed} warmed, ${failed} failed in ${duration}ms`);
+
+    return { success: failed === 0, warmed, failed, duration };
+  }
+
+  /**
+   * Schedules periodic cache warming
+   */
+  scheduleWarming(config: {
+    name: string;
+    cronExpression: string;
+    type: 'entity';
+    config: { entityIds: string[]; entityType: string };
+    enabled?: boolean;
+  }): void {
+    if (!config.enabled) {
+      console.log(`Cache warming job "${config.name}" is disabled`);
+      return;
+    }
+
+    // Cancel existing job if it exists
+    this.cancelWarming(config.name);
+
+    const job = this.scheduler.scheduleJob(config.name, config.cronExpression, async () => {
+      try {
+        console.log(`Running scheduled cache warming: ${config.name}`);
+
+        if (config.type === 'entity') {
+          await this.warmEntityCache(config.config.entityIds, config.config.entityType);
+        }
+      } catch (error) {
+        console.error(`Scheduled cache warming failed for "${config.name}":`, error);
+      }
+    });
+
+    this.warmingJobs.set(config.name, job);
+    console.log(`Scheduled cache warming job "${config.name}" with cron: ${config.cronExpression}`);
+  }
+
+  /**
+   * Cancels a scheduled warming job
+   */
+  cancelWarming(name: string): boolean {
+    const job = this.warmingJobs.get(name);
+    if (job) {
+      job.cancel();
+      this.warmingJobs.delete(name);
+      console.log(`Cancelled cache warming job: ${name}`);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Gets list of active warming jobs
+   */
+  getActiveJobs(): string[] {
+    return Array.from(this.warmingJobs.keys());
+  }
+
+  /**
+   * Performs a comprehensive cache warming operation
+   */
+  async warmAll(config: {
+    entities?: Array<{ entityIds: string[]; entityType: string }>;
+  }): Promise<{
+    entities: { success: boolean; warmed: number; failed: number; duration: number };
+    totalDuration: number;
+  }> {
+    const startTime = Date.now();
+
+    // Warm entities
+    const firstEntity = config.entities?.[0];
+    const entityResults = firstEntity
+      ? await this.warmEntityCache(firstEntity.entityIds, firstEntity.entityType)
+      : { success: true, warmed: 0, failed: 0, duration: 0 };
+
+    const totalDuration = Date.now() - startTime;
+
+    return {
+      entities: entityResults,
+      totalDuration
+    };
+  }
+
+  /**
+   * Loads a batch of entities (placeholder - would need actual entity loading logic)
+   */
+  private async loadEntitiesBatch(entityIds: string[], entityType: string): Promise<any[]> {
+    // This is a placeholder - in a real implementation, this would load entities
+    // from the database using the appropriate entity manager or query system
+    console.log(`Loading batch of ${entityIds.length} ${entityType} entities: ${entityIds.slice(0, 3).join(', ')}...`);
+
+    // Simulate loading delay
+    await new Promise(resolve => setTimeout(resolve, 10));
+
+    // Return mock entities - in real implementation, this would be actual entity data
+    return entityIds.map(id => ({ id, type: entityType, loaded: true }));
+  }
+}

package/core/cache/CompressionUtils.ts

@@ -0,0 +1,110 @@
+import { gzip, gunzip } from 'zlib';
+import { promisify } from 'util';
+
+const gzipAsync = promisify(gzip);
+const gunzipAsync = promisify(gunzip);
+
+/**
+ * Compression utilities for cache payloads. Automatically compresses data
+ * over 1KB threshold to reduce memory usage and network transfer for Redis.
+ *
+ * Features:
+ * - Gzip compression for payloads > 1KB
+ * - Automatic compression/decompression
+ * - Metadata tracking for compressed data
+ * - Error handling with fallback to uncompressed data
+ */
+export class CompressionUtils {
+  private static readonly COMPRESSION_THRESHOLD = 1024; // 1KB
+  private static readonly COMPRESSION_PREFIX = '__COMPRESSED__';
+
+  /**
+   * Compresses data if it exceeds the threshold size
+   */
+  static async compress(data: any): Promise<any> {
+    try {
+      const serialized = JSON.stringify(data);
+      const size = Buffer.byteLength(serialized, 'utf8');
+
+      if (size <= this.COMPRESSION_THRESHOLD) {
+        return data; // No compression needed
+      }
+
+      const compressed = await gzipAsync(serialized);
+      const compressedData = compressed.toString('base64');
+
+      // Return compressed data with metadata
+      return {
+        [this.COMPRESSION_PREFIX]: true,
+        data: compressedData,
+        originalSize: size,
+        compressedSize: compressed.length
+      };
+    } catch (error) {
+      // Fallback to uncompressed data on compression error
+      console.warn('Compression failed, using uncompressed data:', error);
+      return data;
+    }
+  }
+
+  /**
+   * Decompresses data if it was previously compressed
+   */
+  static async decompress(data: any): Promise<any> {
+    try {
+      // Check if data is compressed
+      if (typeof data === 'object' && data !== null && data[this.COMPRESSION_PREFIX]) {
+        const compressedBuffer = Buffer.from(data.data, 'base64');
+        const decompressed = await gunzipAsync(compressedBuffer);
+        return JSON.parse(decompressed.toString('utf8'));
+      }
+
+      // Data is not compressed
+      return data;
+    } catch (error) {
+      // Fallback to original data on decompression error
+      console.warn('Decompression failed, using original data:', error);
+      return data;
+    }
+  }
+
+  /**
+   * Checks if data is compressed
+   */
+  static isCompressed(data: any): boolean {
+    return typeof data === 'object' && data !== null && data[this.COMPRESSION_PREFIX] === true;
+  }
+
+  /**
+   * Gets compression statistics for monitoring
+   */
+  static getCompressionStats(data: any): { compressed: boolean; originalSize?: number; compressedSize?: number; ratio?: number } {
+    if (this.isCompressed(data)) {
+      const originalSize = data.originalSize;
+      const compressedSize = data.compressedSize;
+      const ratio = originalSize > 0 ? compressedSize / originalSize : 0;
+
+      return {
+        compressed: true,
+        originalSize,
+        compressedSize,
+        ratio
+      };
+    }
+
+    return { compressed: false };
+  }
+
+  /**
+   * Estimates if data would benefit from compression
+   */
+  static shouldCompress(data: any): boolean {
+    try {
+      const serialized = JSON.stringify(data);
+      const size = Buffer.byteLength(serialized, 'utf8');
+      return size > this.COMPRESSION_THRESHOLD;
+    } catch {
+      return false;
+    }
+  }
+}

package/core/cache/MemoryCache.ts

@@ -0,0 +1,251 @@
+import { type CacheProvider, type CacheStats } from './CacheProvider';
+import { logger } from '../Logger';
+
+interface CacheEntry<T> {
+    value: T;
+    expiresAt?: number;
+    lastAccessed: number;
+    accessCount: number;
+}
+
+export interface MemoryCacheConfig {
+    maxSize?: number; // Maximum number of entries
+    maxMemory?: number; // Maximum memory usage in bytes
+    defaultTTL?: number; // Default TTL in milliseconds
+    cleanupInterval?: number; // Cleanup interval in milliseconds
+}
+
+/**
+ * In-memory cache implementation with TTL and LRU eviction
+ */
+export class MemoryCache implements CacheProvider {
+    private cache = new Map<string, CacheEntry<any>>();
+    private config: Required<MemoryCacheConfig>;
+    private cleanupTimer?: Timer;
+    private stats = {
+        hits: 0,
+        misses: 0,
+        size: 0,
+        memoryUsage: 0
+    };
+    private accessCounter = 0; // For LRU ordering
+
+    constructor(config: MemoryCacheConfig = {}) {
+        this.config = {
+            maxSize: config.maxSize ?? 10000,
+            maxMemory: config.maxMemory ?? 100 * 1024 * 1024, // 100MB default
+            defaultTTL: config.defaultTTL ?? 3600000, // 1 hour default
+            cleanupInterval: config.cleanupInterval ?? 60000 // 1 minute default
+        };
+
+        this.startCleanupTimer();
+    }
+
+    async get<T>(key: string): Promise<T | null> {
+        const entry = this.cache.get(key);
+
+        if (!entry) {
+            this.stats.misses++;
+            return null;
+        }
+
+        // Check if expired
+        if (entry.expiresAt && Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            this.stats.misses++;
+            this.updateMemoryUsage();
+            return null;
+        }
+
+        // Update access tracking for LRU
+        entry.lastAccessed = ++this.accessCounter;
+        entry.accessCount++;
+
+        this.stats.hits++;
+        return entry.value;
+    }
+
+    async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+        const expiresAt = ttl ? Date.now() + ttl : (this.config.defaultTTL ? Date.now() + this.config.defaultTTL : undefined);
+
+        const entry: CacheEntry<T> = {
+            value,
+            expiresAt,
+            lastAccessed: ++this.accessCounter,
+            accessCount: 1
+        };
+
+        const wasNew = !this.cache.has(key);
+        this.cache.set(key, entry);
+
+        if (wasNew) {
+            this.stats.size++;
+        }
+
+        this.updateMemoryUsage();
+
+        // Evict if necessary
+        await this.evictIfNeeded();
+    }
+
+    async delete(key: string | string[]): Promise<void> {
+        const keys = Array.isArray(key) ? key : [key];
+        let deletedCount = 0;
+
+        for (const k of keys) {
+            if (this.cache.delete(k)) {
+                deletedCount++;
+            }
+        }
+
+        this.stats.size -= deletedCount;
+        this.updateMemoryUsage();
+    }
+
+    async clear(): Promise<void> {
+        this.cache.clear();
+        this.stats.size = 0;
+        this.stats.memoryUsage = 0;
+        this.stats.hits = 0;
+        this.stats.misses = 0;
+    }
+
+    async getMany<T>(keys: string[]): Promise<(T | null)[]> {
+        const results: (T | null)[] = [];
+
+        for (const key of keys) {
+            const value = await this.get<T>(key);
+            results.push(value);
+        }
+
+        return results;
+    }
+
+    async setMany<T>(entries: Array<{key: string, value: T, ttl?: number}>): Promise<void> {
+        for (const entry of entries) {
+            await this.set(entry.key, entry.value, entry.ttl);
+        }
+    }
+
+    async deleteMany(keys: string[]): Promise<void> {
+        return this.delete(keys);
+    }
+
+    async invalidatePattern(pattern: string): Promise<void> {
+        // Simple pattern matching - convert glob to regex
+        const regex = new RegExp(pattern.replace(/\*/g, '.*').replace(/\?/g, '.'));
+
+        const keysToDelete: string[] = [];
+        for (const key of Array.from(this.cache.keys())) {
+            if (regex.test(key)) {
+                keysToDelete.push(key);
+            }
+        }
+
+        await this.delete(keysToDelete);
+    }
+
+    async ping(): Promise<boolean> {
+        return true; // Memory cache is always available
+    }
+
+    async getStats(): Promise<CacheStats> {
+        const totalRequests = this.stats.hits + this.stats.misses;
+        const hitRate = totalRequests > 0 ? this.stats.hits / totalRequests : 0;
+
+        return {
+            hits: this.stats.hits,
+            misses: this.stats.misses,
+            hitRate,
+            size: this.stats.size,
+            memoryUsage: this.stats.memoryUsage
+        };
+    }
+
+    private updateMemoryUsage(): void {
+        // Rough estimation of memory usage
+        // Each entry has overhead for the key, value, and metadata
+        let memoryUsage = 0;
+        for (const [key, entry] of Array.from(this.cache.entries())) {
+            memoryUsage += key.length * 2; // Rough string overhead
+            memoryUsage += this.estimateValueSize(entry.value);
+            memoryUsage += 100; // Overhead for entry metadata
+        }
+        this.stats.memoryUsage = memoryUsage;
+    }
+
+    private estimateValueSize(value: any): number {
+        if (value === null || value === undefined) return 8;
+        if (typeof value === 'string') return value.length * 2;
+        if (typeof value === 'number') return 8;
+        if (typeof value === 'boolean') return 1;
+        if (Array.isArray(value)) {
+            return value.reduce((size, item) => size + this.estimateValueSize(item), 16); // Array overhead
+        }
+        if (typeof value === 'object') {
+            let size = 16; // Object overhead
+            for (const key in value) {
+                size += key.length * 2 + this.estimateValueSize(value[key]);
+            }
+            return size;
+        }
+        return 16; // Default size for other types
+    }
+
+    private async evictIfNeeded(): Promise<void> {
+        // Check size limit
+        if (this.stats.size > this.config.maxSize) {
+            await this.evictLRU(Math.ceil(this.config.maxSize * 0.1)); // Evict 10% of max size
+        }
+
+        // Check memory limit
+        if (this.stats.memoryUsage > this.config.maxMemory) {
+            await this.evictLRU(Math.ceil(this.config.maxSize * 0.1)); // Evict 10% of max size
+        }
+    }
+
+    private async evictLRU(count: number): Promise<void> {
+        // Sort entries by last accessed time (oldest first)
+        const entries = Array.from(this.cache.entries())
+            .map(([key, entry]) => ({ key, entry }))
+            .sort((a, b) => a.entry.lastAccessed - b.entry.lastAccessed);
+
+        const keysToDelete = entries.slice(0, count).map(item => item.key);
+        await this.delete(keysToDelete);
+
+        logger.debug(`Evicted ${keysToDelete.length} entries from cache due to LRU policy`);
+    }
+
+    private startCleanupTimer(): void {
+        this.cleanupTimer = setInterval(() => {
+            this.cleanupExpired();
+        }, this.config.cleanupInterval);
+    }
+
+    private cleanupExpired(): void {
+        const now = Date.now();
+        const keysToDelete: string[] = [];
+
+        for (const [key, entry] of Array.from(this.cache.entries())) {
+            if (entry.expiresAt && now > entry.expiresAt) {
+                keysToDelete.push(key);
+            }
+        }
+
+        if (keysToDelete.length > 0) {
+            this.delete(keysToDelete).catch(error => {
+                logger.error('Error during cache cleanup:', error);
+            });
+        }
+    }
+
+    /**
+     * Stop the cleanup timer (useful for testing or shutdown)
+     */
+    stopCleanup(): void {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+    }
+}

package/core/cache/MultiLevelCache.ts

@@ -0,0 +1,180 @@
+import type { CacheProvider, CacheStats } from './CacheProvider.js';
+import type { CacheConfig } from '../../config/cache.config.js';
+
+/**
+ * MultiLevelCache implements a two-tier caching strategy with L1 in-memory cache
+ * and L2 persistent cache (Redis). This provides optimal performance by serving
+ * frequently accessed data from memory while maintaining persistence across requests.
+ *
+ * Key Features:
+ * - L1 MemoryCache for fast access to hot data
+ * - L2 RedisCache for persistence and cross-instance sharing
+ * - Automatic L1 promotion on L2 cache hits
+ * - Configurable TTL strategies for each level
+ * - Write-through strategy for data consistency
+ */
+export class MultiLevelCache implements CacheProvider {
+  private l1Cache: CacheProvider;
+  private l2Cache: CacheProvider | null;
+  private config: CacheConfig;
+
+  constructor(l1Cache: CacheProvider, l2Cache: CacheProvider | null, config: CacheConfig) {
+    this.l1Cache = l1Cache;
+    this.l2Cache = l2Cache;
+    this.config = config;
+  }
+
+  getL1Cache(): CacheProvider {
+    return this.l1Cache;
+  }
+
+  getL2Cache(): CacheProvider | null {
+    return this.l2Cache;
+  }
+
+  async get(key: string): Promise<any | null> {
+    // Try L1 cache first
+    const l1Result = await this.l1Cache.get(key);
+    if (l1Result !== null) {
+      return l1Result;
+    }
+
+    // If L1 miss and L2 exists, try L2
+    if (this.l2Cache) {
+      const l2Result = await this.l2Cache.get(key);
+      if (l2Result !== null) {
+        // Promote to L1 cache for faster future access
+        await this.l1Cache.set(key, l2Result, this.config.defaultTTL);
+        return l2Result;
+      }
+    }
+
+    return null;
+  }
+
+  async set(key: string, value: any, ttl?: number): Promise<void> {
+    const effectiveTTL = ttl || this.config.defaultTTL;
+
+    // Set in L1 cache
+    await this.l1Cache.set(key, value, effectiveTTL);
+
+    // Set in L2 cache if available
+    if (this.l2Cache) {
+      await this.l2Cache.set(key, value, effectiveTTL);
+    }
+  }
+
+  async delete(key: string | string[]): Promise<void> {
+    // Delete from L1 cache
+    await this.l1Cache.delete(key);
+
+    // Delete from L2 cache if available
+    if (this.l2Cache) {
+      await this.l2Cache.delete(key);
+    }
+  }
+
+  async clear(): Promise<void> {
+    await this.l1Cache.clear();
+    if (this.l2Cache) {
+      await this.l2Cache.clear();
+    }
+  }
+
+  async getMany<T>(keys: string[]): Promise<(T | null)[]> {
+    const results: (T | null)[] = new Array(keys.length).fill(null);
+    const missingIndices: number[] = [];
+    const missingKeys: string[] = [];
+
+    // Try L1 cache first
+    const l1Results = await this.l1Cache.getMany<T>(keys);
+    for (let i = 0; i < keys.length; i++) {
+      const l1Value = l1Results[i];
+      const key = keys[i];
+      if (l1Value !== null && l1Value !== undefined) {
+        results[i] = l1Value;
+      } else if (key !== undefined) {
+        missingIndices.push(i);
+        missingKeys.push(key);
+      }
+    }
+
+    // If L2 exists and we have missing keys, try L2
+    if (this.l2Cache && missingKeys.length > 0) {
+      const l2Results = await this.l2Cache.getMany<T>(missingKeys);
+      for (let i = 0; i < missingKeys.length; i++) {
+        const value = l2Results[i];
+        const originalIndex = missingIndices[i];
+        const missingKey = missingKeys[i];
+        if (value !== null && value !== undefined && originalIndex !== undefined && missingKey !== undefined) {
+          results[originalIndex] = value;
+          // Promote to L1 cache
+          await this.l1Cache.set(missingKey, value, this.config.defaultTTL);
+        }
+      }
+    }
+
+    return results;
+  }
+
+  async setMany<T>(entries: Array<{key: string, value: T, ttl?: number}>): Promise<void> {
+    // Apply default TTL to entries without one
+    const entriesWithTTL = entries.map(e => ({
+      ...e,
+      ttl: e.ttl || this.config.defaultTTL
+    }));
+
+    // Set in L1 cache
+    await this.l1Cache.setMany(entriesWithTTL);
+
+    // Set in L2 cache if available
+    if (this.l2Cache) {
+      await this.l2Cache.setMany(entriesWithTTL);
+    }
+  }
+
+  async deleteMany(keys: string[]): Promise<void> {
+    await this.l1Cache.deleteMany(keys);
+    if (this.l2Cache) {
+      await this.l2Cache.deleteMany(keys);
+    }
+  }
+
+  async invalidatePattern(pattern: string): Promise<void> {
+    await this.l1Cache.invalidatePattern(pattern);
+    if (this.l2Cache) {
+      await this.l2Cache.invalidatePattern(pattern);
+    }
+  }
+
+  async ping(): Promise<boolean> {
+    const l1Ping = await this.l1Cache.ping();
+
+    if (!this.l2Cache) {
+      return l1Ping;
+    }
+
+    const l2Ping = await this.l2Cache.ping();
+
+    // Multi-level cache is healthy if both levels are healthy
+    return l1Ping && l2Ping;
+  }
+
+  async getStats(): Promise<CacheStats> {
+    const l1Stats = await this.l1Cache.getStats();
+    const l2Stats = this.l2Cache ? await this.l2Cache.getStats() : null;
+
+    const totalHits = l1Stats.hits + (l2Stats?.hits || 0);
+    const totalMisses = l1Stats.misses + (l2Stats?.misses || 0);
+    const totalRequests = totalHits + totalMisses;
+    const hitRate = totalRequests > 0 ? totalHits / totalRequests : 0;
+
+    return {
+      hits: totalHits,
+      misses: totalMisses,
+      hitRate,
+      size: l1Stats.size + (l2Stats?.size || 0),
+      memoryUsage: (l1Stats.memoryUsage || 0) + (l2Stats?.memoryUsage || 0)
+    };
+  }
+}