@onlineapps/conn-orch-registry 1.2.2 → 2.0.0

package/README.md

@@ -6,7 +6,7 @@
 
 > A lightweight client for microservice registration and heartbeat over RabbitMQ.
 > Sends the full service specification (including `operations`) in the `register`
-> message — see [operations-registry-contract.md §2](../../../docs/standards/operations-registry-contract.md).
+> message — see [operations-registry-contract.md §2](../../../docs/biz/30-operations/registration-wire.md).
 
 ## 🚀 Features
 
@@ -120,8 +120,8 @@ See [docs/api.md](https://github.com/onlineapps/conn-orch-registry/blob/main/doc
 
 ## 🔗 Related Documentation
 
-- **[⭐ Complete Two-Tier Validation System](/docs/modules/validator.md)** - Full validation architecture and flow
-- [Registry Module Overview](/docs/modules/registry.md) - High-level registry system architecture
+- **[Two-Tier Validation Architecture](/docs/architecture/validator.md)** - Full validation architecture and flow
+- [Registry Architecture](/docs/architecture/registry.md) - High-level registry system architecture
 - [api_services_registry](/api/api_services_registry/README.md) - Registry service implementation
 
 ## ✅ Testing
@@ -149,6 +149,6 @@ This project is licensed under the MIT License. See [LICENSE](https://github.com
 
 ## 📚 Documentation
 
-- [Complete Connectors Documentation](../../../docs/modules/connector.md)
-- [Testing Standards](../../../docs/modules/connector.md#testing-standards)
+- [Complete Connectors Documentation](/docs/architecture/connector.md)
+- [Testing Standard](/docs/standards/TESTING.md)
 

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/standards/operations-registry-contract.md).
+> [operations-registry-contract.md §2](../../../../docs/biz/30-operations/registration-wire.md).
 
 ## Usage
 
@@ -129,7 +129,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/standards/operations-registry-contract.md))
+- `serviceInfo.operations` - Operations map (see [operations-registry-contract.md §3](../../../../docs/biz/30-operations/registration-wire.md))
 - `serviceInfo.metadata` - Service metadata object
 - `serviceInfo.health` - Health check endpoint
 

package/examples/basicUsage.js

@@ -9,7 +9,7 @@
  * 5. Start heartbeat loop
  * 6. Graceful shutdown on process signals
  *
