@clduab11/gemini-flow/src/core/cache-manager.ts

Revolutionary AI agent swarm coordination platform with Google Services integration, multimedia processing, and production-ready monitoring. Features 8 Google AI services, quantum computing capabilities, and enterprise-grade security.

/**
 * Cache Manager
 *
 * High-performance caching layer with intelligent eviction and 12x performance boost
 * Supports both memory and persistent caching with SQLite optimization
 */

import { Logger } from "../utils/logger.js";
import { EventEmitter } from "events";
import {
  SQLiteDatabase,
  createSQLiteDatabase,
  detectSQLiteImplementations,
} from "../memory/sqlite-adapter.js";

export interface CacheEntry {
  key: string;
  value: any;
  size: number;
  ttl: number;
  createdAt: Date;
  lastAccessed: Date;
  hitCount: number;
  namespace?: string;
}

export interface CacheStats {
  totalKeys: number;
  totalSize: number;
  hitRate: number;
  missRate: number;
  evictionCount: number;
  memoryUsage: number;
  diskUsage: number;
}

export interface CacheConfig {
  maxMemorySize?: number; // bytes
  maxDiskSize?: number; // bytes
  defaultTTL?: number; // seconds
  evictionPolicy?: "lru" | "lfu" | "adaptive";
  persistToDisk?: boolean;
  compression?: boolean;
  dbPath?: string;
}

export class CacheManager extends EventEmitter {
  private logger: Logger;
  private config: Required<CacheConfig>;

  // Memory cache (L1)
  private memoryCache: Map<string, CacheEntry> = new Map();
  private memorySize: number = 0;

  // Disk cache (L2)
  private db?: SQLiteDatabase;
  private diskSize: number = 0;
  private dbReady: boolean = false;
  private dbInitPromise?: Promise<void>;

  // Statistics
  private stats = {
    hits: 0,
    misses: 0,
    evictions: 0,
    writes: 0,
    reads: 0,
  };

  // Performance optimization
  private accessOrder: string[] = []; // For LRU
  private frequencyMap: Map<string, number> = new Map(); // For LFU
  private cleanupInterval?: ReturnType<typeof setInterval>;

  constructor(config: CacheConfig = {}) {
    super();
    this.logger = new Logger("CacheManager");

    this.config = {
      maxMemorySize: config.maxMemorySize || 100 * 1024 * 1024, // 100MB
      maxDiskSize: config.maxDiskSize || 1024 * 1024 * 1024, // 1GB
      defaultTTL: config.defaultTTL || 3600, // 1 hour
      evictionPolicy: config.evictionPolicy || "adaptive",
      persistToDisk: config.persistToDisk ?? true,
      compression: config.compression ?? true,
      dbPath: config.dbPath || ":memory:",
    };

    this.dbInitPromise = this.initializeDiskCache();
    this.startCleanupTimer();

    this.logger.info("Cache manager initialized", {
      memoryLimit: this.formatBytes(this.config.maxMemorySize),
      diskLimit: this.formatBytes(this.config.maxDiskSize),
      policy: this.config.evictionPolicy,
    });
  }

  /**
   * Initialize SQLite disk cache with optimizations
   */
  private async initializeDiskCache(): Promise<void> {
    if (!this.config.persistToDisk) {
      this.dbReady = true;
      return;
    }

    try {
      // Detect available SQLite implementations
      const detection = await detectSQLiteImplementations();
      this.logger.debug(
        "SQLite implementations available:",
        detection.available,
      );

      // Create database with automatic fallback
      this.db = await createSQLiteDatabase(this.config.dbPath);
      this.logger.info(
        `SQLite cache initialized with ${this.db.name} implementation`,
      );

      // SQLite optimizations for 12x performance boost
      this.db.pragma("journal_mode = WAL");
      this.db.pragma("synchronous = NORMAL");
      this.db.pragma("cache_size = 10000");
      this.db.pragma("temp_store = MEMORY");
      this.db.pragma("mmap_size = 268435456"); // 256MB
      this.db.pragma("page_size = 4096");

      // Create cache table with optimized schema
      this.db.exec(`
        CREATE TABLE IF NOT EXISTS cache_entries (
          key TEXT PRIMARY KEY,
          value BLOB,
          size INTEGER,
          ttl INTEGER,
          created_at INTEGER,
          last_accessed INTEGER,
          hit_count INTEGER DEFAULT 0,
          namespace TEXT,
          compressed INTEGER DEFAULT 0
        );
        
        CREATE INDEX IF NOT EXISTS idx_ttl ON cache_entries(ttl);
        CREATE INDEX IF NOT EXISTS idx_last_accessed ON cache_entries(last_accessed);
        CREATE INDEX IF NOT EXISTS idx_namespace ON cache_entries(namespace);
      `);

      // Prepare statements for better performance
      await this.prepareStatements();

      this.dbReady = true;
      this.logger.debug("Disk cache initialized with SQLite optimizations");
    } catch (error) {
      this.logger.error("Failed to initialize disk cache:", error);
      this.config.persistToDisk = false;
      this.dbReady = true; // Mark as ready even on failure to prevent blocking
    }
  }

