@morojs/moro 1.7.30 → 1.8.1

package/dist/moro.js

@@ -242,21 +242,29 @@ export class Moro extends EventEmitter {
         // Default to enabled (true) unless explicitly disabled
         const jobsEnabled = this.config.jobs?.enabled !== false && options.jobs?.enabled !== false;
         if (jobsEnabled) {
-            const leaderElectionOptions = this.config.jobs?.leaderElection?.enabled !== false
+            const le = this.config.jobs?.leaderElection;
+            const leaderElectionOptions = le?.enabled !== false
                 ? {
-                    strategy: this.config.jobs?.leaderElection?.strategy ?? 'file',
-                    lockPath: this.config.jobs?.leaderElection?.lockPath,
-                    lockTimeout: this.config.jobs?.leaderElection?.lockTimeout,
-                    heartbeatInterval: this.config.jobs?.leaderElection?.heartbeatInterval,
+                    strategy: le?.strategy ?? 'file',
+                    ...(le?.lockPath !== undefined ? { lockPath: le.lockPath } : {}),
+                    ...(le?.lockTimeout !== undefined ? { lockTimeout: le.lockTimeout } : {}),
+                    ...(le?.heartbeatInterval !== undefined
+                        ? { heartbeatInterval: le.heartbeatInterval }
+                        : {}),
                 }
                 : undefined;
+            const jobs = this.config.jobs;
             const jobSchedulerOptions = {
-                maxConcurrentJobs: this.config.jobs?.maxConcurrentJobs,
-                enableLeaderElection: this.config.jobs?.leaderElection?.enabled !== false,
-                leaderElection: leaderElectionOptions,
-                executor: this.config.jobs?.executor,
-                stateManager: this.config.jobs?.stateManager,
-                gracefulShutdownTimeout: this.config.jobs?.gracefulShutdownTimeout,
+                enableLeaderElection: jobs?.leaderElection?.enabled !== false,
+                ...(jobs?.maxConcurrentJobs !== undefined
+                    ? { maxConcurrentJobs: jobs.maxConcurrentJobs }
+                    : {}),
+                ...(leaderElectionOptions !== undefined ? { leaderElection: leaderElectionOptions } : {}),
+                ...(jobs?.executor !== undefined ? { executor: jobs.executor } : {}),
+                ...(jobs?.stateManager !== undefined ? { stateManager: jobs.stateManager } : {}),
+                ...(jobs?.gracefulShutdownTimeout !== undefined
+                    ? { gracefulShutdownTimeout: jobs.gracefulShutdownTimeout }
+                    : {}),
             };
             this.jobScheduler = new JobScheduler(createFrameworkLogger('Jobs'), jobSchedulerOptions);
             this.jobHealthChecker = new JobHealthChecker(this.jobScheduler, createFrameworkLogger('JobHealth'));
@@ -277,7 +285,7 @@ export class Moro extends EventEmitter {
         // is registered before module middleware that might bypass it
         this.autoDiscoveryOptions = options.autoDiscover !== false ? options : null;
         // Emit initialization event through enterprise event bus
-        this.eventBus.emit('framework:initialized', {
+        void this.eventBus.emit('framework:initialized', {
             options,
             config: this.config,
             runtime: this.runtimeType,
@@ -459,7 +467,7 @@ export class Moro extends EventEmitter {
     enableDocs(config) {
         this.documentation.enableDocs(config, this.intelligentRouting);
         this.logger.info(`API Documentation enabled at ${config.basePath || '/docs'}`, 'Documentation');
-        this.eventBus.emit('docs:enabled', { config });
+        void this.eventBus.emit('docs:enabled', { config });
     }
     // Get OpenAPI specification
     getOpenAPISpec() {
@@ -499,7 +507,7 @@ export class Moro extends EventEmitter {
         // Standard middleware integration (req, res, next pattern)
         if (typeof middlewareOrFunction === 'function' && middlewareOrFunction.length >= 3) {
             this.coreFramework.addMiddleware(middlewareOrFunction);
-            this.eventBus.emit('middleware:registered', {
+            void this.eventBus.emit('middleware:registered', {
                 type: 'standard',
                 middleware: middlewareOrFunction,
             });
@@ -508,7 +516,7 @@ export class Moro extends EventEmitter {
         // Function-style middleware execution
         if (typeof middlewareOrFunction === 'function' && middlewareOrFunction.length <= 1) {
             await middlewareOrFunction(this);
-            this.eventBus.emit('middleware:executed', {
+            void this.eventBus.emit('middleware:executed', {
                 type: 'function',
                 middleware: middlewareOrFunction,
             });
@@ -525,7 +533,7 @@ export class Moro extends EventEmitter {
             return this;
         }
         // Fallback: emit event for unknown middleware types
-        this.eventBus.emit('middleware:advanced', {
+        void this.eventBus.emit('middleware:advanced', {
             middleware: middlewareOrFunction,
             config,
         });
@@ -595,14 +603,14 @@ export class Moro extends EventEmitter {
     }
     // Module loading with events
     async loadModule(moduleOrPath) {
-        this.eventBus.emit('module:loading', {
+        void this.eventBus.emit('module:loading', {
             moduleId: typeof moduleOrPath === 'string' ? moduleOrPath : moduleOrPath.name,
         });
         if (typeof moduleOrPath === 'string') {
             const module = await this.importModule(moduleOrPath);
             await this.coreFramework.loadModule(module);
             this.loadedModules.add(moduleOrPath);
-            this.eventBus.emit('module:loaded', {
+            void this.eventBus.emit('module:loaded', {
                 moduleId: module.name,
                 version: module.version || '1.0.0',
             });
@@ -610,7 +618,7 @@ export class Moro extends EventEmitter {
         else {
             await this.coreFramework.loadModule(moduleOrPath);
             this.loadedModules.add(moduleOrPath.name);
-            this.eventBus.emit('module:loaded', {
+            void this.eventBus.emit('module:loaded', {
                 moduleId: moduleOrPath.name,
                 version: moduleOrPath.version || '1.0.0',
             });
@@ -624,7 +632,7 @@ export class Moro extends EventEmitter {
     }
     // Database helper with events
     database(adapter) {
-        this.eventBus.emit('database:connected', {
+        void this.eventBus.emit('database:connected', {
             adapter: adapter.constructor.name,
             config: 'hidden',
         });
@@ -747,7 +755,11 @@ export class Moro extends EventEmitter {
             this.startWithClustering(port, host, callback);
             return;
         }
-        this.eventBus.emit('server:starting', { port, runtime: this.runtimeType });
+        // Single-process graceful shutdown: SIGINT/SIGTERM (Ctrl-C) drain in-flight
+        // work via close() by default; a second signal force-exits. Opt out with
+        // `server.gracefulShutdown: false`. (Cluster mode wires its own handlers.)
+        this.registerProcessShutdownHandlers();
+        void this.eventBus.emit('server:starting', { port, runtime: this.runtimeType });
         // Add documentation middleware first (if enabled)
         try {
             const docsMiddleware = this.documentation.getDocsMiddleware();
@@ -767,8 +779,11 @@ export class Moro extends EventEmitter {
         const startServer = () => {
             const actualCallback = () => {
                 const displayHost = host || 'localhost';
+                const serverKind = this.engine;
                 this.logger.info('Moro Server Started', 'Server');
                 this.logger.info(`Runtime: ${this.runtimeType}`, 'Server');
+                this.logger.info(`HTTP engine: ${serverKind.server}` +
+                    (serverKind.enginePackage ? ` (${serverKind.enginePackage})` : ''), 'Server');
                 this.logger.info(`HTTP API: http://${displayHost}:${port}`, 'Server');
                 if (this.config.websocket.enabled) {
                     this.logger.info(`WebSocket: ws://${displayHost}:${port}`, 'Server');
@@ -781,7 +796,11 @@ export class Moro extends EventEmitter {
                     // Log performance stats
                     this.unifiedRouter.logPerformanceStats();
                 }
-                this.eventBus.emit('server:started', { port, runtime: this.runtimeType });
+                void this.eventBus.emit('server:started', {
+                    port,
+                    runtime: this.runtimeType,
+                    engine: serverKind,
+                });
                 // Start job scheduler after server starts
                 this.startJobScheduler().catch(err => {
                     this.logger.error(`Failed to start job scheduler: ${String(err)}`);
@@ -813,20 +832,30 @@ export class Moro extends EventEmitter {
             this.ensureAutoDiscoveryComplete().then(() => this.ensureRoutesLoaded()),
             this.processQueuedWebSocketRegistrations(),
         ])
-            .then(() => {
-            startServer();
-        })
-            .catch(error => {
+            .then(() => startServer(), initError => {
+            // Initialization (auto-discovery / WebSocket setup) failed — this is
+            // NOT the listen() call. Handle it here so a subsequent listen()
+            // failure can't be misdiagnosed as an init failure and retried.
             this.logger.error('Initialization failed during server start', 'Framework', {
-                error: error instanceof Error ? error.message : String(error),
+                error: initError instanceof Error ? initError.message : String(initError),
             });
-            // For auto-discovery failures, start server anyway
-            // For WebSocket failures with queued registrations, error will propagate
-            if (error instanceof Error &&
-                error.message.includes('WebSocket features require a WebSocket adapter')) {
-                throw error;
+            // WebSocket-adapter misconfiguration is fatal; propagate it.
+            if (initError instanceof Error &&
+                initError.message.includes('WebSocket features require a WebSocket adapter')) {
+                throw initError;
             }
+            // A non-fatal init issue (e.g. auto-discovery) — start the server anyway.
             startServer();
+        })
+            .catch(error => {
+            // startServer()/listen() failed — e.g. EADDRINUSE thrown synchronously
+            // by the native engine. Retrying would fail identically, so surface it
+            // via the 'error' event (Node's server convention) instead of retrying
+            // into an unhandled rejection. With no 'error' listener, EventEmitter
+            // rethrows — the desired visible crash for a fatal bind failure.
+            const message = error instanceof Error ? error.message : String(error);
+            this.logger.error(`Failed to start server on port ${port}: ${message}`, 'Framework');
+            this.emit('error', error);
         });
     }
     // Public method to manually initialize auto-discovery
@@ -997,7 +1026,7 @@ export class Moro extends EventEmitter {
             if (matches) {
                 req.params = {};
                 route.paramNames.forEach((name, index) => {
-                    req.params[name] = matches[index + 1];
+                    req.params[name] = matches[index + 1] ?? '';
                 });
             }
             // Get handler function
@@ -1113,6 +1142,15 @@ export class Moro extends EventEmitter {
     get core() {
         return this.coreFramework;
     }
+    // Which HTTP server actually booted (engine/node/http2), the package
+    // backing a native engine, and the fallback reason when one was requested
+    // but the Node server booted instead. Stable surface for logs/tests/benchmarks.
+    get engine() {
+        return this.coreFramework.getServerKind();
+    }
+    getServerKind() {
+        return this.coreFramework.getServerKind();
+    }
     // Public API for accessing the DI container
     getContainer() {
         return this.coreFramework.getContainer();
@@ -1203,6 +1241,8 @@ export class Moro extends EventEmitter {
         // This provides the intuitive developer experience users expect
         for (const route of this.routes) {
             const handler = this.routeHandlers[route.handler];
+            if (!handler)
+                continue;
             // Get direct access to the HTTP server through the core framework
             const httpServer = this.coreFramework.httpServer;
             // Create a wrapper handler that handles validation, rate limiting, and return values
@@ -1278,7 +1318,7 @@ export class Moro extends EventEmitter {
                     }
                     // Rate limiting middleware
                     if (route.rateLimit) {
-                        const clientId = req.ip || req.connection.remoteAddress || 'unknown';
+                        const clientId = req.ip || req.connection?.remoteAddress || 'unknown';
                         const key = `${route.method}:${route.path}:${clientId}`;
                         if (!this.checkRateLimit(key, route.rateLimit)) {
                             res.status(429).json({
@@ -1506,20 +1546,20 @@ export class Moro extends EventEmitter {
         this.logger.info('Module changes detected, reloading...', 'ModuleDiscovery');
         // Unload existing modules (if supported)
         // For now, just log the change
-        this.eventBus.emit('modules:changed', {
+        void this.eventBus.emit('modules:changed', {
             modules: modules.map(m => ({ name: m.name, version: m.version })),
             timestamp: new Date(),
         });
     }
     // Legacy method for backward compatibility
     autoDiscoverModules(modulesPath) {
-        // Redirect to new system
-        this.initializeAutoDiscovery({
+        // Redirect to new system (legacy sync shim over the async discovery path).
+        void this.initializeAutoDiscovery({
             autoDiscover: {
                 enabled: true,
                 paths: [modulesPath],
             },
-        });
+        }).catch(err => this.logger.error(`Auto-discovery failed: ${String(err)}`, 'ModuleDiscovery'));
     }
     async importModule(modulePath) {
         // Convert file path to proper file URL for Windows compatibility
@@ -1694,7 +1734,7 @@ export class Moro extends EventEmitter {
             process.on('SIGTERM', workerShutdown);
             process.on('SIGINT', workerShutdown);
             // Continue with normal server startup for this worker
-            this.eventBus.emit('server:starting', {
+            void this.eventBus.emit('server:starting', {
                 port,
                 runtime: this.runtimeType,
                 worker: process.pid,
@@ -1716,37 +1756,53 @@ export class Moro extends EventEmitter {
             const workerCallback = () => {
                 const displayHost = host || 'localhost';
                 this.logger.info(`Worker ${process.pid} ready on ${displayHost}:${port}`, 'Worker');
-                this.eventBus.emit('server:started', {
+                void this.eventBus.emit('server:started', {
                     port,
                     runtime: this.runtimeType,
                     worker: process.pid,
+                    engine: this.engine,
                 });
             };
             // Ensure WebSocket setup is complete before starting worker
-            this.processQueuedWebSocketRegistrations()
-                .then(() => {
+            const startWorkerListening = () => {
                 if (host) {
                     this.coreFramework.listen(port, host, workerCallback);
                 }
                 else {
                     this.coreFramework.listen(port, workerCallback);
                 }
-            })
+            };
+            this.processQueuedWebSocketRegistrations()
+                .then(startWorkerListening)
                 .catch(error => {
+                const message = error instanceof Error ? error.message : String(error);
+                const code = error?.code;
+                // listen() itself failed (EADDRINUSE etc.): retrying is guaranteed to
+                // fail again and would surface as an unhandled rejection crash-loop.
+                // Log fatally and exit so the cluster primary sees a clean death.
+                // Prefer the code the native/Node servers set; fall back to message.
+                if (code === 'EADDRINUSE' ||
+                    code === 'EACCES' ||
+                    /EADDRINUSE|failed to bind/i.test(message)) {
+                    this.logger.error(`Worker ${process.pid} could not bind port ${port}: ${message}`, 'Worker');
+                    process.exit(1);
+                }
                 this.logger.error('WebSocket initialization failed in worker', 'Worker', {
-                    error: error instanceof Error ? error.message : String(error),
+                    error: message,
                 });
                 // For WebSocket failures with queued registrations, error will propagate
                 if (error instanceof Error &&
                     error.message.includes('WebSocket features require a WebSocket adapter')) {
                     throw error;
                 }
-                // Start anyway for other errors
-                if (host) {
-                    this.coreFramework.listen(port, host, workerCallback);
+                // WebSocket setup failed but the HTTP server can still serve: start
+                // anyway, and surface (not swallow) a listen failure from this path.
+                try {
+                    startWorkerListening();
                 }
-                else {
-                    this.coreFramework.listen(port, workerCallback);
+                catch (listenError) {
+                    this.logger.error(`Worker ${process.pid} failed to start: ${listenError instanceof Error ? listenError.message : String(listenError)}`, 'Worker');
+                    process.exit(1);
                 }
             });
         }
@@ -1765,8 +1821,93 @@ export class Moro extends EventEmitter {
      * Gracefully close the application and clean up resources
      * This should be called in tests and during shutdown
      */
+    shutdownHandlersRegistered = false;
+    isShuttingDown = false;
+    // Per-instance opt-in uncaught-error listeners (removed by close()).
+    processListeners = [];
+    // Graceful shutdown is driven by ONE process-level SIGINT/SIGTERM handler
+    // shared across every Moro instance (installed once), so creating many apps
+    // never accumulates process listeners. Instances register here on listen()
+    // and deregister on close().
+    static activeInstances = new Set();
+    static globalSignalsInstalled = false;
+    static globalShuttingDown = false;
+    static installGlobalShutdownSignals() {
+        if (Moro.globalSignalsInstalled)
+            return;
+        Moro.globalSignalsInstalled = true;
+        const handle = (signal, code) => {
+            // A second signal while already draining forces an immediate exit, so a
+            // stuck shutdown can never make the process unkillable via Ctrl-C.
+            if (Moro.globalShuttingDown) {
+                process.exit(code);
+                return;
+            }
+            Moro.globalShuttingDown = true;
+            const instances = Array.from(Moro.activeInstances);
+            instances[0]?.logger.info(`Received ${signal}, shutting down gracefully...`, 'Server');
+            Promise.allSettled(instances.map(inst => inst.close()))
+                .then(() => process.exit(code))
+                .catch(() => process.exit(1));
+        };
+        process.on('SIGINT', () => handle('SIGINT', 0));
+        process.on('SIGTERM', () => handle('SIGTERM', 0));
+    }
+    /**
+     * Enable graceful shutdown for this instance. SIGINT/SIGTERM (Ctrl-C) drain
+     * in-flight work via close() by default; a second signal force-exits. Opt out
+     * with `server.gracefulShutdown: false` (e.g. when the host app owns signals).
+     * Uncaught-error draining is separate and opt-in (`server.handleUncaught`).
+     */
+    registerProcessShutdownHandlers() {
+        if (this.shutdownHandlersRegistered)
+            return;
+        const serverCfg = this.config.server;
+        if (serverCfg?.gracefulShutdown === false)
+            return; // default ON; opt out here
+        this.shutdownHandlersRegistered = true;
+        Moro.activeInstances.add(this);
+        Moro.installGlobalShutdownSignals();
+        // Opt-in uncaught-error draining (per instance, removed on close()).
+        if (serverCfg?.handleUncaught === true) {
+            const add = (event, handler) => {
+                process.on(event, handler);
+                this.processListeners.push([event, handler]);
+            };
+            add('unhandledRejection', reason => {
+                this.logger.error(`Unhandled promise rejection: ${String(reason)}`, 'Server');
+                this.drainAndExit(1);
+            });
+            add('uncaughtException', err => {
+                this.logger.error(`Uncaught exception: ${err instanceof Error ? err.stack || err.message : String(err)}`, 'Server');
+                this.drainAndExit(1);
+            });
+        }
+    }
+    drainAndExit(code) {
+        if (this.isShuttingDown) {
+            process.exit(code);
+            return;
+        }
+        this.isShuttingDown = true;
+        this.close()
+            .then(() => process.exit(code))
+            .catch(() => process.exit(1));
+    }
+    /** Deregister this instance from process shutdown handling (called by close()). */
+    removeProcessShutdownHandlers() {
+        Moro.activeInstances.delete(this);
+        for (const [event, handler] of this.processListeners) {
+            process.removeListener(event, handler);
+        }
+        this.processListeners = [];
+        this.shutdownHandlersRegistered = false;
+    }
     async close() {
         this.logger.debug('Closing Moro application...');
+        // Detach our process signal listeners so repeated create/close cycles
+        // (tests, or a host that spins up many apps) don't leak process listeners.
+        this.removeProcessShutdownHandlers();
         // Run user-registered onClose hooks first, while subsystems are still alive.
         // Failures in one hook don't prevent subsequent hooks or Moro's own teardown.
         if (this.closeHooks.length > 0) {
@@ -1834,6 +1975,13 @@ export class Moro extends EventEmitter {
                 // Only wait for close if the server is actually listening
                 const isListening = server?.listening || server?.address?.() !== null;
                 if (isListening) {
+                    // Stop accepting new connections and let in-flight requests finish,
+                    // but don't hang on idle keep-alive / WebSocket connections: close
+                    // idle sockets right away, then force-close whatever remains at the
+                    // deadline so this promise reflects a real close instead of only the
+                    // timer firing. (closeIdle/closeAllConnections exist on the Node http
+                    // server; the uWS/engine backends ignore the optional calls.)
+                    server?.closeIdleConnections?.();
                     await Promise.race([
                         new Promise(resolve => {
                             httpServer.close(() => {
@@ -1841,7 +1989,15 @@ export class Moro extends EventEmitter {
                             });
                         }),
                         new Promise(resolve => {
-                            const timer = setTimeout(resolve, 2000); // 2 second timeout
+                            const timer = setTimeout(() => {
+                                try {
+                                    server?.closeAllConnections?.();
+                                }
+                                catch {
+                                    // best-effort force-close
+                                }
+                                resolve();
+                            }, 2000); // 2 second grace period
                             timer.unref(); // Don't keep process alive
                         }),
                     ]);
@@ -1951,19 +2107,21 @@ export class Moro extends EventEmitter {
         }
         const jobOptions = {
             name: options.name || name,
-            enabled: options.enabled,
-            priority: options.priority,
-            timezone: options.timezone,
-            maxConcurrent: options.maxConcurrent,
-            timeout: options.timeout,
-            maxRetries: options.maxRetries,
-            retryDelay: options.retryDelay,
-            retryBackoff: options.retryBackoff,
-            enableCircuitBreaker: options.enableCircuitBreaker,
-            metadata: options.metadata,
-            onStart: options.onStart,
-            onComplete: options.onComplete,
-            onError: options.onError,
+            ...(options.enabled !== undefined ? { enabled: options.enabled } : {}),
+            ...(options.priority !== undefined ? { priority: options.priority } : {}),
+            ...(options.timezone !== undefined ? { timezone: options.timezone } : {}),
+            ...(options.maxConcurrent !== undefined ? { maxConcurrent: options.maxConcurrent } : {}),
+            ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
+            ...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
+            ...(options.retryDelay !== undefined ? { retryDelay: options.retryDelay } : {}),
+            ...(options.retryBackoff !== undefined ? { retryBackoff: options.retryBackoff } : {}),
+            ...(options.enableCircuitBreaker !== undefined
+                ? { enableCircuitBreaker: options.enableCircuitBreaker }
+                : {}),
+            ...(options.metadata !== undefined ? { metadata: options.metadata } : {}),
+            ...(options.onStart !== undefined ? { onStart: options.onStart } : {}),
+            ...(options.onComplete !== undefined ? { onComplete: options.onComplete } : {}),
+            ...(options.onError !== undefined ? { onError: options.onError } : {}),
         };
         const jobId = this.jobScheduler.registerJob(name, jobSchedule, handler, jobOptions);
         this.logger.info(`Job registered: ${name} (${jobId})`);
@@ -2131,7 +2289,7 @@ export class Moro extends EventEmitter {
         // Store config and trigger initialization immediately
         this.graphqlConfig = options;
         this.graphqlInitPromise = this.initializeGraphQL(options);
-        this.eventBus.emit('graphql:configured', { options });
+        void this.eventBus.emit('graphql:configured', { options });
         return this;
     }
     /**
@@ -2786,7 +2944,7 @@ export class Moro extends EventEmitter {
         // Store config for lazy initialization
         this.mailConfig = config;
         this.logger.debug('Mail system configured (will initialize on first use)', 'Mail');
-        this.eventBus.emit('mail:configured', { config });
+        void this.eventBus.emit('mail:configured', { config });
         return this;
     }
     /**
@@ -2816,7 +2974,9 @@ export class Moro extends EventEmitter {
                     await this.ensureQueueInitialized();
                     await this.processQueue(queueName, async (job) => {
                         if (this.mailManager) {
-                            return await this.mailManager.send(job.data);
+                            // deliver() bypasses the queue check; send() would re-enqueue the
+                            // job forever and never actually transmit the email.
+                            return await this.mailManager.deliver(job.data);
                         }
                         throw new Error('Mail manager not initialized');
                     });
@@ -2864,19 +3024,19 @@ export class Moro extends EventEmitter {
     async sendMail(options) {
         // Lazy initialize on first use
         await this.ensureMailInitialized();
-        this.eventBus.emit('mail:sending', { options });
+        void this.eventBus.emit('mail:sending', { options });
         try {
             const result = await this.mailManager.send(options);
             if (result.success) {
-                this.eventBus.emit('mail:sent', { result, options });
+                void this.eventBus.emit('mail:sent', { result, options });
             }
             else {
-                this.eventBus.emit('mail:failed', { error: new Error(result.error), options });
+                void this.eventBus.emit('mail:failed', { error: new Error(result.error), options });
             }
             return result;
         }
         catch (error) {
-            this.eventBus.emit('mail:failed', { error, options });
+            void this.eventBus.emit('mail:failed', { error, options });
             throw error;
         }
     }