@onlineapps/cookbook-router 2.0.0 → 3.0.0

package/README.md

@@ -1,3 +1,14 @@
+> Status: current
+> Owns: the publication of a workflow message to a service's queue, once the registry says that service is available
+
+<!-- BEGIN GENERATED: library-uniform — regenerate: npx oa-sync-template readme-uniform --all -->
+Uniform: [library/orchestration](../../connector/conn-orch-validator/manifests/library.manifest.json)
+
+Duty sections that apply:
+
+- `all`: L-MAIN, L-ENGINES, L-TESTS, L-TEST-SCRIPT, L-PACK-TESTS, L-PINS, L-NO-FILE-RANGE, L-CHANGELOG, L-README, L-README-REGION, L-CONSUMER
+<!-- END GENERATED: library-uniform -->
+
 # @onlineapps/cookbook-router
 
 Publishes a workflow message to a service's workflow queue, after checking with
@@ -62,7 +73,16 @@ verbatim to both collaborators, so their keys travel through it:
 | `cacheEnabled` | `ServiceDiscovery` | `true` |
 | `cacheTTL` | `ServiceDiscovery` (ms) | `300000` |
 | `ensureQueues` | `QueueManager` — assert the queue before the first publish | `true` |
-| `defaultOptions` | `QueueManager` — merged into every publish and assert | `{ durable: true, persistent: true }` |
+| `queueOptions` | `QueueManager` — merged into every queue declaration | `{ durable: true }` |
+| `publishOptions` | `QueueManager` — merged into every publish | `{ persistent: true }` |
+
+A queue declaration and a message are two different things, so their defaults
+are two objects with two owners. `queueOptions` reaches
+`mqClient.assertQueue()`, whose declared option set is `durable`, `arguments`,
+`exclusive` and `autoDelete`; `publishOptions` reaches `mqClient.publish()` as
+amqplib message properties. One object fed both until d.396d, which meant the
+queue was declared with `persistent` and the message published with `durable` —
+neither of which the receiving side reads.
 
 A key not in this table is not read by anything here.
 

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@onlineapps/cookbook-router",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Message routing for cookbook workflows - handles service discovery and queue routing",
+  "oa": {
+    "category": "orchestration"
+  },
   "main": "src/index.js",
   "scripts": {
-    "test": "jest",
+    "test": "npm run test:unit",
+    "test:unit": "jest tests/unit",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
-    "docs": "jsdoc2md --files src/**/*.js > API.md"
+    "docs": "jsdoc2md --files 'src/**/*.js' > API.md.tmp && mv API.md.tmp API.md || (rm -f API.md.tmp; exit 1)"
   },
   "keywords": [
     "cookbook",
@@ -20,10 +24,11 @@
   "license": "PROPRIETARY",
   "dependencies": {},
   "devDependencies": {
-    "jest": "^29.7.0"
+    "jest": "^29.7.0",
+    "jsdoc-to-markdown": "^8.0.0"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=24.0.0 <25"
   },
   "files": [
     "src"

package/src/index.js

@@ -22,6 +22,9 @@ const CookbookRouter = require('./router');
 const ServiceDiscovery = require('./serviceDiscovery');
 const QueueManager = require('./queueManager');
 
+// Single source of the published version — see module.exports.VERSION below.
+const pkg = require('../package.json');
+
 module.exports = {
   // Main router class
   CookbookRouter,
@@ -35,6 +38,12 @@ module.exports = {
     return new CookbookRouter(mqClient, registryClient, options);
   },
 
-  // Utility exports
-  VERSION: '1.0.0'
+  // Utility exports.
+  //
+  // Read, never retyped: until 2026-09-03 this said '1.0.0' while the package
+  // was published at 2.0.0, so every consumer was told the package still sat on
+  // the major that the 2026-09-02 routing-rail removal had ended. A version is
+  // a descriptive fact and never belongs in a hand-written literal
+  // (.claude/rules/doc-code-binding.md §1).
+  VERSION: pkg.version
 };

package/src/queueManager.js

@@ -1,21 +1,58 @@
 'use strict';
 
 /**
- * QueueManager - Queue operations and management
+ * What describes the QUEUE. Handed to `mqClient.assertQueue()`, whose declared
+ * option set is `durable`, `arguments`, `exclusive`, `autoDelete`.
  */
+const DEFAULT_QUEUE_OPTIONS = Object.freeze({ durable: true });
+
+/** What describes the MESSAGE. Handed to `mqClient.publish()`. */
+const DEFAULT_PUBLISH_OPTIONS = Object.freeze({ persistent: true });
 
+/**
+ * QueueManager - Queue operations and management
+ *
+ * A QUEUE and a MESSAGE are two different things, and neither one's defaults
+ * belong to the other. Until d.396d this class held ONE object for both —
+ * `defaultOptions: { durable: true, persistent: true }` — and spread it into the
+ * publish AND into the queue declaration, so each call site was handed a key it
+ * has no use for. Measured in both directions on the unit tier:
+ *
+ *     assertQueue('split.queue', { durable: true, persistent: true })
+ *     publish('control.publish', …,  { durable: true, persistent: true })
+ *
+ * `persistent` is a message property (amqplib `Options.Publish`) and means
+ * nothing to a queue; `durable` is a queue property and means nothing to a
+ * message. Nothing objected, because `@onlineapps/mq-client-core` read the two
+ * keys it knew and dropped the rest in silence — and since d.396c it no longer
+ * does: `assertQueue()` refuses an option it does not read, by name. What was an
+ * invisible confusion becomes a throw the moment the pin moves, and the cure is
+ * not to catch it but to stop sending a message property to a queue.
+ *
+ * So there are two defaults with two owners, `queueOptions` and `publishOptions`,
+ * and each call site merges only its own.
+ */
 class QueueManager {
   constructor(mqClient, options = {}) {
     this.mqClient = mqClient;
+    // `...options` comes FIRST so the computed keys below survive it. It used to
+    // come last, which undid the merge it was written to extend: a caller passing
+    // `{ durable: false }` replaced the whole defaults object rather than
+    // overriding one key of it, and lost the other default in the process. Every
+    // key this class does not compute is still forwarded untouched — `router.js`
+    // hands its whole options object to both collaborators.
     this.options = {
+      ...options,
       ensureQueues: options.ensureQueues !== false,
-      defaultOptions: {
-        durable: true,
-        persistent: true,
-        ...options.defaultOptions
+      queueOptions: {
+        ...DEFAULT_QUEUE_OPTIONS,
+        ...options.queueOptions
       },
-      logger: options.logger || console,
-      ...options
+      publishOptions: {
+        ...DEFAULT_PUBLISH_OPTIONS,
+        ...options.publishOptions
+      },
+      logger: options.logger || console
     };
 
     this.ensuredQueues = new Set();
@@ -25,7 +62,7 @@ class QueueManager {
    * Publish message to queue
    * @param {string} queueName - Target queue name
    * @param {Object} message - Message to publish
-   * @param {Object} options - Publishing options
+   * @param {Object} options - Publishing options (amqplib `Options.Publish`)
    * @returns {Promise<boolean>}
    */
   async publish(queueName, message, options = {}) {
@@ -43,9 +80,9 @@ class QueueManager {
         timestamp: new Date().toISOString()
       };
 
-      // Merge publishing options
+      // Merge publishing options — the MESSAGE defaults, never the queue's.
       const publishOptions = {
-        ...this.options.defaultOptions,
+        ...this.options.publishOptions,
         ...options
       };
 
@@ -73,7 +110,8 @@ class QueueManager {
   /**
    * Ensure queue exists
    * @param {string} queueName - Queue name
-   * @param {Object} options - Queue options
+   * @param {Object} options - Queue options, as `mqClient.assertQueue()` declares
+   *   them (`durable`, `arguments`, `exclusive`, `autoDelete`)
    * @returns {Promise<boolean>}
    */
   async ensureQueue(queueName, options = {}) {
@@ -82,19 +120,16 @@ class QueueManager {
       return true;
     }
 
+    // The QUEUE defaults, never the message's.
     const queueOptions = {
-      ...this.options.defaultOptions,
+      ...this.options.queueOptions,
       ...options
     };
 
-    try {
-      await this.mqClient.assertQueue(queueName, queueOptions);
-      this.ensuredQueues.add(queueName);
-      return true;
-    } catch (error) {
-      throw error;
-    }
+    await this.mqClient.assertQueue(queueName, queueOptions);
+    this.ensuredQueues.add(queueName);
+    return true;
   }
 }
 
-module.exports = QueueManager;
+module.exports = QueueManager;

package/src/router.js

@@ -27,7 +27,7 @@ class CookbookRouter {
     // reads is dead (`.claude/rules/change-discipline.md` § Removing).
     // `options` is still forwarded whole to the two collaborators below, so
     // their own keys (`cacheEnabled`, `cacheTTL`, `ensureQueues`,
-    // `defaultOptions`) reach them unchanged.
+    // `queueOptions`, `publishOptions`) reach them unchanged.
     this.options = {
       logger: console,
       ...options