bunsane 0.3.1 → 0.4.0

package/core/cache/CompressionUtils.ts

@@ -19,7 +19,11 @@ export class CompressionUtils {
   private static readonly COMPRESSION_PREFIX = '__COMPRESSED__';
 
   /**
-   * Compresses data if it exceeds the threshold size
+   * Compresses data if it exceeds the threshold size.
+   * Returns the original value (unmodified) when below threshold, or a
+   * compressed wrapper object when above. Callers that need the final
+   * storage string should use compressForStorage() to avoid a second
+   * JSON.stringify pass.
    */
   static async compress(data: any): Promise<any> {
     try {
@@ -33,7 +37,6 @@ export class CompressionUtils {
       const compressed = await gzipAsync(serialized);
       const compressedData = compressed.toString('base64');
 
-      // Return compressed data with metadata
       return {
         [this.COMPRESSION_PREFIX]: true,
         data: compressedData,
@@ -41,12 +44,40 @@ export class CompressionUtils {
         compressedSize: compressed.length
       };
     } catch (error) {
-      // Fallback to uncompressed data on compression error
       console.warn('Compression failed, using uncompressed data:', error);
       return data;
     }
   }
 
+  /**
+   * Serializes data to the final string written to Redis.
+   * Reuses the JSON.stringify pass done for size measurement so values
+   * below the compression threshold are never stringified twice.
+   * Values above the threshold are gzip-compressed and then stringified once.
+   */
+  static async compressForStorage(data: any): Promise<string> {
+    try {
+      const serialized = JSON.stringify(data);
+      const size = Buffer.byteLength(serialized, 'utf8');
+
+      if (size <= this.COMPRESSION_THRESHOLD) {
+        return serialized;
+      }
+
+      const compressed = await gzipAsync(serialized);
+      const wrapper = {
+        [this.COMPRESSION_PREFIX]: true,
+        data: compressed.toString('base64'),
+        originalSize: size,
+        compressedSize: compressed.length,
+      };
+      return JSON.stringify(wrapper);
+    } catch (error) {
+      console.warn('Compression failed, using uncompressed data:', error);
+      return JSON.stringify(data);
+    }
+  }
+
   /**
    * Decompresses data if it was previously compressed
    */

package/core/cache/MemoryCache.ts

@@ -12,8 +12,8 @@ function formatBytes(bytes: number): string {
 interface CacheEntry<T> {
     value: T;
     expiresAt?: number;
-    lastAccessed: number;
     accessCount: number;
+    size: number; // Estimated bytes (key + value + metadata), cached for O(1) memory accounting
 }
 
 export interface MemoryCacheConfig {
@@ -36,7 +36,6 @@ export class MemoryCache implements CacheProvider {
         size: 0,
         memoryUsage: 0
     };
-    private accessCounter = 0; // For LRU ordering
 
     constructor(config: MemoryCacheConfig = {}) {
         this.config = {
@@ -60,13 +59,15 @@ export class MemoryCache implements CacheProvider {
         // Check if expired
         if (entry.expiresAt && Date.now() > entry.expiresAt) {
             this.cache.delete(key);
+            this.stats.size--;
+            this.stats.memoryUsage = Math.max(0, this.stats.memoryUsage - entry.size);
             this.stats.misses++;
-            this.updateMemoryUsage();
             return null;
         }
 
-        // Update access tracking for LRU
-        entry.lastAccessed = ++this.accessCounter;
+        // Move to end of Map iteration order (most recently used) for O(1) LRU.
+        this.cache.delete(key);
+        this.cache.set(key, entry);
         entry.accessCount++;
 
         this.stats.hits++;
@@ -76,21 +77,27 @@ export class MemoryCache implements CacheProvider {
     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 size = this.entrySize(key, value);
         const entry: CacheEntry<T> = {
             value,
             expiresAt,
-            lastAccessed: ++this.accessCounter,
-            accessCount: 1
+            accessCount: 1,
+            size
         };
 
-        const wasNew = !this.cache.has(key);
-        this.cache.set(key, entry);
-
-        if (wasNew) {
+        // Incremental memory accounting: adjust by the delta instead of
+        // re-walking the entire cache on every write.
+        // Delete before set so the key moves to the end of Map iteration
+        // order (most recently used position for LRU eviction).
+        const existing = this.cache.get(key);
+        if (existing) {
+            this.stats.memoryUsage = Math.max(0, this.stats.memoryUsage - existing.size);
+            this.cache.delete(key);
+        } else {
             this.stats.size++;
         }
-
-        this.updateMemoryUsage();
+        this.cache.set(key, entry);
+        this.stats.memoryUsage += size;
 
         // Evict if necessary
         await this.evictIfNeeded();
@@ -98,16 +105,15 @@ export class MemoryCache implements CacheProvider {
 
     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++;
+            const entry = this.cache.get(k);
+            if (entry) {
+                this.cache.delete(k);
+                this.stats.size--;
+                this.stats.memoryUsage = Math.max(0, this.stats.memoryUsage - entry.size);
             }
         }
-
-        this.stats.size -= deletedCount;
-        this.updateMemoryUsage();
     }
 
     async clear(): Promise<void> {
@@ -144,7 +150,7 @@ export class MemoryCache implements CacheProvider {
         const regex = new RegExp(pattern.replace(/\*/g, '.*').replace(/\?/g, '.'));
 
         const keysToDelete: string[] = [];
-        for (const key of Array.from(this.cache.keys())) {
+        for (const key of this.cache.keys()) {
             if (regex.test(key)) {
                 keysToDelete.push(key);
             }
@@ -171,16 +177,9 @@ export class MemoryCache implements CacheProvider {
         };
     }
 
-    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 entrySize(key: string, value: any): number {
+        // key string overhead + value estimate + fixed per-entry metadata
+        return key.length * 2 + this.estimateValueSize(value) + 100;
     }
 
     private estimateValueSize(value: any): number {
@@ -214,14 +213,16 @@ export class MemoryCache implements CacheProvider {
     }
 
     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);
+        // Map iteration order is insertion order. get() and set() move accessed/
+        // updated keys to the end, so keys at the front are least recently used.
+        // Collect the first `count` keys without sorting or materialising a full array.
+        const keysToDelete: string[] = [];
+        for (const key of this.cache.keys()) {
+            if (keysToDelete.length >= count) break;
+            keysToDelete.push(key);
+        }
 
-        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`);
     }
 
@@ -229,13 +230,15 @@ export class MemoryCache implements CacheProvider {
         this.cleanupTimer = setInterval(() => {
             this.cleanupExpired();
         }, this.config.cleanupInterval);
+        // Allow the process to exit without waiting for this maintenance timer.
+        this.cleanupTimer?.unref?.();
     }
 
     private cleanupExpired(): void {
         const now = Date.now();
         const keysToDelete: string[] = [];
 
-        for (const [key, entry] of Array.from(this.cache.entries())) {
+        for (const [key, entry] of this.cache) {
             if (entry.expiresAt && now > entry.expiresAt) {
                 keysToDelete.push(key);
             }

package/core/cache/RedisCache.ts

@@ -161,6 +161,8 @@ export class RedisCache implements CacheProvider {
                 logger.error({ error, msg: 'Failed to get Redis memory info' });
             }
         }, 300000); // 5 minutes
+        // Allow the process to exit without waiting for this monitoring timer.
+        this.monitoringInterval?.unref?.();
     }
 
     /**
@@ -192,8 +194,7 @@ export class RedisCache implements CacheProvider {
     async set<T>(key: string, value: T, ttl?: number): Promise<void> {
         try {
             const prefixedKey = this.prefixKey(key);
-            const compressedValue = await CompressionUtils.compress(value);
-            const serializedValue = JSON.stringify(compressedValue);
+            const serializedValue = await CompressionUtils.compressForStorage(value);
 
             if (ttl) {
                 await this.client.setex(prefixedKey, Math.floor(ttl / 1000), serializedValue);
@@ -273,8 +274,7 @@ export class RedisCache implements CacheProvider {
 
             for (const entry of entries) {
                 const prefixedKey = this.prefixKey(entry.key);
-                const compressedValue = await CompressionUtils.compress(entry.value);
-                const serializedValue = JSON.stringify(compressedValue);
+                const serializedValue = await CompressionUtils.compressForStorage(entry.value);
 
                 if (entry.ttl) {
                     pipeline.setex(prefixedKey, Math.floor(entry.ttl / 1000), serializedValue);

package/core/cache/health.ts

@@ -0,0 +1,30 @@
+import { type CacheProvider } from './CacheProvider';
+import { logger } from '../Logger';
+
+/**
+ * Health check operations: ping and getStats.
+ */
+
+export async function getStats(provider: CacheProvider) {
+    try {
+        return await provider.getStats();
+    } catch (error) {
+        logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error getting cache stats', error });
+        return {
+            hits: 0,
+            misses: 0,
+            hitRate: 0,
+            size: 0,
+            memoryUsage: 0
+        };
+    }
+}
+
+export async function ping(provider: CacheProvider): Promise<boolean> {
+    try {
+        return await provider.ping();
+    } catch (error) {
+        logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Cache ping failed', error });
+        return false;
+    }
+}

package/core/cache/invalidation.ts

@@ -0,0 +1,96 @@
+import { type CacheProvider } from './CacheProvider';
+import { MultiLevelCache } from './MultiLevelCache';
+import { RedisCache } from './RedisCache';
+import { logger } from '../Logger';
+
+export interface InvalidationMessage {
+    instanceId: string;
+    type: 'key' | 'pattern';
+    keys?: string[];
+    pattern?: string;
+}
+
+const INVALIDATION_CHANNEL = 'bunsane:cache:invalidate';
+
+/**
+ * Setup pub/sub for cross-instance cache invalidation.
+ * Only activates when using MultiLevel provider with a Redis L2.
+ * Returns true if pub/sub was successfully enabled.
+ */
+export async function setupPubSub(
+    provider: CacheProvider,
+    instanceId: string,
+    handleRemoteInvalidation: (raw: string) => Promise<void>
+): Promise<boolean> {
+    if (!(provider instanceof MultiLevelCache)) return false;
+
+    const l2 = provider.getL2Cache();
+    if (!(l2 instanceof RedisCache)) return false;
+
+    try {
+        await l2.subscribeInvalidation(
+            INVALIDATION_CHANNEL,
+            (_channel, message) => handleRemoteInvalidation(message)
+        );
+        logger.info({ scope: 'cache', component: 'CacheManager', msg: 'Cross-instance cache invalidation enabled', instanceId });
+        return true;
+    } catch (error) {
+        logger.warn({ scope: 'cache', component: 'CacheManager', msg: 'Failed to setup pub/sub', error });
+        return false;
+    }
+}
+
+/**
+ * Handle an invalidation message from another instance.
+ * Ignores messages from self. Invalidates L1 only (L2 is shared Redis).
+ */
+export async function handleRemoteInvalidation(
+    provider: CacheProvider,
+    instanceId: string,
+    raw: string
+): Promise<void> {
+    try {
+        const msg: InvalidationMessage = JSON.parse(raw);
+
+        // Ignore our own messages
+        if (msg.instanceId === instanceId) return;
+
+        if (!(provider instanceof MultiLevelCache)) return;
+        const l1 = provider.getL1Cache();
+
+        if (msg.type === 'key' && msg.keys) {
+            await l1.deleteMany(msg.keys);
+        } else if (msg.type === 'pattern' && msg.pattern) {
+            await l1.invalidatePattern(msg.pattern);
+        }
+
+        logger.debug({ scope: 'cache', component: 'CacheManager', msg: 'Applied remote invalidation', from: msg.instanceId, type: msg.type });
+    } catch (error) {
+        logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error handling remote invalidation', error });
+    }
+}
+
+/**
+ * Publish an invalidation event to other instances via Redis pub/sub.
+ */
+export async function publishInvalidation(
+    provider: CacheProvider,
+    pubSubEnabled: boolean,
+    instanceId: string,
+    type: 'key' | 'pattern',
+    keys?: string[],
+    pattern?: string
+): Promise<void> {
+    if (!pubSubEnabled) return;
+    if (!(provider instanceof MultiLevelCache)) return;
+
+    const l2 = provider.getL2Cache();
+    if (!(l2 instanceof RedisCache)) return;
+
+    try {
+        const msg: InvalidationMessage = { instanceId, type, keys, pattern };
+        await l2.publishInvalidation(INVALIDATION_CHANNEL, JSON.stringify(msg));
+    } catch (error) {
+        logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error publishing invalidation', error });
+    }
+}

package/core/cache/strategies/writeInvalidate.ts

@@ -0,0 +1,111 @@
+import { type CacheProvider } from '../CacheProvider';
+import { type CacheConfig } from '../../../config/cache.config';
+import { logger } from '../../Logger';
+
+/**
+ * Write-invalidate strategy: entity and component invalidation operations.
+ * publishInvalidation is passed as a callback to avoid circular imports.
+ */
+
+type PublishFn = (type: 'key' | 'pattern', keys?: string[], pattern?: string) => Promise<void>;
+
+export async function invalidateEntity(provider: CacheProvider, config: CacheConfig, publishInvalidation: PublishFn, id: string): Promise<void> {
+    if (!config.enabled || !config.entity?.enabled) {
+        return;
+    }
+
+    try {
+        const key = `entity:${id}`;
+        await provider.delete(key);
+        await publishInvalidation('key', [key]);
+    } catch (error) {
+        logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error invalidating entity from cache', error });
+    }
+}
+
+export async function invalidateEntities(provider: CacheProvider, config: CacheConfig, publishInvalidation: PublishFn, entityIds: string[]): Promise<void> {
+    if (!config.enabled || entityIds.length === 0) {
+        return;
+    }
+    await Promise.all(
+        entityIds.flatMap(id => [
+            invalidateEntity(provider, config, publishInvalidation, id),
+            invalidateAllEntityComponents(provider, config, publishInvalidation, id),
+        ])
+    );
+}
+
+export async function invalidateAllEntityComponents(provider: CacheProvider, config: CacheConfig, publishInvalidation: PublishFn, entityId: string): Promise<void> {
+    if (!config.enabled || !config.component?.enabled) {
+        return;
+    }
+
+    try {
+        const pattern = `component:${entityId}:*`;
+        await provider.invalidatePattern(pattern);
+        await publishInvalidation('pattern', undefined, pattern);
+    } catch (error) {
+        logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error invalidating all entity components from cache', error });
+    }
+}
+
+export async function invalidateComponent(provider: CacheProvider, config: CacheConfig, publishInvalidation: PublishFn, entityId: string, typeId: string): Promise<void> {
+    if (!config.enabled || !config.component?.enabled) {
+        return;
+    }
+
+    try {
+        logger.trace({
+            msg: 'Invalidating component from cache',
+            entityId,
+            typeId
+        })
+        const key = `component:${entityId}:${typeId}`;
+        await provider.delete(key);
+        await publishInvalidation('key', [key]);
+    } catch (error) {
+        logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error invalidating component from cache', error });
+    }
+}
+
+export async function invalidateComponents(provider: CacheProvider, config: CacheConfig, publishInvalidation: PublishFn, components: Array<{ entityId: string; typeId: string }>): Promise<void> {
+    if (!config.enabled || !config.component?.enabled) {
+        return;
+    }
+
+    try {
+        const keys = components.map(comp => `component:${comp.entityId}:${comp.typeId}`);
+        await provider.deleteMany(keys);
+        await publishInvalidation('key', keys);
+    } catch (error) {
+        logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error invalidating components from cache', error });
+    }
+}
+
+/**
+ * Invalidate all listed component types for one entity in a single round-trip.
+ * Optionally includes the entity existence key.
+ * Emits a single pub/sub message carrying all keys rather than one per component.
+ */
+export async function invalidateEntityComponents(
+    provider: CacheProvider,
+    config: CacheConfig,
+    publishInvalidation: PublishFn,
+    entityId: string,
+    componentTypeIds: string[],
+    opts?: { includeEntityKey?: boolean },
+): Promise<void> {
+    if (!config.enabled) return;
+    if (componentTypeIds.length === 0 && !opts?.includeEntityKey) return;
+
+    try {
+        const keys: string[] = componentTypeIds.map(typeId => `component:${entityId}:${typeId}`);
+        if (opts?.includeEntityKey) {
+            keys.push(`entity:${entityId}`);
+        }
+        await provider.deleteMany(keys);
+        await publishInvalidation('key', keys);
+    } catch (error) {
+        logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error invalidating entity components', entityId, error });
+    }
+}