@onlineapps/conn-orch-registry 3.0.0 → 4.0.0

package/src/registryEventConsumer.js

@@ -5,10 +5,11 @@
  * Implements opt-in subscription to registry.changes exchange.
  * Maintains local service index and enables lazy loading of specs.
  *
- * @module @onlineapps/connector-registry-client/src/registryEventConsumer
+ * @module @onlineapps/conn-orch-registry/src/registryEventConsumer
  */
 
 const EventEmitter = require('events');
+const { assertLogger } = require('@onlineapps/logger-contract');
 
 // The storage connector arrives by INJECTION. There used to be an implicit
 // default here — `require('@onlineapps/connector-storage')` inside a try/catch
@@ -27,12 +28,19 @@ class RegistryEventConsumer extends EventEmitter {
    * @param {Object} [opts.redis] - Optional Redis client for index persistence
    * @param {Object} [opts.storageConfig] - Configuration for StorageConnector
    * @param {Object} [opts.StorageConnector] - Injectable StorageConnector class for testing
+   * @param {Object} opts.logger - Logger with info/warn/error/debug; required, validated here
+   *   (docs/governance/confirmations/connector-logger-contract.md 001)
    * @param {boolean} [opts.cacheEnabled=true] - Enable local spec caching
    * @param {number} [opts.maxCacheSize=50] - Maximum cached specs
    */
-  constructor({ queueManager, serviceName, redis = null, storageConfig = {}, StorageConnector = null, cacheEnabled = true, maxCacheSize = 50 }) {
+  constructor({ queueManager, serviceName, redis = null, storageConfig = {}, StorageConnector = null, logger, cacheEnabled = true, maxCacheSize = 50 }) {
     super();
 
+    this.logger = assertLogger(
+      'RegistryEventConsumer',
+      logger,
+      'registry index changes are readable in the service log rather than on stdout'
+    );
     this.queueManager = queueManager;
     this.serviceName = serviceName;
     this.redis = redis;
@@ -92,7 +100,10 @@ class RegistryEventConsumer extends EventEmitter {
       await this.storage.initialize();
       this.emit('storageReady');
     } else {
-      console.warn('Storage connector not configured - spec downloading disabled (index-only mode)');
+      this.logger.warn('[RegistryEventConsumer] Index-only mode - spec downloading disabled', {
+        serviceName: this.serviceName,
+        reason: 'no storage connector configured'
+      });
     }
   }
 
@@ -102,49 +113,44 @@ class RegistryEventConsumer extends EventEmitter {
    */
   async subscribeToChanges() {
     try {
-      const channel = this.queueManager.channel;
-
       // Assert exchange exists (fanout type for broadcasting)
-      await channel.assertExchange(this.exchangeName, 'fanout', {
+      await this.queueManager.assertExchange(this.exchangeName, 'fanout', {
         durable: true
       });
 
-      // Create service-specific queue for registry events
-      // Try to assert queue with arguments, fall back to simple assert if conflict
-      try {
-        await channel.assertQueue(this.eventsQueueName, {
-          durable: true,
-          arguments: {
-            'x-message-ttl': 60000, // Messages expire after 1 minute
-            'x-max-length': 1000     // Keep max 1000 messages
-          }
-        });
-      } catch (error) {
-        if (error.code === 406) {
-          // Queue exists with different arguments, use it as-is
-          await channel.assertQueue(this.eventsQueueName, {
-            durable: true
-          });
-        } else {
-          throw error;
-        }
-      }
+      // The events queue is a BUSINESS queue of this service, and its declaration —
+      // durable, 1 min TTL, 1000 messages, dead-letter route to `<service>.dlq` —
+      // belongs to `queueConfig` in the core (`business['registry.events']`), not to
+      // an options object written here. The 406 branch this replaces was a fallback
+      // in the literal sense architecture-principles §3 forbids: it answered "the
+      // queue exists with different arguments" by using it anyway, which is how a
+      // queue keeps whatever arguments whoever declared it first happened to pass.
+      // It is asserted here, ahead of the binding, because a binding needs the queue
+      // to exist; `consume()` below asserts the same declaration from the same owner.
+      await this.queueManager.ensureQueues([this.eventsQueueName]);
 
       // Bind queue to exchange (receive all registry events)
-      await channel.bindQueue(this.eventsQueueName, this.exchangeName, '');
+      await this.queueManager.bindQueue(this.eventsQueueName, this.exchangeName, '');
 
       // Load initial snapshot from Redis if available
       await this.loadIndexFromCache();
 
-      // Start consuming events
-      await channel.consume(
+      // Start consuming events on the core's delivery rail: one attempt, and a
+      // failure is rejected into `<service>.dlq` instead of being dropped
+      // (d.198b-3; @onlineapps/mq-client-core README § consume() — the delivery
+      // contract).
+      await this.queueManager.consume(
         this.eventsQueueName,
         msg => this._handleRegistryEvent(msg),
-        { noAck: false }
+        { requeueOnError: false }
       );
 
       this.emit('subscribed', { queue: this.eventsQueueName, exchange: this.exchangeName });
-      console.log(`[${this.serviceName}] Subscribed to registry changes on ${this.eventsQueueName}`);
+      this.logger.info('[RegistryEventConsumer] Subscribed to registry changes', {
+        serviceName: this.serviceName,
+        queue: this.eventsQueueName,
+        exchange: this.exchangeName
+      });
 
       // Request initial snapshot
       await this.requestSnapshot();
@@ -181,24 +187,32 @@ class RegistryEventConsumer extends EventEmitter {
           break;
 
         default:
-          console.log(`[${this.serviceName}] Unknown event type: ${event.type}`);
+          this.logger.warn('[RegistryEventConsumer] Unknown registry event type', {
+            serviceName: this.serviceName,
+            eventType: event.type
+          });
       }
 
       // Persist index after update
       await this.persistIndex();
 
-      // Acknowledge message
-      this.queueManager.channel.ack(msg);
+      // No ack here: returning IS the ack (d.198b-3). The core settles the delivery
+      // on the channel that delivered it, once this handler resolves.
 
       // Emit event for service to react
       this.emit('registryEvent', event);
 
     } catch (error) {
-      console.error(`[${this.serviceName}] Failed to handle registry event:`, error);
-      this.emit('error', error);
-
-      // Reject message without requeue
-      this.queueManager.channel.nack(msg, false, false);
+      // Not emitted as an 'error' event: an EventEmitter with no 'error' listener
+      // rethrows what is emitted, so a delivery the core knows how to reject would
+      // become an uncatchable crash. The rejection is the one report.
+      //
+      // Rethrown, not nacked by hand: the consumer was registered with a
+      // one-attempt budget, so the core rejects this delivery into
+      // `<service>.dlq` and publishes a `message_dlq` event for it. The
+      // `nack(msg, false, false)` this replaces asked the broker to DROP it, and
+      // the queue declared nowhere to put it anyway.
+      throw error;
     }
   }
 
@@ -219,7 +233,12 @@ class RegistryEventConsumer extends EventEmitter {
     });
 
     this.emit('serviceUpdated', { service, fingerprint, version });
-    console.log(`[${this.serviceName}] Service ${service} updated with fingerprint ${fingerprint}`);
+    this.logger.info('[RegistryEventConsumer] Service spec published', {
+      serviceName: this.serviceName,
+      service,
+      fingerprint,
+      version
+    });
   }
 
   /**
@@ -234,7 +253,11 @@ class RegistryEventConsumer extends EventEmitter {
       entry.updatedAt = event.timestamp;
 
       this.emit('statusChanged', { service, status });
-      console.log(`[${this.serviceName}] Service ${service} status changed to ${status}`);
+      this.logger.info('[RegistryEventConsumer] Service status changed', {
+        serviceName: this.serviceName,
+        service,
+        status
+      });
     }
   }
 
@@ -259,7 +282,10 @@ class RegistryEventConsumer extends EventEmitter {
     }
 
     this.emit('snapshotReceived', { count: services.length });
-    console.log(`[${this.serviceName}] Received snapshot with ${services.length} services`);
+    this.logger.info('[RegistryEventConsumer] Registry snapshot applied', {
+      serviceName: this.serviceName,
+      count: services.length
+    });
   }
 
   /**
@@ -281,7 +307,10 @@ class RegistryEventConsumer extends EventEmitter {
       fingerprintsToRemove.forEach(fp => this.specCache.delete(fp));
 
       this.emit('serviceRemoved', { service });
-      console.log(`[${this.serviceName}] Service ${service} removed from index`);
+      this.logger.info('[RegistryEventConsumer] Service removed from index', {
+        serviceName: this.serviceName,
+        service
+      });
     }
   }
 
@@ -296,10 +325,13 @@ class RegistryEventConsumer extends EventEmitter {
       timestamp: new Date().toISOString()
     };
 
-    await this.queueManager.channel.publish(
+    // Published to the fanout exchange, never to a queue: the first argument names
+    // the target for the log line, and `routingKey: ''` is a VALUE a fanout ignores
+    // — the same shape the core's own monitoring publisher uses.
+    await this.queueManager.publish(
       this.exchangeName,
-      '',
-      Buffer.from(JSON.stringify(request))
+      request,
+      { exchange: this.exchangeName, routingKey: '' }
     );
   }
 
@@ -312,11 +344,19 @@ class RegistryEventConsumer extends EventEmitter {
     // Get entry from index
     const entry = this.serviceIndex.get(serviceName);
     if (!entry) {
-      throw new Error(`Service ${serviceName} not found in index`);
+      throw new Error(
+        `[RegistryEventConsumer] Service ${serviceName} not found in index - `
+        + 'the registry has published no entry under that name. '
+        + 'Fix: wait for the service to register, or check the name against getActiveServices().'
+      );
     }
 
     if (entry.status !== 'ACTIVE') {
-      throw new Error(`Service ${serviceName} is not active (status: ${entry.status})`);
+      throw new Error(
+        `[RegistryEventConsumer] Service ${serviceName} is not active (status: ${entry.status}) - `
+        + 'only an ACTIVE entry exposes a specification. '
+        + 'Fix: wait for the service to finish registering, or read the index entry with getServiceInfo().'
+      );
     }
 
     const { fingerprint, bucket, path } = entry;
@@ -340,7 +380,13 @@ class RegistryEventConsumer extends EventEmitter {
     }
 
     // Download from MinIO with verification
-    console.log(`[${this.serviceName}] Downloading spec for ${serviceName} from ${bucket}/${path}`);
+    this.logger.debug('[RegistryEventConsumer] Downloading spec', {
+      consumer: this.serviceName,
+      service: serviceName,
+      bucket,
+      path,
+      fingerprint
+    });
 
     const content = await this.storage.downloadWithVerification(
       bucket,
@@ -402,7 +448,10 @@ class RegistryEventConsumer extends EventEmitter {
         3600 // Expire after 1 hour
       );
     } catch (error) {
-      console.error(`[${this.serviceName}] Failed to persist index:`, error);
+      this.logger.error('[RegistryEventConsumer] Failed to persist index', {
+        serviceName: this.serviceName,
+        error: error.message
+      });
     }
   }
 
@@ -419,10 +468,16 @@ class RegistryEventConsumer extends EventEmitter {
         this.serviceIndex = new Map(entries);
 
         this.emit('indexLoaded', { count: this.serviceIndex.size });
-        console.log(`[${this.serviceName}] Loaded ${this.serviceIndex.size} services from cache`);
+        this.logger.info('[RegistryEventConsumer] Service index loaded from cache', {
+          serviceName: this.serviceName,
+          count: this.serviceIndex.size
+        });
       }
     } catch (error) {
-      console.error(`[${this.serviceName}] Failed to load index from cache:`, error);
+      this.logger.error('[RegistryEventConsumer] Failed to load index from cache', {
+        serviceName: this.serviceName,
+        error: error.message
+      });
     }
   }