bunsane 0.3.1 → 0.4.0

package/core/cache/CacheManager.ts

@@ -2,18 +2,48 @@ 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';
+import {
+    getEntity as _getEntity,
+    setEntityWriteThrough as _setEntityWriteThrough,
+    getEntities as _getEntities,
+    setEntitiesWriteThrough as _setEntitiesWriteThrough,
+    getComponentsByEntity as _getComponentsByEntity,
+    setComponentWriteThrough as _setComponentWriteThrough,
+    setComponentsBatchWriteThrough as _setComponentsBatchWriteThrough,
+    getComponents as _getComponents,
+    setComponentsWriteThrough as _setComponentsWriteThrough,
+} from './strategies/writeThrough';
+import {
+    invalidateEntity as _invalidateEntity,
+    invalidateEntities as _invalidateEntities,
+    invalidateAllEntityComponents as _invalidateAllEntityComponents,
+    invalidateComponent as _invalidateComponent,
+    invalidateComponents as _invalidateComponents,
+    invalidateEntityComponents as _invalidateEntityComponents,
+} from './strategies/writeInvalidate';
+import {
+    setupPubSub as _setupPubSub,
+    handleRemoteInvalidation as _handleRemoteInvalidation,
+    publishInvalidation as _publishInvalidation,
+} from './invalidation';
+import {
+    getStats as _getStats,
+    ping as _ping,
+} from './health';
 
-interface InvalidationMessage {
-    instanceId: string;
-    type: 'key' | 'pattern';
-    keys?: string[];
-    pattern?: string;
-}
+/**
+ * Sentinel value written to the cache to record "known absent" lookups.
+ * String literal (not object) so it round-trips cleanly through
+ * JSON.stringify in RedisCache + CompressionUtils. Callers must treat it
+ * as a cache hit but propagate a `null`/`[]` upstream.
+ */
+export const COMPONENT_TOMBSTONE = '__TOMBSTONE__' as const;
+export const RELATION_TOMBSTONE = '__TOMBSTONE__' as const;
+export type ComponentCacheValue = ComponentData | typeof COMPONENT_TOMBSTONE;
 
 /**
  * High-level cache operations manager
@@ -23,13 +53,12 @@ interface InvalidationMessage {
 export class CacheManager {
     private static instance: CacheManager;
     private provider: CacheProvider;
-    private config: CacheConfig;
+    private config: Readonly<CacheConfig>;
     private instanceId = crypto.randomUUID();
     private pubSubEnabled = false;
-    private static readonly INVALIDATION_CHANNEL = 'bunsane:cache:invalidate';
 
     private constructor() {
-        this.config = defaultCacheConfig;
+        this.config = Object.freeze({ ...defaultCacheConfig });
         this.provider = CacheFactory.create(this.config);
     }
 
@@ -48,7 +77,7 @@ export class CacheManager {
         await this.shutdownProvider();
         this.pubSubEnabled = false;
 
-        this.config = { ...defaultCacheConfig, ...config };
+        this.config = Object.freeze({ ...defaultCacheConfig, ...config });
         this.provider = CacheFactory.create(this.config);
 
         await this.setupPubSub();
@@ -57,10 +86,11 @@ export class CacheManager {
     }
 
     /**
-     * Get the current cache configuration
+     * Get the current cache configuration.
+     * Config is frozen once set so callers may hold the reference safely.
      */
