@goatlab/node-backend 1.2.0 → 1.3.0

package/dist/container/Container.js

@@ -4,6 +4,7 @@ exports.Container = void 0;
 const node_async_hooks_1 = require("node:async_hooks");
 const helpers_1 = require("./helpers");
 const LruCache_1 = require("./LruCache");
+const types_1 = require("./types");
 // Instantiation helper moved to helpers.ts for better performance
 /**
  * ═══════════════════════════════════════════════════════════════════════════════
@@ -98,6 +99,22 @@ class Container {
      * Lazy-allocated to save memory for unused services
      */
     managers = {};
+    /**
+     * Kill switch: Set of blocked tenant IDs
+     * Blocked tenants are rejected immediately at bootstrap without initialization
+     */
+    blockedTenants = new Set();
+    /**
+     * Cooldown tracker: tenants whose initializer recently failed
+     * Maps tenant cache key -> expiry timestamp (Date.now() + cooldown)
+     * Prevents retry storms when a tenant's initializer is broken
+     */
+    initializerCooldowns = new Map();
+    /**
+     * Bootstrap call counter for sampled heap checks
+     * Only check memory every N calls to minimize overhead
+     */
+    bootstrapCounter = 0;
     /**
      * AsyncLocalStorage provides automatic tenant context isolation
      * Each async call tree gets its own isolated service instances
@@ -122,6 +139,12 @@ class Container {
      * Prevents concurrent bootstrap for same tenant from running initializer twice
      */
     initializerPromises = new Map();
+    /**
+     * Tracks in-flight disposal operations per tenant
+     * Bootstrap waits for pending disposal to complete before re-initializing
+     * Prevents duplicate live instances when invalidation overlaps with re-bootstrap
+     */
+    disposalPromises = new Map();
     // ═══════════════════════════════════════════════════════════════════════════
     // ⚡ PERFORMANCE OPTIMIZATION CACHES
     // ═══════════════════════════════════════════════════════════════════════════
@@ -139,16 +162,9 @@ class Container {
     /**
      * Initializer cache: stores initialized instances per tenant with LRU eviction
      * Avoids re-running the expensive initializer function for the same tenant
-     * Key is a serialized version of tenant metadata, value is the initialized instances
-     * Uses accessOrder to track LRU for eviction when cache exceeds maxInitializerCacheSize
-     */
-    initializerCache = new Map();
-    /**
-     * Tracks access order for LRU eviction of initializerCache entries
-     * Key is cache key, value is access timestamp (incrementing counter)
+     * Uses tiny-lru for O(1) eviction instead of hand-rolled linear scan
      */
-    initializerAccessOrder = new Map();
-    initializerAccessCounter = 0;
+    initializerCache;
     // ═══════════════════════════════════════════════════════════════════════════
     // 📊 PERFORMANCE METRICS
     // ═══════════════════════════════════════════════════════════════════════════
@@ -205,6 +221,13 @@ class Container {
         }
         ++this.metrics[idx];
     }
+    /**
+     * Emit a structured event if an event handler is configured
+     * No-op if onEvent is not set, keeping zero overhead when unused
+     */
+    emit(event) {
+        this.options.onEvent?.(event);
+    }
     // ═══════════════════════════════════════════════════════════════════════════
     // 🏗️ CONSTRUCTOR & INITIALIZATION
     // ═══════════════════════════════════════════════════════════════════════════
@@ -234,8 +257,14 @@ class Container {
             enableDiagnostics: false,
             enableDistributedInvalidation: false,
             distributedInvalidator: undefined,
+            initializerCooldownMs: 0,
+            onEvent: undefined,
+            maxHeapUsageRatio: 0,
+            heapCheckInterval: 10,
             ...options,
         };
+        // Initialize LRU cache for initializer results (O(1) eviction)
+        this.initializerCache = (0, LruCache_1.createServiceCache)(this.options.maxInitializerCacheSize);
         // Pre-cache factory lookups for better performance
         this.preloadFactoryCache();
         // Setup distributed cache invalidation if enabled
@@ -449,21 +478,24 @@ class Container {
                         `Available services: ${available}`);
                 }
                 // Only wrap objects that are safe to wrap