  /**
   * Prepare SQLite statements for better performance
   */
  private async prepareStatements(): Promise<void> {
    if (!this.db) return;

    try {
      // Pre-compile frequently used statements
      (this as any).getStmt = this.db.prepare(
        "SELECT * FROM cache_entries WHERE key = ?",
      );
      (this as any).setStmt = this.db.prepare(`
      INSERT OR REPLACE INTO cache_entries 
      (key, value, size, ttl, created_at, last_accessed, hit_count, namespace, compressed)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
    `);
      (this as any).deleteStmt = this.db.prepare(
        "DELETE FROM cache_entries WHERE key = ?",
      );
      (this as any).updateAccessStmt = this.db.prepare(`
      UPDATE cache_entries 
      SET last_accessed = ?, hit_count = hit_count + 1 
      WHERE key = ?
    `);
      (this as any).cleanupStmt = this.db.prepare(
        "DELETE FROM cache_entries WHERE ttl < ?",
      );
    } catch (error) {
      this.logger.error("Failed to prepare statements:", error);
      // Continue without prepared statements - will use direct queries
    }
  }

  /**
   * Get value from cache with L1/L2 hierarchy
   */
  async get(key: string): Promise<any> {
    const startTime = performance.now();
    this.stats.reads++;

    try {
      // Check L1 (memory) cache first
      const memoryEntry = this.memoryCache.get(key);
      if (memoryEntry && !this.isExpired(memoryEntry)) {
        this.updateMemoryAccess(key, memoryEntry);
        this.stats.hits++;

        const latency = performance.now() - startTime;
        this.emit("cache_hit", { key, source: "memory", latency });

        return memoryEntry.value;
      }

      // Wait for DB initialization if needed
      if (this.dbInitPromise && !this.dbReady) {
        await this.dbInitPromise;
      }

      // Check L2 (disk) cache
      if (this.config.persistToDisk && this.db && this.dbReady) {
        const diskEntry = this.getDiskEntry(key);
        if (diskEntry && !this.isExpired(diskEntry)) {
          this.updateDiskAccess(key);

          // Promote to L1 cache
          await this.promoteToMemory(key, diskEntry);

          this.stats.hits++;
          const latency = performance.now() - startTime;
          this.emit("cache_hit", { key, source: "disk", latency });

          return diskEntry.value;
        }
      }

      // Cache miss
      this.stats.misses++;
      const latency = performance.now() - startTime;
      this.emit("cache_miss", { key, latency });

      return null;
    } catch (error) {
      this.logger.error("Cache get error", { key, error });
      return null;
    }
  }