-    public getConfig(): CacheConfig {
-        return { ...this.config };
+    public getConfig(): Readonly<CacheConfig> {
+        return this.config;
     }
 
     /**
@@ -77,18 +107,7 @@ export class CacheManager {
      * 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;
-        }
+        return _getEntity(this.provider, this.config, id);
     }
 
     /**
@@ -96,35 +115,14 @@ export class CacheManager {
      * 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 });
-        }
+        return _setEntityWriteThrough(this.provider, this.config, entity, ttl);
     }
 
     /**
      * 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 });
-        }
+        return _invalidateEntity(this.provider, this.config, this._publishInvalidation.bind(this), id);
     }
 
     /**
@@ -132,18 +130,7 @@ export class CacheManager {
      * 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);
-        }
+        return _getEntities(this.provider, this.config, ids);
     }
 
     /**
@@ -151,22 +138,7 @@ export class CacheManager {
      * 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 });
-        }
+        return _setEntitiesWriteThrough(this.provider, this.config, entities, ttl);
     }
 
     // Component caching methods
@@ -175,72 +147,33 @@ export class CacheManager {
      * 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;
-        }
+        return _getComponentsByEntity(this.provider, this.config, entityId, componentType);
     }
 
     /**
      * Set components for an entity in cache with write-through strategy.
      * Converts BaseComponent instances to ComponentData format for cache compatibility with DataLoader.
+     * Delegates to setComponentsBatchWriteThrough for a single-entity, 2-RTT batch.
      */
     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. BaseComponent does not track
-            // createdAt/updatedAt today (data-model gap), but we preserve an
-            // existing cache entry's createdAt when available and stamp
-            // updatedAt=now, so consumers see monotonic update times rather
-            // than a reset on every write-through (H-CACHE-3 — full fix
-            // requires BaseComponent timestamp tracking).
-            for (const component of components) {
-                const typeId = componentType || component.getTypeID();
-                const key = `component:${entityId}:${typeId}`;
-
-                const now = new Date();
-                let createdAt: Date = now;
-                try {
-                    const existing = await this.provider.get<ComponentData>(key);
-                    if (existing && existing.createdAt) {
-                        createdAt = existing.createdAt instanceof Date
-                            ? existing.createdAt
-                            : new Date(existing.createdAt);
-                    }
-                } catch {
-                    // Cache miss or provider error — fall through to now.
-                }
+        return _setComponentWriteThrough(this.provider, this.config, entityId, components, componentType, ttl);
+    }
 
-                const componentData: ComponentData = {
-                    id: component.id,
-                    entityId: entityId,
-                    typeId: typeId,
-                    data: component.data(),
-                    createdAt,
-                    updatedAt: now,
-                    deletedAt: null
-                };
-
-                await this.provider.set(key, componentData, effectiveTTL);
-            }
-        } catch (error) {
-            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error setting components in cache', err: error });
-        }
+    /**
+     * Batch write-through for BaseComponent instances across any number of
+     * entities. Performs exactly 2 Redis round-trips regardless of entry count:
+     *   1. pipelined getMany  — reads existing entries to preserve createdAt (H-CACHE-3)
+     *   2. pipelined setMany  — writes all updated entries
+     *
+     * Signature:
+     *   setComponentsBatchWriteThrough(
+     *     entries: Array<{ entityId: string; typeId: string; component: BaseComponent; ttl?: number }>
+     *   ): Promise<void>
+     */
+    public async setComponentsBatchWriteThrough(
+        entries: Array<{ entityId: string; typeId: string; component: BaseComponent; ttl?: number }>,
+    ): Promise<void> {
+        return _setComponentsBatchWriteThrough(this.provider, this.config, entries);
     }
 
     /**
@@ -248,22 +181,20 @@ export class CacheManager {
      * 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;
-        }
+        return _invalidateComponent(this.provider, this.config, this._publishInvalidation.bind(this), entityId, typeId);
+    }
 
-        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 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.
+     */
+    public async invalidateEntityComponents(
+        entityId: string,
+        componentTypeIds: string[],
+        opts?: { includeEntityKey?: boolean },
+    ): Promise<void> {
+        return _invalidateEntityComponents(this.provider, this.config, this._publishInvalidation.bind(this), entityId, componentTypeIds, opts);
     }
 
     /**
@@ -271,17 +202,7 @@ export class CacheManager {
      * 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 });
-        }
+        return _invalidateComponents(this.provider, this.config, this._publishInvalidation.bind(this), components);
     }
 
     /**
@@ -291,15 +212,7 @@ export class CacheManager {
      * stale L1/L2 cache entries.
      */
     public async invalidateEntities(entityIds: string[]): Promise<void> {
-        if (!this.config.enabled || entityIds.length === 0) {
-            return;
-        }
-        await Promise.all(
-            entityIds.flatMap(id => [
-                this.invalidateEntity(id),
-                this.invalidateAllEntityComponents(id),
-            ])
-        );
+        return _invalidateEntities(this.provider, this.config, this._publishInvalidation.bind(this), entityIds);
     }
 
     /**
@@ -307,55 +220,103 @@ export class CacheManager {
      * 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;
-        }
+        return _invalidateAllEntityComponents(this.provider, this.config, this._publishInvalidation.bind(this), entityId);
+    }
+
+    /**
+     * Get components by entity and type from cache (for DataLoader integration).
+     * Returns COMPONENT_TOMBSTONE for keys whose absence was previously
+     * recorded; callers must treat this as a hit and propagate null upstream.
+     */
+    public async getComponents(keys: Array<{ entityId: string; typeId: string }>): Promise<(ComponentCacheValue | null)[]> {
+        return _getComponents(this.provider, this.config, keys);
+    }
 
