@onlineapps/mq-client-core 2.0.1 → 3.0.0

package/src/monitoring-publish.js

@@ -4,7 +4,11 @@
  * Provides resilient, fail-safe publishing to monitoring queues (monitoring.workflow, monitoring.services).
  * 
  * Principles:
- * - Fail-safe: Never throws errors, always logs failures
+ * - Fail-safe about PUBLISHING: a broker that is down or a queue that does not
+ *   exist yet returns `false` and is reported, never thrown. The single
+ *   exception is a missing or incomplete `logger`, which is a programming error
+ *   in the caller: without it the "always logs failures" half of this promise
+ *   cannot hold, so the call refuses instead of dropping events in silence.
  * - Resilient: Handles queue unavailability gracefully (queue doesn't exist yet, RabbitMQ down)
  * - Unified: Single API for all monitoring publish operations across all services
  * - Encapsulated: All monitoring publish logic in one place, no duplication
@@ -15,13 +19,30 @@
  */
 
 const { PublishError, ConnectionError } = require('./utils/errorHandler');
+const { assertLogger } = require('@onlineapps/logger-contract');
 const { QueueNotFoundError, classifyPublishError } = require('./utils/publishErrors');
 
 /**
  * Check if error indicates queue doesn't exist or RabbitMQ is unavailable
+ *
+ * The queue is named because the last question it asks —
+ * `classifyPublishError()` — builds a `QueueNotFoundError`, and that error carries
+ * a queue name it must be told (d.435); the caller has had it all along.
+ *
+ * @param {Error} error - The error a publish to `queueName` produced.
+ * @param {string} queueName - The queue that publish was aimed at.
  * @private
  */
-function isQueueUnavailableError(error) {
+function isQueueUnavailableError(error, queueName) {
+  if (typeof queueName !== 'string' || queueName === '') {
+    throw new Error(
+      '[monitoring-publish] isQueueUnavailableError requires the queue name - '
+        + 'Expected: the caller names the queue whose publish failed, so the classification it asks '
+        + 'for carries a real name. Fix: pass it as the second argument, e.g. '
+        + 'isQueueUnavailableError(error, queueName).'
+    );
+  }
+
   if (!error) return false;
   
   const errorMessage = error.message || String(error);
@@ -50,7 +71,7 @@ function isQueueUnavailableError(error) {
   }
   
   // Classify publish errors
-  const classified = classifyPublishError(error);
+  const classified = classifyPublishError(error, queueName);
   if (classified instanceof QueueNotFoundError) {
     return true;
   }
@@ -64,91 +85,97 @@ function isQueueUnavailableError(error) {
  * @param {Object} mqClient - BaseClient instance (must be connected)
  * @param {string} queueName - Queue name ('monitoring.workflow' or 'monitoring.services')
  * @param {Object} message - Message to publish (must include event_type)
- * @param {Object} [logger] - Logger instance (optional, for logging)
+ * @param {Object} logger - Logger with info/warn/error/debug (REQUIRED)
  * @param {Object} [context] - Additional context for logging (optional)
  * @returns {Promise<boolean>} - true if published successfully, false otherwise (never throws)
+ * @throws {Error} If the logger is missing or incomplete — the ONLY throw here.
  */
-async function publishToMonitoringResilient(mqClient, queueName, message, logger = null, context = {}) {
+async function publishToMonitoringResilient(mqClient, queueName, message, logger, context = {}) {
+  // BREAKING (2026-09-07): the logger is required and validated up front. This
+  // function is fail-safe by design — every failure path below returns `false`
+  // and says why through the logger — so a missing logger turned it into a
+  // silent no-op: the caller got `false` and nobody ever learned that monitoring
+  // events were being dropped. Owner confirmation
+  // `docs/governance/confirmations/connector-logger-contract.md` 001/002.
+  assertLogger(
+    'publishToMonitoringResilient',
+    logger,
+    'every skipped or failed monitoring publish is reported instead of silently returning false',
+    'pass the logger your service already built as the fourth argument'
+  );
+
   // Validate inputs
   if (!mqClient) {
-    if (logger) {
-      logger.warn('Monitoring publish skipped: mqClient not provided', context);
-    }
+    logger.warn('Monitoring publish skipped: mqClient not provided', context);
     return false;
   }
 
   if (!mqClient.isConnected || typeof mqClient.isConnected !== 'function' || !mqClient.isConnected()) {
-    if (logger) {
-      logger.warn(`Monitoring publish skipped: mqClient not connected (queue: ${queueName})`, context);
-    }
+    logger.warn(`Monitoring publish skipped: mqClient not connected (queue: ${queueName})`, context);
     return false;
   }
 
   if (!message || !message.event_type) {
-    if (logger) {
-      logger.warn(`Monitoring publish skipped: message missing event_type (queue: ${queueName})`, {
-        ...context,
-        hasMessage: !!message
-      });
-    }
+    logger.warn(`Monitoring publish skipped: message missing event_type (queue: ${queueName})`, {
+      ...context,
+      hasMessage: !!message
+    });
     return false;
   }
 
   // Validate queue name
   if (queueName !== 'monitoring.workflow' && queueName !== 'monitoring.services') {
-    if (logger) {
-      logger.warn(`Monitoring publish skipped: invalid queue name (expected monitoring.workflow or monitoring.services, got: ${queueName})`, context);
-    }
+    logger.warn(`Monitoring publish skipped: invalid queue name (expected monitoring.workflow or monitoring.services, got: ${queueName})`, context);
     return false;
   }
 
   try {
     const WORKFLOW_FANOUT = 'monitoring.workflow.fanout';
+    // The exchange is NAMED, not declared: it is a fanout owned by the monitoring
+    // consumer, which asserts it from the declaration in `config/queueConfig.js`
+    // ('monitoring' → 'workflow.fanout'). `exchangeType` stood here for the
+    // per-publish `assertExchange()` the publish path made until d.342, and left
+    // with it — a key nothing reads is not kept lying around
+    // (`change-discipline.md` § Removing something removes its declaration).
     const publishOptions = queueName === 'monitoring.workflow'
-      ? { exchange: WORKFLOW_FANOUT, exchangeType: 'fanout', routingKey: '' }
+      ? { exchange: WORKFLOW_FANOUT, routingKey: '' }
       : {};
     await mqClient.publish(queueName, message, publishOptions);
-    
-    if (logger && logger.debug) {
-      logger.debug(`Published to ${queueName}`, {
-        ...context,
-        event_type: message.event_type,
-        workflow_id: message.workflow_id,
-        service_name: message.service_name
-      });
-    }
-    
+
+    logger.debug(`Published to ${queueName}`, {
+      ...context,
+      event_type: message.event_type,
+      workflow_id: message.workflow_id,
+      service_name: message.service_name
+    });
+
     return true;
   } catch (error) {
     // Check if this is a queue unavailable error
-    if (isQueueUnavailableError(error)) {
+    if (isQueueUnavailableError(error, queueName)) {
       // Queue doesn't exist yet or RabbitMQ is unavailable - log but don't fail
-      if (logger && logger.warn) {
-        logger.warn(`Monitoring queue ${queueName} not available (queue may not exist yet or RabbitMQ unavailable)`, {
-          ...context,
-          error: error.message,
-          errorCode: error.code,
-          event_type: message.event_type,
-          workflow_id: message.workflow_id,
-          service_name: message.service_name
-        });
-      }
-      return false;
-    }
-    
-    // Other errors - log as warning but don't fail
-    if (logger && logger.warn) {
-      logger.warn(`Failed to publish to monitoring queue ${queueName}`, {
+      logger.warn(`Monitoring queue ${queueName} not available (queue may not exist yet or RabbitMQ unavailable)`, {
         ...context,
         error: error.message,
         errorCode: error.code,
-        errorName: error.name,
         event_type: message.event_type,
         workflow_id: message.workflow_id,
         service_name: message.service_name
       });
+      return false;
     }
-    
+
+    // Other errors - log as warning but don't fail
+    logger.warn(`Failed to publish to monitoring queue ${queueName}`, {
+      ...context,
+      error: error.message,
+      errorCode: error.code,
+      errorName: error.name,
+      event_type: message.event_type,
+      workflow_id: message.workflow_id,
+      service_name: message.service_name
+    });
+
     return false;
   }
 }
@@ -158,7 +185,7 @@ async function publishToMonitoringResilient(mqClient, queueName, message, logger
  * 
  * @param {Object} mqClient - BaseClient instance (must be connected)
  * @param {Object} message - Message with event_type ('completed' | 'failed' | 'progress'), workflow_id, etc.
- * @param {Object} [logger] - Logger instance (optional)
+ * @param {Object} logger - Logger with info/warn/error/debug (REQUIRED)
  * @param {Object} [context] - Additional context for logging (optional)
  * @returns {Promise<boolean>} - true if published successfully, false otherwise (never throws)
  * 
@@ -172,7 +199,7 @@ async function publishToMonitoringResilient(mqClient, queueName, message, logger
  *   timestamp: new Date().toISOString()
  * }, logger);
  */
-async function publishToMonitoringWorkflow(mqClient, message, logger = null, context = {}) {
+async function publishToMonitoringWorkflow(mqClient, message, logger, context = {}) {
   return publishToMonitoringResilient(mqClient, 'monitoring.workflow', message, logger, context);
 }
 
@@ -181,7 +208,7 @@ async function publishToMonitoringWorkflow(mqClient, message, logger = null, con
  * 
  * @param {Object} mqClient - BaseClient instance (must be connected)
  * @param {Object} message - Message with event_type ('service.registered' | 'service.validation.completed' | etc.), service_name, etc.
- * @param {Object} [logger] - Logger instance (optional)
+ * @param {Object} logger - Logger with info/warn/error/debug (REQUIRED)
  * @param {Object} [context] - Additional context for logging (optional)
  * @returns {Promise<boolean>} - true if published successfully, false otherwise (never throws)
  * 
@@ -194,7 +221,7 @@ async function publishToMonitoringWorkflow(mqClient, message, logger = null, con
  *   timestamp: new Date().toISOString()
  * }, logger);
  */
-async function publishToMonitoringServices(mqClient, message, logger = null, context = {}) {
+async function publishToMonitoringServices(mqClient, message, logger, context = {}) {
   return publishToMonitoringResilient(mqClient, 'monitoring.services', message, logger, context);
 }