@morojs/moro 1.5.4 → 1.5.6

package/src/core/routing/index.ts

@@ -256,20 +256,91 @@ export class IntelligentRouteBuilder implements RouteBuilder {
 
 // Executable route with intelligent middleware ordering
 export class ExecutableRoute implements CompiledRoute {
-  constructor(public readonly schema: RouteSchema) {}
+  // PERFORMANCE OPTIMIZATION: Pre-analyze route requirements
+  private readonly requiresAuth: boolean;
+  private readonly requiresValidation: boolean;
+  private readonly requiresRateLimit: boolean;
+  private readonly requiresCache: boolean;
+  private readonly hasBeforeMiddleware: boolean;
+  private readonly hasAfterMiddleware: boolean;
+  private readonly hasTransformMiddleware: boolean;
+  private readonly isFastPath: boolean;
+
+  constructor(public readonly schema: RouteSchema) {
+    // Pre-calculate what this route actually needs
+    this.requiresAuth = !!this.schema.auth;
+    this.requiresValidation = !!this.schema.validation;
+    this.requiresRateLimit = !!this.schema.rateLimit;
+    this.requiresCache = !!this.schema.cache;
+    this.hasBeforeMiddleware = !!this.schema.middleware?.before?.length;
+    this.hasAfterMiddleware = !!this.schema.middleware?.after?.length;
+    this.hasTransformMiddleware = !!this.schema.middleware?.transform?.length;
+
+    // Fast path: no middleware, no auth, no validation, no rate limiting
+    this.isFastPath =
+      !this.requiresAuth &&
+      !this.requiresValidation &&
+      !this.requiresRateLimit &&
+      !this.requiresCache &&
+      !this.hasBeforeMiddleware &&
+      !this.hasAfterMiddleware &&
+      !this.hasTransformMiddleware;
+
+    // Log fast path routes for monitoring
+    if (this.isFastPath) {
+      logger.debug(`Fast path route: ${this.schema.method} ${this.schema.path}`, 'FastPath');
+    }
+  }
 
   async execute(req: HttpRequest, res: HttpResponse): Promise<void> {
     const validatedReq = req as ValidatedRequest;
 
     try {
-      // Execute middleware in intelligent order
-      await this.executePhase('before', validatedReq, res);
-      await this.executePhase('rateLimit', validatedReq, res);
-      await this.executePhase('auth', validatedReq, res);
-      await this.executePhase('validation', validatedReq, res);
-      await this.executePhase('transform', validatedReq, res);
-      await this.executePhase('cache', validatedReq, res);
-      await this.executePhase('after', validatedReq, res);
+      // PERFORMANCE OPTIMIZATION: Fast path for simple routes
+      if (this.isFastPath) {
+        // Skip all middleware - execute handler directly
+        const result = await this.schema.handler(validatedReq, res);
+        if (result !== undefined && !res.headersSent) {
+          res.json(result);
+        }
+        return;
+      }
+
+      // Optimized middleware execution - only run what's needed
+      if (this.hasBeforeMiddleware) {
+        await this.executePhase('before', validatedReq, res);
+        if (res.headersSent) return;
+      }
+
+      if (this.requiresRateLimit) {
+        await this.executePhase('rateLimit', validatedReq, res);
+        if (res.headersSent) return;
+      }
+
+      if (this.requiresAuth) {
+        await this.executePhase('auth', validatedReq, res);
+        if (res.headersSent) return;
+      }
+
+      if (this.requiresValidation) {
+        await this.executePhase('validation', validatedReq, res);
+        if (res.headersSent) return;
+      }
+
+      if (this.hasTransformMiddleware) {
+        await this.executePhase('transform', validatedReq, res);
+        if (res.headersSent) return;
+      }
+
+      if (this.requiresCache) {
+        await this.executePhase('cache', validatedReq, res);
+        if (res.headersSent) return;
+      }
+
+      if (this.hasAfterMiddleware) {
+        await this.executePhase('after', validatedReq, res);
+        if (res.headersSent) return;
+      }
 
       // Execute handler last
       if (!res.headersSent) {
@@ -361,15 +432,32 @@ export class ExecutableRoute implements CompiledRoute {
     req: HttpRequest,
     res: HttpResponse
   ): Promise<void> {
+    // PERFORMANCE OPTIMIZATION: Reduce Promise overhead
     return new Promise((resolve, reject) => {
+      let resolved = false;
+
+      const next = () => {
+        if (!resolved) {
+          resolved = true;
+          resolve();
+        }
+      };
+
       try {
-        const next = () => resolve();
         const result = middleware(req, res, next);
         if (result instanceof Promise) {
-          result.then(() => resolve()).catch(reject);
+          result.then(() => !resolved && next()).catch(reject);
+        } else {
+          // Synchronous middleware - call next immediately if not called
+          if (!resolved) {
+            next();
+          }
         }
       } catch (error) {
-        reject(error);
+        if (!resolved) {
+          resolved = true;
+          reject(error);
+        }
       }
     });
   }
@@ -475,6 +563,22 @@ export class ExecutableRoute implements CompiledRoute {
       config: this.schema.cache,
     });
   }
+
+  // Performance monitoring
+  getPerformanceInfo() {
+    return {
+      path: this.schema.path,
+      method: this.schema.method,
+      isFastPath: this.isFastPath,
+      requiresAuth: this.requiresAuth,
+      requiresValidation: this.requiresValidation,
+      requiresRateLimit: this.requiresRateLimit,
+      requiresCache: this.requiresCache,
+      hasBeforeMiddleware: this.hasBeforeMiddleware,
+      hasAfterMiddleware: this.hasAfterMiddleware,
+      hasTransformMiddleware: this.hasTransformMiddleware,
+    };
+  }
 }
 
 // Factory functions for creating routes

package/src/moro.ts

@@ -11,6 +11,7 @@ import {
   logger as globalLogger,
   applyLoggingConfiguration,
 } from './core/logger';
+import { Logger } from './types/logger';
 import { MiddlewareManager } from './core/middleware';
 import { IntelligentRoutingManager } from './core/routing/app-integration';
 import { RouteBuilder, RouteSchema, CompiledRoute } from './core/routing';
@@ -19,7 +20,12 @@ import { readdirSync, statSync } from 'fs';
 import { join } from 'path';
 import { EventEmitter } from 'events';
 // Configuration System Integration
-import { initializeConfig, getGlobalConfig, type AppConfig } from './core/config';
+import {
+  initializeConfig,
+  getGlobalConfig,
+  loadConfigWithOptions,
+  type AppConfig,
+} from './core/config';
 // Runtime System Integration
 import {
   RuntimeAdapter,
@@ -37,7 +43,7 @@ export class Moro extends EventEmitter {
   // Enterprise event system integration
   private eventBus: MoroEventBus;
   // Application logger
-  private logger = createFrameworkLogger('App');
+  private logger!: Logger;
   // Intelligent routing system
   private intelligentRouting = new IntelligentRoutingManager();
   // Documentation system
@@ -53,72 +59,33 @@ export class Moro extends EventEmitter {
   constructor(options: MoroOptions = {}) {
     super(); // Call EventEmitter constructor
 
-    // Configure logger from environment variables BEFORE config system initialization
-    // This ensures the config loading process respects the log level
+    // Apply logging configuration BEFORE config loading to avoid DEBUG spam
+    // 1. Environment variables (base level)
     const envLogLevel = process.env.LOG_LEVEL || process.env.MORO_LOG_LEVEL;
     if (envLogLevel) {
       applyLoggingConfiguration({ level: envLogLevel }, undefined);
     }
 
-    // Initialize configuration system - create a deep copy for this instance
-    this.config = JSON.parse(JSON.stringify(initializeConfig()));
-
-    // Apply logging configuration from the loaded config (this happens after config file processing)
-    if (this.config.logging) {
-      applyLoggingConfiguration(this.config.logging, undefined);
-    }
-
-    // Apply additional logging configuration from createApp options (takes precedence)
+    // 2. createApp logger options (highest precedence)
     if (options.logger !== undefined) {
       applyLoggingConfiguration(undefined, options.logger);
     }
 
-    // Apply performance configuration from createApp options (takes precedence)
-    if (options.performance) {
-      if (options.performance.clustering) {
-        this.config.performance.clustering = {
-          ...this.config.performance.clustering,
-          ...options.performance.clustering,
-        };
-      }
-      if (options.performance.compression) {
-        this.config.performance.compression = {
-          ...this.config.performance.compression,
-          ...options.performance.compression,
-        };
-      }
-      if (options.performance.circuitBreaker) {
-        this.config.performance.circuitBreaker = {
-          ...this.config.performance.circuitBreaker,
-          ...options.performance.circuitBreaker,
-        };
-      }
-    }
+    // Create logger AFTER initial configuration
+    this.logger = createFrameworkLogger('App');
 
-    // Apply modules configuration from createApp options (takes precedence)
-    if (options.modules) {
-      if (options.modules.cache) {
-        this.config.modules.cache = {
-          ...this.config.modules.cache,
-          ...options.modules.cache,
-        };
-      }
-      if (options.modules.rateLimit) {
-        this.config.modules.rateLimit = {
-          ...this.config.modules.rateLimit,
-          ...options.modules.rateLimit,
-        };
-      }
-      if (options.modules.validation) {
-        this.config.modules.validation = {
-          ...this.config.modules.validation,
-          ...options.modules.validation,
-        };
-      }
+    // Use simplified global configuration system
+    this.config = initializeConfig(options);
+
+    // Apply config file logging if it exists (may override createApp options if needed)
+    if (this.config.logging && !options.logger) {
+      applyLoggingConfiguration(this.config.logging, undefined);
+      // Recreate logger with updated config
+      this.logger = createFrameworkLogger('App');
     }
 
     this.logger.info(
-      `Configuration system initialized: ${this.config.server.environment}:${this.config.server.port}`
+      `Configuration system initialized: ${process.env.NODE_ENV || 'development'}:${this.config.server.port}`
     );
 
     // Initialize runtime system
@@ -127,10 +94,11 @@ export class Moro extends EventEmitter {
 
     this.logger.info(`Runtime system initialized: ${this.runtimeType}`, 'Runtime');
 
-    // Pass logging configuration from config to framework
+    // Pass configuration from config to framework
     const frameworkOptions: any = {
       ...options,
       logger: this.config.logging,
+      websocket: this.config.websocket.enabled ? options.websocket || {} : false,
     };
 
     this.coreFramework = new MoroCore(frameworkOptions);
@@ -540,8 +508,9 @@ export class Moro extends EventEmitter {
       this.logger.info('Moro Server Started', 'Server');
       this.logger.info(`Runtime: ${this.runtimeType}`, 'Server');
       this.logger.info(`HTTP API: http://${displayHost}:${port}`, 'Server');
-      this.logger.info(`WebSocket: ws://${displayHost}:${port}`, 'Server');
-      this.logger.info('Native Node.js HTTP • Zero Dependencies • Maximum Performance', 'Server');
+      if (this.config.websocket.enabled) {
+        this.logger.info(`WebSocket: ws://${displayHost}:${port}`, 'Server');
+      }
       this.logger.info('Learn more at https://morojs.com', 'Server');
 
       // Log intelligent routes info
@@ -935,55 +904,84 @@ export class Moro extends EventEmitter {
     return module.default || module;
   }
 
-  // Clustering support for massive performance gains with proper cleanup
+  /**
+   * Node.js Clustering Implementation
+   * This clustering algorithm is based on published research and Node.js best practices.
+   *
+   * IPC (Inter-Process Communication) Considerations:
+   * - Excessive workers create IPC bottlenecks (Source: BetterStack Node.js Guide)
+   * - Round-robin scheduling provides better load distribution (Node.js Documentation)
+   * - Message passing overhead increases significantly with worker count
+   *
+   * Memory Management:
+   * - ~2GB per worker prevents memory pressure and GC overhead
+   * - Conservative heap limits reduce memory fragmentation
+   *
+   * References:
+   * - Node.js Cluster Documentation: https://nodejs.org/api/cluster.html
+   * - BetterStack Node.js Clustering: https://betterstack.com/community/guides/scaling-nodejs/node-clustering/
+   */
   private clusterWorkers = new Map<number, any>();
+
   private startWithClustering(port: number, host?: string, callback?: () => void): void {
     const cluster = require('cluster');
     const os = require('os');
 
-    // Smart worker count calculation based on actual bottlenecks
+    // Worker count calculation - respect user choice
     let workerCount = this.config.performance?.clustering?.workers || os.cpus().length;
 
-    // Auto-optimize worker count based on system characteristics
-    if (workerCount === 'auto' || workerCount > 8) {
-      // For high-core machines, limit workers to prevent IPC/memory bottlenecks
+    // Only auto-optimize if user hasn't specified a number or set it to 'auto'
+    if (workerCount === 'auto') {
       const cpuCount = os.cpus().length;
       const totalMemoryGB = os.totalmem() / (1024 * 1024 * 1024);
 
-      // Optimal worker count formula based on research
-      if (cpuCount >= 16) {
-        // High-core machines: focus on memory/IPC efficiency
-        workerCount = Math.min(Math.ceil(totalMemoryGB / 2), 4); // 2GB per worker max, cap at 4
-      } else if (cpuCount >= 8) {
-        // Mid-range machines: balanced approach
-        workerCount = Math.min(cpuCount / 2, 4);
-      } else {
-        // Low-core machines: use all cores
-        workerCount = cpuCount;
+      // Get memory per worker from config - if not set by user, calculate dynamically
+      let memoryPerWorkerGB = this.config.performance?.clustering?.memoryPerWorkerGB;
+
+      if (!memoryPerWorkerGB) {
+        // Dynamic calculation: (Total RAM - 4GB headroom) / CPU cores
+        const headroomGB = 4;
+        memoryPerWorkerGB = Math.max(0.5, Math.floor((totalMemoryGB - headroomGB) / cpuCount));
       }
 
+      // Conservative formula based on general guidelines:
+      // - Don't exceed CPU cores
+      // - Respect user's memory allocation preference
+      // - Let the system resources determine the limit
+      workerCount = Math.min(
+        cpuCount, // Don't exceed CPU cores
+        Math.floor(totalMemoryGB / memoryPerWorkerGB) // User-configurable memory per worker
+      );
+
       this.logger.info(
-        `Auto-optimized workers: ${workerCount} (CPU: ${cpuCount}, RAM: ${totalMemoryGB.toFixed(1)}GB)`,
+        `Auto-calculated worker count: ${workerCount} (CPU: ${cpuCount}, RAM: ${totalMemoryGB.toFixed(1)}GB, ${memoryPerWorkerGB}GB per worker)`,
         'Cluster'
       );
+    } else if (typeof workerCount === 'number') {
+      // User specified a number - respect their choice
+      this.logger.info(`Using user-specified worker count: ${workerCount}`, 'Cluster');
     }
 
     if (cluster.isPrimary) {
-      this.logger.info(`🚀 Starting ${workerCount} workers for maximum performance`, 'Cluster');
+      this.logger.info(`Starting ${workerCount} workers`, 'Cluster');
 
       // Optimize cluster scheduling for high concurrency
-      cluster.schedulingPolicy = cluster.SCHED_RR; // Round-robin scheduling
+      // Round-robin is the default on all platforms except Windows (Node.js docs)
+      // Provides better load distribution than shared socket approach
+      cluster.schedulingPolicy = cluster.SCHED_RR;
 
       // Set cluster settings for better performance
       cluster.setupMaster({
-        exec: process.argv[1],
+        exec: process.argv[1] || process.execPath,
         args: process.argv.slice(2),
         silent: false,
       });
 
-      // Optimize IPC to reduce communication overhead
+      // IPC Optimization: Reduce communication overhead between master and workers
+      // Research shows excessive IPC can create bottlenecks in clustered applications
+      // (Source: BetterStack - Node.js Clustering Guide)
       process.env.NODE_CLUSTER_SCHED_POLICY = 'rr'; // Ensure round-robin
-      process.env.NODE_DISABLE_COLORS = '1'; // Reduce IPC message size
+      process.env.NODE_DISABLE_COLORS = '1'; // Reduce IPC message size by disabling color codes
 
       // Graceful shutdown handler
       const gracefulShutdown = () => {
@@ -1004,37 +1002,32 @@ export class Moro extends EventEmitter {
       process.on('SIGINT', gracefulShutdown);
       process.on('SIGTERM', gracefulShutdown);
 
-      // Fork workers with proper tracking and CPU affinity
+      // Fork workers with basic tracking
       for (let i = 0; i < workerCount; i++) {
-        const worker = cluster.fork({
-          WORKER_ID: i,
-          WORKER_CPU_AFFINITY: i % os.cpus().length, // Distribute workers across CPUs
-        });
+        const worker = cluster.fork();
         this.clusterWorkers.set(worker.process.pid!, worker);
-        this.logger.info(
-          `Worker ${worker.process.pid} started (CPU ${i % os.cpus().length})`,
-          'Cluster'
-        );
+        this.logger.info(`Worker ${worker.process.pid} started`, 'Cluster');
 
-        // Handle individual worker messages (reuse handler)
+        // Handle individual worker messages
         worker.on('message', this.handleWorkerMessage.bind(this));
       }
 
-      // Handle worker exits with cleanup
+      // Simple worker exit handling
       cluster.on('exit', (worker: any, code: number, signal: string) => {
-        // Clean up worker tracking
-        this.clusterWorkers.delete(worker.process.pid);
-
-        this.logger.warn(
-          `Worker ${worker.process.pid} died (${signal || code}). Restarting...`,
-          'Cluster'
-        );
-
-        // Restart worker with proper tracking
-        const newWorker = cluster.fork();
-        this.clusterWorkers.set(newWorker.process.pid!, newWorker);
-        newWorker.on('message', this.handleWorkerMessage.bind(this));
-        this.logger.info(`Worker ${newWorker.process.pid} started`, 'Cluster');
+        const pid = worker.process.pid;
+        this.clusterWorkers.delete(pid);
+
+        if (code !== 0 && !worker.exitedAfterDisconnect) {
+          this.logger.warn(
+            `Worker ${pid} died unexpectedly (${signal || code}). Restarting...`,
+            'Cluster'
+          );
+
+          // Simple restart
+          const newWorker = cluster.fork();
+          this.clusterWorkers.set(newWorker.process.pid!, newWorker);
+          this.logger.info(`Worker ${newWorker.process.pid} restarted`, 'Cluster');
+        }
       });
 
       // Master process callback
@@ -1047,13 +1040,29 @@ export class Moro extends EventEmitter {
       process.env.UV_THREADPOOL_SIZE = '64';
 
       // Reduce logging contention in workers (major bottleneck)
+      // Multiple workers writing to same log files creates I/O contention
       if (this.config.logging) {
         // Workers log less frequently to reduce I/O contention
-        this.config.logging.level = 'warn'; // Only warnings and errors
+        applyLoggingConfiguration(undefined, { level: 'warn' }); // Only warnings and errors
       }
 
-      // Memory optimization for workers
-      process.env.NODE_OPTIONS = '--max-old-space-size=1024'; // Limit memory per worker
+      // Research-based memory optimization for workers
+      const os = require('os');
+      const totalMemoryGB = os.totalmem() / (1024 * 1024 * 1024);
+      const workerCount = Object.keys(require('cluster').workers || {}).length || 1;
+
+      // Conservative memory allocation
+      const heapSizePerWorkerMB = Math.min(
+        Math.floor(((totalMemoryGB * 1024) / workerCount) * 0.8), // 80% of available memory
+        1536 // Cap at 1.5GB (GC efficiency threshold from research)
+      );
+
+      process.env.NODE_OPTIONS = `--max-old-space-size=${heapSizePerWorkerMB}`;
+
+      this.logger.debug(
+        `Worker memory allocated: ${heapSizePerWorkerMB}MB heap (${workerCount} workers, ${totalMemoryGB.toFixed(1)}GB total)`,
+        'Worker'
+      );
 
       // Optimize V8 flags for better performance (Rust-level optimizations)
       if (process.env.NODE_ENV === 'production') {
@@ -1149,7 +1158,7 @@ export class Moro extends EventEmitter {
     }
   }
 
-  // Reusable worker message handler (avoids creating new functions)
+  // Simple worker message handler
   private handleWorkerMessage(message: any): void {
     // Handle inter-worker communication if needed
     if (message.type === 'health-check') {
@@ -1160,6 +1169,49 @@ export class Moro extends EventEmitter {
     // Log other worker messages
     this.logger.debug(`Worker message: ${JSON.stringify(message)}`, 'Cluster');
   }
+
+  /**
+   * Gracefully close the application and clean up resources
+   * This should be called in tests and during shutdown
+   */
+  async close(): Promise<void> {
+    this.logger.debug('Closing Moro application...');
+
+    // Flush logger buffer before shutdown
+    try {
+      // Use flushBuffer for immediate synchronous flush
+      this.logger.flushBuffer();
+    } catch (error) {
+      // Ignore flush errors during shutdown
+    }
+
+    // Close the core framework with timeout
+    if (this.coreFramework && (this.coreFramework as any).httpServer) {
+      try {
+        await Promise.race([
+          new Promise<void>(resolve => {
+            (this.coreFramework as any).httpServer.close(() => {
+              resolve();
+            });
+          }),
+          new Promise<void>(resolve => setTimeout(resolve, 2000)), // 2 second timeout
+        ]);
+      } catch (error) {
+        // Force close if graceful close fails
+        this.logger.warn('Force closing HTTP server due to timeout');
+      }
+    }
+
+    // Clean up event listeners
+    try {
+      this.eventBus.removeAllListeners();
+      this.removeAllListeners();
+    } catch (error) {
+      // Ignore cleanup errors
+    }
+
+    this.logger.debug('Moro application closed successfully');
+  }
 }
 
 // Export convenience function

package/src/types/config.ts

@@ -3,7 +3,6 @@
 export interface ServerConfig {
   port: number;
   host: string;
-  environment: 'development' | 'staging' | 'production';
   maxConnections: number;
   timeout: number;
 }
@@ -19,7 +18,7 @@ export interface ServiceDiscoveryConfig {
 
 export interface DatabaseConfig {
   url?: string;
-  redis: {
+  redis?: {
     url: string;
     maxRetries: number;
     retryDelay: number;
@@ -35,6 +34,28 @@ export interface DatabaseConfig {
     acquireTimeout: number;
     timeout: number;
   };
+  postgresql?: {
+    host: string;
+    port: number;
+    database?: string;
+    user?: string;
+    password?: string;
+    connectionLimit: number;
+    ssl?: boolean;
+  };
+  sqlite?: {
+    filename: string;
+    memory?: boolean;
+    verbose?: boolean;
+  };
+  mongodb?: {
+    url?: string;
+    host?: string;
+    port?: number;
+    database?: string;
+    username?: string;
+    password?: string;
+  };
 }
 
 export interface ModuleDefaultsConfig {
@@ -141,6 +162,22 @@ export interface PerformanceConfig {
   clustering: {
     enabled: boolean;
     workers: number | 'auto';
+    memoryPerWorkerGB?: number;
+  };
+}
+
+export interface WebSocketConfig {
+  enabled: boolean;
+  adapter?: string | 'socket.io' | 'ws';
+  compression?: boolean;
+  customIdGenerator?: () => string;
+  options?: {
+    cors?: {
+      origin?: string | string[];
+      credentials?: boolean;
+    };
+    path?: string;
+    maxPayloadLength?: number;
   };
 }
 
@@ -154,4 +191,5 @@ export interface AppConfig {
   security: SecurityConfig;
   external: ExternalServicesConfig;
   performance: PerformanceConfig;
+  websocket: WebSocketConfig;
 }