+    /**
+     * Set components in cache with write-through strategy (for DataLoader integration).
+     *
+     * When `requestedKeys` is supplied and `component.negativeCacheEnabled` is
+     * true, tombstones are written for any requested key not present in
+     * `components` (within the same setMany call — single round-trip).
+     */
+    public async setComponentsWriteThrough(
+        components: ComponentData[],
+        ttlOrRequested?: number | Array<{ entityId: string; typeId: string }>,
+        ttlIfRequested?: number,
+    ): Promise<void> {
+        return _setComponentsWriteThrough(this.provider, this.config, components, ttlOrRequested, ttlIfRequested);
+    }
+
+    // Relation negative-cache methods
+
+    /**
+     * Build the cache key for a relation tombstone. Null byte separator
+     * prevents collision when relationField contains hyphens or colons.
+     */
+    private static relationCacheKey(entityId: string, relationField: string, relatedType: string, foreignKey?: string): string {
+        const fk = foreignKey ?? '';
+        return `relation:${entityId}\x00${relationField}\x00${relatedType}\x00${fk}`;
+    }
+
+    /**
+     * Bulk-check relation tombstones. Returns true at index i when the
+     * relation at keys[i] was previously recorded as empty.
+     */
+    public async getRelationsEmpty(
+        keys: Array<{ entityId: string; relationField: string; relatedType: string; foreignKey?: string }>,
+    ): Promise<boolean[]> {
+        if (!this.config.enabled || !this.config.relation?.negativeCacheEnabled) {
+            return keys.map(() => false);
+        }
         try {
-            const pattern = `component:${entityId}:*`;
-            await this.provider.invalidatePattern(pattern);
-            await this.publishInvalidation('pattern', undefined, pattern);
+            const cacheKeys = keys.map(k => CacheManager.relationCacheKey(k.entityId, k.relationField, k.relatedType, k.foreignKey));
+            const values = await this.provider.getMany<string>(cacheKeys);
+            return values.map(v => v === RELATION_TOMBSTONE);
         } catch (error) {
-            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error invalidating all entity components from cache', error });
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error getting relation tombstones', error });
+            return keys.map(() => false);
         }
     }
 
     /**
-     * Get components by entity and type from cache (for DataLoader integration)
+     * Record relation tombstones for keys whose query returned []. TTL
+     * defaults to relation.negativeCacheTtl (60s).
      */
