@onlineapps/mq-client-core 1.0.83 → 2.0.0

package/README.md

@@ -62,6 +62,30 @@ await mqClient.publish('workflow.control', { workflowId: '123', data: '...' });
 - `isConnected()` - Check connection status
 - `onError(callback)` - Register error handler
 
+`publish()` and the workflow helpers built on it resolve to `undefined`; failure is
+signalled by a thrown `PublishError`, never by a falsy return.
+
+### Queue ownership — publishing never creates an owned queue
+
+A missing queue is answered by who owns the name, not by the client's scope:
+
+| Name | Owner | Missing at publish time |
+|---|---|---|
+| `workflow.*`, `registry.*`, `infrastructure.*`, `validation.*`, `monitoring.*`, `telemetry.*`, `delivery.*` | the infrastructure service that declares it | `QueueNotFoundError` (`kind: 'infrastructure'`) |
+| `{service}.workflow`, `{service}.queue`, `{service}.dlq` | the owning service, via `setupServiceQueues()` **after** registration | `QueueNotFoundError` (`kind: 'business'`) |
+| anything else | nobody | created with default options, if `recoveryScope` allows it |
+
+Publishing must never create an owned queue: `sendToQueue()`/`assertQueue()` would
+declare it with default arguments — no TTL, no DLQ — and the owner's later
+`setupServiceQueues()` then fails with 406 `PRECONDITION_FAILED` because the
+arguments no longer match. The rule is enforced in two places, and both are
+required: the 404 branch of `_publishOnce()` refuses the publish, and
+`RecoveryWorker.handleQueueNotFound()` refuses to create the queue behind it.
+
+`recoveryScope: 'business'` (the default every `ConnectorMQClient` sets) says the
+client belongs to a business service. It has never meant "may create business
+queues".
+
 ## Architecture
 
 ```

package/jest.config.js

@@ -0,0 +1,15 @@
+'use strict';
+
+/**
+ * Default tier: unit + component only.
+ *
+ * `tests/integration` is excluded here and served by `jest.integration.config.js`
+ * instead, because that tier fails fast on a missing `RABBITMQ_URL` — folding it
+ * into the default run would make `npm test` unrunnable without a broker, and the
+ * usual "fix" for that is a skip, which is how a suite quietly leaves the
+ * regression loop (`.claude/rules/service-refactoring.md` #4).
+ */
+module.exports = {
+  testEnvironment: 'node',
+  testPathIgnorePatterns: ['/node_modules/', '/tests/integration/']
+};

package/jest.integration.config.js

@@ -0,0 +1,16 @@
+'use strict';
+
+/**
+ * Integration tier: runs against the live broker, never skipped.
+ *
+ * `globalSetup` aborts the whole run before Jest builds a describe tree when
+ * `RABBITMQ_URL` is missing or the broker is unreachable — see
+ * `tests/integration/setup.js`.
+ */
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['**/tests/integration/**/*.test.js'],
+  testTimeout: 30000,
+  globalSetup: './tests/integration/setup.js',
+  verbose: true
+};

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@onlineapps/mq-client-core",
-  "version": "1.0.83",
+  "version": "2.0.0",
   "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 --config=jest.integration.config.js"
   },
   "keywords": [
     "rabbitmq",
@@ -21,7 +21,7 @@
     "amqplib": "^0.10.3",
     "ajv": "^8.12.0",
     "lodash.merge": "^4.6.2",
-    "@onlineapps/runtime-config": "1.0.2"
+    "@onlineapps/runtime-config": "1.0.3"
   },
   "devDependencies": {
     "jest": "^29.7.0"

package/src/BaseClient.js

@@ -263,6 +263,19 @@ class BaseClient {
 
   /**
    * Acknowledge a raw broker message (delegates to transport).
+   *
+   * Settling is idempotent: the transport marks the delivery via `msg._mqProcessed`
+   * and `consume()` skips its own auto-ack for a message the handler already
+   * settled (`transports/rabbitmqClient.js:1769` and `:2268`). Calling this from
+   * inside a consume handler is therefore supported, not a double-settle.
+   *
+   * Until 2026-08-28 this method was declared TWICE in this class; the second,
+   * later declaration silently overrode this one and omitted the
+   * `typeof this._transport.ack !== 'function'` capability check below, so a
+   * transport without `ack` failed with `TypeError: this._transport.ack is not a
+   * function` instead of the actionable message. Same defect shape as the
+   * duplicate pair removed from the storage connector.
+   *
    * @param {Object} msg - Broker message object
    * @returns {Promise<void>}
    */
@@ -292,31 +305,6 @@ class BaseClient {
     return await this._transport.nack(msg, options);
   }
 
-  /**
-   * Acknowledges a RabbitMQ message.
-   * @param {Object} msg - RabbitMQ message object.
-   * @returns {Promise<void>}
-   */
-  async ack(msg) {
-    if (!this._connected || !this._transport) {
-      throw new ConnectionError('Cannot ack: client is not connected');
-    }
-    return this._transport.ack(msg);
-  }
-
-  /**
-   * Negative-acknowledges a RabbitMQ message.
-   * @param {Object} msg - RabbitMQ message object.
-   * @param {Object} [options] - Options such as { requeue: boolean }.
-   * @returns {Promise<void>}
-   */
-  async nack(msg, options = {}) {
-    if (!this._connected || !this._transport) {
-      throw new ConnectionError('Cannot nack: client is not connected');
-    }
-    return this._transport.nack(msg, options);
-  }
-
   /**
    * Registers a global error handler. Internal or transport-level errors will be forwarded here.
    * @param {function(Error): void} callback

package/src/config/queueConfig.js

@@ -174,15 +174,12 @@ module.exports = {
     },
 
     /**
-     * delivery.result - Final delivery status events for audits/monitoring
+     * `delivery.result` used to be defined here as an "audit" queue. It never had a
+     * consumer in any commit, so everything published to it expired unread inside its
+     * 24h TTL. Delivery outcome is persisted durably (and redacted) through
+     * monitoring.workflow -> workflow_traces instead — see docs/architecture/delivery.md.
+     * Do not re-add it; enrich the monitoring.workflow event instead.
      */
-    result: {
-      durable: true,
-      arguments: {
-        'x-message-ttl': 86400000, // 24 hours TTL for audit traceability
-        'x-max-length': 50000
-      }
-    },
 
     /**
      * delivery.websocket.notify - Notifications for Gateway websocket hub
@@ -370,10 +367,13 @@ module.exports = {
      * 
      * 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
-     * 
+     * - type: 'register'   - Service registration requests (full spec + operations)
+     * - type: 'heartbeat'  - Periodic health check messages (sent every 10s)
+     * - type: 'deregister' - Voluntary shutdown notice
+     * (The legacy 'apiDescription' / 'apiDescriptionRequest' types are no
+     *  longer supported — see operations-registry-contract.md §2.)
+     *
+     *
      * Architecture rationale:
      * - Single consumer on registry.register handles all message types
      * - Simplifies queue management (one queue instead of multiple)

package/src/transports/rabbitmqClient.js

@@ -19,6 +19,41 @@ const RecoveryWorker = require('../workers/RecoveryWorker');
 const PublishMonitor = require('../monitoring/PublishMonitor');
 const runtimeCfg = require('../config');
 
+/** AMQP basic.publish fields forwarded from publish() options (amqplib Options.Publish). */
+const AMQP_MESSAGE_PROPERTY_KEYS = [
+  'correlationId',
+  'replyTo',
+  'messageId',
+  'timestamp',
+  'type',
+  'priority',
+  'expiration',
+  'contentType',
+  'contentEncoding',
+  'userId',
+  'appId',
+];
+
+/**
+ * Merge persistent + headers with whitelisted AMQP message properties for sendToQueue/publish.
+ * @param {Object} options
+ * @param {boolean} persistent
+ * @param {Object} headers
+ * @returns {Object}
+ */
+function buildAmqpMessageProperties(options, persistent, headers) {
+  const props = { persistent };
+  if (headers && typeof headers === 'object') {
+    props.headers = headers;
+  }
+  for (const key of AMQP_MESSAGE_PROPERTY_KEYS) {
+    if (options[key] !== undefined && options[key] !== null && options[key] !== '') {
+      props[key] = options[key];
+    }
+  }
+  return props;
+}
+
 /**
  * Local structured logger (module-owned) to avoid dependency cycles.
  *
@@ -1283,10 +1318,16 @@ class RabbitMQClient extends EventEmitter {
     try {
       // Ensure queue exists if publishing directly to queue and using default exchange
       if (!exchange) {
+        // RPC / client reply targets: server-named exclusive queues (amq.gen-*) or direct reply-to
+        // exist only on the client's connection — another connection cannot checkQueue them.
+        const skipQueueExistencePrecheck =
+          queue === 'amq.rabbitmq.reply-to' || queue.startsWith('amq.gen-');
+
         // CRITICAL: For infrastructure queues, they should already exist with specific arguments from queueConfig
         // Use queueChannel (regular channel) for checkQueue/assertQueue to avoid RPC reply queue issues
         // If queue doesn't exist (404), we should NOT auto-create it - infrastructure queues must be created explicitly
         // This prevents creating queues with wrong arguments (no TTL) which causes 406 errors later
+        if (!skipQueueExistencePrecheck) {
         try {
           // Ensure queue channel exists and is open (auto-recreates if closed)
           await this._ensureQueueChannel();
@@ -1302,27 +1343,44 @@ class RabbitMQClient extends EventEmitter {
           // Queue exists - proceed to publish
         } catch (checkErr) {
           // If queue doesn't exist (404), this je ERROR – ale rozlišujeme infra vs. non-infra:
-          // - Infrastructure queues (workflow.*, registry.*, infrastructure.*, monitoring.*, validation.*)
-          //   musí být vytvořené infra službami předem → QueueNotFoundError(isInfrastructure=true)
-          // - Non-infrastructure queues můžeme (pro business scénáře) vytvořit s default parametry
+          // 404 na chybějící frontu se rozpadá na tři případy podle vlastnictví:
+          // - Infrastrukturní fronty (`queueConfig.isInfrastructureQueue`) zakládají
+          //   infra služby předem → QueueNotFoundError(kind='infrastructure').
+          // - Business fronty (`queueConfig.isBusinessQueue`, tj. `{service}.{workflow|queue|dlq}`)
+          //   zakládá vlastnící služba přes setupServiceQueues() po registraci
+          //   → QueueNotFoundError(kind='business'). Publisher je nikdy nevytváří.
+          // - Ostatní jména (ani infra, ani business vzor) se smějí založit
+          //   s default parametry, pokud to scope RecoveryWorkeru dovoluje.
           if (checkErr.code === 404) {
-            // Check if this is an infrastructure queue using queueConfig
-            let isInfraQueue = false;
-            try {
-              const queueConfig = require('../config/queueConfig');
-              isInfraQueue = queueConfig.isInfrastructureQueue(queue);
-            } catch (requireErr) {
-              // Fallback to pattern matching if queueConfig not available
-              isInfraQueue = queue.startsWith('workflow.') || 
-                            queue.startsWith('registry.') || 
-                            queue.startsWith('infrastructure.') || 
-                            queue.startsWith('monitoring.') || 
-                            queue.startsWith('validation.');
-            }
-            
-            if (isInfraQueue) {
+            // `../config/queueConfig` is a sibling module of this file; the require
+            // cannot fail. It used to sit in a try/catch whose `catch` re-implemented
+            // `isInfrastructureQueue` as an inline prefix list — a fallback
+            // (`architecture-principles.md` §3) that had also gone stale: it was
+            // missing `telemetry.` and `delivery.`, both of which the real
+            // queueConfig classifies as infrastructure. A fallback that answers
+            // differently from the thing it stands in for is a second, wrong source
+            // of truth, so it is gone.
+            const queueConfig = require('../config/queueConfig');
+
+            if (queueConfig.isInfrastructureQueue(queue)) {
               // Jasný, hlasitý signál pro infra služby – fronta chybí, je to programátorská chyba
-              throw new QueueNotFoundError(queue, true, checkErr);
+              throw new QueueNotFoundError(queue, true, checkErr, 'infrastructure');
+            }
+
+            // Business queues (`{service}.{workflow|queue|dlq}`) MUST exist before
+            // publish. `sendToQueue()`/`assertQueue()` with default options would
+            // create them with no TTL and no DLQ, and the owning service's later
+            // `setupServiceQueues()` then hits 406 PRECONDITION_FAILED because the
+            // arguments no longer match. The queue is created by the owner AFTER
+            // registration; a publisher that creates it is a programming error.
+            //
+            // The rule and this exact wording came from
+            // `conn-infra-mq/src/transports/rabbitmqClient.js:264-277` — a transport
+            // that nothing in `src/` instantiated, so the guard protected nobody
+            // while this file, the one every client actually runs, auto-created the
+            // queue and only printed a warning.
+            if (queueConfig.isBusinessQueue(queue)) {
+              throw new QueueNotFoundError(queue, false, checkErr, 'business');
             }
           // For non-infrastructure queues, check if queue creation is allowed before auto-creating
           // Check recovery scope and filter
@@ -1358,6 +1416,7 @@ class RabbitMQClient extends EventEmitter {
             throw checkErr;
           }
         }
+        }
         // Publish to queue using ConfirmChannel (for publisher confirms)
         // Channel is guaranteed to be open (ensured above)
         console.log(`[RabbitMQClient] [mq-client-core] [PUBLISH] Sending message to queue "${queue}" (size: ${buffer.length} bytes)`);
@@ -1383,7 +1442,11 @@ class RabbitMQClient extends EventEmitter {
           
           // Send message with callback
           try {
-            originalChannel.sendToQueue(queue, buffer, { persistent, headers }, (err, ok) => {
+            originalChannel.sendToQueue(
+              queue,
+              buffer,
+              buildAmqpMessageProperties(options, persistent, headers),
+              (err, ok) => {
               callbackInvoked = true;
               this._clearTimeout(timeout);
               
@@ -1483,7 +1546,12 @@ class RabbitMQClient extends EventEmitter {
             reject(new Error(`Exchange publish confirmation timeout for exchange "${exchange}" after ${this._publishConfirmationTimeout}ms`));
           }, this._publishConfirmationTimeout);
           
-          this._channel.publish(exchange, routingKey, buffer, { persistent, headers }, (err, ok) => {
+          this._channel.publish(
+            exchange,
+            routingKey,
+            buffer,
+            buildAmqpMessageProperties(options, persistent, headers),
+            (err, ok) => {
             this._clearTimeout(timeout);
             if (err) {
               console.error(`[RabbitMQClient] [mq-client-core] [PUBLISH] Exchange publish callback error:`, err.message);

package/src/utils/publishErrors.js

@@ -36,15 +36,34 @@ class QueueNotFoundError extends PermanentPublishError {
    * @param {string} queueName
    * @param {boolean} isInfrastructure
    * @param {Error} [cause]
+   * @param {('infrastructure'|'business'|'unknown')} [kind] - Which ownership rule
+   *   was violated. Defaults to `'infrastructure'`/`'unknown'` from
+   *   `isInfrastructure`, so existing two- and three-argument callers are unchanged.
    */
-  constructor(queueName, isInfrastructure, cause) {
-    const baseMessage = isInfrastructure
-      ? `Cannot publish to infrastructure queue ${queueName}: queue does not exist. Infrastructure queues must be created explicitly with correct arguments (TTL, max-length, etc.) before publishing.`
-      : `Queue ${queueName} does not exist`;
+  constructor(queueName, isInfrastructure, cause, kind) {
+    const resolvedKind = kind || (isInfrastructure ? 'infrastructure' : 'unknown');
+    let baseMessage;
+    if (resolvedKind === 'infrastructure') {
+      baseMessage =
+        `Cannot publish to infrastructure queue ${queueName}: queue does not exist. ` +
+        'Infrastructure queues must be created explicitly with correct arguments ' +
+        '(TTL, max-length, etc.) before publishing.';
+    } else if (resolvedKind === 'business') {
+      baseMessage =
+        `Cannot publish to business queue ${queueName}: queue does not exist. ` +
+        'Expected: business queues are created by their owning service via ' +
+        'setupServiceQueues() AFTER successful registration, with the arguments ' +
+        'queueConfig prescribes (TTL, DLQ). Fix: call setupServiceQueues() before ' +
+        'publishing — publishing must never create the queue, because sendToQueue() ' +
+        'would create it with default arguments (no TTL, no DLQ).';
+    } else {
+      baseMessage = `Queue ${queueName} does not exist`;
+    }
     super(baseMessage, cause);
     this.name = 'QueueNotFoundError';
     this.queueName = queueName;
     this.isInfrastructure = !!isInfrastructure;
+    this.kind = resolvedKind;
   }
 }
 

package/src/workers/RecoveryWorker.js

@@ -7,11 +7,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)
+ * - business: totéž + zakládání front, ale POUZE těch, které nemají vlastníka
+ *   (viz Queue Creation níže). Scope říká, ČÍ ten klient je — ne co smí založit.
+ *
+ * Queue Creation — vlastnictví fronty rozhoduje, ne scope:
+ * - infrastrukturní fronty (`queueConfig.isInfrastructureQueue`) zakládá vlastnící
+ *   infra služba předem → tento worker je nikdy nezaloží, chybu propustí dál;
+ * - business fronty (`queueConfig.isBusinessQueue`, tj. `{service}.{workflow|queue|dlq}`)
+ *   zakládá vlastnící služba přes `setupServiceQueues()` po registraci, s argumenty
+ *   z queueConfig (TTL, DLQ) → tento worker je nikdy nezaloží, chybu propustí dál;
+ * - ostatní jména (ani infra, ani business vzor) smí založit, pokud to scope
+ *   a `queueCreationFilter` dovolují — buď přes `queueCreationCallback`
+ *   (deleguje na QueueManager), nebo přímo.
  */
 class RecoveryWorker {
   /**
@@ -66,7 +73,27 @@ class RecoveryWorker {
       throw error;
     }
 
-    // Business queues - create if scope allows
+    // Business queues ({service}.{workflow|queue|dlq}) must exist too — they are
+    // created by their owning service via setupServiceQueues() AFTER registration,
+    // with the arguments queueConfig prescribes.
+    //
+    // Measured 2026-08-28: without this branch the ownership guard in
+    // `_publishOnce` was defeated by its own error path. The publish was refused
+    // correctly, the caller saw PublishError — and then this worker, listening for
+    // QueueNotFoundError on the client's error event, created the very queue the
+    // guard had just refused ("[RecoveryWorker] ✓ Created queue '<q>' (direct)"),
+    // with default arguments and no TTL. Refusing at one door while opening the
+    // other is not a guard.
+    //
+    // `_scope: 'business'` says the CLIENT belongs to a business service. It has
+    // never meant "may create business queues", and ConnectorMQClient.js:74 sets
+    // it for every biz service, so that reading made the rule vacuous.
+    if (error.kind === 'business') {
+      this._logger?.error?.(`[RecoveryWorker] Cannot create business queue '${error.queueName}' - it is created by its owning service via setupServiceQueues() after registration`);
+      throw error;
+    }
+
+    // Everything else - create if scope allows
     if (this._queueCreationEnabled) {
       // Check filter if provided
       if (this._queueCreationFilter && !this._queueCreationFilter(error.queueName)) {

package/tests/unit/queueConfig-delivery.test.js

@@ -1,38 +0,0 @@
-'use strict';
-
-const queueConfig = require('../../src/config/queueConfig');
-
-describe('queueConfig delivery infrastructure', () => {
-  test('delivery.retry configuration', () => {
-    const config = queueConfig.getInfrastructureQueueConfig('delivery.retry');
-    expect(config).toEqual({
-      durable: true,
-      arguments: {
-        'x-max-length': 10000
-      }
-    });
-  });
-
-  test('delivery.result configuration', () => {
-    const config = queueConfig.getInfrastructureQueueConfig('delivery.result');
-    expect(config).toEqual({
-      durable: true,
-      arguments: {
-        'x-message-ttl': 86400000,
-        'x-max-length': 50000
-      }
-    });
-  });
-
-  test('delivery.websocket.notify configuration', () => {
-    const config = queueConfig.getInfrastructureQueueConfig('delivery.websocket.notify');
-    expect(config).toEqual({
-      durable: true,
-      arguments: {
-        'x-message-ttl': 60000,
-        'x-max-length': 10000
-      }
-    });
-  });
-});
-

package/tests/unit/queueConfig-validation.test.js

@@ -1,28 +0,0 @@
-'use strict';
-
-const queueConfig = require('../../src/config/queueConfig');
-
-describe('queueConfig validation infrastructure', () => {
-  test('validation.requests configuration', () => {
-    const config = queueConfig.getInfrastructureQueueConfig('validation.requests');
-    expect(config).toEqual({
-      durable: true,
-      arguments: {
-        'x-message-ttl': 300000,
-        'x-max-length': 10000
-      }
-    });
-  });
-
-  test('validation.responses configuration', () => {
-    const config = queueConfig.getInfrastructureQueueConfig('validation.responses');
-    expect(config).toEqual({
-      durable: true,
-      arguments: {
-        'x-message-ttl': 300000,
-        'x-max-length': 10000
-      }
-    });
-  });
-});
-