bunsane 0.1.4 → 0.2.0

package/core/cache/CacheManager.ts

@@ -0,0 +1,520 @@
+import { type CacheProvider } from './CacheProvider';
+import { type CacheConfig, defaultCacheConfig } from '../../config/cache.config';
+import { CacheFactory } from './CacheFactory';
+import { MultiLevelCache } from './MultiLevelCache';
+import { RedisCache } from './RedisCache';
+import { logger } from '../Logger';
+import type { Entity } from '../Entity';
+import type { BaseComponent } from '../components';
+import type { ComponentData } from '../RequestLoaders';
+
+interface InvalidationMessage {
+    instanceId: string;
+    type: 'key' | 'pattern';
+    keys?: string[];
+    pattern?: string;
+}
+
+/**
+ * High-level cache operations manager
+ * Singleton that provides entity and component caching methods
+ * Note: Query-level caching has been removed in favor of component-level caching only
+ */
+export class CacheManager {
+    private static instance: CacheManager;
+    private provider: CacheProvider;
+    private config: CacheConfig;
+    private instanceId = crypto.randomUUID();
+    private pubSubEnabled = false;
+    private static readonly INVALIDATION_CHANNEL = 'bunsane:cache:invalidate';
+
+    private constructor() {
+        this.config = defaultCacheConfig;
+        this.provider = CacheFactory.create(this.config);
+    }
+
+    public static getInstance(): CacheManager {
+        if (!CacheManager.instance) {
+            CacheManager.instance = new CacheManager();
+        }
+        return CacheManager.instance;
+    }
+
+    /**
+     * Initialize or reinitialize the cache manager with new config
+     */
+    public async initialize(config: Partial<CacheConfig>): Promise<void> {
+        // Shutdown old provider before replacing
+        await this.shutdownProvider();
+        this.pubSubEnabled = false;
+
+        this.config = { ...defaultCacheConfig, ...config };
+        this.provider = CacheFactory.create(this.config);
+
+        await this.setupPubSub();
+
+        logger.info({ scope: 'cache', component: 'CacheManager', msg: 'CacheManager initialized', provider: this.config.provider, enabled: this.config.enabled });
+    }
+
+    /**
+     * Get the current cache configuration
+     */
+    public getConfig(): CacheConfig {
+        return { ...this.config };
+    }
+
+    /**
+     * Get the current cache provider
+     */
+    public getProvider(): CacheProvider {
+        return this.provider;
+    }
+
+    // Entity caching methods
+
+    /**
+     * Get an entity existence check from cache
+     * Returns entity ID if exists, null if not found
+     */
+    public async getEntity(id: string): Promise<string | null> {
+        if (!this.config.enabled || !this.config.entity?.enabled) {
+            return null;
+        }
+
+        try {
+            const key = `entity:${id}`;
+            const result = await this.provider.get<string>(key);
+            return result || null;
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error getting entity from cache', error });
+            return null;
+        }
+    }
+
+    /**
+     * Set an entity existence in cache with write-through strategy
+     * Only caches entity ID for existence tracking, not full entity data
+     */
+    public async setEntityWriteThrough(entity: Entity, ttl?: number): Promise<void> {
+        if (!this.config.enabled || !this.config.entity?.enabled) {
+            return;
+        }
+
+        try {
+            const key = `entity:${entity.id}`;
+            const effectiveTTL = ttl ?? this.config.entity.ttl;
+            // Only cache entity ID for existence check
+            await this.provider.set(key, entity.id, effectiveTTL);
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error setting entity in cache', error });
+        }
+    }
+
+    /**
+     * Invalidate an entity from cache
+     */
+    public async invalidateEntity(id: string): Promise<void> {
+        if (!this.config.enabled || !this.config.entity?.enabled) {
+            return;
+        }
+
+        try {
+            const key = `entity:${id}`;
+            await this.provider.delete(key);
+            await this.publishInvalidation('key', [key]);
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error invalidating entity from cache', error });
+        }
+    }
+
+    /**
+     * Get multiple entity existence checks from cache (for DataLoader integration)
+     * Returns entity IDs if they exist, null if not found
+     */
+    public async getEntities(ids: string[]): Promise<(string | null)[]> {
+        if (!this.config.enabled || !this.config.entity?.enabled) {
+            return ids.map(() => null);
+        }
+
+        try {
+            const cacheKeys = ids.map(id => `entity:${id}`);
+            const results = await this.provider.getMany<string>(cacheKeys);
+            return results;
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error getting entities from cache', error });
+            return ids.map(() => null);
+        }
+    }
+
+    /**
+     * Set multiple entity existences in cache with write-through strategy (for DataLoader integration)
+     * Only caches entity IDs for existence tracking, not full entity data
+     */
+    public async setEntitiesWriteThrough(entities: Entity[], ttl?: number): Promise<void> {
+        if (!this.config.enabled || !this.config.entity?.enabled) {
+            return;
+        }
+
+        try {
+            const effectiveTTL = ttl ?? this.config.entity?.ttl;
+            const entries = entities.map(entity => ({
+                key: `entity:${entity.id}`,
+                // Only cache entity ID for existence check
+                value: entity.id,
+                ttl: effectiveTTL
+            }));
+            await this.provider.setMany(entries);
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error setting entities in cache', error });
+        }
+    }
+
+    // Component caching methods
+
+    /**
+     * Get components for an entity from cache
+     */
+    public async getComponentsByEntity(entityId: string, componentType?: string): Promise<BaseComponent[] | null> {
+        if (!this.config.enabled || !this.config.component?.enabled) {
+            return null;
+        }
+
+        try {
+            const key = componentType
+                ? `component:${entityId}:${componentType}`
+                : `components:${entityId}`;
+            return await this.provider.get<BaseComponent[]>(key);
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error getting components from cache', error });
+            return null;
+        }
+    }
+
+    /**
+     * Set components for an entity in cache with write-through strategy.
+     * Converts BaseComponent instances to ComponentData format for cache compatibility with DataLoader.
+     */
+    public async setComponentWriteThrough(entityId: string, components: BaseComponent[], componentType?: string, ttl?: number): Promise<void> {
+        if (!this.config.enabled || !this.config.component?.enabled) {
+            return;
+        }
+
+        try {
+            const effectiveTTL = ttl ?? this.config.component.ttl;
+            
+            // Convert BaseComponent to ComponentData format for cache compatibility with DataLoader
+            for (const component of components) {
+                const typeId = componentType || component.getTypeID();
+                const key = `component:${entityId}:${typeId}`;
+                
+                // Create ComponentData structure matching what DataLoader expects
+                const componentData: ComponentData = {
+                    id: component.id,
+                    entityId: entityId,
+                    typeId: typeId,
+                    data: component.data(),
+                    createdAt: new Date(), // Component doesn't track this, use current time
+                    updatedAt: new Date(),
+                    deletedAt: null
+                };
+                
+                await this.provider.set(key, componentData, effectiveTTL);
+            }
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error setting components in cache', error });
+        }
+    }
+
+    /**
+     * Invalidate a specific component for an entity from cache
+     * More granular than invalidateComponents which can invalidate all components
+     */
+    public async invalidateComponent(entityId: string, typeId: string): Promise<void> {
+        if (!this.config.enabled || !this.config.component?.enabled) {
+            return;
+        }
+
+        try {
+            logger.trace({
+                msg: 'Invalidating component from cache',
+                entityId,
+                typeId
+            })
+            const key = `component:${entityId}:${typeId}`;
+            await this.provider.delete(key);
+            await this.publishInvalidation('key', [key]);
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error invalidating component from cache', error });
+        }
+    }
+
+    /**
+     * Invalidate multiple specific components from cache
+     * Useful for bulk invalidation operations
+     */
+    public async invalidateComponents(components: Array<{ entityId: string; typeId: string }>): Promise<void> {
+        if (!this.config.enabled || !this.config.component?.enabled) {
+            return;
+        }
+
+        try {
+            const keys = components.map(comp => `component:${comp.entityId}:${comp.typeId}`);
+            await this.provider.deleteMany(keys);
+            await this.publishInvalidation('key', keys);
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error invalidating components from cache', error });
+        }
+    }
+
+    /**
+     * Invalidate all components for a specific entity from cache
+     * Uses pattern matching to efficiently clear all component caches for an entity
+     */
+    public async invalidateAllEntityComponents(entityId: string): Promise<void> {
+        if (!this.config.enabled || !this.config.component?.enabled) {
+            return;
+        }
+
+        try {
+            const pattern = `component:${entityId}:*`;
+            await this.provider.invalidatePattern(pattern);
+            await this.publishInvalidation('pattern', undefined, pattern);
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error invalidating all entity components from cache', error });
+        }
+    }
+
+    /**
+     * Get components by entity and type from cache (for DataLoader integration)
+     */
+    public async getComponents(keys: Array<{ entityId: string; typeId: string }>): Promise<(ComponentData | null)[]> {
+        if (!this.config.enabled || !this.config.component?.enabled) {
+            return keys.map(() => null);
+        }
+
+        try {
+            const cacheKeys = keys.map(k => `component:${k.entityId}:${k.typeId}`);
+            const results = await this.provider.getMany<ComponentData>(cacheKeys);
+            return results;
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error getting components from cache', error });
+            return keys.map(() => null);
+        }
+    }
+
+    /**
+     * Set components in cache with write-through strategy (for DataLoader integration)
+     */
+    public async setComponentsWriteThrough(components: ComponentData[], ttl?: number): Promise<void> {
+        if (!this.config.enabled || !this.config.component?.enabled) {
+            return;
+        }
+
+        try {
+            const effectiveTTL = ttl ?? this.config.component?.ttl;
+            const entries = components.map(comp => ({
+                key: `component:${comp.entityId}:${comp.typeId}`,
+                value: comp,
+                ttl: effectiveTTL
+            }));
+            await this.provider.setMany(entries);
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error setting components in cache', error });
+        }
+    }
+
+    // Generic cache methods
+
+    /**
+     * Generic get method
+     */
+    public async get<T>(key: string): Promise<T | null> {
+        if (!this.config.enabled) {
+            return null;
+        }
+
+        try {
+            return await this.provider.get<T>(key);
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error getting from cache', error });
+            return null;
+        }
+    }
+
+    /**
+     * Generic set method
+     */
+    public async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+        if (!this.config.enabled) {
+            return;
+        }
+
+        try {
+            const effectiveTTL = ttl ?? this.config.defaultTTL;
+            await this.provider.set(key, value, effectiveTTL);
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error setting in cache', error });
+        }
+    }
+
+    /**
+     * Generic delete method
+     */
+    public async delete(key: string | string[]): Promise<void> {
+        if (!this.config.enabled) {
+            return;
+        }
+
+        try {
+            await this.provider.delete(key);
+            const keys = Array.isArray(key) ? key : [key];
+            await this.publishInvalidation('key', keys);
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error deleting from cache', error });
+        }
+    }
+
+    /**
+     * Clear all cache
+     */
+    public async clear(): Promise<void> {
+        if (!this.config.enabled) {
+            return;
+        }
+
+        try {
+            await this.provider.clear();
+            await this.publishInvalidation('pattern', undefined, '*');
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error clearing cache', error });
+        }
+    }
+
+    /**
+     * Get cache statistics
+     */
+    public async getStats() {
+        try {
+            return await this.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
+            };
+        }
+    }
+
+    /**
+     * Health check for cache
+     */
+    public async ping(): Promise<boolean> {
+        try {
+            return await this.provider.ping();
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Cache ping failed', error });
+            return false;
+        }
+    }
+
+    // --- Cross-instance pub/sub ---
+
+    /**
+     * Setup pub/sub for cross-instance cache invalidation.
+     * Only activates when using MultiLevel provider with a Redis L2.
+     */
+    private async setupPubSub(): Promise<void> {
+        if (!(this.provider instanceof MultiLevelCache)) return;
+
+        const l2 = this.provider.getL2Cache();
+        if (!(l2 instanceof RedisCache)) return;
+
+        try {
+            await l2.subscribeInvalidation(
+                CacheManager.INVALIDATION_CHANNEL,
+                (_channel, message) => this.handleRemoteInvalidation(message)
+            );
+            this.pubSubEnabled = true;
+            logger.info({ scope: 'cache', component: 'CacheManager', msg: 'Cross-instance cache invalidation enabled', instanceId: this.instanceId });
+        } catch (error) {
+            logger.warn({ scope: 'cache', component: 'CacheManager', msg: 'Failed to setup pub/sub', error });
+        }
+    }
+
+    /**
+     * Handle an invalidation message from another instance.
+     * Ignores messages from self. Invalidates L1 only (L2 is shared Redis).
+     */
+    private async handleRemoteInvalidation(raw: string): Promise<void> {
+        try {
+            const msg: InvalidationMessage = JSON.parse(raw);
+
+            // Ignore our own messages
+            if (msg.instanceId === this.instanceId) return;
+
+            if (!(this.provider instanceof MultiLevelCache)) return;
+            const l1 = this.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.
+     */
+    private async publishInvalidation(type: 'key' | 'pattern', keys?: string[], pattern?: string): Promise<void> {
+        if (!this.pubSubEnabled) return;
+        if (!(this.provider instanceof MultiLevelCache)) return;
+
+        const l2 = this.provider.getL2Cache();
+        if (!(l2 instanceof RedisCache)) return;
+
+        try {
+            const msg: InvalidationMessage = { instanceId: this.instanceId, type, keys, pattern };
+            await l2.publishInvalidation(CacheManager.INVALIDATION_CHANNEL, JSON.stringify(msg));
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error publishing invalidation', error });
+        }
+    }
+
+    /**
+     * Shutdown the current provider (disconnect Redis, stop Memory cleanup timer)
+     */
+    private async shutdownProvider(): Promise<void> {
+        try {
+            const provider = this.provider as any;
+            // RedisCache has disconnect()
+            if (typeof provider.disconnect === 'function') {
+                await provider.disconnect();
+            }
+            // MemoryCache has stopCleanup()
+            if (typeof provider.stopCleanup === 'function') {
+                provider.stopCleanup();
+            }
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error shutting down provider', error });
+        }
+    }
+
+    /**
+     * Shutdown the cache manager
+     */
+    public async shutdown(): Promise<void> {
+        try {
+            await this.shutdownProvider();
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error shutting down cache', error });
+        }
+    }
+}

package/core/cache/CacheProvider.ts

@@ -0,0 +1,34 @@
+/**
+ * Cache Provider Interface for BunSane Framework
+ * Defines the contract for all cache implementations
+ */
+
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    hitRate: number;
+    size: number;
+    memoryUsage?: number;
+}
+
+export interface CacheProvider {
+    // Basic operations
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    delete(key: string | string[]): Promise<void>;
+    clear(): Promise<void>;
+
+    // Batch operations
+    getMany<T>(keys: string[]): Promise<(T | null)[]>;
+    setMany<T>(entries: Array<{key: string, value: T, ttl?: number}>): Promise<void>;
+    deleteMany(keys: string[]): Promise<void>;
+
+    // Pattern-based operations
+    invalidatePattern(pattern: string): Promise<void>;
+
+    // Health check
+    ping(): Promise<boolean>;
+
+    // Statistics
+    getStats(): Promise<CacheStats>;
+}