-    public async getComponents(keys: Array<{ entityId: string; typeId: string }>): Promise<(ComponentData | null)[]> {
-        if (!this.config.enabled || !this.config.component?.enabled) {
-            return keys.map(() => null);
+    public async setRelationsEmpty(
+        keys: Array<{ entityId: string; relationField: string; relatedType: string; foreignKey?: string }>,
+        ttl?: number,
+    ): Promise<void> {
+        if (!this.config.enabled || !this.config.relation?.negativeCacheEnabled || keys.length === 0) {
+            return;
         }
-
         try {
-            const cacheKeys = keys.map(k => `component:${k.entityId}:${k.typeId}`);
-            const results = await this.provider.getMany<ComponentData>(cacheKeys);
-            return results;
+            const effectiveTTL = ttl ?? this.config.relation.negativeCacheTtl ?? 60_000;
+            const entries = keys.map(k => ({
+                key: CacheManager.relationCacheKey(k.entityId, k.relationField, k.relatedType, k.foreignKey),
+                value: RELATION_TOMBSTONE,
+                ttl: effectiveTTL,
+            }));
+            await this.provider.setMany(entries);
         } catch (error) {
-            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error getting components from cache', error });
-            return keys.map(() => null);
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error setting relation tombstones', error });
         }
     }
 
     /**
-     * Set components in cache with write-through strategy (for DataLoader integration)
+     * Drop a relation tombstone. Call when a target component is created
+     * that may newly satisfy the relation. Pub/sub invalidation is wired
+     * identically to component invalidation.
      */
-    public async setComponentsWriteThrough(components: ComponentData[], ttl?: number): Promise<void> {
-        if (!this.config.enabled || !this.config.component?.enabled) {
+    public async invalidateRelation(entityId: string, relationField: string, relatedType: string, foreignKey?: string): Promise<void> {
+        if (!this.config.enabled || !this.config.relation?.negativeCacheEnabled) {
             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);
+            const key = CacheManager.relationCacheKey(entityId, relationField, relatedType, foreignKey);
+            await this.provider.delete(key);
+            await this._publishInvalidation('key', [key]);
         } catch (error) {
-            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error setting components in cache', error });
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error invalidating relation tombstone', error });
         }
     }
 
@@ -404,7 +365,7 @@ export class CacheManager {
         try {
             await this.provider.delete(key);
             const keys = Array.isArray(key) ? key : [key];
-            await this.publishInvalidation('key', keys);
+            await this._publishInvalidation('key', keys);
         } catch (error) {
             logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error deleting from cache', error });
         }
@@ -420,7 +381,7 @@ export class CacheManager {
 
         try {
             await this.provider.clear();
-            await this.publishInvalidation('pattern', undefined, '*');
+            await this._publishInvalidation('pattern', undefined, '*');
         } catch (error) {
             logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error clearing cache', error });
         }
@@ -430,30 +391,14 @@ export class CacheManager {
      * 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
-            };
-        }
+        return _getStats(this.provider);
     }
 
     /**
      * 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;
-        }
+        return _ping(this.provider);
     }
 
     // --- Cross-instance pub/sub ---
@@ -463,21 +408,11 @@ export class CacheManager {
      * 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 });
-        }
+        this.pubSubEnabled = await _setupPubSub(
+            this.provider,
+            this.instanceId,
+            (raw) => this.handleRemoteInvalidation(raw)
+        );
     }
 
     /**
@@ -485,43 +420,14 @@ export class CacheManager {
      * 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 });
-        }
+        return _handleRemoteInvalidation(this.provider, this.instanceId, raw);
     }
 
     /**
      * 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 });
-        }
+    private async _publishInvalidation(type: 'key' | 'pattern', keys?: string[], pattern?: string): Promise<void> {
+        return _publishInvalidation(this.provider, this.pubSubEnabled, this.instanceId, type, keys, pattern);
     }
 
     /**
@@ -572,4 +478,4 @@ export class CacheManager {
             logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error shutting down cache', error });
         }
     }
-}
+}