-                // Avoid wrapping Promises, arrays, thenable objects, Prisma clients, or Redis clients
+                // Avoid wrapping Promises, arrays, thenable objects, or opted-out services
                 if (typeof value === 'object' &&
                     value !== null &&
                     !Array.isArray(value) &&
                     !(value instanceof Promise) &&
                     typeof value.then !== 'function' &&
-                    // Avoid wrapping Prisma clients (they have complex internal properties)
+                    // Symbol-based opt-out: preferred mechanism for any service
+                    !(types_1.NO_CONTAINER_PROXY in value && value[types_1.NO_CONTAINER_PROXY]) &&
+                    // Legacy duck-typing checks (kept for backwards compatibility)
+                    // Prisma clients
                     !('_engine' in value &&
                         '_extensions' in value &&
                         '$connect' in value) &&
-                    // Avoid wrapping Redis clients (they have ioredis-specific properties)
+                    // Redis/ioredis clients
                     !('options' in value && 'status' in value && 'connector' in value) &&
-                    // Avoid wrapping cache service objects (Keyv instances with opts property)
+                    // Keyv instances
                     !('opts' in value) &&
-                    // Avoid wrapping cache store objects
+                    // Cache store objects
                     !('store' in value && 'namespace' in value)) {
                     // Safe to wrap - create nested proxy
                     return this.createContextProxy(value, newPath);
@@ -507,30 +539,14 @@ class Container {
             return `tenant:hash:${this.simpleHash(json)}`;
         }
         catch {
-            // Last resort for circular refs
-            return `tenant:ts:${Date.now()}`;
-        }
-    }
-    /**
-     * Evict the least recently used entry from initializerCache if at capacity
-     * Called before adding a new entry when cache is at maxInitializerCacheSize
-     */
-    evictLruFromInitializerCache() {
-        if (this.initializerCache.size < this.options.maxInitializerCacheSize) {
-            return;
-        }
-        // Find the LRU entry (lowest access counter)
-        let lruKey = null;
-        let lruTime = Number.POSITIVE_INFINITY;
-        for (const [key, time] of this.initializerAccessOrder) {
-            if (time < lruTime) {
-                lruTime = time;
-                lruKey = key;
-            }
-        }
-        if (lruKey) {
-            this.initializerCache.delete(lruKey);
-            this.initializerAccessOrder.delete(lruKey);
+            // For circular refs, build a stable key from sorted own-property keys + values
+            // This is deterministic unlike Date.now() which guarantees cache misses
+            const keys = Object.keys(m).sort();
+            const parts = keys.map(k => {
+                const v = m[k];
+                return `${k}=${typeof v === 'object' ? typeof v : v}`;
+            });
+            return `tenant:keys:${this.simpleHash(parts.join('|'))}`;
         }
     }
     /**
@@ -540,12 +556,27 @@ class Container {
      */
     async getOrCreateInstances(meta) {
         const cacheKey = this.createTenantCacheKey(meta);
+        // Wait for any pending disposal before re-initializing this tenant
+        const m = meta;
+        const tenantId = m.id ?? m.tenantId ?? m.name;
+        if (tenantId) {
+            const pendingDisposal = this.disposalPromises.get(String(tenantId));
+            if (pendingDisposal) {
+                await pendingDisposal;
+            }
+        }
+        // Check cooldown: reject if initializer recently failed for this tenant
+        if (this.options.initializerCooldownMs > 0) {
+            const cooldownExpiry = this.initializerCooldowns.get(cacheKey);
+            if (cooldownExpiry && Date.now() < cooldownExpiry) {
+                const remainingMs = cooldownExpiry - Date.now();
+                throw new Error(`Tenant initializer is in cooldown (${remainingMs}ms remaining). Previous initialization failed.`);
+            }
+        }
         // Check if we already have initialized instances for this tenant
         const cachedInstances = this.initializerCache.get(cacheKey);
         if (cachedInstances) {
             this.inc(Container.METRIC.INIT_HITS);
-            // Update access order for LRU tracking
-            this.initializerAccessOrder.set(cacheKey, ++this.initializerAccessCounter);
             return cachedInstances;
         }
         // Check if initialization is already in progress for this tenant
@@ -558,14 +589,19 @@ class Container {
         this.initializerPromises.set(cacheKey, initPromise);
         try {
             const instances = await initPromise;
-            // Evict LRU entry if cache is at capacity
-            this.evictLruFromInitializerCache();
-            // Cache the result for future use
+            // Cache the result for future use (LRU eviction handled by tiny-lru)
             this.initializerCache.set(cacheKey, instances);
-            // Track access order for LRU
-            this.initializerAccessOrder.set(cacheKey, ++this.initializerAccessCounter);
+            // Clear any previous cooldown on success
+            this.initializerCooldowns.delete(cacheKey);
             return instances;
         }
+        catch (error) {
+            // Set cooldown on failure to prevent retry storms
+            if (this.options.initializerCooldownMs > 0) {
+                this.initializerCooldowns.set(cacheKey, Date.now() + this.options.initializerCooldownMs);
+            }
+            throw error;
+        }
         finally {
             // Clean up inflight promise tracking
             this.initializerPromises.delete(cacheKey);
@@ -598,16 +634,60 @@ class Container {
      * 4. Returns both the instances and your function's result
      */
     async bootstrap(meta, fn) {
+        // Kill switch: reject blocked tenants immediately
+        const m = meta;
+        const tenantId = m.id ?? m.tenantId ?? m.name;
+        const tenantIdStr = tenantId ? String(tenantId) : undefined;
+        if (tenantIdStr && this.blockedTenants.has(tenantIdStr)) {
+            this.emit({
+                type: 'tenant:blocked',
+                tenantId: tenantIdStr,
+                timestamp: Date.now(),
+            });
+            throw new Error(`Tenant '${tenantIdStr}' is blocked. Use container.unblockTenant() to restore access.`);
+        }
+        // Memory pressure check (sampled to avoid overhead)
+        if (this.options.maxHeapUsageRatio > 0) {
+            this.bootstrapCounter++;
+            if (this.bootstrapCounter % this.options.heapCheckInterval === 0) {
+                const { heapUsed, heapTotal } = process.memoryUsage();
+                const ratio = heapUsed / heapTotal;
+                if (ratio > this.options.maxHeapUsageRatio) {
+                    throw new Error(`Memory pressure: heap usage ${(ratio * 100).toFixed(1)}% exceeds limit ${(this.options.maxHeapUsageRatio * 100).toFixed(1)}%. Rejecting new bootstrap.`);
+                }
+            }
+        }
+        const startTime = Date.now();
+        this.emit({
+            type: 'bootstrap:start',
+            tenantId: tenantIdStr,
+            timestamp: startTime,
+        });
         try {
             // Phase 1: Get or create services for this tenant (with caching)
             const instances = await this.getOrCreateInstances(meta);
+            const cached = this.initializerCache.get(this.createTenantCacheKey(meta)) !== undefined;
             // Phase 2: Run user function within tenant context
             const result = await this.runWithContext(instances, meta, fn || (async () => undefined));
+            this.emit({
+                type: 'bootstrap:complete',
+                tenantId: tenantIdStr,
+                durationMs: Date.now() - startTime,
+                cached,
+                timestamp: Date.now(),
+            });
             // Type assertion: we trust that initializer provides all required services
             // In practice, this is validated at runtime by the context proxy
             return { instances: instances, result };
         }
         catch (err) {
+            this.emit({
+                type: 'bootstrap:error',
+                tenantId: tenantIdStr,
+                error: err instanceof Error ? err : new Error(String(err)),
+                durationMs: Date.now() - startTime,
+                timestamp: Date.now(),
+            });
             if (this.options.enableDiagnostics) {
                 console.error('Container bootstrap failed:', err);
             }
@@ -653,98 +733,86 @@ class Container {
      */
     async bootstrapBatch(tenantBatch, options = {}) {
         const { concurrency = 10, continueOnError = true, timeout, onProgress, } = options;
-        const results = [];
         const total = tenantBatch.length;
+        const results = new Array(total);
         let completed = 0;
+        let nextIndex = 0;
         let shouldAbort = false;
-        // Process tenants in chunks based on concurrency limit
-        for (let i = 0; i < total; i += concurrency) {
-            // Check if we should abort due to previous error in fail-fast mode
-            if (shouldAbort) {
-                break;
-            }
-            const chunk = tenantBatch.slice(i, i + concurrency);
-            const chunkPromises = chunk.map(async ({ metadata, fn }) => {
-                const startTime = Date.now();
-                try {
-                    // Apply timeout if specified
-                    let bootstrapPromise = this.bootstrap(metadata, fn);
-                    if (timeout) {
-                        bootstrapPromise = Promise.race([
-                            bootstrapPromise,
-                            new Promise((_, reject) => setTimeout(() => reject(new Error(`Bootstrap timeout after ${timeout}ms`)), timeout)),
-                        ]);
-                    }
-                    const { instances, result } = await bootstrapPromise;
-                    const endTime = Date.now();
-                    this.inc(Container.METRIC.BATCH_OPS);
-                    return {
-                        metadata,
-                        status: 'success',
-                        instances,
-                        result,
-                        metrics: {
-                            startTime,
-                            endTime,
-                            duration: endTime - startTime,
-                        },
-                    };
-                }
-                catch (error) {
-                    const endTime = Date.now();
-                    this.inc(Container.METRIC.BATCH_ERRORS);
-                    if (this.options.enableDiagnostics) {
-                        console.error(`Batch bootstrap failed for tenant:`, metadata, error);
-                    }
-                    const result = {
-                        metadata,
-                        status: 'error',
-                        error: error instanceof Error ? error : new Error(String(error)),
-                        metrics: {
-                            startTime,
-                            endTime,
-                            duration: endTime - startTime,
-                        },
-                    };
-                    if (!continueOnError) {
-                        // Mark that we should abort processing
-                        shouldAbort = true;
-                    }
-                    return result;
-                }
-                finally {
-                    completed++;
-                    onProgress?.(completed, total, metadata);
+        // Process a single tenant and return its result at the correct index
+        const processTenant = async (index) => {
+            const { metadata, fn } = tenantBatch[index];
+            const startTime = Date.now();
+            try {
+                let bootstrapPromise = this.bootstrap(metadata, fn);
+                if (timeout) {
+                    bootstrapPromise = Promise.race([
+                        bootstrapPromise,
+                        new Promise((_, reject) => setTimeout(() => reject(new Error(`Bootstrap timeout after ${timeout}ms`)), timeout)),
+                    ]);
                 }
-            });
-            // Wait for current chunk to complete before starting next
-            const chunkResults = await Promise.allSettled(chunkPromises);
-            // Extract results from Promise.allSettled
-            for (const settledResult of chunkResults) {
-                if (settledResult.status === 'fulfilled') {
-                    results.push(settledResult.value);
+                const { instances, result } = await bootstrapPromise;
+                const endTime = Date.now();
+                this.inc(Container.METRIC.BATCH_OPS);
+                results[index] = {
+                    metadata,
+                    status: 'success',
+                    instances,
+                    result,
+                    metrics: {
+                        startTime,
+                        endTime,
+                        duration: endTime - startTime,
+                    },
+                };
+            }
+            catch (error) {
+                const endTime = Date.now();
+                this.inc(Container.METRIC.BATCH_ERRORS);
+                if (this.options.enableDiagnostics) {
+                    console.error(`Batch bootstrap failed for tenant:`, metadata, error);
                 }
-                else if (continueOnError) {
-                    // This shouldn't happen as we handle errors above, but just in case
-                    results.push({
-                        metadata: tenantBatch[results.length].metadata,
-                        status: 'error',
-                        error: settledResult.reason,
-                        metrics: {
-                            startTime: Date.now(),
-                            endTime: Date.now(),
-                            duration: 0,
-                        },
-                    });
+                results[index] = {
+                    metadata,
+                    status: 'error',
+                    error: error instanceof Error ? error : new Error(String(error)),
+                    metrics: {
+                        startTime,
+                        endTime,
+                        duration: endTime - startTime,
+                    },
+                };
+                if (!continueOnError) {
+                    shouldAbort = true;
                 }
             }
-            // Check if we had any errors and should fail fast
-            if (!continueOnError && results.some(r => r.status === 'error')) {
-                const errorResult = results.find(r => r.status === 'error');
-                throw errorResult?.error || new Error('Batch operation failed');
+            finally {
+                completed++;
+                onProgress?.(completed, total, metadata);
+            }
+        };
+        // Pool-based concurrency: start new work as soon as any slot frees up
+        const workers = [];
+        const runWorker = async () => {
+            while (!shouldAbort && nextIndex < total) {
+                const index = nextIndex++;
+                await processTenant(index);
             }
+        };
+        // Launch workers up to the concurrency limit
+        const workerCount = Math.min(concurrency, total);
+        for (let i = 0; i < workerCount; i++) {
+            workers.push(runWorker());
         }
-        return results;
+        await Promise.allSettled(workers);
+        // In fail-fast mode, throw the first error found
+        if (!continueOnError) {
+            const errorResult = results.find(r => r?.status === 'error');
+            if (errorResult?.error) {
+                throw errorResult.error;
+            }
+        }
+        // Filter out any undefined slots (from aborted processing)
+        return results.filter(Boolean);
     }
     /**
      * Invalidate multiple tenant caches in batch
@@ -898,8 +966,9 @@ class Container {
         // Clear optimization caches as well
         this.proxyCache.clear();
         this.initializerCache.clear();
-        this.initializerAccessOrder.clear();
         this.initializerPromises.clear();
+        this.disposalPromises.clear();
+        this.initializerCooldowns.clear();
         // Note: contextProxyCache is a WeakMap and will be garbage collected automatically
     }
     /**
@@ -945,8 +1014,9 @@ class Container {
         // Clear optimization caches as well
         this.proxyCache.clear();
         this.initializerCache.clear();
-        this.initializerAccessOrder.clear();
         this.initializerPromises.clear();
+        this.disposalPromises.clear();
+        this.initializerCooldowns.clear();
         // Note: contextProxyCache is a WeakMap and will be garbage collected automatically
         return result;
     }
@@ -1022,32 +1092,51 @@ class Container {
      * This only affects the current instance
      */
     invalidateTenantLocally(tenantId, reason) {
+        this.emit({
+            type: 'tenant:invalidated',
+            tenantId,
+            reason,
+            timestamp: Date.now(),
+        });
         if (this.options.enableDiagnostics) {
             console.log(`Invalidating tenant cache locally: ${tenantId}`, reason ? `(${reason})` : '');
         }
-        // Clear service instance caches for this tenant with disposal
+        // Clear service instance caches for this tenant with tracked disposal
+        const disposalTasks = [];
         for (const manager of Object.values(this.managers)) {
             const instance = manager.get(tenantId);
             if (instance) {
-                (0, helpers_1.safeDispose)(instance).catch(err => {
+                disposalTasks.push((0, helpers_1.safeDispose)(instance).catch(err => {
                     if (this.options.enableDiagnostics) {
                         console.warn('Error disposing tenant instance:', err);
                     }
-                });
+                }));
             }
             manager.delete(tenantId);
         }
-        // Clear initializer cache for this tenant
-        for (const [cacheKey] of this.initializerCache.entries()) {
-            if (cacheKey.includes(tenantId)) {
-                this.initializerCache.delete(cacheKey);
-            }
+        // Track disposal so bootstrap can wait for it before re-initializing
+        if (disposalTasks.length > 0) {
+            const disposalPromise = Promise.all(disposalTasks).then(() => {
+                this.disposalPromises.delete(tenantId);
+            });
+            this.disposalPromises.set(tenantId, disposalPromise);
+        }
+        // Clear initializer cache for this tenant (exact match, not substring)
+        const exactKey = `tenant:${tenantId}`;
+        if (this.initializerCache.get(exactKey) !== undefined) {
+            this.initializerCache.delete(exactKey);
         }
     }
     /**
      * Invalidate cached data for a specific service type (local only) with disposal support
      */
     invalidateServiceLocally(serviceType, reason) {
+        this.emit({
+            type: 'service:invalidated',
+            serviceType,
+            reason,
+            timestamp: Date.now(),
+        });
         if (this.options.enableDiagnostics) {
             console.log(`Invalidating service cache locally: ${serviceType}`, reason ? `(${reason})` : '');
         }
@@ -1119,8 +1208,9 @@ class Container {
         }
         this.proxyCache.clear();
         this.initializerCache.clear();
-        this.initializerAccessOrder.clear();
         this.initializerPromises.clear();
+        this.disposalPromises.clear();
+        this.initializerCooldowns.clear();
         return result;
     }
     /**
@@ -1159,7 +1249,9 @@ class Container {
             pathCacheSize: 0, // removed - no longer tracked
             proxyCacheSize: this.proxyCache.size,
             factoryCacheSize: this.factoryCache.size,
-            initializerCacheSize: this.initializerCache.size,
+            initializerCacheSize: typeof this.initializerCache.size === 'function'
+                ? this.initializerCache.size()
+                : (this.initializerCache.size ?? 0),
             initializerPromisesSize: this.initializerPromises.size,
             cacheHitRatio: hits + misses > 0 ? hits / (hits + misses) : 0,
             batchSuccessRatio: batchOps > 0 ? (batchOps - batchErrors) / batchOps : 0,
@@ -1299,6 +1391,34 @@ class Container {
             }
         }
     }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // 🛑 KILL SWITCH
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Block a tenant from bootstrapping. Blocked tenants are rejected immediately.
+     * Use this for: runaway crons, infinite loops, compromised keys, legal holds.
+     */
+    blockTenant(tenantId) {
+        this.blockedTenants.add(tenantId);
+    }
+    /**
+     * Unblock a previously blocked tenant, restoring normal bootstrap behavior.
+     */
+    unblockTenant(tenantId) {
+        this.blockedTenants.delete(tenantId);
+    }
+    /**
+     * Check if a tenant is currently blocked.
+     */
+    isTenantBlocked(tenantId) {
+        return this.blockedTenants.has(tenantId);
+    }
+    /**
+     * Get the set of all currently blocked tenant IDs.
+     */
+    getBlockedTenants() {
+        return this.blockedTenants;
+    }
 }
 exports.Container = Container;
 //# sourceMappingURL=Container.js.map