  /**
   * Set value in cache with intelligent placement
   */
  async set(
    key: string,
    value: any,
    ttl?: number,
    namespace?: string,
  ): Promise<void> {
    const startTime = performance.now();
    this.stats.writes++;

    try {
      const serializedValue = this.serialize(value);
      const size = this.calculateSize(serializedValue);
      const actualTTL = ttl || this.config.defaultTTL;
      const expiresAt = Date.now() + actualTTL * 1000;

      const entry: CacheEntry = {
        key,
        value,
        size,
        ttl: expiresAt,
        createdAt: new Date(),
        lastAccessed: new Date(),
        hitCount: 0,
        namespace,
      };

      // Decide placement based on size and frequency
      const shouldUseMemory = this.shouldUseMemoryCache(size, key);

      if (shouldUseMemory) {
        await this.setMemoryEntry(key, entry);
      }

      // Wait for DB initialization if needed
      if (this.dbInitPromise && !this.dbReady) {
        await this.dbInitPromise;
      }

      // Always persist to disk if enabled (for durability)
      if (this.config.persistToDisk && this.db && this.dbReady) {
        await this.setDiskEntry(key, entry, serializedValue);
      }

      const latency = performance.now() - startTime;
      this.emit("cache_set", {
        key,
        size,
        latency,
        location: shouldUseMemory ? "memory" : "disk",
      });
    } catch (error) {
      this.logger.error("Cache set error", { key, error });
      throw error;
    }
  }

  /**
   * Delete from cache
   */
  async delete(key: string): Promise<boolean> {
    let deleted = false;

    // Remove from memory
    if (this.memoryCache.has(key)) {
      const entry = this.memoryCache.get(key)!;
      this.memorySize -= entry.size;
      this.memoryCache.delete(key);
      this.removeFromAccessOrder(key);
      deleted = true;
    }

    // Remove from disk
    if (this.config.persistToDisk && this.db && this.dbReady) {
      try {
        const result = (this as any).deleteStmt.run(key);
        if (result.changes > 0) {
          deleted = true;
        }
      } catch (error) {
        this.logger.error("Disk delete error", { key, error });
      }
    }

    if (deleted) {
      this.emit("cache_delete", { key });
    }

    return deleted;
  }

  /**
   * Check if entry has expired
   */
  private isExpired(entry: CacheEntry): boolean {
    return Date.now() > entry.ttl;
  }

  /**
   * Update memory cache access
   */
  private updateMemoryAccess(key: string, entry: CacheEntry): void {
    entry.lastAccessed = new Date();
    entry.hitCount++;

    // Update LRU order
    this.removeFromAccessOrder(key);
    this.accessOrder.push(key);

    // Update LFU frequency
    const currentFreq = this.frequencyMap.get(key) || 0;
    this.frequencyMap.set(key, currentFreq + 1);
  }

  /**
   * Update disk cache access
   */
  private updateDiskAccess(key: string): void {
    if (!this.db) return;

    try {
      (this as any).updateAccessStmt.run(Date.now(), key);
    } catch (error) {
      this.logger.debug("Disk access update failed", { key, error });
    }
  }

  /**
   * Get entry from disk cache
   */
  private getDiskEntry(key: string): CacheEntry | null {
    if (!this.db || !this.dbReady) return null;

    try {
      const row = (this as any).getStmt
        ? (this as any).getStmt.get(key)
        : this.db.prepare("SELECT * FROM cache_entries WHERE key = ?").get(key);
      if (!row) return null;

      return {
        key: row.key,
        value: this.deserialize(row.value, row.compressed),
        size: row.size,
        ttl: row.ttl,
        createdAt: new Date(row.created_at),
        lastAccessed: new Date(row.last_accessed),
        hitCount: row.hit_count,
        namespace: row.namespace,
      };
    } catch (error) {
      this.logger.error("Disk get error", { key, error });
      return null;
    }
  }

  /**
   * Promote disk entry to memory cache
   */
  private async promoteToMemory(key: string, entry: CacheEntry): Promise<void> {
    if (this.shouldUseMemoryCache(entry.size, key)) {
      await this.setMemoryEntry(key, entry);
    }
  }

  /**
   * Set entry in memory cache
   */
  private async setMemoryEntry(key: string, entry: CacheEntry): Promise<void> {
    // Ensure space in memory cache
    await this.ensureMemorySpace(entry.size);

    // Remove existing entry if present
    if (this.memoryCache.has(key)) {
      const existing = this.memoryCache.get(key)!;
      this.memorySize -= existing.size;
      this.removeFromAccessOrder(key);
    }

    // Add new entry
    this.memoryCache.set(key, entry);
    this.memorySize += entry.size;
    this.accessOrder.push(key);

    // Update frequency map
    const currentFreq = this.frequencyMap.get(key) || 0;
    this.frequencyMap.set(key, currentFreq + 1);
  }

