@onlineapps/conn-infra-mq 1.1.0

package/src/layers/RPCHandler.js

@@ -0,0 +1,324 @@
+'use strict';
+
+/**
+ * RPCHandler - Manages RPC (Remote Procedure Call) patterns
+ * Handles request-response communication with correlation IDs and timeouts
+ */
+class RPCHandler {
+  constructor(mqClient, queueManager, config = {}) {
+    this.client = mqClient;
+    this.queueManager = queueManager;
+    this.config = {
+      defaultTimeout: config.defaultTimeout || 5000,
+      replyQueuePrefix: config.replyQueuePrefix || 'rpc.reply',
+      ...config
+    };
+    this.pendingRequests = new Map();
+    this.replyQueue = null;
+    this.replyConsumer = null;
+  }
+
+  /**
+   * Initialize RPC handler (create reply queue)
+   */
+  async initialize() {
+    if (this.replyQueue) {
+      return this.replyQueue;
+    }
+
+    // Create exclusive reply queue
+    this.replyQueue = await this.queueManager.createTemporaryQueue(
+      this.config.replyQueuePrefix,
+      {
+        exclusive: true,
+        autoDelete: true,
+        expires: 3600000 // 1 hour
+      }
+    );
+
+    // Start consuming replies
+    this.replyConsumer = await this.client.consume(
+      (message, rawMsg) => this.handleReply(message, rawMsg),
+      {
+        queue: this.replyQueue,
+        noAck: true
+      }
+    );
+
+    return this.replyQueue;
+  }
+
+  /**
+   * Send RPC request and wait for response
+   * @param {string} targetQueue - Target service queue
+   * @param {Object} request - Request message
+   * @param {Object} options - RPC options
+   */
+  async call(targetQueue, request, options = {}) {
+    // Ensure reply queue exists
+    await this.initialize();
+
+    const correlationId = this.generateCorrelationId();
+    const timeout = options.timeout || this.config.defaultTimeout;
+
+    // Create promise for response
+    const responsePromise = new Promise((resolve, reject) => {
+      // Setup timeout
+      const timeoutHandle = setTimeout(() => {
+        this.pendingRequests.delete(correlationId);
+        reject(new Error(`RPC request timeout after ${timeout}ms`));
+      }, timeout);
+
+      // Store pending request
+      this.pendingRequests.set(correlationId, {
+        resolve,
+        reject,
+        timeoutHandle,
+        startTime: Date.now(),
+        targetQueue
+      });
+    });
+
+    // Send request with correlation ID and reply queue
+    await this.client.publish(request, {
+      queue: targetQueue,
+      correlationId,
+      replyTo: this.replyQueue,
+      expiration: timeout.toString(),
+      ...options
+    });
+
+    return responsePromise;
+  }
+
+  /**
+   * Setup service as RPC server
+   * @param {string} queue - Queue to listen on
+   * @param {Function} handler - Request handler function
+   * @param {Object} options - Server options
+   */
+  async serve(queue, handler, options = {}) {
+    return this.client.consume(async (request, rawMsg) => {
+      const { correlationId, replyTo } = rawMsg.properties;
+
+      if (!replyTo) {
+        // Not an RPC request, handle normally
+        if (options.allowNonRPC) {
+          await handler(request, rawMsg);
+        }
+        await this.client.ack(rawMsg);
+        return;
+      }
+
+      try {
+        // Process request
+        const response = await handler(request, rawMsg);
+
+        // Send response
+        if (replyTo && correlationId) {
+          await this.client.publish(response, {
+            queue: replyTo,
+            correlationId
+          });
+        }
+
+        await this.client.ack(rawMsg);
+      } catch (error) {
+        // Send error response
+        if (replyTo && correlationId) {
+          await this.client.publish(
+            {
+              error: {
+                message: error.message,
+                code: error.code || 'RPC_ERROR',
+                timestamp: Date.now()
+              }
+            },
+            {
+              queue: replyTo,
+              correlationId
+            }
+          );
+        }
+
+        // Reject or acknowledge based on configuration
+        if (options.rejectOnError) {
+          await this.client.nack(rawMsg, false);
+        } else {
+          await this.client.ack(rawMsg);
+        }
+      }
+    }, {
+      queue,
+      ...options
+    });
+  }
+
+  /**
+   * Handle RPC reply
+   * @private
+   */
+  handleReply(message, rawMsg) {
+    const { correlationId } = rawMsg.properties;
+
+    if (!correlationId || !this.pendingRequests.has(correlationId)) {
+      // Unknown or expired request
+      return;
+    }
+
+    const pending = this.pendingRequests.get(correlationId);
+    this.pendingRequests.delete(correlationId);
+
+    // Clear timeout
+    clearTimeout(pending.timeoutHandle);
+
+    // Calculate round-trip time
+    const rtt = Date.now() - pending.startTime;
+
+    // Check for error response
+    if (message && message.error) {
+      const error = new Error(message.error.message || 'RPC error');
+      error.code = message.error.code;
+      error.rtt = rtt;
+      pending.reject(error);
+    } else {
+      // Add metadata to response
+      if (typeof message === 'object' && message !== null) {
+        message._rpcMetadata = {
+          rtt,
+          correlationId,
+          targetQueue: pending.targetQueue
+        };
+      }
+      pending.resolve(message);
+    }
+  }
+
+  /**
+   * Call multiple RPC requests in parallel
+   * @param {Array} requests - Array of { queue, request, options } objects
+   */
+  async callMany(requests) {
+    const promises = requests.map(req =>
+      this.call(req.queue, req.request, req.options)
+        .then(response => ({ success: true, response, queue: req.queue }))
+        .catch(error => ({ success: false, error, queue: req.queue }))
+    );
+
+    return Promise.all(promises);
+  }
+
+  /**
+   * Call with retry logic
+   * @param {string} targetQueue - Target service queue
+   * @param {Object} request - Request message
+   * @param {Object} options - RPC options with retry configuration
+   */
+  async callWithRetry(targetQueue, request, options = {}) {
+    const maxRetries = options.maxRetries || 3;
+    const retryDelay = options.retryDelay || 1000;
+    let lastError;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await this.call(targetQueue, request, options);
+      } catch (error) {
+        lastError = error;
+
+        if (attempt < maxRetries) {
+          // Wait before retry with exponential backoff
+          const delay = retryDelay * Math.pow(2, attempt);
+          await new Promise(resolve => setTimeout(resolve, delay));
+        }
+      }
+    }
+
+    throw lastError;
+  }
+
+  /**
+   * Broadcast request to multiple queues and collect responses
+   * @param {Array} queues - Target queues
+   * @param {Object} request - Request message
+   * @param {Object} options - Broadcast options
+   */
+  async broadcast(queues, request, options = {}) {
+    const timeout = options.timeout || this.config.defaultTimeout;
+    const waitForAll = options.waitForAll !== false;
+
+    const results = [];
+    const promises = [];
+
+    for (const queue of queues) {
+      const promise = this.call(queue, request, { timeout })
+        .then(response => {
+          results.push({ queue, response, success: true });
+          return { queue, response, success: true };
+        })
+        .catch(error => {
+          const result = { queue, error: error.message, success: false };
+          if (!waitForAll) {
+            results.push(result);
+          }
+          return result;
+        });
+
+      promises.push(promise);
+    }
+
+    if (waitForAll) {
+      const allResults = await Promise.all(promises);
+      return allResults;
+    } else {
+      // Race for first successful response
+      await Promise.race(promises.filter(p => p.then(r => r.success)));
+      return results;
+    }
+  }
+
+  /**
+   * Generate unique correlation ID
+   * @private
+   */
+  generateCorrelationId() {
+    return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  /**
+   * Get pending requests count
+   */
+  getPendingCount() {
+    return this.pendingRequests.size;
+  }
+
+  /**
+   * Clear all pending requests
+   */
+  clearPending() {
+    for (const pending of this.pendingRequests.values()) {
+      clearTimeout(pending.timeoutHandle);
+      pending.reject(new Error('RPC handler shutdown'));
+    }
+    this.pendingRequests.clear();
+  }
+
+  /**
+   * Cleanup RPC handler
+   */
+  async cleanup() {
+    this.clearPending();
+
+    if (this.replyQueue) {
+      try {
+        await this.queueManager.deleteQueue(this.replyQueue);
+      } catch (error) {
+        // Queue might already be deleted
+      }
+      this.replyQueue = null;
+    }
+
+    this.replyConsumer = null;
+  }
+}
+
+module.exports = RPCHandler;

