@onlineapps/mq-client-core 4.2.0 → 5.1.0

package/src/monitoring-publish.js

@@ -18,19 +18,66 @@
  *   await publishToMonitoringWorkflow(mqClient, { event_type: 'completed', workflow_id: '...', ... }, logger);
  */
 
-const { PublishError, ConnectionError } = require('./utils/errorHandler');
+const { ConnectionError } = require('./utils/errorHandler');
 const { assertLogger } = require('@onlineapps/logger-contract');
-const { QueueNotFoundError, classifyPublishError } = require('./utils/publishErrors');
+const {
+  AMQP_NOT_FOUND,
+  QueueNotFoundError,
+  TransientPublishError
+} = require('./utils/publishErrors');
 
 /**
- * Check if error indicates queue doesn't exist or RabbitMQ is unavailable
+ * The socket-level codes that mean the broker was not reachable at all. Node sets
+ * them, not this package, and they are codes rather than words.
+ */
+const UNREACHABLE_SOCKET_CODES = new Set(['ECONNREFUSED', 'ENOTFOUND', 'ETIMEDOUT']);
+
+/**
+ * How deep a cause chain this function is willing to walk.
  *
- * 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.
+ * The measured chain is three links — `PublishError` (BaseClient) → the publish
+ * classification → amqplib's raw error — so the bound is an upper limit on a real
+ * shape, not a guess about an unknown one. It exists because `error.cause` is set by
+ * whoever threw, and a chain that points back at itself would otherwise spin.
+ */
+const MAX_CAUSE_DEPTH = 8;
+
+/**
+ * Does this error — or anything it was caused by — mean the queue was not there to
+ * publish into, or the broker was not reachable?
+ *
+ * DECIDED BY CLASS AND CODE, NEVER BY THE MESSAGE. Until d.676 the decision read
+ * substrings: `'not connected'`, `'Connection closed'`, `'NOT_FOUND'`, `'404'`,
+ * `'no queue'`, `'queue does not exist'`, `'Channel closed'`. Every one of those
+ * sentences belongs to somebody else — amqplib writes the broker's refusal, this
+ * package writes its own — so the classification broke on any rewording and nothing
+ * reported the break (`docs/biz/70-contracts/error-handling.md` §6: "Message-based
+ * routing; breaks on any wording change — branch on `err.code`").
+ *
+ * WHY THE CHAIN AND NOT THE ERROR ITSELF: `BaseClient.publish()` wraps every
+ * transport failure in a `PublishError` and puts the real error in `cause`. So the
+ * object handed to this function is the wrapper, its `instanceof` tests never
+ * matched, and only the substrings ever fired — by accident, because the wrapper's
+ * message quotes the cause's sentence. Two shapes were measured answering `false`
+ * although the queue really was unavailable: a `QueueNotFoundError` with
+ * `kind: 'unowned'`, whose sentence carries none of the substrings, and a
+ * retry-exhausted publish, whose sentence quotes no cause at all.
+ *
+ * The carriers this walks for, and what each stands for:
+ *   - `QueueNotFoundError` — the publish path's own ownership refusal (the queue is
+ *     absent, whichever owner should have created it);
+ *   - `ConnectionError` — the client is not connected, or the connection dropped
+ *     (`CONNECTION_CLOSED_UNEXPECTEDLY`);
+ *   - `TransientPublishError` — the channel or connection went away mid-publish;
+ *     amqplib's `IllegalOperationError` ("Channel closed"), which carries no code of
+ *     its own, reaches here as exactly this class;
+ *   - `code === 404` — amqplib's raw `NOT_FOUND`;
+ *   - `ECONNREFUSED` / `ENOTFOUND` / `ETIMEDOUT` — the broker was unreachable.
  *
  * @param {Error} error - The error a publish to `queueName` produced.
- * @param {string} queueName - The queue that publish was aimed at.
+ * @param {string} queueName - The queue that publish was aimed at. Required since
+ *   d.435 and part of the exported contract; it is what the refusal below names.
+ * @returns {boolean}
  * @private
  */
 function isQueueUnavailableError(error, queueName) {
@@ -43,39 +90,21 @@ function isQueueUnavailableError(error, queueName) {
     );
   }
 
-  if (!error) return false;
-  
-  const errorMessage = error.message || String(error);
-  const errorCode = error.code || '';
-  const errorName = error.name || '';
-  
-  // Connection errors
-  if (error instanceof ConnectionError || 
-      errorCode === 'ECONNREFUSED' || 
-      errorCode === 'ENOTFOUND' || 
-      errorCode === 'ETIMEDOUT' ||
-      errorMessage.includes('not connected') ||
-      errorMessage.includes('Connection closed')) {
-    return true;
-  }
-  
-  // Queue doesn't exist errors
-  if (error instanceof QueueNotFoundError ||
-      errorName === 'QueueNotFoundError' ||
-      errorMessage.includes('NOT_FOUND') || 
-      errorMessage.includes('404') ||
-      errorMessage.includes('no queue') ||
-      errorMessage.includes('queue does not exist') ||
-      errorMessage.includes('Channel closed')) {
-    return true;
-  }
-  
-  // Classify publish errors
-  const classified = classifyPublishError(error, queueName);
-  if (classified instanceof QueueNotFoundError) {
-    return true;
+  let link = error;
+
+  for (let depth = 0; depth < MAX_CAUSE_DEPTH && link instanceof Error; depth += 1) {
+    if (link instanceof QueueNotFoundError
+      || link instanceof ConnectionError
+      || link instanceof TransientPublishError
+      || link.code === AMQP_NOT_FOUND
+      || UNREACHABLE_SOCKET_CODES.has(link.code)) {
+      return true;
+    }
+
+    if (link.cause === link) break;
+    link = link.cause;
   }
-  
+
   return false;
 }
 