  /**
   * Set entry in disk cache
   */
  private async setDiskEntry(
    key: string,
    entry: CacheEntry,
    serializedValue: any,
  ): Promise<void> {
    if (!this.db || !this.dbReady) return;

    try {
      const compressed = this.config.compression ? 1 : 0;
      const valueToStore = this.config.compression
        ? this.compress(serializedValue)
        : serializedValue;

      const stmt =
        (this as any).setStmt ||
        this.db.prepare(`
        INSERT OR REPLACE INTO cache_entries 
        (key, value, size, ttl, created_at, last_accessed, hit_count, namespace, compressed)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
      `);

      stmt.run(
        key,
        valueToStore,
        entry.size,
        entry.ttl,
        entry.createdAt.getTime(),
        entry.lastAccessed.getTime(),
        entry.hitCount,
        entry.namespace,
        compressed,
      );
    } catch (error) {
      this.logger.error("Disk set error", { key, error });
    }
  }

  /**
   * Determine if entry should use memory cache
   */
  private shouldUseMemoryCache(size: number, key: string): boolean {
    // Large entries go to disk
    if (size > this.config.maxMemorySize * 0.1) {
      return false;
    }

    // Frequently accessed entries go to memory
    const frequency = this.frequencyMap.get(key) || 0;
    if (frequency > 5) {
      return true;
    }

    // Check available memory space
    const availableMemory = this.config.maxMemorySize - this.memorySize;
    return availableMemory >= size;
  }

  /**
   * Ensure sufficient memory space
   */
  private async ensureMemorySpace(requiredSize: number): Promise<void> {
    while (this.memorySize + requiredSize > this.config.maxMemorySize) {
      const evicted = await this.evictFromMemory();
      if (!evicted) {
        break; // No more entries to evict
      }
    }
  }

  /**
   * Evict entry from memory cache
   */
  private async evictFromMemory(): Promise<boolean> {
    if (this.memoryCache.size === 0) {
      return false;
    }

    let keyToEvict: string;

    switch (this.config.evictionPolicy) {
      case "lru":
        keyToEvict = this.accessOrder[0];
        break;

      case "lfu":
        keyToEvict = this.findLFUKey();
        break;

      case "adaptive":
        keyToEvict = this.findAdaptiveEvictionKey();
        break;

      default:
        keyToEvict = this.accessOrder[0];
    }

    if (keyToEvict) {
      const entry = this.memoryCache.get(keyToEvict)!;
      this.memorySize -= entry.size;
      this.memoryCache.delete(keyToEvict);
      this.removeFromAccessOrder(keyToEvict);
      this.frequencyMap.delete(keyToEvict);

      this.stats.evictions++;
      this.emit("cache_evict", {
        key: keyToEvict,
        reason: this.config.evictionPolicy,
      });

      return true;
    }

    return false;
  }

  /**
   * Find least frequently used key
   */
  private findLFUKey(): string {
    let minFreq = Infinity;
    let lfuKey = "";

    for (const [key, freq] of this.frequencyMap) {
      if (freq < minFreq && this.memoryCache.has(key)) {
        minFreq = freq;
        lfuKey = key;
      }
    }

    return lfuKey || this.accessOrder[0];
  }

  /**
   * Find key for adaptive eviction (combines LRU and LFU)
   */
  private findAdaptiveEvictionKey(): string {
    const candidates = this.accessOrder.slice(
      0,
      Math.min(10, this.accessOrder.length),
    );
    let bestKey = candidates[0];
    let bestScore = Infinity;

    for (const key of candidates) {
      const entry = this.memoryCache.get(key);
      if (!entry) continue;

      const frequency = this.frequencyMap.get(key) || 0;
      const recency = Date.now() - entry.lastAccessed.getTime();

      // Adaptive score (lower is better for eviction)
      const score = frequency * 0.3 + (1 / (recency + 1)) * 0.7;

      if (score < bestScore) {
        bestScore = score;
        bestKey = key;
      }
    }

    return bestKey;
  }