- * See: api/docs/standards/operations-registry-contract.md §2 MQ wire format
+ * See: api/docs/biz/30-operations/registration-wire.md §2 MQ wire format
  */
 
 function requireEnv(name, description) {
@@ -81,7 +81,7 @@ registryClient.on(EVENTS.ERROR, (err) => {
  * In a real service this is typically loaded from config/service/operations.json
  * plus the endpoint manifest.
  *
- * @see api/docs/standards/operations-registry-contract.md §3 Operation schema
+ * @see api/docs/biz/30-operations/registration-wire.md §3 Operation schema
  */
 async function loadServiceSpec() {
   return {

package/examples/event-consumer-example.js

@@ -34,7 +34,7 @@ async function main() {
 
   // Register ourselves with the registry. The full spec (endpoints +
   // operations) is published as part of the register message — see
-  // api/docs/standards/operations-registry-contract.md §2.
+  // api/docs/biz/30-operations/registration-wire.md §2.
   await client.register({
     endpoints: [{ path: '/hello', method: 'GET' }],
     operations: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-registry",
-  "version": "1.2.2",
+  "version": "2.0.0",
   "license": "MIT",
   "description": "Connector-registry-client 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": [
@@ -27,22 +27,19 @@
     "test:unit": "jest --testPathPattern=unit --coverage",
     "test:component": "jest --testPathPattern=component --coverage",
     "test:integration": "jest --config=jest.integration.config.js",
-    "test:integration:required": "REQUIRE_SERVICES=true jest --config=jest.integration.config.js",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage --coverageReporters=text-lcov html",
     "semantic-release": "semantic-release",
-    "lint": "eslint src test examples --ext .js --cache --cache-location .eslintcache",
+    "lint": "eslint src tests examples --ext .js --cache --cache-location .eslintcache",
     "docs": "jsdoc2md --files src/**/*.js > API.md"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@onlineapps/conn-base-storage": "1.0.9",
-    "@onlineapps/mq-client-core": "1.0.83",
-    "@onlineapps/runtime-config": "1.0.2",
+    "@onlineapps/mq-client-core": "2.0.0",
+    "@onlineapps/runtime-config": "1.0.3",
     "amqplib": "^0.10.9",
-    "ioredis": "^5.8.0",
     "uuid": "^9.0.1"
   },
   "devDependencies": {
@@ -56,6 +53,7 @@
     "eslint-config-prettier": "^10.1.5",
     "eslint-plugin-import": "^2.30.1",
     "eslint-plugin-prettier": "^5.4.0",
+    "ioredis": "^5.8.0",
     "jest": "^29.6.1",
     "semantic-release": "^22.0.12"
   },

package/src/defaults.js

@@ -13,6 +13,21 @@ module.exports = {
 
   specProtocol: 'http',
   specHost: '127.0.0.1',
+
+  /**
+   * How long register() waits for the registry's `registerResponse` /
+   * `register.confirmed` message before it fails.
+   *
+   * Owned here (module default), injectable per client via the
+   * `registrationTimeoutMs` constructor option and per call via
+   * `serviceInfo.timeout`. Never read from the environment inside the client.
+   *
+   * 30 s matches the registry's own validation timeout
+   * (`api/infra/api_services_registry/src/listeners/registry.listener.js` —
+   * `}, 30000); // 30 seconds timeout for Registry`), so a service gives the
+   * registry the full window it needs before declaring the round-trip dead.
+   */
+  registrationTimeoutMs: 30000,
 };
 
 

package/src/events.js

@@ -8,7 +8,7 @@
  * Legacy `apiDescriptionRequest` / `apiDescriptionSent` events were removed —
  * the full service specification travels as part of the `register` message.
  *
- * @see api/docs/standards/operations-registry-contract.md §2 MQ wire format
+ * @see api/docs/biz/30-operations/registration-wire.md §2 MQ wire format
  * @module @onlineapps/connector-registry-client/src/events
  */
 

package/src/registryClient.js

@@ -19,8 +19,8 @@
  *  - 'registerRejected'
  *  - 'error'
  *
- * @see api/docs/standards/operations-registry-contract.md §2 MQ wire format
- * @see api/docs/standards/OPERATIONS.md
+ * @see api/docs/biz/30-operations/registration-wire.md §2 MQ wire format
+ * @see api/docs/biz/30-operations/schema-v3.md
  *
  * @module @onlineapps/connector-registry-client/src/registryClient
  */
@@ -30,7 +30,7 @@ const QueueManager = require('./queueManager');
 const RegistryEventConsumer = require('./registryEventConsumer');
 const { v4: uuidv4 } = require('uuid');
 const queueConfig = require('@onlineapps/mq-client-core/src/config/queueConfig');
-const runtimeCfg = require('./config');
+const DEFAULTS = require('./defaults');
 
 
 class ServiceRegistryClient extends EventEmitter {
@@ -44,14 +44,25 @@ class ServiceRegistryClient extends EventEmitter {
    * @param {string} [opts.apiQueue='api_services_queuer'] - Queue name for heartbeat and API traffic
    * @param {string} [opts.registryQueue='registry.register'] - Queue name for registry messages
    * @param {Object} [opts.validationProof=null] - Validation proof object {hash, data} (injected from outside)
+   * @param {number} [opts.registrationTimeoutMs] - How long register() waits for the registry response
+   *   before rejecting. Default comes from ./defaults.js (30000 ms); never read from the environment here.
    */
   constructor({ amqpUrl, serviceName, version, specificationEndpoint = '/api/v1/specification',
                 heartbeatInterval = 10000, apiQueue = 'api_services_queuer', registryQueue = 'registry.register',
-                registryUrl = null, redis = null, storageConfig = {}, validationProof = null }) {
+                registryUrl = null, redis = null, storageConfig = {}, validationProof = null,
+                registrationTimeoutMs = DEFAULTS.registrationTimeoutMs }) {
     super();
     if (!amqpUrl || !serviceName || !version) {
       throw new Error('amqpUrl, serviceName, and version are required');
     }
+    if (typeof registrationTimeoutMs !== 'number' || !Number.isFinite(registrationTimeoutMs) || registrationTimeoutMs <= 0) {
+      throw new Error(
+        `[RegistryClient] ${serviceName}: Invalid registrationTimeoutMs - expected a positive number of milliseconds, `
+        + `got ${JSON.stringify(registrationTimeoutMs)}. Fix: pass a positive registrationTimeoutMs `
+        + `(module default ${DEFAULTS.registrationTimeoutMs}).`
+      );
+    }
+    this.registrationTimeoutMs = registrationTimeoutMs;
     this.serviceName = serviceName;
     this.version = version;
     // Spec endpoint is still configurable, but defaults are module-owned and can be overridden via runtime config.
@@ -385,8 +396,21 @@ class ServiceRegistryClient extends EventEmitter {
       throw new Error('endpoints must be an array');
     }
 
+    // FAIL-FAST: a client that was never initialized, or that has been closed, is not
+    // usable. It used to silently call queueManager.init() here, which re-opened a
+    // channel WITHOUT restarting the response consumer started by init() - so the
+    // registry answered into a queue nobody was reading and register() waited out the
+    // full timeout. No fallbacks (architecture-principles §3), fail fast (§4).
+    if (!this.queueManager.channel) {
+      throw new Error(
+        `[RegistryClient] ${this.serviceName}: Cannot register - the MQ channel is not open `
+        + '(client not initialized or already closed). Expected: init() completed before register(). '
+        + 'Fix: call init() on a fresh ServiceRegistryClient; a closed client is not reusable.'
+      );
+    }
+
     const msgId = uuidv4();
-    // @see api/docs/standards/operations-registry-contract.md §2 MQ wire format
+    // @see api/docs/biz/30-operations/registration-wire.md §2 MQ wire format
     const msg = {
       id: msgId,
       type: 'register',
@@ -422,8 +446,9 @@ class ServiceRegistryClient extends EventEmitter {
       console.log(`[RegistryClient] ${this.serviceName}: ⚠️  NO validation proof available - Registry will perform Tier 2 validation`);
     }
 
-    // Create promise to wait for registration response
-    const timeout = serviceInfo.timeout || 30000; // 30 seconds default
+    // Create promise to wait for registration response.
+    // Timeout is injected (constructor) or overridden per call - never read from env here.
+    const timeout = serviceInfo.timeout || this.registrationTimeoutMs;
     const responsePromise = new Promise((resolve, reject) => {
       // Store resolver for this registration request
       this.pendingRegistrations = this.pendingRegistrations || new Map();
@@ -434,7 +459,12 @@ class ServiceRegistryClient extends EventEmitter {
         if (this.pendingRegistrations.has(msgId)) {
           this.pendingRegistrations.delete(msgId);
           this.pendingTimeouts.delete(msgId);
-          reject(new Error(`Registration timeout after ${timeout}ms - no response from registry`));
+          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 `
+            + 'api_services_registry) or raise registrationTimeoutMs.'
+          ));
         }
       }, timeout);
 
@@ -442,10 +472,10 @@ class ServiceRegistryClient extends EventEmitter {
       this.pendingTimeouts.set(msgId, timeoutId);
     });
 
-    // Initialize queueManager if not already initialized
-    if (!this.queueManager.channel) {
-      await this.queueManager.init();
-    }
+    // The publish path below can throw before anyone awaits responsePromise. This no-op
+    // handler marks the promise as handled so an abort never surfaces as an unhandled
+    // rejection; the real result is still awaited at the end of this method.
+    responsePromise.catch(() => {});
 
     // Send registration message to registry
     // CRITICAL: Use queueConfig.js to get correct parameters (TTL, max-length, etc.)
@@ -457,20 +487,21 @@ class ServiceRegistryClient extends EventEmitter {
     } catch (queueError) {
       const errorMsg = `[RegistryClient] ${this.serviceName}: Cannot register - infrastructure queue verification failed: ${queueError.message}`;
       console.error(errorMsg);
-      throw new Error(errorMsg);
+      throw this._abortPendingRegistration(msgId, new Error(errorMsg));
     }
 
     console.log(`[RegistryClient] ${this.serviceName}: Sending registration message to queue: ${this.registryQueue}`);
     console.log(`[RegistryClient] ${this.serviceName}: Message type: ${msg.type}, serviceName: ${msg.serviceName}, version: ${msg.version}`);
-    
-    // Send message synchronously (sendToQueue is synchronous, returns boolean)
-    // But check channel state first to fail fast
-    if (!this.queueManager.channel) {
-      throw new Error(`[RegistryClient] ${this.serviceName}: Cannot publish - channel not initialized. Ensure MQ connection is established.`);
-    }
-    
-    if (this.queueManager.channel.closed) {
-      throw new Error(`[RegistryClient] ${this.serviceName}: Cannot publish - channel is closed. MQ connection may be lost.`);
+
+    // Send message synchronously (sendToQueue is synchronous, returns boolean).
+    // The channel existed when register() started; it can still have been closed while
+    // the infrastructure-queue check awaited above.
+    if (!this.queueManager.channel || this.queueManager.channel.closed) {
+      throw this._abortPendingRegistration(msgId, new Error(
+        `[RegistryClient] ${this.serviceName}: Cannot publish - the MQ channel closed before the registration `
+        + 'message was sent. Expected: an open channel for the whole register() call. '
+        + 'Fix: re-create the client (init() + register()) once the MQ connection is back.'
+      ));
     }
 
     try {
@@ -486,31 +517,49 @@ class ServiceRegistryClient extends EventEmitter {
     } catch (sendError) {
       const errorMsg = `[RegistryClient] ${this.serviceName}: Failed to send registration message: ${sendError.message}`;
       console.error(errorMsg);
-      throw new Error(errorMsg);
+      throw this._abortPendingRegistration(msgId, new Error(errorMsg));
     }
 
     this.emit('registerSent', msg);
 
-    // Wait for registration response from registry
-    try {
-      console.log(`[RegistryClient] ${this.serviceName}: [AWAIT] Waiting for registration response promise...`);
-      const response = await responsePromise;
-      console.log(`[RegistryClient] ${this.serviceName}: [AWAIT] ✓ Promise resolved, response received:`, {
-        hasResponse: !!response,
-        responseType: typeof response,
-        responseKeys: response ? Object.keys(response) : [],
-        hasSuccess: !!response?.success,
-        hasCertificate: !!response?.certificate
-      });
-      return response;
-    } catch (error) {
-      return {
-        success: false,
-        message: error.message,
-        serviceName: this.serviceName,
-        version: this.version
-      };
+    // Wait for registration response from registry.
+    // A timeout or an abort REJECTS - it is not downgraded to `{ success: false }`,
+    // which is what a legitimate registry rejection looks like (e.g. missing
+    // validation proof). The caller must be able to tell "the registry said no"
+    // from "the registry never answered" (architecture-principles §3, §4).
+    console.log(`[RegistryClient] ${this.serviceName}: [AWAIT] Waiting for registration response promise...`);
+    const response = await responsePromise;
+    console.log(`[RegistryClient] ${this.serviceName}: [AWAIT] ✓ Promise resolved, response received:`, {
+      hasResponse: !!response,
+      responseType: typeof response,
+      responseKeys: response ? Object.keys(response) : [],
+      hasSuccess: !!response?.success,
+      hasCertificate: !!response?.certificate
+    });
+    return response;
+  }
+
+  /**
+   * Cancels one in-flight registration: clears its timeout, drops it from the pending
+   * maps and rejects its promise with `error`.
+   * @param {string} msgId - Registration request id
+   * @param {Error} error - Error the pending promise is rejected with
+   * @returns {Error} the same error, so callers can `throw this._abortPendingRegistration(...)`
+   * @private
+   */
+  _abortPendingRegistration(msgId, error) {
+    const pending = this.pendingRegistrations && this.pendingRegistrations.get(msgId);
+    if (this.pendingTimeouts && this.pendingTimeouts.has(msgId)) {
+      clearTimeout(this.pendingTimeouts.get(msgId));
+      this.pendingTimeouts.delete(msgId);
+    }
+    if (this.pendingRegistrations) {
+      this.pendingRegistrations.delete(msgId);
     }
+    if (pending) {
+      pending.reject(error);
+    }
+    return error;
   }
 
   /**
@@ -737,17 +786,20 @@ class ServiceRegistryClient extends EventEmitter {
    * @returns {Promise<void>}
    */
   async close() {
-    // Clear all pending registration timeouts
-    if (this.pendingTimeouts) {
-      for (const timeoutId of this.pendingTimeouts.values()) {
-        clearTimeout(timeoutId);
+    // Abort every in-flight registration. Clearing the maps without rejecting (the
+    // behaviour until 2026-08-27) cleared the timeout too, so the register() promise
+    // never settled and its caller waited forever.
+    if (this.pendingRegistrations) {
+      for (const msgId of Array.from(this.pendingRegistrations.keys())) {
+        this._abortPendingRegistration(msgId, new Error(
+          `[RegistryClient] ${this.serviceName}: Registration aborted - the client was closed while waiting `
+          + 'for the registry response. Expected: register() settles before close(). '
+          + 'Fix: await register() before close(), or init() and register() again on a new client.'
+        ));
       }
-      this.pendingTimeouts.clear();
     }
-
-    // Clear pending registrations (don't reject - client is closing)
-    if (this.pendingRegistrations) {
-      this.pendingRegistrations.clear();
+    if (this.pendingTimeouts) {
+      this.pendingTimeouts.clear();
     }
 
     this.stopHeartbeat();

package/src/registryEventConsumer.js

@@ -10,14 +10,14 @@
 
 const EventEmitter = require('events');
 
-// Default StorageConnector - can be overridden for testing
-let DefaultStorageConnector;
-try {
-  DefaultStorageConnector = require('@onlineapps/connector-storage');
-} catch (e) {
-  // StorageConnector not available, must be injected
-  DefaultStorageConnector = null;
-}
+// The storage connector arrives by INJECTION. There used to be an implicit
+// default here — `require('@onlineapps/connector-storage')` inside a try/catch
+// that turned the miss into `null`. Three defects in five lines: the package
+// does not exist and nothing declared it (§20), the catch is a silent fallback
+// (architecture-principles.md §3), and the consequence surfaced layers away
+// from the cause, as "Storage connector not available for downloading specs" at
+// download time. The constructor now fail-fasts at the moment the caller asks
+// for storage without supplying one.
 
 class RegistryEventConsumer extends EventEmitter {
   /**
@@ -37,12 +37,12 @@ class RegistryEventConsumer extends EventEmitter {
     this.serviceName = serviceName;
     this.redis = redis;
 
-    // Use injected StorageConnector or default one
-    this.StorageConnectorClass = StorageConnector || DefaultStorageConnector;
+    this.StorageConnectorClass = StorageConnector;
 
-    // Initialize storage connector for MinIO access ONLY when config is explicitly provided.
-    // Service discovery (active/inactive status) does NOT require storage.
-    // Without explicit storageConfig, we run in "index-only" mode (spec downloading disabled).
+    // Storage is initialised for MinIO access ONLY when config is explicitly
+    // provided. Service discovery (active/inactive status) does NOT require
+    // storage, so without a complete storageConfig this runs in "index-only"
+    // mode and spec downloading is off.
     const hasStorageConfig =
       storageConfig &&
       typeof storageConfig === 'object' &&
@@ -51,7 +51,17 @@ class RegistryEventConsumer extends EventEmitter {
       storageConfig.accessKey &&
       storageConfig.secretKey;
 
-    this.storage = (this.StorageConnectorClass && hasStorageConfig)
+    if (hasStorageConfig && !this.StorageConnectorClass) {
+      throw new Error(
+        '[RegistryEventConsumer] storageConfig was given without a StorageConnector - '
+        + 'Expected: the connector class injected as options.StorageConnector, because this package '
+        + 'declares no storage implementation of its own. '
+        + 'Fix: pass StorageConnector (e.g. require("@onlineapps/conn-base-storage")), or drop '
+        + 'storageConfig to run in index-only mode.'
+      );
+    }
+
+    this.storage = hasStorageConfig
       ? new this.StorageConnectorClass({
         ...storageConfig,
         cacheEnabled,
@@ -317,9 +327,16 @@ class RegistryEventConsumer extends EventEmitter {
       return this.specCache.get(fingerprint);
     }
 
-    // Check if storage is available
+    // Index-only mode is a legitimate construction, so this is not a bug — but
+    // the caller asked for something this consumer was never built to do, and
+    // has to learn which of the two to change (architecture-principles.md §5).
     if (!this.storage) {
-      throw new Error('Storage connector not available for downloading specs');
+      throw new Error(
+        '[RegistryEventConsumer] Spec download requested in index-only mode - '
+        + 'Expected: a storage connector, which this consumer was constructed without. '
+        + 'Fix: construct it with storageConfig and StorageConnector, or read the service '
+        + 'index only (isServiceActive, getActiveServices, getServiceInfo).'
+      );
     }
 
     // Download from MinIO with verification