@@ -115,6 +144,26 @@ async function publishToMonitoringResilient(mqClient, queueName, message, logger
     return false;
   }
 
+  // The client's own events go out on the client's own channel (d.724). Said here, in the
+  // one place that knows these messages are the client talking about itself; `publish()`
+  // would put them on the channel carrying the caller's business messages, where a
+  // refusal of an event closes the channel and takes those with it (measured d.711).
+  // Reported and skipped rather than thrown, like every other precondition in this
+  // function: it is fail-safe about publishing by contract (§ Principles above), and a
+  // transport without the method would otherwise turn a monitoring event into a caller's
+  // exception.
+  if (typeof mqClient.publishTelemetry !== 'function') {
+    logger.warn(
+      `Monitoring publish skipped: the client has no publishTelemetry() (queue: ${queueName}) - `
+        + 'Expected: a client whose telemetry has a channel of its own, so a refused event cannot '
+        + 'close the channel a business message is waiting on. '
+        + 'Fix: pass a @onlineapps/mq-client-core BaseClient, or a client that forwards '
+        + 'publishTelemetry() to one.',
+      context
+    );
+    return false;
+  }
+
   if (!message || !message.event_type) {
     logger.warn(`Monitoring publish skipped: message missing event_type (queue: ${queueName})`, {
       ...context,
@@ -140,7 +189,7 @@ async function publishToMonitoringResilient(mqClient, queueName, message, logger
     const publishOptions = queueName === 'monitoring.workflow'
       ? { exchange: WORKFLOW_FANOUT, routingKey: '' }
       : {};
-    await mqClient.publish(queueName, message, publishOptions);
+    await mqClient.publishTelemetry(queueName, message, publishOptions);
 
     logger.debug(`Published to ${queueName}`, {
       ...context,

package/src/scheduler-request.js

@@ -81,7 +81,7 @@ const describeErrors = (errors) => (errors || [])
  */
 function validateRecurrences(document, source) {
   if (typeof source !== 'string' || source.trim() === '') {
-    throw new Error(
+    throw invalidRequest(
       '[mq-client-core/scheduler-request] Missing source - Expected: a name for what is being '
         + 'checked, because every refusal below quotes it and a wrong name sends the reader to the '
         + 'wrong place. Fix: pass what the caller calls this document (e.g. "the declaration").'
@@ -89,7 +89,7 @@ function validateRecurrences(document, source) {
   }
 
   if (!document || typeof document !== 'object' || Array.isArray(document)) {
-    throw new Error(
+    throw invalidRequest(
       `[mq-client-core/scheduler-request] ${source} is not a declaration - Expected: an object with a "recurrences" list, `
         + `got ${Array.isArray(document) ? 'an array' : typeof document}. `
         + 'Fix: write { "recurrences": [ … ] }, or remove the file if the service declares none.'
@@ -97,7 +97,7 @@ function validateRecurrences(document, source) {
   }
 
   if (!validateDeclaration(document)) {
-    throw new Error(
+    throw invalidRequest(
       `[mq-client-core/scheduler-request] ${source} does not hold: ${describeErrors(validateDeclaration.errors)} - `
         + 'Expected: every record carries id, cookbook_ref, cron (five fields) and an explicit '
         + 'IANA timezone, and nothing this shape does not declare. '
@@ -110,7 +110,7 @@ function validateRecurrences(document, source) {
   const seen = new Set();
   for (const recurrence of document.recurrences) {
     if (seen.has(recurrence.id)) {
-      throw new Error(
+      throw invalidRequest(
         `[mq-client-core/scheduler-request] ${source} declares the id "${recurrence.id}" twice - Expected: one record per `
           + 'id, because the id travels as the scheduler\'s idempotency_key and a second record '
           + 'would silently overwrite the first at every boot. '
@@ -123,6 +123,26 @@ function validateRecurrences(document, source) {
   return document.recurrences;
 }
 
+/**
+ * The code every refusal of a builder carries — and only those (`SCHEDULER_REQUEST_INVALID`).
+ *
+ * A caller has two kinds of failure to tell apart and must never do it by the wording of a
+ * message: a request that cannot be built (a record that breaks the declaration rules, tenancy,
+ * a missing key or requester, a key the port does not declare) and a request that could not be
+ * SENT (no connection, a publish the broker refused). The wrapper's boot phase 0.7b isolates the
+ * first as a failed source and stops the boot on the second (confirmation `scheduler` 020,
+ * operational reading 1). So the builders mark their refusals with this code, and
+ * `publishSchedulerRequest()` and the port's construction never do.
+ */
+const SCHEDULER_REQUEST_INVALID = 'SCHEDULER_REQUEST_INVALID';
+
+/** A builder's refusal: the message as written, plus the code that names its kind. */
+function invalidRequest(message) {
+  const error = new Error(message);
+  error.code = SCHEDULER_REQUEST_INVALID;
+  return error;
+}
+
 /** A whole number a tenant or workspace id may be: ≥ 1, never 0 (confirmation scheduler 002). */
 const isContextId = (value) => Number.isInteger(value) && value >= 1;
 
@@ -169,7 +189,7 @@ const NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
 /** The key that identifies the item, whatever kind it is - required by the contract's root. */
 function requireIdempotencyKey(idempotencyKey) {
   if (typeof idempotencyKey !== 'string' || idempotencyKey.trim() === '') {
-    throw new Error(
+    throw invalidRequest(
       '[mq-client-core/scheduler-request] Missing idempotency_key - Expected: the stable identity '
         + 'of this item, chosen by the caller. The scheduler decides a one-shot item ONCE by this '
         + 'key, so a key invented here would turn every retry of one fact into a second run. '
@@ -183,7 +203,7 @@ function requireIdempotencyKey(idempotencyKey) {
 /** The service registering, cancelling or reporting - checked by the scheduler against services.json. */
 function requireRequestedBy(requestedBy) {
   if (typeof requestedBy !== 'string' || requestedBy.trim() === '') {
-    throw new Error(
+    throw invalidRequest(
       '[mq-client-core/scheduler-request] Missing requested_by - Expected: the platform name of the '
         + 'service sending this request; the scheduler checks it against api/config/services.json '
         + "and against the cookbook's own trigger declaration. "
@@ -197,7 +217,7 @@ function requireRequestedBy(requestedBy) {
 /** Both context ids, under the one rule confirmation `scheduler` 002 fixed. */
 function requireTenancy(tenantId, workspaceId) {
   if (!isContextId(tenantId)) {
-    throw new Error(
+    throw invalidRequest(
       `[mq-client-core/scheduler-request] Invalid tenant_id ${JSON.stringify(tenantId)} - Expected: `
         + 'a whole number of at least 1. The owner rejected a reserved value: 0 is not a platform '
         + 'scope, and an absent tenant is an error rather than a default (confirmation scheduler 002). '
@@ -208,7 +228,7 @@ function requireTenancy(tenantId, workspaceId) {
   }
 
   if (!isContextId(workspaceId)) {
-    throw new Error(
+    throw invalidRequest(
       `[mq-client-core/scheduler-request] Invalid workspace_id ${JSON.stringify(workspaceId)} - `
         + 'Expected: a whole number of at least 1, under the same rule as the tenant (confirmation '
         + 'scheduler 002). Fix: pass workspaceId with every request - a recurrence carries it in the '
@@ -242,7 +262,7 @@ function buildEventRequest({ event, tenantId, workspaceId, requestedBy, idempote
   requireTenancy(tenantId, workspaceId);
 
   if (!event || typeof event !== 'object' || Array.isArray(event)) {
-    throw new Error(
+    throw invalidRequest(
       `[mq-client-core/scheduler-request] Missing event - Expected: { service, name } - who it `
         + 'happened to and what happened, both of them. '
         + 'Fix: pass the fact this service publishes, never a cookbook name.'
@@ -251,7 +271,7 @@ function buildEventRequest({ event, tenantId, workspaceId, requestedBy, idempote
 
   for (const [field, value] of [['service', event.service], ['name', event.name]]) {
     if (typeof value !== 'string' || !NAME_PATTERN.test(value)) {
-      throw new Error(
+      throw invalidRequest(
         `[mq-client-core/scheduler-request] Invalid event.${field} ${JSON.stringify(value)} - `
           + 'Expected: the platform spelling, lower case letters, digits and dashes '
           + '(the pattern the scheduler\'s own contract declares). '
@@ -414,7 +434,7 @@ function createSchedulerPublisher({ mqClient, requestedBy } = {}) {
       // something, and dropping it in silence hides both (`architecture-principles.md` §3).
       for (const key of Object.keys(record)) {
         if (!RECURRING_PORT_KEYS.includes(key)) {
-          throw new Error(
+          throw invalidRequest(
             `[mq-client-core/scheduler-request] registerRecurring got a key the request does not declare ("${key}") - `
               + 'Expected: exactly { id, cookbookRef, cron, timezone, tenantId, workspaceId, input?, catchUp? }. '
               + 'Fix: remove the key from the record the service returns / the ctx.scheduler call.'
@@ -472,6 +492,7 @@ function createSchedulerPublisher({ mqClient, requestedBy } = {}) {
 module.exports = {
   schedulerRequestQueue,
   SENDABLE_KINDS,
+  SCHEDULER_REQUEST_INVALID,
   validateRecurrences,
   buildRecurringRequest,
   buildEventRequest,