  /**
   * Remove key from access order array
   */
  private removeFromAccessOrder(key: string): void {
    const index = this.accessOrder.indexOf(key);
    if (index !== -1) {
      this.accessOrder.splice(index, 1);
    }
  }

  /**
   * Start cleanup timer for expired entries
   */
  private startCleanupTimer(): void {
    this.cleanupInterval = setInterval(() => {
      this.cleanup();
    }, 60000); // Every minute
  }

  /**
   * Clean up expired entries
   */
  private async cleanup(): Promise<void> {
    const now = Date.now();
    let cleanedCount = 0;

    // Clean memory cache
    for (const [key, entry] of this.memoryCache) {
      if (now > entry.ttl) {
        this.memorySize -= entry.size;
        this.memoryCache.delete(key);
        this.removeFromAccessOrder(key);
        this.frequencyMap.delete(key);
        cleanedCount++;
      }
    }

    // Clean disk cache
    if (this.config.persistToDisk && this.db && this.dbReady) {
      try {
        const result = (this as any).cleanupStmt.run(now);
        cleanedCount += result.changes;
      } catch (error) {
        this.logger.error("Disk cleanup error", error);
      }
    }

    if (cleanedCount > 0) {
      this.logger.debug("Cache cleanup completed", { cleanedCount });
      this.emit("cache_cleanup", { cleanedCount });
    }
  }

  /**
   * Serialize value for storage
   */
  private serialize(value: any): any {
    if (typeof value === "string") {
      return value;
    }
    return JSON.stringify(value);
  }

  /**
   * Deserialize value from storage
   */
  private deserialize(value: any, compressed: boolean = false): any {
    try {
      if (compressed) {
        value = this.decompress(value);
      }

      if (typeof value === "string") {
        try {
          return JSON.parse(value);
        } catch {
          return value; // Return as string if not JSON
        }
      }
      return value;
    } catch (error) {
      this.logger.error("Deserialization error", error);
      return null;
    }
  }

  /**
   * Compress data (simple implementation)
   */
  private compress(data: any): Buffer {
    // TODO: Implement actual compression (gzip, lz4, etc.)
    return Buffer.from(JSON.stringify(data));
  }

  /**
   * Decompress data
   */
  private decompress(data: Buffer): string {
    // TODO: Implement actual decompression
    return data.toString();
  }

  /**
   * Calculate size of serialized data
   */
  private calculateSize(data: any): number {
    if (Buffer.isBuffer(data)) {
      return data.length;
    }
    return Buffer.byteLength(JSON.stringify(data), "utf8");
  }

  /**
   * Format bytes for display
   */
  private formatBytes(bytes: number): string {
    const units = ["B", "KB", "MB", "GB"];
    let value = bytes;
    let unit = 0;

    while (value >= 1024 && unit < units.length - 1) {
      value /= 1024;
      unit++;
    }

    return `${value.toFixed(1)}${units[unit]}`;
  }

  /**
   * Get cache statistics
   */
  getStats(): CacheStats {
    const totalRequests = this.stats.hits + this.stats.misses;

    return {
      totalKeys: this.memoryCache.size,
      totalSize: this.memorySize,
      hitRate: totalRequests > 0 ? this.stats.hits / totalRequests : 0,
      missRate: totalRequests > 0 ? this.stats.misses / totalRequests : 0,
      evictionCount: this.stats.evictions,
      memoryUsage: this.memorySize,
      diskUsage: this.diskSize, // TODO: Calculate actual disk usage
    };
  }

  /**
   * Clear all cache entries
   */
  async clear(): Promise<void> {
    // Clear memory
    this.memoryCache.clear();
    this.memorySize = 0;
    this.accessOrder = [];
    this.frequencyMap.clear();

    // Clear disk
    if (this.config.persistToDisk && this.db && this.dbReady) {
      try {
        this.db.exec("DELETE FROM cache_entries");
      } catch (error) {
        this.logger.error("Disk clear error", error);
      }
    }

    this.emit("cache_clear");
  }

  /**
   * Shutdown cache manager
   */
  shutdown(): void {
    if (this.cleanupInterval) {
      clearInterval(this.cleanupInterval);
    }

    if (this.db) {
      this.db.close();
    }

    this.logger.info("Cache manager shutdown");
  }
}