@morojs/moro 1.6.2 → 1.6.3

package/src/core/pooling/object-pool-manager.ts

@@ -1,630 +0,0 @@
-// Unified Object Pool Manager
-// Consolidates object pooling from http-server, router, and other components
-
-import { createFrameworkLogger } from '../logger/index.js';
-import * as crypto from 'crypto';
-const logger = createFrameworkLogger('ObjectPoolManager');
-
-/**
- * Generic object pool for reusable objects
- */
-class ObjectPool<T> {
-  private pool: T[] = [];
-  private readonly factory: () => T;
-  private readonly reset?: (obj: T) => void;
-  private readonly maxSize: number;
-  private acquireCount = 0;
-  private releaseCount = 0;
-  private createCount = 0;
-
-  constructor(factory: () => T, maxSize: number = 100, reset?: (obj: T) => void) {
-    this.factory = factory;
-    this.maxSize = maxSize;
-    this.reset = reset;
-  }
-
-  acquire(): T {
-    this.acquireCount++;
-
-    if (this.pool.length > 0) {
-      return this.pool.pop()!;
-    }
-
-    this.createCount++;
-    return this.factory();
-  }
-
-  release(obj: T): void {
-    if (this.pool.length >= this.maxSize) {
-      return; // Pool is full, let it be garbage collected
-    }
-
-    this.releaseCount++;
-
-    // Reset object if reset function provided
-    if (this.reset) {
-      this.reset(obj);
-    }
-
-    this.pool.push(obj);
-  }
-
-  get size(): number {
-    return this.pool.length;
-  }
-
-  get stats() {
-    return {
-      poolSize: this.pool.length,
-      maxSize: this.maxSize,
-      acquireCount: this.acquireCount,
-      releaseCount: this.releaseCount,
-      createCount: this.createCount,
-      utilization: this.maxSize > 0 ? this.pool.length / this.maxSize : 0,
-    };
-  }
-
-  clear(): void {
-    this.pool = [];
-  }
-}
-
-/**
- * LRU Cache for route lookups
- */
-class LRUCache<K, V> {
-  private cache = new Map<K, V>();
-  private readonly maxSize: number;
-  private hits = 0;
-  private misses = 0;
-
-  constructor(maxSize: number = 500) {
-    this.maxSize = maxSize;
-  }
-
-  get(key: K): V | undefined {
-    const value = this.cache.get(key);
-    if (value !== undefined) {
-      this.hits++;
-      // Move to end (most recently used)
-      this.cache.delete(key);
-      this.cache.set(key, value);
-      return value;
-    }
-    this.misses++;
-    return undefined;
-  }
-
-  set(key: K, value: V): void {
-    if (this.cache.has(key)) {
-      this.cache.delete(key);
-    }
-
-    this.cache.set(key, value);
-
-    // Evict oldest if over capacity
-    if (this.cache.size > this.maxSize) {
-      const firstKey = this.cache.keys().next().value;
-      if (firstKey !== undefined) {
-        this.cache.delete(firstKey);
-      }
-    }
-  }
-
-  has(key: K): boolean {
-    return this.cache.has(key);
-  }
-
-  delete(key: K): boolean {
-    return this.cache.delete(key);
-  }
-
-  clear(): void {
-    this.cache.clear();
-    this.hits = 0;
-    this.misses = 0;
-  }
-
-  get size(): number {
-    return this.cache.size;
-  }
-
-  get stats() {
-    const total = this.hits + this.misses;
-    return {
-      size: this.cache.size,
-      maxSize: this.maxSize,
-      hits: this.hits,
-      misses: this.misses,
-      hitRate: total > 0 ? this.hits / total : 0,
-    };
-  }
-}
-
-/**
- * ObjectPoolManager - Singleton for managing all object pools
- * Consolidates pools from:
- * - MoroHttpServer (paramObjectPool, bufferPool)
- * - Router (paramObjectPool)
- * - Various route caches
- */
-export class ObjectPoolManager {
-  private static instance: ObjectPoolManager | null = null;
-
-  // Parameter object pool (for route params)
-  private paramPool: ObjectPool<Record<string, string>>;
-
-  // Header object pool (for parsed headers)
-  private headerPool: ObjectPool<Record<string, string>>;
-
-  // Query object pool (for parsed query strings)
-  private queryPool: ObjectPool<Record<string, string>>;
-
-  // Buffer pools by size
-  private bufferPools: Map<number, ObjectPool<Buffer>>;
-  private readonly bufferSizes = [64, 256, 1024, 4096, 16384];
-
-  // Route lookup cache
-  private routeCache: LRUCache<string, any>;
-
-  // Response cache (for common responses - now includes full response metadata)
-  private responseCache: LRUCache<
-    string,
-    { buffer: Buffer; headers: Record<string, string>; statusCode: number }
-  >;
-
-  // Performance monitoring
-  private performanceStats = {
-    poolHits: 0,
-    poolMisses: 0,
-    totalAcquisitions: 0,
-    totalReleases: 0,
-    lastAdjustment: 0,
-    adjustmentInterval: 60000, // 1 minute
-  };
-
-  // Adaptive pool sizing
-  private poolUsageHistory: Map<string, number[]> = new Map();
-  private adaptiveMode = true;
-
-  private constructor() {
-    // Set initial last adjustment time to prevent immediate adjustment
-    this.performanceStats.lastAdjustment = Date.now();
-
-    // Initialize parameter object pool with adaptive sizing
-    this.paramPool = new ObjectPool(
-      () => ({}),
-      100, // Initial size
-      (obj: Record<string, string>) => {
-        // Clear all properties
-        for (const key in obj) {
-          delete obj[key];
-        }
-      }
-    );
-
-    // Initialize header object pool
-    this.headerPool = new ObjectPool(
-      () => ({}),
-      50, // Initial size - headers are less common to pool
-      (obj: Record<string, string>) => {
-        // Clear all properties
-        for (const key in obj) {
-          delete obj[key];
-        }
-      }
-    );
-
-    // Initialize query object pool
-    this.queryPool = new ObjectPool(
-      () => ({}),
-      100, // Initial size - queries are very common
-      (obj: Record<string, string>) => {
-        // Clear all properties
-        for (const key in obj) {
-          delete obj[key];
-        }
-      }
-    );
-
-    // Initialize buffer pools with enhanced sizing
-    this.bufferPools = new Map();
-    this.bufferSizes.forEach(size => {
-      this.bufferPools.set(
-        size,
-        new ObjectPool<Buffer>(() => Buffer.allocUnsafe(size), this.getOptimalPoolSize(size))
-      );
-    });
-
-    // Initialize caches with enhanced statistics
-    this.routeCache = new LRUCache(500);
-    this.responseCache = new LRUCache(200); // Increased for full response caching
-
-    // Pre-warm pools for better initial performance
-    this.preWarmPools();
-
-    logger.debug(
-      'ObjectPoolManager initialized with enhanced performance features',
-      'Initialization'
-    );
-  }
-
-  /**
-   * Pre-warm pools with initial objects for better startup performance
-   */
-  private preWarmPools(): void {
-    // Pre-warm parameter pool
-    for (let i = 0; i < 20; i++) {
-      const obj = this.paramPool.acquire();
-      this.paramPool.release(obj);
-    }
-
-    // Pre-warm header pool
-    for (let i = 0; i < 10; i++) {
-      const obj = this.headerPool.acquire();
-      this.headerPool.release(obj);
-    }
-
-    // Pre-warm query pool
-    for (let i = 0; i < 20; i++) {
-      const obj = this.queryPool.acquire();
-      this.queryPool.release(obj);
-    }
-
-    // Pre-warm buffer pools
-    this.bufferSizes.forEach(size => {
-      const pool = this.bufferPools.get(size);
-      if (pool) {
-        for (let i = 0; i < Math.min(10, pool.stats.maxSize); i++) {
-          const buffer = pool.acquire();
-          pool.release(buffer);
-        }
-      }
-    });
-
-    logger.debug('Object pools pre-warmed', 'PoolManager');
-  }
-
-  /**
-   * Get optimal pool size based on buffer size and usage patterns
-   */
-  private getOptimalPoolSize(bufferSize: number): number {
-    // Smaller buffers can have larger pools
-    if (bufferSize <= 256) return 100;
-    if (bufferSize <= 1024) return 75;
-    if (bufferSize <= 4096) return 50;
-    return 25; // Large buffers need smaller pools
-  }
-
-  static getInstance(): ObjectPoolManager {
-    if (!this.instance) {
-      this.instance = new ObjectPoolManager();
-    }
-    return this.instance;
-  }
-
-  /**
-   * Reset the singleton (useful for testing)
-   */
-  static reset(): void {
-    if (this.instance) {
-      this.instance.clearAll();
-    }
-    this.instance = null;
-  }
-
-  // Parameter Object Pool
-
-  acquireParams(): Record<string, string> {
-    this.performanceStats.totalAcquisitions++;
-    const obj = this.paramPool.acquire();
-
-    if (this.poolUsageHistory.has('params')) {
-      const history = this.poolUsageHistory.get('params')!;
-      if (history.length >= 100) {
-        history.shift(); // Keep only last 100 measurements
-      }
-      history.push(this.paramPool.size);
-    } else {
-      this.poolUsageHistory.set('params', [this.paramPool.size]);
-    }
-
-    return obj;
-  }
-
-  releaseParams(obj: Record<string, string>): void {
-    this.performanceStats.totalReleases++;
-    this.paramPool.release(obj);
-
-    // Adaptive pool sizing based on usage patterns
-    if (
-      this.adaptiveMode &&
-      Date.now() - this.performanceStats.lastAdjustment > this.performanceStats.adjustmentInterval
-    ) {
-      this.adjustPoolSizes();
-    }
-  }
-
-  // Header Object Pool
-
-  acquireHeaders(): Record<string, string> {
-    this.performanceStats.totalAcquisitions++;
-    return this.headerPool.acquire();
-  }
-
-  releaseHeaders(obj: Record<string, string>): void {
-    this.performanceStats.totalReleases++;
-    this.headerPool.release(obj);
-  }
-
-  // Query Object Pool
-
-  acquireQuery(): Record<string, string> {
-    this.performanceStats.totalAcquisitions++;
-    return this.queryPool.acquire();
-  }
-
-  releaseQuery(obj: Record<string, string>): void {
-    this.performanceStats.totalReleases++;
-    this.queryPool.release(obj);
-  }
-
-  // Request ID Generation
-
-  generateRequestId(): string {
-    return crypto.randomUUID();
-  }
-
-  // Buffer Pool
-
-  acquireBuffer(size: number): Buffer {
-    this.performanceStats.totalAcquisitions++;
-
-    // Find smallest buffer that fits
-    for (const poolSize of this.bufferSizes) {
-      if (size <= poolSize) {
-        const pool = this.bufferPools.get(poolSize);
-        if (pool) {
-          const buffer = pool.acquire();
-          this.performanceStats.poolHits++;
-
-          // Track usage for adaptive sizing
-          const poolKey = `buffer_${poolSize}`;
-          if (this.poolUsageHistory.has(poolKey)) {
-            const history = this.poolUsageHistory.get(poolKey)!;
-            if (history.length >= 100) {
-              history.shift();
-            }
-            history.push(pool.size);
-          } else {
-            this.poolUsageHistory.set(poolKey, [pool.size]);
-          }
-
-          return buffer;
-        }
-      }
-    }
-
-    // No pool available for this size, allocate directly
-    this.performanceStats.poolMisses++;
-    return Buffer.allocUnsafe(size);
-  }
-
-  releaseBuffer(buffer: Buffer): void {
-    this.performanceStats.totalReleases++;
-    const size = buffer.length;
-    const pool = this.bufferPools.get(size);
-    if (pool) {
-      pool.release(buffer);
-
-      // Adaptive pool sizing based on usage patterns
-      if (
-        this.adaptiveMode &&
-        Date.now() - this.performanceStats.lastAdjustment > this.performanceStats.adjustmentInterval
-      ) {
-        this.adjustPoolSizes();
-      }
-    }
-    // If no pool for this size, let it be garbage collected
-  }
-
-  // Route Cache
-
-  getCachedRoute(key: string): any {
-    return this.routeCache.get(key);
-  }
-
-  cacheRoute(key: string, route: any): void {
-    this.routeCache.set(key, route);
-  }
-
-  hasCachedRoute(key: string): boolean {
-    return this.routeCache.has(key);
-  }
-
-  clearRouteCache(): void {
-    this.routeCache.clear();
-  }
-
-  // Response Cache (For Opt-In Explicit Caching Only)
-  // NOTE: This cache is NOT used automatically by the framework.
-  // It's available for developers who explicitly want to cache specific responses.
-  // Developers must carefully manage cache keys to avoid stale/incorrect data.
-
-  getCachedResponse(
-    key: string
-  ): { buffer: Buffer; headers: Record<string, string>; statusCode: number } | undefined {
-    return this.responseCache.get(key);
-  }
-
-  cacheResponse(
-    key: string,
-    buffer: Buffer,
-    headers: Record<string, string>,
-    statusCode: number = 200
-  ): void {
-    // Cache responses up to 4KB
-    // WARNING: Only use this for static responses that never change
-    if (buffer.length < 4096) {
-      this.responseCache.set(key, {
-        buffer: Buffer.from(buffer), // Clone to avoid mutations
-        headers: { ...headers }, // Clone headers
-        statusCode,
-      });
-    }
-  }
-
-  hasCachedResponse(key: string): boolean {
-    return this.responseCache.has(key);
-  }
-
-  clearResponseCache(): void {
-    this.responseCache.clear();
-  }
-
-  /**
-   * Adaptively adjust pool sizes based on usage patterns
-   */
-  private adjustPoolSizes(): void {
-    this.performanceStats.lastAdjustment = Date.now();
-
-    // Adjust parameter pool size
-    const paramHistory = this.poolUsageHistory.get('params') || [];
-    if (paramHistory.length >= 10) {
-      const avgUsage = paramHistory.reduce((sum, size) => sum + size, 0) / paramHistory.length;
-      const targetSize = Math.min(Math.max(Math.round(avgUsage * 1.2), 50), 200); // 20% buffer, 50-200 range
-
-      if (Math.abs(this.paramPool.stats.maxSize - targetSize) > 10) {
-        logger.debug(
-          `Adjusting param pool size from ${this.paramPool.stats.maxSize} to ${targetSize}`,
-          'PoolManager'
-        );
-        // Note: We can't directly change maxSize, but we can log the recommendation
-        // In a real implementation, we'd recreate the pool with the new size
-      }
-    }
-
-    // Adjust buffer pool sizes
-    this.bufferSizes.forEach(size => {
-      const poolKey = `buffer_${size}`;
-      const history = this.poolUsageHistory.get(poolKey) || [];
-      if (history.length >= 10) {
-        const avgUsage = history.reduce((sum, size) => sum + size, 0) / history.length;
-        const pool = this.bufferPools.get(size);
-        if (pool) {
-          const currentMax = pool.stats.maxSize;
-          const targetMax = this.getOptimalPoolSize(size);
-
-          if (Math.abs(currentMax - targetMax) > 5) {
-            logger.debug(
-              `Buffer pool ${size}B: usage ${avgUsage.toFixed(1)}/${currentMax}, target ${targetMax}`,
-              'PoolManager'
-            );
-          }
-        }
-      }
-    });
-
-    logger.debug('Pool size adjustment cycle completed', 'PoolManager');
-  }
-
-  /**
-   * Enable or disable adaptive pool sizing
-   */
-  setAdaptiveMode(enabled: boolean): void {
-    this.adaptiveMode = enabled;
-    logger.debug(`Adaptive pool sizing ${enabled ? 'enabled' : 'disabled'}`, 'PoolManager');
-  }
-
-  // Utility Methods
-
-  /**
-   * Clear all pools and caches
-   */
-  clearAll(): void {
-    this.paramPool.clear();
-    this.headerPool.clear();
-    this.queryPool.clear();
-    this.bufferPools.forEach(pool => pool.clear());
-    this.routeCache.clear();
-    this.responseCache.clear();
-    logger.debug('All pools and caches cleared', 'Maintenance');
-  }
-
-  /**
-   * Force garbage collection on pooled objects
-   */
-  forceCleanup(): void {
-    this.clearAll();
-
-    // Force GC if available
-    if (globalThis?.gc) {
-      globalThis.gc();
-      logger.debug('Forced garbage collection', 'Maintenance');
-    }
-  }
-
-  /**
-   * Get comprehensive performance statistics
-   */
-  getStats() {
-    const bufferPoolStats: Record<string, any> = {};
-    this.bufferPools.forEach((pool, size) => {
-      bufferPoolStats[`${size}B`] = pool.stats;
-    });
-
-    return {
-      paramPool: this.paramPool.stats,
-      headerPool: this.headerPool.stats,
-      queryPool: this.queryPool.stats,
-      bufferPools: bufferPoolStats,
-      routeCache: this.routeCache.stats,
-      responseCache: this.responseCache.stats,
-      totalMemory: {
-        params: this.paramPool.size * 50, // Rough estimate
-        headers: this.headerPool.size * 100, // Rough estimate
-        queries: this.queryPool.size * 50, // Rough estimate
-        buffers: Array.from(this.bufferPools.values()).reduce((sum, pool) => sum + pool.size, 0),
-        routes: this.routeCache.size * 200, // Rough estimate
-        responses: this.responseCache.size * 1000, // Rough estimate (increased for full responses)
-      },
-    };
-  }
-
-  /**
-   * Get performance summary for monitoring
-   */
-  getPerformanceSummary() {
-    const stats = this.getStats();
-    const routeCacheTotal = stats.routeCache.hits + stats.routeCache.misses;
-    const responseCacheTotal = stats.responseCache.hits + stats.responseCache.misses;
-
-    return {
-      routeCacheHitRate: routeCacheTotal > 0 ? (stats.routeCache.hits / routeCacheTotal) * 100 : 0,
-      responseCacheHitRate:
-        responseCacheTotal > 0 ? (stats.responseCache.hits / responseCacheTotal) * 100 : 0,
-      paramPoolUtilization: stats.paramPool.utilization * 100,
-      totalMemoryKB: Object.values(stats.totalMemory).reduce((a, b) => a + b, 0) / 1024,
-    };
-  }
-
-  /**
-   * Log performance statistics
-   */
-  logStats(): void {
-    const summary = this.getPerformanceSummary();
-    logger.info('ObjectPoolManager Performance', 'Stats', {
-      routeCacheHitRate: `${summary.routeCacheHitRate.toFixed(1)}%`,
-      responseCacheHitRate: `${summary.responseCacheHitRate.toFixed(1)}%`,
-      paramPoolUtilization: `${summary.paramPoolUtilization.toFixed(1)}%`,
-      totalMemory: `${summary.totalMemoryKB.toFixed(1)} KB`,
-    });
-  }
-}
-
-/**
- * Convenience function to get the singleton instance
- */
-export function getPoolManager(): ObjectPoolManager {
-  return ObjectPoolManager.getInstance();
-}