package/src/layers/RetryHandler.js

@@ -0,0 +1,370 @@
+'use strict';
+
+/**
+ * RetryHandler - Manages message retry logic and dead letter queue handling
+ * Implements exponential backoff, max retries, and error recovery patterns
+ */
+class RetryHandler {
+  constructor(mqClient, config = {}) {
+    this.client = mqClient;
+    this.config = {
+      maxRetries: config.maxRetries || 3,
+      initialDelay: config.initialDelay || 1000,
+      maxDelay: config.maxDelay || 30000,
+      backoffMultiplier: config.backoffMultiplier || 2,
+      dlqSuffix: config.dlqSuffix || '.dlq',
+      ...config
+    };
+    this.retryStats = {
+      totalRetries: 0,
+      successfulRetries: 0,
+      failedRetries: 0,
+      dlqMessages: 0
+    };
+  }
+
+  /**
+   * Process message with retry logic
+   * @param {Function} handler - Message processing function
+   * @param {Object} message - Message to process
+   * @param {Object} rawMsg - Raw message from AMQP
+   * @param {Object} options - Retry options
+   */
+  async processWithRetry(handler, message, rawMsg, options = {}) {
+    const maxRetries = options.maxRetries || this.config.maxRetries;
+    const retryCount = this.getRetryCount(message, rawMsg);
+
+    try {
+      // Attempt to process message
+      await handler(message, rawMsg);
+
+      // Success - acknowledge
+      await this.client.ack(rawMsg);
+
+      // Update stats if this was a retry
+      if (retryCount > 0) {
+        this.retryStats.successfulRetries++;
+      }
+
+      return { success: true, retryCount };
+    } catch (error) {
+      // Processing failed
+      return this.handleFailure(error, message, rawMsg, retryCount, maxRetries, options);
+    }
+  }
+
+  /**
+   * Handle processing failure
+   * @private
+   */
+  async handleFailure(error, message, rawMsg, retryCount, maxRetries, options = {}) {
+    const queueName = rawMsg.fields.routingKey || rawMsg.fields.queue || options.queue;
+
+    // Add error context to message
+    const enrichedMessage = {
+      ...message,
+      _error: {
+        message: error.message,
+        code: error.code,
+        stack: error.stack,
+        timestamp: Date.now(),
+        queue: queueName
+      },
+      _retryCount: retryCount + 1
+    };
+
+    if (retryCount < maxRetries) {
+      // Retry the message
+      await this.retryMessage(enrichedMessage, queueName, retryCount + 1, options);
+
+      // Acknowledge original to remove from queue
+      await this.client.ack(rawMsg);
+
+      this.retryStats.totalRetries++;
+
+      return { success: false, retried: true, retryCount: retryCount + 1 };
+    } else {
+      // Max retries exceeded, send to DLQ
+      await this.sendToDLQ(enrichedMessage, queueName, error, options);
+
+      // Acknowledge to remove from main queue
+      await this.client.ack(rawMsg);
+
+      this.retryStats.failedRetries++;
+      this.retryStats.dlqMessages++;
+
+      return { success: false, retried: false, dlq: true, retryCount };
+    }
+  }
+
+  /**
+   * Retry a message with delay
+   * @param {Object} message - Message to retry
+   * @param {string} queue - Original queue name
+   * @param {number} retryCount - Current retry attempt
+   * @param {Object} options - Retry options
+   */
+  async retryMessage(message, queue, retryCount, options = {}) {
+    const delay = this.calculateDelay(retryCount);
+
+    // Add retry metadata
+    const retryMessage = {
+      ...message,
+      _retry: {
+        count: retryCount,
+        delay,
+        timestamp: Date.now(),
+        originalQueue: queue
+      }
+    };
+
+    // Use delayed message plugin if available, otherwise setTimeout
+    if (options.useDelayedPlugin) {
+      // RabbitMQ delayed message plugin
+      await this.client.publish(retryMessage, {
+        queue,
+        headers: {
+          'x-delay': delay,
+          'x-retry-count': retryCount
+        }
+      });
+    } else {
+      // Manual delay
+      setTimeout(async () => {
+        try {
+          await this.client.publish(retryMessage, {
+            queue,
+            headers: {
+              'x-retry-count': retryCount,
+              'x-retry-timestamp': Date.now()
+            }
+          });
+        } catch (error) {
+          console.error(`Failed to retry message: ${error.message}`);
+        }
+      }, delay);
+    }
+  }
+
+  /**
+   * Send message to Dead Letter Queue
+   * @param {Object} message - Failed message
+   * @param {string} originalQueue - Original queue name
+   * @param {Error} error - The error that caused the failure
+   * @param {Object} options - DLQ options
+   */
+  async sendToDLQ(message, originalQueue, error, options = {}) {
+    const dlqName = options.dlqName || `${originalQueue}${this.config.dlqSuffix}`;
+
+    const dlqMessage = {
+      ...message,
+      _dlq: {
+        originalQueue,
+        sentAt: Date.now(),
+        reason: error.message,
+        errorCode: error.code,
+        maxRetriesReached: true,
+        retryCount: message._retryCount || 0
+      }
+    };
+
+    await this.client.publish(dlqMessage, {
+      queue: dlqName,
+      persistent: true // DLQ messages should be persistent
+    });
+  }
+
+  /**
+   * Process messages from DLQ (for manual intervention or reprocessing)
+   * @param {string} dlqName - Dead Letter Queue name
+   * @param {Function} handler - Handler for DLQ messages
+   * @param {Object} options - Processing options
+   */
+  async processDLQ(dlqName, handler, options = {}) {
+    return this.client.consume(async (message, rawMsg) => {
+      try {
+        const action = await handler(message, rawMsg);
+
+        switch (action) {
+          case 'retry':
+            // Requeue to original queue
+            const originalQueue = message._dlq?.originalQueue || options.defaultQueue;
+            if (originalQueue) {
+              // Reset retry count
+              const retriedMessage = { ...message };
+              delete retriedMessage._dlq;
+              delete retriedMessage._retryCount;
+              delete retriedMessage._error;
+
+              await this.client.publish(retriedMessage, { queue: originalQueue });
+              await this.client.ack(rawMsg);
+            }
+            break;
+
+          case 'discard':
+            // Remove from DLQ
+            await this.client.ack(rawMsg);
+            break;
+
+          case 'keep':
+          default:
+            // Leave in DLQ (nack without requeue)
+            await this.client.nack(rawMsg, false);
+            break;
+        }
+      } catch (error) {
+        console.error(`DLQ processing error: ${error.message}`);
+        await this.client.nack(rawMsg, false);
+      }
+    }, {
+      queue: dlqName,
+      prefetch: 1, // Process DLQ messages one at a time
+      ...options
+    });
+  }
+
+  /**
+   * Calculate retry delay with exponential backoff
+   * @private
+   */
+  calculateDelay(retryCount) {
+    const delay = Math.min(
+      this.config.initialDelay * Math.pow(this.config.backoffMultiplier, retryCount - 1),
+      this.config.maxDelay
+    );
+
+    // Add jitter to prevent thundering herd
+    const jitter = Math.random() * 0.1 * delay;
+
+    return Math.floor(delay + jitter);
+  }
+
+  /**
+   * Get retry count from message or headers
+   * @private
+   */
+  getRetryCount(message, rawMsg) {
+    // Check message property
+    if (message._retryCount !== undefined) {
+      return message._retryCount;
+    }
+
+    // Check headers
+    if (rawMsg.properties?.headers?.['x-retry-count'] !== undefined) {
+      return parseInt(rawMsg.properties.headers['x-retry-count'], 10);
+    }
+
+    // Check death count (RabbitMQ dead letter)
+    if (rawMsg.properties?.headers?.['x-death']) {
+      const deaths = rawMsg.properties.headers['x-death'];
+      if (Array.isArray(deaths) && deaths.length > 0) {
+        return deaths[0].count || 0;
+      }
+    }
+
+    return 0;
+  }
+
+  /**
+   * Create a retry-enabled consumer
+   * @param {string} queue - Queue to consume from
+   * @param {Function} handler - Message handler
+   * @param {Object} options - Consumer options
+   */
+  async consumeWithRetry(queue, handler, options = {}) {
+    return this.client.consume(async (message, rawMsg) => {
+      await this.processWithRetry(handler, message, rawMsg, {
+        ...options,
+        queue
+      });
+    }, {
+      queue,
+      ...options
+    });
+  }
+
+  /**
+   * Get retry statistics
+   */
+  getStats() {
+    return {
+      ...this.retryStats,
+      successRate: this.retryStats.totalRetries > 0
+        ? (this.retryStats.successfulRetries / this.retryStats.totalRetries * 100).toFixed(2) + '%'
+        : 'N/A'
+    };
+  }
+
+  /**
+   * Reset retry statistics
+   */
+  resetStats() {
+    this.retryStats = {
+      totalRetries: 0,
+      successfulRetries: 0,
+      failedRetries: 0,
+      dlqMessages: 0
+    };
+  }
+
+  /**
+   * Bulk retry messages from DLQ
+   * @param {string} dlqName - DLQ name
+   * @param {string} targetQueue - Target queue for retry
+   * @param {number} limit - Maximum messages to retry
+   */
+  async bulkRetryFromDLQ(dlqName, targetQueue, limit = 100) {
+    let count = 0;
+    const results = {
+      processed: 0,
+      retried: 0,
+      failed: 0
+    };
+
+    await this.client.consume(async (message, rawMsg) => {
+      if (count >= limit) {
+        await this.client.nack(rawMsg, true); // Requeue
+        return;
+      }
+
+      count++;
+      results.processed++;
+
+      try {
+        // Clean up message
+        const cleanMessage = { ...message };
+        delete cleanMessage._dlq;
+        delete cleanMessage._error;
+        delete cleanMessage._retryCount;
+
+        // Republish to target queue
+        await this.client.publish(cleanMessage, {
+          queue: targetQueue,
+          headers: {
+            'x-dlq-retry': true,
+            'x-retry-timestamp': Date.now()
+          }
+        });
+
+        await this.client.ack(rawMsg);
+        results.retried++;
+      } catch (error) {
+        console.error(`Failed to retry DLQ message: ${error.message}`);
+        await this.client.nack(rawMsg, false);
+        results.failed++;
+      }
+
+      // Stop consuming if limit reached
+      if (count >= limit) {
+        // TODO: Cancel consumer
+      }
+    }, {
+      queue: dlqName,
+      prefetch: 10
+    });
+
+    return results;
+  }
+}
+
+module.exports = RetryHandler;