@onlineapps/conn-orch-registry 6.0.3 → 7.0.0

package/docs/REGISTRY_CLIENT_GUIDE.md

@@ -31,7 +31,7 @@ Microservice                Registry                  Backend
 > The legacy `apiDescriptionRequest` / `sendApiDescription` round-trip has
 > been removed — the full service specification (including the `operations`
 > map) travels as part of the `register` message. See
-> [operations-registry-contract.md §2](../../../../docs/biz/30-operations/registration-wire.md).
+> [registration-wire.md §2.1](../../../../docs/biz/30-operations/registration-wire.md).
 
 ## Usage
 
@@ -131,7 +131,7 @@ against the Operations Registry contract and either confirms or rejects.
 
 **Parameters:**
 - `serviceInfo.endpoints` - Array of API endpoints
-- `serviceInfo.operations` - Operations map (see [operations-registry-contract.md §3](../../../../docs/biz/30-operations/registration-wire.md))
+- `serviceInfo.operations` - Operations map (see [registration-wire.md §3](../../../../docs/biz/30-operations/registration-wire.md))
 - `serviceInfo.metadata` - Service metadata object
 - `serviceInfo.health` - Health check endpoint
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-registry",
-  "version": "6.0.3",
+  "version": "7.0.0",
   "license": "MIT",
   "description": "conn-orch-registry provides the core communication mechanism for microservices in this environment. It enables them to interact with a services_registry to receive and fulfill tasks by submitting heartbeats or their API descriptions.",
   "keywords": [
@@ -18,7 +18,9 @@
     "docs/",
     "examples/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md",
+    "API.md"
   ],
   "oa": {
     "category": "orchestration"
@@ -37,7 +39,7 @@
   },
   "dependencies": {
     "@onlineapps/logger-contract": "2.0.0",
-    "@onlineapps/mq-client-core": "4.2.0",
+    "@onlineapps/mq-client-core": "5.0.0",
     "uuid": "^9.0.1"
   },
   "devDependencies": {

package/src/registryClient.js

@@ -68,6 +68,38 @@ const RETIRED_SERVICE_INFO_KEYS = Object.freeze({
     + 'destructure it, so deployability is read from that CI job and never from a registration message'
 });
 
+/**
+ * The keys `register()` ACCEPTS — the whole input contract of the call (d.702).
+ *
+ * It is the caller's half of `api/docs/biz/30-operations/registration-wire.md`
+ * §2.1: the five register-message fields a CALLER supplies, plus `timeout`, which
+ * is this call's own response budget and reaches no message. The rest of §2.1
+ * (`id`, `type`, `serviceName`, `version`, `specificationEndpoint`,
+ * `responseQueue`, `timestamp`, `validationProof`, `validationData`) is client
+ * state bound in the constructor, never caller input — a caller cannot set it and
+ * this table must not invite one to try.
+ *
+ * Any other key is refused BY NAME, for the same reason the table above exists:
+ * until d.702 `register()` refused six retired keys and dropped everything else in
+ * silence, so `helth`, `current_step` or `name` bought a confirmed registration
+ * whose message never carried the value. A key silently dropped leaves the caller
+ * believing something travelled, and a typo in an optional key is exactly the
+ * shape nobody notices (`architecture-principles.md` §3 no fallbacks, §4
+ * fail-fast).
+ *
+ * `RETIRED_SERVICE_INFO_KEYS` is the subset that can still say WHY the key went;
+ * ONE membership check reads both tables, so there is no second list to drift
+ * (`.claude/rules/change-discipline.md` § One rail per concern).
+ */
+const ACCEPTED_SERVICE_INFO_KEYS = Object.freeze({
+  endpoints: 'the `endpoints` array of the register message (§2.1); `[]` for every v3 service',
+  operations: 'the complete `operations` map the registry validates (§3)',
+  metadata: 'the `{ version, description }` object stored beside the spec (§2.1)',
+  health: 'the legacy health path of the register message; liveness travels by heartbeat (§2.2)',
+  workspaceScoped: 'the boolean emitted only when the service declares it (§2.1)',
+  timeout: 'how long THIS call waits for the registry verdict; it reaches no message'
+});
+
 
 class ServiceRegistryClient extends EventEmitter {
   /**
@@ -95,7 +127,7 @@ class ServiceRegistryClient extends EventEmitter {
    *   docs/governance/confirmations/connector-logger-contract.md 001 + 002.
    */
   constructor({ amqpUrl, serviceName, version, specificationEndpoint,
-                heartbeatInterval, apiQueue = 'api_services_queuer', registryQueue = 'registry.register',
+                heartbeatInterval, instanceId, apiQueue = 'api_services_queuer', registryQueue = 'registry.register',
                 redis = null, storageConfig = {}, validationProof = null, logger,
                 registryKeyPrefix = DEFAULTS.registryKeyPrefix,
                 registrationTimeoutMs = DEFAULTS.registrationTimeoutMs }) {
@@ -118,6 +150,32 @@ class ServiceRegistryClient extends EventEmitter {
         + `(module default ${DEFAULTS.registrationTimeoutMs}).`
       );
     }
+    // WHICH RUNNING COPY. The service NAME says which service; until d.817 nothing said
+    // which copy, so a short-lived foreign instance deregistered the live one and three
+    // services then beat into `unknown` for nine hours (INFRA batch 398, from production
+    // logs; owner decision `registry-instance-identity` 001).
+    //
+    // INJECTED, never made here (§1 DI, §3 no fallback): the wrapper makes ONE value per
+    // process at boot and hands the same one to `monitoring-core` as `serviceInstanceId`,
+    // so a second birthplace here would give one running copy two identities. Rule 11 —
+    // no default, no `|| uuidv4()`, no transition period.
+    if (typeof instanceId !== 'string' || instanceId === '') {
+      throw new Error(
+        `[RegistryClient] ${serviceName}: Missing instanceId - got ${JSON.stringify(instanceId)}. `
+        + 'Expected: a non-empty string naming THIS running copy of the service, the same value for the '
+        + 'whole process; the service name says which service, this says which copy. '
+        + 'Fix: pass the instance id the wrapper made once at boot (SERVICE_INSTANCE_ID when the '
+        + 'deployment gives one, otherwise a UUID v4) - this client never makes one, because the same '
+        + 'value also reaches monitoring-core as serviceInstanceId.'
+      );
+    }
+    this.instanceId = instanceId;
+    // Where the registry answers THIS copy's registration (conf
+    // `registry-instance-identity` 001 (c), d.817c) — carried as `responseQueue`.
+    // The shared `<service>.registry` (`serviceRegistryQueue`, set in `init()`)
+    // carries the registry's own prompts to every copy.
+    this.instanceResponseQueue = `${serviceName}.registry.${instanceId}`;
+
     this.registrationTimeoutMs = registrationTimeoutMs;
     this.serviceName = serviceName;
     this.version = version;
@@ -195,8 +253,42 @@ class ServiceRegistryClient extends EventEmitter {
     // agreeing today, and 406 PRECONDITION-FAILED the day the two drift apart
     // (`.claude/rules/change-discipline.md` § One rail per concern).
     const consumerStartTime = Date.now();
+    // TWO queues, two jobs (conf `registry-instance-identity` 001 (c), d.817c):
+    //  - `<service>.registry`, shared by every copy — the registry's own prompts
+    //    (`revalidate`; `api_services_registry` `revalidationRequester.js` sends to
+    //    `<serviceName>.registry`);
+    //  - `<service>.registry.<instance_id>` — the answers to THIS copy's registration,
+    //    named in `register`'s `responseQueue`, so a live copy can no longer eat the
+    //    confirmation meant for another.
+    // Both have a dead-letter route in `queueConfig` (the per-instance template landed
+    // first, d.817b — the order conf 002 made binding), so `consume()` accepts both.
     this.serviceRegistryQueue = `${this.serviceName}.registry`;
 
+    for (const queue of [this.serviceRegistryQueue, this.instanceResponseQueue]) {
+      await this._startRegistryConsumer(queue);
+    }
+
+    // One line for the whole boot of this client: which queues it talks on, and how
+    // long the consumers took to attach. Replaces the four FÁZE 0.5/0.6 markers.
+    this.logger.info('[RegistryClient] Initialized', {
+      serviceName: this.serviceName,
+      version: this.version,
+      registryQueue: this.registryQueue,
+      promptQueue: this.serviceRegistryQueue,
+      responseQueue: this.instanceResponseQueue,
+      consumerStartupMs: Date.now() - consumerStartTime
+    });
+  }
+
+  /**
+   * Attach this client's handler to one registry queue, within a bounded wait.
+   *
+   * @param {string} queue - `<service>.registry` or `<service>.registry.<instance_id>`
+   * @returns {Promise<void>}
+   * @throws {Error} naming the queue, carrying the source's classification
+   * @private
+   */
+  async _startRegistryConsumer(queue) {
     const CONSUME_TIMEOUT = 5000; // 5 seconds
     // `requeueOnError: false` is the budget this consumer has always had, said in
     // the core's word: ONE attempt. The difference is where a failure goes — the
@@ -206,7 +298,7 @@ class ServiceRegistryClient extends EventEmitter {
     // nothing itself (@onlineapps/mq-client-core README § consume() — the delivery
     // contract).
     const consumeRegistryPromise = this.queueManager.consume(
-      this.serviceRegistryQueue,
+      queue,
       msg => this._handleRegistryMessage(msg),
       { requeueOnError: false }
     );
@@ -214,7 +306,7 @@ class ServiceRegistryClient extends EventEmitter {
     const consumeRegistryTimeoutPromise = new Promise((_, reject) => {
       consumeRegistryTimeout = setTimeout(() => {
         reject(new Error(
-          `[RegistryClient] consume() timeout for ${this.serviceRegistryQueue} after ${CONSUME_TIMEOUT}ms - `
+          `[RegistryClient] consume() timeout for ${queue} after ${CONSUME_TIMEOUT}ms - `
           + 'the broker never confirmed the consumer. Fix: check RabbitMQ responsiveness and that the queue exists.'
         ));
       }, CONSUME_TIMEOUT);
@@ -234,7 +326,7 @@ class ServiceRegistryClient extends EventEmitter {
       // { cause })` carries no own property, so the marker used to die here.
       // Nothing is classified HERE — what the source left unmarked stays unmarked.
       const refusal = new Error(
-        `[RegistryClient] ${this.serviceName}: Failed to start consumer on ${this.serviceRegistryQueue} - `
+        `[RegistryClient] ${this.serviceName}: Failed to start consumer on ${queue} - `
         + `${consumeErr.message}. Fix: check RabbitMQ health; without this consumer no registry reply is ever read.`,
         { cause: consumeErr }
       );
@@ -244,16 +336,6 @@ class ServiceRegistryClient extends EventEmitter {
     } finally {
       if (consumeRegistryTimeout) clearTimeout(consumeRegistryTimeout);
     }
-
-    // One line for the whole boot of this client: which queues it talks on, and how
-    // long the consumer took to attach. Replaces the four FÁZE 0.5/0.6 markers.
-    this.logger.info('[RegistryClient] Initialized', {
-      serviceName: this.serviceName,
-      version: this.version,
-      registryQueue: this.registryQueue,
-      responseQueue: this.serviceRegistryQueue,
-      consumerStartupMs: Date.now() - consumerStartTime
-    });
   }
 
   /**
@@ -468,11 +550,17 @@ class ServiceRegistryClient extends EventEmitter {
    * Registers the service with the registry.
    * Registry will validate if the service is properly tested and valid.
    * Upon successful validation, the service will be activated and can start heartbeats.
-   * @param {Object} serviceInfo - Service registration information
-   * @param {Array} serviceInfo.endpoints - API endpoints provided by the service
-   * @param {Object} serviceInfo.metadata - Additional service metadata
-   * @param {string} serviceInfo.health - Health check endpoint
-   * @param {number} serviceInfo.timeout - Timeout for registration response (default: 30000ms)
+   * @param {Object} serviceInfo - Service registration information. It accepts EXACTLY the keys
+   *   below (`ACCEPTED_SERVICE_INFO_KEYS`) — any other key is refused by name, and a retired one
+   *   (`RETIRED_SERVICE_INFO_KEYS`) with the reason it went. Nothing is dropped in silence: a key
+   *   this call ignored would leave the caller believing it travelled.
+   * @param {Array} [serviceInfo.endpoints] - API endpoints provided by the service; `[]` for v3 services
+   * @param {Object} [serviceInfo.operations] - The complete `operations` map the registry validates
+   * @param {Object} [serviceInfo.metadata] - `{ version, description }` stored beside the spec
+   * @param {string} [serviceInfo.health] - Legacy health path; liveness travels by heartbeat
+   * @param {boolean} [serviceInfo.workspaceScoped] - Emitted only when the service declares it
+   * @param {number} [serviceInfo.timeout] - How long THIS call waits for the registry verdict
+   *   (default: the constructor's registrationTimeoutMs). It reaches no message.
    * @returns {Promise<{success: boolean, message: string, serviceName: string, version: string,
    *   registrationId: (string|undefined), validated: boolean, certificate: (Object|null),
    *   errorCode: (string|null|undefined)}>} The registry verdict. `errorCode` is the
@@ -492,9 +580,12 @@ class ServiceRegistryClient extends EventEmitter {
       );
     }
 
-    // A retired key is refused BY NAME, before anything is published: dropping it
-    // in silence would leave the caller believing it travelled. The value is never
-    // echoed - two of these keys carried a secret.
+    // ONE membership check over the two tables above, before anything is published.
+    // A key the contract does not name is refused BY NAME: dropping it in silence
+    // would leave the caller believing it travelled. A retired key keeps its own
+    // reason - it is the subset that can still say what replaced it. Neither
+    // refusal echoes the value: two of the retired keys carried a secret, and an
+    // unknown key can carry anything.
     for (const key of Object.keys(serviceInfo)) {
       if (Object.prototype.hasOwnProperty.call(RETIRED_SERVICE_INFO_KEYS, key)) {
         throw new Error(
@@ -503,6 +594,15 @@ class ServiceRegistryClient extends EventEmitter {
           + `Fix: delete "${key}" from the object passed to register().`
         );
       }
+      if (!Object.prototype.hasOwnProperty.call(ACCEPTED_SERVICE_INFO_KEYS, key)) {
+        throw new Error(
+          `[RegistryClient] ${this.serviceName}: serviceInfo key "${key}" is not part of the registration `
+          + `contract - Expected one of: ${Object.keys(ACCEPTED_SERVICE_INFO_KEYS).join(', ')} `
+          + '(api/docs/biz/30-operations/registration-wire.md §2.1). '
+          + `Fix: delete "${key}" from the object passed to register(), or send the value under the key `
+          + 'the contract names for it.'
+        );
+      }
     }
 
     // FAIL-FAST: a client that was never initialized, or that has been closed, is not
@@ -519,9 +619,32 @@ class ServiceRegistryClient extends EventEmitter {
     }
 
     const msgId = uuidv4();
+
+    // FAIL-FAST: one request id, one pending registration. `pendingRegistrations` and
+    // `pendingTimeouts` are keyed by this id, and until d.760b a second call under an id
+    // that was still pending simply set() over both - which dropped the earlier timer's
+    // handle. Nothing could reach it afterwards: the registry's answer clears by id
+    // (_handleRegistryMessage), and close() walks the table, so both found only the newer
+    // handle and the older timer ran to its full 30 s. Cancelling the earlier registration
+    // here instead would be a fallback (§3): its caller is still awaiting an answer that
+    // belongs to it, and this class cannot know which of the two calls is the mistake.
+    if (this.pendingRegistrations && this.pendingRegistrations.has(msgId)) {
+      throw new Error(
+        `[RegistryClient] ${this.serviceName}: Duplicate request id "${msgId}" - a registration with this id `
+        + 'is still pending. Expected: one register() in flight per request id; it is settled by the registry '
+        + `answer, by the ${this.registrationTimeoutMs}ms timeout or by close(). `
+        + 'Fix: await the register() already in flight before starting another one, and - if the ids repeat '
+        + 'because uuid.v4 is stubbed - give each registration its own id.'
+      );
+    }
+
     // @see api/docs/biz/30-operations/registration-wire.md §2 MQ wire format
     const msg = {
       id: msgId,
+      // WHICH REQUEST (`id`, per call) and WHICH COPY (`instance_id`, per process) are
+      // two identities with two lifetimes — d.817, owner `registry-instance-identity` 001.
+      // snake_case is the one spelling the wire has (`workflow-message-aliases` 001).
+      instance_id: this.instanceId,
       type: 'register',
       serviceName: this.serviceName,
       version: this.version,
@@ -530,7 +653,7 @@ class ServiceRegistryClient extends EventEmitter {
       operations: serviceInfo.operations || {},
       metadata: serviceInfo.metadata || {},
       health: serviceInfo.health || '/health',
-      responseQueue: this.serviceRegistryQueue, // Queue for registry to send response
+      responseQueue: this.instanceResponseQueue, // THIS copy's answer queue (conf registry-instance-identity 001 (c))
       timestamp: new Date().toISOString()
     };
 
@@ -572,7 +695,7 @@ class ServiceRegistryClient extends EventEmitter {
           reject(new Error(
             `[RegistryClient] ${this.serviceName}: Registration timed out - no response from the registry `
             + `within ${timeout}ms. Expected: api_services_registry consumes '${this.registryQueue}' and answers `
-            + `on '${this.serviceRegistryQueue}'. Fix: start api_services_registry (docker compose up -d `
+            + `on '${this.instanceResponseQueue}'. Fix: start api_services_registry (docker compose up -d `
             + 'api_services_registry) or raise registrationTimeoutMs.'
           ));
         }
@@ -627,7 +750,7 @@ class ServiceRegistryClient extends EventEmitter {
         serviceName: this.serviceName,
         version: this.version,
         registryQueue: this.registryQueue,
-        responseQueue: this.serviceRegistryQueue,
+        responseQueue: this.instanceResponseQueue,
         requestId: msgId,
         hasValidationProof: !!this.validationProof,
         proofHash: this.validationProof
@@ -701,6 +824,9 @@ class ServiceRegistryClient extends EventEmitter {
       id: uuidv4(),
       type: 'deregister',
       serviceName: this.serviceName,
+      // The reason this key exists at all: the registry deletes only on a match, so a
+      // short-lived foreign copy can no longer deregister the live one (d.817).
+      instance_id: this.instanceId,
       version: this.version,
       timestamp: new Date().toISOString()
     };
@@ -752,6 +878,9 @@ class ServiceRegistryClient extends EventEmitter {
       id: uuidv4(),
       type: 'heartbeat',
       serviceName: this.serviceName,
+      // The beat says which copy is alive, so the registry can keep its availability
+      // episodes per instance instead of per name (d.817, INFRA half).
+      instance_id: this.instanceId,
       version: this.version,
       specificationEndpoint: this.specificationEndpoint,
       timestamp: new Date().toISOString()
@@ -801,6 +930,24 @@ class ServiceRegistryClient extends EventEmitter {
    *   budget is spent. The loop is already stopped when it is called.
    */
   startHeartbeat(options) {
+    // FAIL-FAST: one client, one loop. Checked before the options, because the state
+    // of the receiver is the problem here whatever the arguments say. Until d.760c the
+    // line at the end of this method wrote the new handle over `heartbeatTimer` and the
+    // earlier loop lost the only reference to itself: it re-arms while that field is
+    // not null, and the field now belonged to the newer loop, so `stopHeartbeat()`
+    // cancelled one loop and the other went on beating for a service that had stopped.
+    // Replacing the running loop silently would be a fallback (§3) - the caller that
+    // started it is not asking for it to be discarded, and this class cannot know which
+    // of the two callers is the mistake.
+    if (this.heartbeatTimer) {
+      throw new Error(
+        `[RegistryClient] ${this.serviceName}: A heartbeat loop is already running - starting a second one would `
+        + 'overwrite the timer handle of the first, which would then beat on with nothing able to stop it. '
+        + 'Expected: one heartbeat loop per client; stop it with stopHeartbeat() first. '
+        + 'Fix: call client.stopHeartbeat() before starting a new loop, or keep the loop that is already running.'
+      );
+    }
+
     if (options === null || typeof options !== 'object' || Array.isArray(options)) {
       throw new Error(
         `[RegistryClient] ${this.serviceName}: Missing heartbeat options - startHeartbeat({ maxFailures, onFatal }) `
@@ -886,12 +1033,21 @@ class ServiceRegistryClient extends EventEmitter {
 
   /**
    * Stops periodic heartbeat messages.
+   *
+   * One scheduler, one cancel: `startHeartbeat()` arms the loop with a recursive
+   * `setTimeout` and nothing in this class has created an interval since that
+   * rewrite (d.503), so `clearTimeout` is the whole job. A `clearInterval` on the
+   * same handle stood beside it until d.752, under a comment offering to cancel
+   * "whether it's from setTimeout or setInterval" — a choice the class does not
+   * have, and one that told every reader the loop might be an interval.
+   *
+   * Setting `heartbeatTimer` to null is the second half and not a formality: the
+   * loop reads it before arming the next beat, so a beat already in flight sees
+   * the stop and schedules nothing.
    */
   stopHeartbeat() {
     if (this.heartbeatTimer) {
-      // Clear timeout regardless of whether it's from setTimeout or setInterval
       clearTimeout(this.heartbeatTimer);
-      clearInterval(this.heartbeatTimer);
       this.heartbeatTimer = null;
     }
   }

package/src/registryEventConsumer.js

@@ -10,6 +10,7 @@
 
 const EventEmitter = require('events');
 const { assertLogger } = require('@onlineapps/logger-contract');
+const { queueConfig } = require('@onlineapps/mq-client-core');
 
 // The storage connector arrives by INJECTION. There used to be an implicit
 // default here — `require('@onlineapps/connector-storage')` inside a try/catch
@@ -88,8 +89,19 @@ class RegistryEventConsumer extends EventEmitter {
     // Reusing it would cause 406 PRECONDITION_FAILED when different queue args (TTL/max-length) are applied.
     this.eventsQueueName = `${serviceName}.registry.events`;
 
-    // Exchange name for registry events
-    this.exchangeName = 'registry.changes';
+    // Exchange name for registry events - from the library that declares the whole
+    // registry section of the topology, never spelled here. Until d.809 this was the
+    // one wire name of this package written twice: a rename in `queueConfig` would
+    // have left this consumer subscribed to an exchange nobody publishes to, with
+    // nothing red anywhere (`change-discipline.md` § One rail per concern).
+    //
+    // Only the NAME. The pinned 4.0.1 declares `registry.changes` as
+    // `{ type: 'exchange', durable: true }` with no `exchangeType`; the tree has
+    // `exchangeType: 'fanout'` (d.712) and is unreleased, so reading the type from the
+    // library today would read `undefined` and defaulting it here would be a fallback
+    // (§3). The `'fanout'` in subscribeToChanges() therefore stays a literal until
+    // mq-client-core is released.
+    this.exchangeName = queueConfig.queueName('registry', 'changes');
   }
 
   /**