@onlineapps/mq-client-core 1.0.34 → 1.0.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/mq-client-core",
-  "version": "1.0.34",
+  "version": "1.0.36",
   "description": "Core MQ client library for RabbitMQ - shared by infrastructure services and connectors",
   "main": "src/index.js",
   "scripts": {

package/src/transports/rabbitmqClient.js

@@ -42,6 +42,21 @@ class RabbitMQClient extends EventEmitter {
     // Auto-reconnect flags
     this._reconnecting = false;
     this._reconnectAttempts = 0;
+    
+    // Channel close hooks - called when channel closes with detailed information
+    this._channelCloseHooks = []; // Array of { type: 'publisher'|'queue'|'consumer', callback: (details) => void }
+    
+    // Health monitoring
+    this._healthCheckInterval = null;
+    this._healthCheckIntervalMs = this._config.healthCheckInterval || 30000; // Default 30s
+    this._healthCheckEnabled = this._config.healthCheckEnabled !== false;
+    
+    // Health reporting callbacks
+    this._healthReportCallback = this._config.healthReportCallback || null; // (health) => Promise<void>
+    this._healthCriticalCallback = this._config.healthCriticalCallback || null; // (health) => Promise<void>
+    this._criticalHealthShutdown = this._config.criticalHealthShutdown !== false; // Default: true - shutdown on critical health
+    this._criticalHealthShutdownDelay = this._config.criticalHealthShutdownDelay || 60000; // Default: 60s delay before shutdown
+    this._criticalHealthStartTime = null; // Track when critical health started
   }
 
   /**
@@ -66,6 +81,50 @@ class RabbitMQClient extends EventEmitter {
   get queueChannel() {
     return this._queueChannel || this._channel; // Fallback to main channel if queueChannel not available
   }
+  
+  /**
+   * Register a hook to be called when a channel closes
+   * @param {string} type - Channel type: 'publisher', 'queue', 'consumer', or 'all'
+   * @param {Function} callback - Callback function receiving close details: { type, channel, error, reason, timestamp, stack }
+   */
+  onChannelClose(type, callback) {
+    this._channelCloseHooks.push({ type, callback });
+  }
+  
+  /**
+   * Call all registered channel close hooks
+   * @private
+   * @param {string} channelType - 'publisher', 'queue', or 'consumer'
+   * @param {Object} channel - The closed channel
+   * @param {Error} error - Error that caused closure (if any)
+   * @param {string} reason - Human-readable reason
+   */
+  _callChannelCloseHooks(channelType, channel, error, reason) {
+    const details = {
+      type: channelType,
+      channel: channel,
+      error: error,
+      reason: reason,
+      timestamp: new Date().toISOString(),
+      stack: error?.stack || new Error().stack,
+      connectionState: this._connection ? (this._connection.closed ? 'closed' : 'open') : 'null',
+      channelCreatedAt: channel?._createdAt || 'unknown',
+      lastOperation: channel?._lastOperation || 'unknown'
+    };
+    
+    for (const hook of this._channelCloseHooks) {
+      if (hook.type === 'all' || hook.type === channelType) {
+        try {
+          hook.callback(details);
+        } catch (hookErr) {
+          console.error(`[RabbitMQClient] [mq-client-core] Channel close hook error:`, hookErr.message);
+        }
+      }
+    }
+    
+    // Emit event for external listeners
+    this.emit('channel:close', details);
+  }
 
   /**
    * Connects to RabbitMQ server and creates a confirm channel.
@@ -101,17 +160,37 @@ class RabbitMQClient extends EventEmitter {
 
       // Use ConfirmChannel to enable publisher confirms for publish operations
       this._channel = await this._connection.createConfirmChannel();
+      
+      // Track channel metadata for debugging
+      this._channel._createdAt = new Date().toISOString();
+      this._channel._closeReason = null;
+      this._channel._lastOperation = 'Initial creation';
+      this._channel._type = 'publisher';
+      
       // Enable publisher confirms explicitly
       this._channel.on('error', async (err) => {
-        console.error('[RabbitMQClient] [mq-client-core] Publisher channel error:', err.message);
+        const reason = `Publisher channel error: ${err.message} (code: ${err.code || 'unknown'})`;
+        this._channel._closeReason = reason;
+        console.error(`[RabbitMQClient] [mq-client-core] ${reason}`);
+        
+        // Call close hooks with detailed information
+        this._callChannelCloseHooks('publisher', this._channel, err, reason);
+        
         // Auto-recreate channel if connection is still alive
         await this._ensurePublisherChannel();
         this.emit('error', err);
       });
       this._channel.on('close', async () => {
-        console.warn('[RabbitMQClient] [mq-client-core] Publisher channel closed - will auto-recreate on next publish');
+        const reason = this._channel._closeReason || 'Publisher channel closed unexpectedly';
+        console.warn(`[RabbitMQClient] [mq-client-core] ${reason} - will auto-recreate on next publish`);
+        
+        // Call close hooks with detailed information
+        this._callChannelCloseHooks('publisher', this._channel, null, reason);
+        
         // Mark channel as null - will be recreated on next publish
+        const closedChannel = this._channel;
         this._channel = null;
+        
         // Try to recreate immediately if connection is alive
         await this._ensurePublisherChannel();
       });
@@ -123,16 +202,35 @@ class RabbitMQClient extends EventEmitter {
       // Create a separate regular channel for queue operations (assertQueue, checkQueue)
       // This avoids RPC reply queue issues with ConfirmChannel.assertQueue()
       this._queueChannel = await this._connection.createChannel();
+      
+      // Track channel metadata for debugging
+      this._queueChannel._createdAt = new Date().toISOString();
+      this._queueChannel._closeReason = null;
+      this._queueChannel._lastOperation = 'Initial creation';
+      this._queueChannel._type = 'queue';
+      
       this._queueChannel.on('error', async (err) => {
-        // Log but don't emit - queue channel errors are less critical
-        console.warn('[RabbitMQClient] Queue channel error:', err.message);
+        const reason = `Queue channel error: ${err.message} (code: ${err.code || 'unknown'})`;
+        this._queueChannel._closeReason = reason;
+        console.warn(`[RabbitMQClient] [mq-client-core] ${reason}`);
+        
+        // Call close hooks with detailed information
+        this._callChannelCloseHooks('queue', this._queueChannel, err, reason);
+        
         // Auto-recreate channel if connection is still alive
         await this._ensureQueueChannel();
       });
       this._queueChannel.on('close', async () => {
-        console.warn('[RabbitMQClient] Queue channel closed - will auto-recreate on next operation');
+        const reason = this._queueChannel._closeReason || 'Queue channel closed unexpectedly';
+        console.warn(`[RabbitMQClient] [mq-client-core] ${reason} - will auto-recreate on next operation`);
+        
+        // Call close hooks with detailed information
+        this._callChannelCloseHooks('queue', this._queueChannel, null, reason);
+        
         // Mark channel as null - will be recreated on next queue operation
+        const closedChannel = this._queueChannel;
         this._queueChannel = null;
+        
         // Try to recreate immediately if connection is alive
         await this._ensureQueueChannel();
       });
@@ -140,19 +238,44 @@ class RabbitMQClient extends EventEmitter {
       // Create a dedicated channel for consume operations
       // This prevents channel conflicts between publish (ConfirmChannel) and consume operations
       this._consumerChannel = await this._connection.createChannel();
+      
+      // Track channel metadata for debugging
+      this._consumerChannel._createdAt = new Date().toISOString();
+      this._consumerChannel._closeReason = null;
+      this._consumerChannel._lastOperation = 'Initial creation';
+      this._consumerChannel._type = 'consumer';
+      
       this._consumerChannel.on('error', async (err) => {
-        console.warn('[RabbitMQClient] Consumer channel error:', err.message);
+        const reason = `Consumer channel error: ${err.message} (code: ${err.code || 'unknown'})`;
+        this._consumerChannel._closeReason = reason;
+        console.warn(`[RabbitMQClient] [mq-client-core] ${reason}`);
+        
+        // Call close hooks with detailed information
+        this._callChannelCloseHooks('consumer', this._consumerChannel, err, reason);
+        
         // Auto-recreate channel and re-register consumers
         await this._ensureConsumerChannel();
         this.emit('error', err);
       });
       this._consumerChannel.on('close', async () => {
-        console.warn('[RabbitMQClient] Consumer channel closed - will auto-recreate and re-register consumers');
+        const reason = this._consumerChannel._closeReason || 'Consumer channel closed unexpectedly';
+        console.warn(`[RabbitMQClient] [mq-client-core] ${reason} - will auto-recreate and re-register consumers`);
+        
+        // Call close hooks with detailed information
+        this._callChannelCloseHooks('consumer', this._consumerChannel, null, reason);
+        
         // Mark channel as null - will be recreated and consumers re-registered
+        const closedChannel = this._consumerChannel;
         this._consumerChannel = null;
+        
         // Try to recreate and re-register consumers immediately if connection is alive
         await this._ensureConsumerChannel();
       });
+      
+      // Start health monitoring if enabled
+      if (this._healthCheckEnabled) {
+        this._startHealthMonitoring();
+      }
     } catch (err) {
       // Cleanup partially created resources
       if (this._connection) {
@@ -194,13 +317,32 @@ class RabbitMQClient extends EventEmitter {
       
       // Create new ConfirmChannel
       this._channel = await this._connection.createConfirmChannel();
+      
+      // Track channel metadata for debugging
+      this._channel._createdAt = new Date().toISOString();
+      this._channel._closeReason = null;
+      this._channel._lastOperation = 'Recreated via _ensurePublisherChannel()';
+      this._channel._type = 'publisher';
+      
       this._channel.on('error', async (err) => {
-        console.error('[RabbitMQClient] [mq-client-core] Publisher channel error:', err.message);
+        const reason = `Publisher channel error: ${err.message} (code: ${err.code || 'unknown'})`;
+        this._channel._closeReason = reason;
+        console.error(`[RabbitMQClient] [mq-client-core] ${reason}`);
+        
+        // Call close hooks
+        this._callChannelCloseHooks('publisher', this._channel, err, reason);
+        
         await this._ensurePublisherChannel();
         this.emit('error', err);
       });
       this._channel.on('close', async () => {
-        console.warn('[RabbitMQClient] [mq-client-core] Publisher channel closed - will auto-recreate on next publish');
+        const reason = this._channel._closeReason || 'Publisher channel closed unexpectedly';
+        console.warn(`[RabbitMQClient] [mq-client-core] ${reason} - will auto-recreate on next publish`);
+        
+        // Call close hooks
+        this._callChannelCloseHooks('publisher', this._channel, null, reason);
+        
+        const closedChannel = this._channel;
         this._channel = null;
         await this._ensurePublisherChannel();
       });
@@ -242,12 +384,31 @@ class RabbitMQClient extends EventEmitter {
       
       // Create new regular channel
       this._queueChannel = await this._connection.createChannel();
+      
+      // Track channel metadata for debugging
+      this._queueChannel._createdAt = new Date().toISOString();
+      this._queueChannel._closeReason = null;
+      this._queueChannel._lastOperation = 'Recreated via _ensureQueueChannel()';
+      this._queueChannel._type = 'queue';
+      
       this._queueChannel.on('error', async (err) => {
-        console.warn('[RabbitMQClient] Queue channel error:', err.message);
+        const reason = `Queue channel error: ${err.message} (code: ${err.code || 'unknown'})`;
+        this._queueChannel._closeReason = reason;
+        console.warn(`[RabbitMQClient] [mq-client-core] ${reason}`);
+        
+        // Call close hooks
+        this._callChannelCloseHooks('queue', this._queueChannel, err, reason);
+        
         await this._ensureQueueChannel();
       });
       this._queueChannel.on('close', async () => {
-        console.warn('[RabbitMQClient] Queue channel closed - will auto-recreate on next operation');
+        const reason = this._queueChannel._closeReason || 'Queue channel closed unexpectedly';
+        console.warn(`[RabbitMQClient] [mq-client-core] ${reason} - will auto-recreate on next operation`);
+        
+        // Call close hooks
+        this._callChannelCloseHooks('queue', this._queueChannel, null, reason);
+        
+        const closedChannel = this._queueChannel;
         this._queueChannel = null;
         await this._ensureQueueChannel();
       });
@@ -286,13 +447,32 @@ class RabbitMQClient extends EventEmitter {
       
       // Create new regular channel
       this._consumerChannel = await this._connection.createChannel();
+      
+      // Track channel metadata for debugging
+      this._consumerChannel._createdAt = new Date().toISOString();
+      this._consumerChannel._closeReason = null;
+      this._consumerChannel._lastOperation = 'Recreated via _ensureConsumerChannel()';
+      this._consumerChannel._type = 'consumer';
+      
       this._consumerChannel.on('error', async (err) => {
-        console.warn('[RabbitMQClient] Consumer channel error:', err.message);
+        const reason = `Consumer channel error: ${err.message} (code: ${err.code || 'unknown'})`;
+        this._consumerChannel._closeReason = reason;
+        console.warn(`[RabbitMQClient] [mq-client-core] ${reason}`);
+        
+        // Call close hooks
+        this._callChannelCloseHooks('consumer', this._consumerChannel, err, reason);
+        
         await this._ensureConsumerChannel();
         this.emit('error', err);
       });
       this._consumerChannel.on('close', async () => {
-        console.warn('[RabbitMQClient] Consumer channel closed - will auto-recreate and re-register consumers');
+        const reason = this._consumerChannel._closeReason || 'Consumer channel closed unexpectedly';
+        console.warn(`[RabbitMQClient] [mq-client-core] ${reason} - will auto-recreate and re-register consumers`);
+        
+        // Call close hooks
+        this._callChannelCloseHooks('consumer', this._consumerChannel, null, reason);
+        
+        const closedChannel = this._consumerChannel;
         this._consumerChannel = null;
         await this._ensureConsumerChannel();
       });
@@ -306,6 +486,7 @@ class RabbitMQClient extends EventEmitter {
             if (consumerInfo.options.queueOptions) {
               try {
                 await this._ensureQueueChannel();
+                this._trackChannelOperation(this._queueChannel, `assertQueue ${queue} (re-register)`);
                 await this._queueChannel.assertQueue(queue, consumerInfo.options.queueOptions);
               } catch (assertErr) {
                 if (assertErr.code === 404) {
@@ -349,7 +530,213 @@ class RabbitMQClient extends EventEmitter {
    * Disconnects: closes channel and connection.
    * @returns {Promise<void>}
    */
+  /**
+   * Start health monitoring - periodically checks channels, queues, and consumers
+   * @private
+   */
+  _startHealthMonitoring() {
+    if (this._healthCheckInterval) {
+      return; // Already started
+    }
+    
+    this._healthCheckInterval = setInterval(async () => {
+      try {
+        await this._performHealthCheck();
+      } catch (err) {
+        console.error(`[RabbitMQClient] [mq-client-core] Health check error:`, err.message);
+        // Emit event for external monitoring
+        this.emit('health:check:error', err);
+      }
+    }, this._healthCheckIntervalMs);
+    
+    console.log(`[RabbitMQClient] [mq-client-core] Health monitoring started (interval: ${this._healthCheckIntervalMs}ms)`);
+  }
+  
+  /**
+   * Stop health monitoring
+   * @private
+   */
+  _stopHealthMonitoring() {
+    if (this._healthCheckInterval) {
+      clearInterval(this._healthCheckInterval);
+      this._healthCheckInterval = null;
+      console.log('[RabbitMQClient] [mq-client-core] Health monitoring stopped');
+    }
+  }
+  
+  /**
+   * Perform health check - verify channels, queues, and consumers
+   * Can be called manually (e.g., before workflow steps in debug mode)
+   * @public (exposed for manual calls)
+   * @returns {Promise<Object>} Health check results
+   */
+  async performHealthCheck() {
+    return this._performHealthCheck();
+  }
+  
+  /**
+   * Perform health check - verify channels, queues, and consumers
+   * @private
+   * @returns {Promise<Object>} Health check results
+   */
+  async _performHealthCheck() {
+    const health = {
+      timestamp: new Date().toISOString(),
+      connection: {
+        exists: !!this._connection,
+        closed: this._connection ? this._connection.closed : true
+      },
+      channels: {
+        publisher: {
+          exists: !!this._channel,
+          closed: this._channel ? this._channel.closed : true
+        },
+        queue: {
+          exists: !!this._queueChannel,
+          closed: this._queueChannel ? this._queueChannel.closed : true
+        },
+        consumer: {
+          exists: !!this._consumerChannel,
+          closed: this._consumerChannel ? this._consumerChannel.closed : true
+        }
+      },
+      consumers: {
+        tracked: this._activeConsumers.size,
+        active: 0,
+        inactive: []
+      },
+      queues: {
+        checked: 0,
+        missing: [],
+        noConsumer: []
+      },
+      healthy: true,
+      issues: []
+    };
+    
+    // Check connection
+    if (!health.connection.exists || health.connection.closed) {
+      health.healthy = false;
+      health.issues.push('Connection is closed or missing');
+    }
+    
+    // Check channels
+    if (health.channels.publisher.closed || !health.channels.publisher.exists) {
+      health.healthy = false;
+      health.issues.push('Publisher channel is closed or missing');
+    }
+    if (health.channels.queue.closed || !health.channels.queue.exists) {
+      health.healthy = false;
+      health.issues.push('Queue channel is closed or missing');
+    }
+    if (health.channels.consumer.closed || !health.channels.consumer.exists) {
+      health.healthy = false;
+      health.issues.push('Consumer channel is closed or missing');
+    }
+    
+    // Check tracked consumers - verify queues exist and have active consumers
+    if (this._connection && !this._connection.closed && this._queueChannel && !this._queueChannel.closed) {
+      for (const [queue, consumerInfo] of this._activeConsumers.entries()) {
+        health.queues.checked++;
+        try {
+          // Check if queue exists
+          this._trackChannelOperation(this._queueChannel, `checkQueue ${queue}`);
+          const queueInfo = await this._queueChannel.checkQueue(queue);
+          if (queueInfo) {
+            // Queue exists - check if consumer is active
+            // Note: RabbitMQ doesn't provide direct API to check if consumer is active
+            // We can only verify that consumerTag is set
+            if (consumerInfo.consumerTag) {
+              health.consumers.active++;
+            } else {
+              health.consumers.inactive.push(queue);
+              health.queues.noConsumer.push(queue);
+              health.healthy = false;
+              health.issues.push(`Queue ${queue} has no active consumer (consumerTag missing)`);
+            }
+          } else {
+            health.queues.missing.push(queue);
+            health.healthy = false;
+            health.issues.push(`Queue ${queue} does not exist`);
+          }
+        } catch (err) {
+          if (err.code === 404) {
+            health.queues.missing.push(queue);
+            health.healthy = false;
+            health.issues.push(`Queue ${queue} does not exist (404)`);
+          } else {
+            health.healthy = false;
+            health.issues.push(`Error checking queue ${queue}: ${err.message}`);
+          }
+        }
+      }
+    }
+    
+    // Emit health check result
+    this.emit('health:check', health);
+    
+    // If unhealthy, log and potentially trigger shutdown
+    if (!health.healthy) {
+      console.error(`[RabbitMQClient] [mq-client-core] Health check FAILED:`, health.issues);
+      console.error(`[RabbitMQClient] [mq-client-core] Health details:`, JSON.stringify(health, null, 2));
+      
+      // Track critical health start time
+      if (!this._criticalHealthStartTime) {
+        this._criticalHealthStartTime = Date.now();
+        console.error(`[RabbitMQClient] [mq-client-core] Critical health detected at ${new Date(this._criticalHealthStartTime).toISOString()}`);
+      }
+      
+      // Report to monitoring if callback provided
+      if (this._healthReportCallback) {
+        try {
+          await this._healthReportCallback(health);
+        } catch (reportErr) {
+          console.error(`[RabbitMQClient] [mq-client-core] Health report callback failed:`, reportErr.message);
+        }
+      }
+      
+      // Call critical health callback if provided
+      if (this._healthCriticalCallback) {
+        try {
+          await this._healthCriticalCallback(health);
+        } catch (criticalErr) {
+          console.error(`[RabbitMQClient] [mq-client-core] Critical health callback failed:`, criticalErr.message);
+        }
+      }
+      
+      // Emit critical health event
+      this.emit('health:critical', health);
+      
+      // Check if we should shutdown after delay
+      if (this._criticalHealthShutdown) {
+        const timeSinceCritical = Date.now() - this._criticalHealthStartTime;
+        if (timeSinceCritical >= this._criticalHealthShutdownDelay) {
+          console.error(`[RabbitMQClient] [mq-client-core] Critical health persisted for ${timeSinceCritical}ms (threshold: ${this._criticalHealthShutdownDelay}ms) - triggering shutdown`);
+          this.emit('health:shutdown', health);
+          // Note: Actual shutdown should be handled by the application using this event
+        } else {
+          const remaining = this._criticalHealthShutdownDelay - timeSinceCritical;
+          console.warn(`[RabbitMQClient] [mq-client-core] Critical health will trigger shutdown in ${remaining}ms if not resolved`);
+        }
+      }
+    } else {
+      // Health is OK - reset critical health tracking
+      if (this._criticalHealthStartTime) {
+        const duration = Date.now() - this._criticalHealthStartTime;
+        console.log(`[RabbitMQClient] [mq-client-core] Health recovered after ${duration}ms of critical state`);
+        this._criticalHealthStartTime = null;
+      }
+      
+      console.log(`[RabbitMQClient] [mq-client-core] Health check OK: ${health.consumers.active}/${health.consumers.tracked} consumers active, ${health.queues.checked} queues checked`);
+    }
+    
+    return health;
+  }
+
   async disconnect() {
+    // Stop health monitoring
+    this._stopHealthMonitoring();
+    
     // Clear active consumers tracking
     this._activeConsumers.clear();
     
@@ -400,6 +787,9 @@ class RabbitMQClient extends EventEmitter {
     // Ensure publisher channel exists and is open (auto-recreates if closed)
     await this._ensurePublisherChannel();
     
+    // Track operation for debugging
+    this._trackChannelOperation(this._channel, `publish to ${queue}`);
+    
     // Log publish attempt for debugging
     console.log(`[RabbitMQClient] [mq-client-core] [PUBLISH] Attempting to publish to queue "${queue}"`);
 
@@ -418,6 +808,7 @@ class RabbitMQClient extends EventEmitter {
         try {
           // Ensure queue channel exists and is open (auto-recreates if closed)
           await this._ensureQueueChannel();
+          this._trackChannelOperation(this._queueChannel, `checkQueue ${queue}`);
           await this._queueChannel.checkQueue(queue);
           // Queue exists - proceed to publish
         } catch (checkErr) {
@@ -445,6 +836,7 @@ class RabbitMQClient extends EventEmitter {
             // For non-infrastructure queues, allow auto-creation with default options
             const queueOptions = options.queueOptions || { durable: this._config.durable };
             console.warn(`[RabbitMQClient] [mq-client-core] [PUBLISH] Auto-creating non-infrastructure queue ${queue} with default options (no TTL). This should be avoided for production.`);
+            this._trackChannelOperation(this._queueChannel, `assertQueue ${queue}`);
             await this._queueChannel.assertQueue(queue, queueOptions);
           } else {
             // Other error - rethrow
@@ -519,6 +911,9 @@ class RabbitMQClient extends EventEmitter {
   async consume(queue, onMessage, options = {}) {
     // Ensure consumer channel exists and is open (auto-recreates if closed and re-registers consumers)
     await this._ensureConsumerChannel();
+    
+    // Track operation for debugging
+    this._trackChannelOperation(this._consumerChannel, `consume from ${queue}`);
 
     const durable = options.durable !== undefined ? options.durable : this._config.durable;
     const prefetch = options.prefetch !== undefined ? options.prefetch : this._config.prefetch;
@@ -597,6 +992,7 @@ class RabbitMQClient extends EventEmitter {
       
       try {
         console.log(`[RabbitMQClient] [mq-client-core] [CONSUMER] About to call assertQueue(${queue}, ${JSON.stringify(queueOptions)})`);
+        this._trackChannelOperation(this._queueChannel, `assertQueue ${queue}`);
         await this._queueChannel.assertQueue(queue, queueOptions);
         console.log(`[RabbitMQClient] [mq-client-core] [CONSUMER] ✓ Queue ${queue} asserted successfully`);
       } catch (assertErr) {