@onlineapps/mq-client-core 1.0.41 → 1.0.45

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@onlineapps/mq-client-core",
-  "version": "1.0.41",
+  "version": "1.0.45",
   "description": "Core MQ client library for RabbitMQ - shared by infrastructure services and connectors",
   "main": "src/index.js",
   "scripts": {
     "test": "jest",
     "test:unit": "jest --testPathPattern=tests/unit",
     "test:component": "jest --testPathPattern=tests/component",
-    "test:integration": "jest --testPathPattern=tests/integration"
+    "test:integration": "jest --testPathPattern=tests/integration",
+    "prepublishOnly": "cd $(git rev-parse --show-toplevel) && bash scripts/pre-publish-compatibility-check.sh shared/mq-client-core",
+    "postpublish": "cd $(git rev-parse --show-toplevel) && bash scripts/update-manifest-from-npm.sh && bash scripts/update-all-services.sh"
   },
   "keywords": [
     "rabbitmq",

package/src/BaseClient.js

@@ -32,6 +32,20 @@ class BaseClient {
 
     // Merge user config with defaults
     this._config = merge({}, defaultConfig, config || {});
+    
+    // EXCEPTION: Fallback for infrastructure client configuration
+    // ENV variable name: RABBITMQ_URL (has priority over config.host and defaultConfig.host)
+    // Priority: config.host (explicit) → RABBITMQ_URL ENV → defaultConfig.host fallback
+    // Only use ENV if host was not explicitly provided in config
+    const userProvidedHost = (config && config.host);
+    if (!userProvidedHost) {
+      // ENV has priority over defaultConfig fallback
+      // Check ENV at runtime (not at module load time)
+      if (process.env.RABBITMQ_URL && process.env.RABBITMQ_URL.trim() !== '') {
+        this._config.host = process.env.RABBITMQ_URL;
+      }
+    }
+    
     this._config.heartbeat =
       this._config.heartbeat ?? Number(process.env.RABBITMQ_HEARTBEAT || 30);
     this._config.connectionName =

package/src/config/defaultConfig.js

@@ -6,14 +6,28 @@
  * Provides default configuration values for MQ Client Core.
  * Users can override any of these by passing a custom config object
  * or by supplying overrides to connect().
+ *
+ * EXCEPTION: Fallbacks are allowed ONLY for infrastructure client configuration.
+ * This is the ONLY place where fallbacks are acceptable.
+ *
+ * Environment variable (checked at runtime, has priority):
+ * - RABBITMQ_URL: Full RabbitMQ URL (e.g., amqp://guest:guest@api_services_queuer:5672)
+ *
+ * Fallback (used only if RABBITMQ_URL is not set):
+ * - amqp://guest:guest@api_services_queuer:5672 (docker-compose default)
+ *
+ * NOTE: host is resolved at runtime in BaseClient constructor, not at module load time.
  */
 
 module.exports = {
   // Transport type: currently only 'rabbitmq' is fully supported.
   type: 'rabbitmq',
 
-  // RabbitMQ connection URI or hostname (e.g., 'amqp://localhost:5672').
-  host: 'amqp://localhost:5672',
+  // RabbitMQ connection URI or hostname.
+  // NOTE: This is a fallback value. BaseClient constructor will check RABBITMQ_URL ENV variable
+  // and override this if ENV is set. ENV variable name: RABBITMQ_URL
+  // Fallback: amqp://guest:guest@api_services_queuer:5672 (docker-compose default)
+  host: 'amqp://guest:guest@api_services_queuer:5672',
 
   // Default queue name; can be overridden per call to publish/consume.
   // Optional for infrastructure services (they may not need a default queue).

package/src/config/queueConfig.js

@@ -23,12 +23,22 @@ module.exports = {
     /**
      * workflow.init - Entry point for all workflows
      * All services listen as competing consumers
+     * 
+     * TTL: 30 seconds - if no business service processes message within 30s, it expires
+     * DLQ routing: Expired messages go to workflow.failed (via x-dead-letter-exchange)
+     * 
+     * Rationale:
+     * - Fast failure detection (30s is enough for service discovery + processing start)
+     * - Prevents message accumulation when no business services are running
+     * - Failed messages go to workflow.failed for monitoring/alerting
      */
     init: {
       durable: true,
       arguments: {
-        'x-message-ttl': 300000,      // 5 minutes TTL
-        'x-max-length': 10000          // Max 10k messages
+        'x-message-ttl': 30000,       // 30 seconds TTL (fast failure if no service available)
+        'x-max-length': 10000,        // Max 10k messages
+        'x-dead-letter-exchange': '',  // Use default exchange for DLQ routing
+        'x-dead-letter-routing-key': 'workflow.failed'  // Route expired messages to workflow.failed
       }
     },
 
@@ -197,14 +207,20 @@ module.exports = {
 
   /**
    * Monitoring infrastructure queue configurations
-   * These are dedicated queues for Monitoring service (separate from delivery queues)
+   * These are dedicated queues for Monitoring service (infrastructure service)
+   * 
+   * CRITICAL: Monitoring is an infrastructure service, monitoring queues are infrastructure queues!
+   * All services (both infrastructure and business) publish monitoring events here.
    */
   monitoring: {
     /**
-     * monitoring.workflow.completed - Completed workflows for monitoring
-     * Business services publish here for observability (separate from workflow.completed for delivery)
+     * monitoring.workflow - Unified workflow lifecycle monitoring
+     * Delivery Dispatcher publishes 'completed'/'failed' events after processing workflow.completed/workflow.failed
+     * Business services publish 'progress' events during workflow step processing
+     * Message format includes event_type: 'completed' | 'failed' | 'progress'
+     * Includes full cookbook and context snapshots for trace storage
      */
-    'workflow.completed': {
+    'workflow': {
       durable: true,
       arguments: {
         'x-message-ttl': 300000,      // 5 minutes TTL
@@ -213,36 +229,19 @@ module.exports = {
     },
 
     /**
-     * monitoring.workflow.failed - Failed workflows for monitoring
-     * Business services publish here for observability (separate from workflow.failed for delivery)
-     */
-    'workflow.failed': {
-      durable: true,
-      arguments: {
-        'x-message-ttl': 300000,      // 5 minutes TTL
-        'x-max-length': 10000
-      }
-    },
-
-    /**
-     * monitoring.registry.events - Registry events for monitoring
-     */
-    'registry.events': {
-      durable: true,
-      arguments: {
-        'x-message-ttl': 60000,       // 1 minute TTL
-        'x-max-length': 5000
-      }
-    },
-
-    /**
-     * monitoring.service.heartbeats - Service heartbeats for monitoring
+     * monitoring.services - Service lifecycle events monitoring
+     * Registry publishes service lifecycle events (registered, validation.completed, version.changed, status.changed)
+     * InfrastructureHealthTracker publishes service status changes
+     * Message format includes event_type: 'service.registered' | 'service.validation.completed' | 
+     *   'service.version.changed' | 'service.deregistered' | 'service.status.changed'
+     * NOTE: Heartbeats are NOT published here (too frequent, every 10s)
+     * NOTE: Healthcheck messages go to infrastructure.health.events exchange
      */
-    'service.heartbeats': {
+    'services': {
       durable: true,
       arguments: {
-        'x-message-ttl': 120000,      // 2 minutes TTL
-        'x-max-length': 10000
+        'x-message-ttl': 600000,      // 10 minutes TTL (longer for service tracking)
+        'x-max-length': 20000
       }
     }
   },
@@ -252,27 +251,28 @@ module.exports = {
    */
   registry: {
     /**
-     * registry.register - Registration requests
+     * registry.register - Main queue for ALL service communication with Registry
+     * 
+     * CRITICAL: This is the ONLY queue used for service-to-Registry communication.
+     * Registry listener processes different message types based on msg.type:
+     * - type: 'register' - Service registration requests
+     * - type: 'heartbeat' - Periodic health check messages (sent every 10s)
+     * - type: 'apiDescription' - API specification responses
+     * 
+     * Architecture rationale:
+     * - Single consumer on registry.register handles all message types
+     * - Simplifies queue management (one queue instead of multiple)
+     * - Registry can process messages in order and maintain state consistency
+     * - All business services send both registration AND heartbeats to this queue
      */
     register: {
       durable: true,
       arguments: {
-        'x-message-ttl': 60000,       // 1 minute TTL
+        'x-message-ttl': 60000,       // 1 minute TTL (for registration requests)
         'x-max-length': 1000
       }
     },
 
-    /**
-     * registry.heartbeats - Service heartbeats
-     */
-    heartbeats: {
-      durable: true,
-      arguments: {
-        'x-message-ttl': 120000,       // 2 minutes TTL
-        'x-max-length': 5000
-      }
-    },
-
     /**
      * registry.changes - Registry event fanout exchange
      * (This is an exchange, not a queue, but included for reference)

package/src/transports/rabbitmqClient.js

@@ -122,6 +122,7 @@ class RabbitMQClient extends EventEmitter {
       client: this,
       scope: this._config.recoveryScope || 'infrastructure',
       queueCreationFilter: this._config.queueCreationFilter || null,
+      queueCreationCallback: this._config.queueCreationCallback || null, // Delegates to QueueManager if provided
       logger: console,
     });
 

package/src/workers/RecoveryWorker.js

@@ -8,12 +8,18 @@ const { QueueNotFoundError } = require('../utils/publishErrors');
  * Scope:
  * - infrastructure: connection recovery, channel recreation, consumer re-registration (NENÍ queue creation)
  * - business: connection recovery, channel recreation, consumer re-registration, queue creation (pokud není infra queue)
+ * 
+ * Queue Creation:
+ * - For business queues: delegates to queueCreationCallback if provided (e.g., QueueManager.setupServiceQueues)
+ * - Falls back to direct queue creation if callback not provided (for backward compatibility)
  */
 class RecoveryWorker {
   /**
    * @param {Object} options
    * @param {Object} options.client - RabbitMQClient instance
    * @param {string} [options.scope='infrastructure'] - 'infrastructure' nebo 'business'
+   * @param {Function} [options.queueCreationCallback] - Callback for queue creation: async (queueName, options) => void
+   *   Should delegate to QueueManager (e.g., setupServiceQueues or ensureQueue)
    * @param {Object} [options.logger] - Logger
    */
   constructor(options = {}) {
@@ -28,6 +34,9 @@ class RecoveryWorker {
     // Scope configuration
     this._queueCreationEnabled = this._scope === 'business';
     this._queueCreationFilter = options.queueCreationFilter || null;
+    
+    // Queue creation callback - delegates to QueueManager if provided
+    this._queueCreationCallback = options.queueCreationCallback || null;
   }
 
   /**
@@ -66,8 +75,17 @@ class RecoveryWorker {
       }
 
       try {
-        await this.createQueue(error.queueName, context.options);
-        this._logger?.info?.(`[RecoveryWorker] ✓ Created queue '${error.queueName}'`);
+        // Use queue creation callback if provided (delegates to QueueManager)
+        // Otherwise fall back to direct queue creation (backward compatibility)
+        if (this._queueCreationCallback) {
+          this._logger?.info?.(`[RecoveryWorker] Delegating queue creation to callback for '${error.queueName}'`);
+          await this._queueCreationCallback(error.queueName, context.options);
+          this._logger?.info?.(`[RecoveryWorker] ✓ Queue '${error.queueName}' created via callback`);
+        } else {
+          // Fallback: direct queue creation (for backward compatibility)
+          await this.createQueue(error.queueName, context.options);
+          this._logger?.info?.(`[RecoveryWorker] ✓ Created queue '${error.queueName}' (direct)`);
+        }
       } catch (createErr) {
         this._logger?.error?.(`[RecoveryWorker] Failed to create queue '${error.queueName}': ${createErr.message}`);
         throw error;