@onlineapps/conn-orch-registry 6.0.3 → 8.0.0

package/README.md

@@ -25,11 +25,11 @@ Duty sections that apply:
 
 > 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/biz/30-operations/registration-wire.md).
+> message — see [registration-wire.md §2](../../../docs/biz/30-operations/registration-wire.md).
 
 ## 🚀 Features
 
-* Automatic queue management (`workflow`, `<serviceName>.registry`, `api_services_queuer`, `registry.register`)
+* Automatic queue management (`workflow`, `<serviceName>.registry`, `<serviceName>.registry.<instanceId>`, `api_services_queuer`, `registry.register`)
 * Periodic heartbeat messages with metadata
 * Full specification (endpoints + operations) published inside `register`
 * Event-driven API using `EventEmitter`
@@ -56,22 +56,28 @@ yarn add @onlineapps/conn-orch-registry
 // NOTE: Do NOT call dotenv.config() in libraries. Export environment variables explicitly.
 
 const { ServiceRegistryClient, EVENTS } = require('@onlineapps/conn-orch-registry');
+// requireEnv(name, description), requirePositiveIntegerEnv(name, description) — see examples/env.js
 
 const client = new ServiceRegistryClient({
-  amqpUrl: process.env.AMQP_URL,
+  amqpUrl: requireEnv('RABBITMQ_URL', 'RabbitMQ URL, amqp://user:pass@host:port'),
   serviceName: 'invoicing',
   version: '1.0.0',
   specificationEndpoint: '/api/v1/specification', // required — see § Configuration
-  heartbeatInterval: 30000,                        // required — see § Configuration
+  heartbeatInterval: requirePositiveIntegerEnv('BIZ_HEARTBEAT_INTERVAL_MS', 'milliseconds between heartbeats'), // required; see § Configuration
+  instanceId: requireEnv('SERVICE_INSTANCE_ID', 'id of THIS running copy, one value per process'), // required; see § Configuration
+  discoveryTimeoutMs: requirePositiveIntegerEnv('REGISTRY_DISCOVERY_TIMEOUT_MS', 'deadline in ms of one getService() read'), // required; see § Configuration
+  redis,                                           // node-redis client getService() reads the projection with
   logger // required — see § Logger contract below
 });
 
 await client.init();
 
 // Publish full service spec in the register message (single round-trip).
+// Only the keys of the registration contract are accepted — endpoints, operations,
+// metadata, health, workspaceScoped, timeout; any other key is refused by name.
 await client.register({
   endpoints: [/* ... */],
-  operations: await loadOperationsJson(), // see operations-registry-contract.md §3
+  operations: await loadOperationsJson(), // see registration-wire.md §3
   metadata: { /* ... */ },
   health: '/health'
 });
@@ -95,7 +101,7 @@ process.on('SIGINT', async () => {
 
 ## 📄 Configuration
 
-Configuration can be provided via environment variables or constructor options:
+Configuration is passed as constructor options; the client reads no environment variable:
 
 | Option                  | Description                                   | Default              |
 | ----------------------- | --------------------------------------------- | -------------------- |
@@ -104,6 +110,8 @@ Configuration can be provided via environment variables or constructor options:
 | `version`               | Service version in SemVer format (required)   | —                    |
 | `specificationEndpoint` | Path the `register`/`heartbeat` messages carry (**required**) | —    |
 | `heartbeatInterval`     | Milliseconds between heartbeats (**required**) | —                   |
+| `instanceId`            | Non-empty string naming THIS running copy, one value per process (**required**) | — |
+| `discoveryTimeoutMs`    | Deadline (ms) of one `getService()` read of the registry projection (**required**) | — |
 | `apiQueue`              | Queue name for heartbeat/API messages         | `api_services_queuer` |
 | `registryQueue`         | Queue name for registry requests              | `registry.register`  |
 
@@ -115,13 +123,32 @@ whenever the caller forgets the first (architecture-principles §3):
   ([registration-wire.md](/api/docs/biz/30-operations/registration-wire.md) §2.1) and the
   registry stores what it is sent, so a substituted path lands in `registry:services` for
   a service that never declared it;
-* the heartbeat cadence has ONE owner — `wrapper.registry.heartbeatInterval`, fed from
-  `BIZ_HEARTBEAT_INTERVAL_MS` (owner confirmation
+* the heartbeat cadence has ONE owner — the environment key `BIZ_HEARTBEAT_INTERVAL_MS`,
+  which `ServiceWrapper` reads and passes to this client; the config key
+  `wrapper.registry.heartbeatInterval` is retired and refused (owner confirmation
   [`biz-health-freshness.md`](/api/docs/governance/confirmations/biz-health-freshness.md)
   001 point 3) — and the freshness window the monitoring side computes is a multiple of it.
 
 Both are refused at construction, by value, naming the fix.
 
+**`discoveryTimeoutMs` carries no default** (d.1093). Without a deadline `getService()`
+waited for as long as Redis was down or half-open, and the workflow step waiting on it hung
+until the broker expired its message. The value belongs to the platform env, which
+`ServiceWrapper` reads and passes here. A lookup that does not end in time is refused with
+`code: 'REGISTRY_DISCOVERY_TIMEOUT'`, and a client that already knows Redis is gone
+(`isReady === false`) with `code: 'REGISTRY_DISCOVERY_UNAVAILABLE'` — both `type: 'TRANSIENT'`,
+so the step is retried. The deadline is a race beside the command, not node-redis'
+`AbortSignal`: aborting a command node-redis 4.7.1 has already sent corrupts its command
+queue (see the CHANGELOG entry of d.1093).
+
+**`instanceId` carries no default either** (d.817, owner confirmation
+`registry-instance-identity` 001). The service name says which service, the instance id
+says which copy; `register`, `heartbeat` and `deregister` carry it as `instance_id`, and
+the registry deletes a registration only when it matches. The client never makes one:
+`@onlineapps/service-wrapper` makes it once at boot (`SERVICE_INSTANCE_ID` when the
+deployment gives one, otherwise a UUID v4) and hands the same value to monitoring as
+`serviceInstanceId`.
+
 `amqpUrl` carries the broker credential, so no error message and no log line of this
 package renders it as given: the URL passes through `redactUrl` from
 `@onlineapps/logger-contract`, which drops the userinfo (`user:password@`) and keeps
@@ -132,8 +159,11 @@ implementace přestěhovala do core vrstvy; one concern, one rail.)
 
 ## 📬 Delivery of registry messages
 
-Both consumers in this package — the service's own `<service>.registry` response queue
-and the `<service>.registry.events` fanout copy — run on the delivery contract of
+The consumers in this package — the shared `<service>.registry` (the registry's own
+prompts, such as `revalidate`, heard by every copy), the answer queue of THIS copy
+`<service>.registry.<instanceId>` (named as `responseQueue` in `register`, so a copy
+never reads the answer meant for another — owner confirmation `registry-instance-identity`
+001 (c), d.817c) and the `<service>.registry.events` fanout copy — run on the delivery contract of
 [`@onlineapps/mq-client-core`](https://www.npmjs.com/package/@onlineapps/mq-client-core)
 (§ `consume()` — the delivery contract), registered with `requeueOnError: false`.
 
@@ -191,15 +221,25 @@ demands is a logger that component writes to). Standard:
 ### Register Request
 ```javascript
 {
+  id: "request-uuid",            // which request
+  instance_id: "copy-id",        // which running copy (the constructor's instanceId)
   type: "register",
   serviceName: "hello-service",
   version: "1.0.0",
-  token: "pre-validation-token",
+  specificationEndpoint: "/api/v1/specification",
   endpoints: [...],
+  operations: { ... },
+  metadata: { ... },
+  health: "/health",
+  responseQueue: "hello-service.registry.copy-id",   // THIS copy's answer queue (d.817c)
   timestamp: "ISO-8601"
+  // + workspaceScoped when the service declares it,
+  // + validationProof / validationData when a proof was injected
 }
 ```
 
+The wire format has one owner: `api/docs/biz/30-operations/registration-wire.md` §2.
+
 ### Register Confirmed
 ```javascript
 {
@@ -225,9 +265,12 @@ fixes it: `api/docs/biz/30-operations/registration-wire.md` §8.
 ### Heartbeat
 ```javascript
 {
+  id: "message-uuid",
   type: "heartbeat",
   serviceName: "hello-service",
-  status: "UP",
+  instance_id: "copy-id",
+  version: "1.0.0",
+  specificationEndpoint: "/api/v1/specification",
   timestamp: "ISO-8601"
 }
 ```

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/examples/basicUsage.js

@@ -1,58 +1,43 @@
 /**
  * basicUsage.js
  *
- * Example demonstrating full lifecycle of ServiceRegistryClient:
- * 1. Load environment variables
- * 2. Instantiate client
- * 3. Initialize (setup queues and start listening for responses)
- * 4. Register with the full service specification (endpoints + operations)
- * 5. Start heartbeat loop
- * 6. Graceful shutdown on process signals
+ * The lifecycle of ServiceRegistryClient:
+ * 1. read the settings from the environment (examples/env.js)
+ * 2. construct the client with every required option
+ * 3. init() — the response queues and their consumers
+ * 4. register() the service specification and branch on the registry's verdict
+ * 5. startHeartbeat() with its failure budget
+ * 6. on SIGINT/SIGTERM: deregister() this copy, then close()
  *
- * See: api/docs/biz/30-operations/registration-wire.md §2 MQ wire format
+ * Environment: RABBITMQ_URL, SERVICE_NAME, SERVICE_VERSION, SPECIFICATION_ENDPOINT,
+ * SERVICE_INSTANCE_ID, BIZ_HEARTBEAT_INTERVAL_MS, REGISTRY_DISCOVERY_TIMEOUT_MS.
+ *
+ * @see README.md § Configuration
+ * @see api/docs/biz/30-operations/registration-wire.md §2 MQ wire format
  */
 
-function requireEnv(name, description) {
-  const value = process.env[name];
-  if (!value || String(value).trim() === '') {
-    throw new Error(`[conn-orch-registry][example] Missing environment variable - ${name} is required. ${description || ''}`);
-  }
-  return String(value).trim();
-}
-
 // Requiring the package by its own name does not resolve from inside the package
-// (no self-reference `exports` field), so the example loads the sources directly —
-// same as examples/event-consumer-example.js. Consumers require
-// '@onlineapps/conn-orch-registry'; see README § Quick Start.
+// (no self-reference `exports` field), so the example loads the sources directly.
+// Consumers require '@onlineapps/conn-orch-registry'; see README § Quick Start.
 const { ServiceRegistryClient, EVENTS } = require('../src/index');
+const { requireEnv, requirePositiveIntegerEnv } = require('./env');
 
-// The logger is a hard requirement of every constructor in this package
-// (README § Logger contract). An example script has no service logger, so it passes
-// `console` explicitly — it implements info/warn/error/debug, and choosing it here is
-// the caller's decision, not a fallback inside the library.
+// The logger is required by every constructor in this package (README § Logger
+// contract). An example script has no service logger, so it passes `console`
+// explicitly — it implements info/warn/error/debug.
 const registryClient = new ServiceRegistryClient({
   logger: console,
-  amqpUrl: requireEnv('AMQP_URL', 'RabbitMQ URL (IPv4-only recommended: amqp://user:pass@127.0.0.1:PORT)'),
-  serviceName: requireEnv('SERVICE_NAME', 'Service logical name'),
-  version: requireEnv('SERVICE_VERSION', 'Service version (SemVer)'),
-  // Both REQUIRED since d.278c — the client substitutes neither, so the example
-  // demands them the same way it demands the URL and the service name.
-  specificationEndpoint: requireEnv('SPECIFICATION_ENDPOINT', 'Path the register message carries (e.g. /api/v1/specification)'),
-  heartbeatInterval: parseInt(requireEnv('HEARTBEAT_INTERVAL', 'Milliseconds between heartbeats'), 10),
-  apiQueue: process.env.API_QUEUE,
-  registryQueue: process.env.REGISTRY_QUEUE
+  amqpUrl: requireEnv('RABBITMQ_URL', 'RabbitMQ URL, amqp://user:pass@host:port'),
+  serviceName: requireEnv('SERVICE_NAME', 'service logical name'),
+  version: requireEnv('SERVICE_VERSION', 'service version, SemVer'),
+  specificationEndpoint: requireEnv('SPECIFICATION_ENDPOINT', 'path the register and heartbeat messages carry, e.g. /api/v1/specification'),
+  instanceId: requireEnv('SERVICE_INSTANCE_ID', 'id of THIS running copy, one value per process'),
+  heartbeatInterval: requirePositiveIntegerEnv('BIZ_HEARTBEAT_INTERVAL_MS', 'milliseconds between heartbeats'),
+  discoveryTimeoutMs: requirePositiveIntegerEnv('REGISTRY_DISCOVERY_TIMEOUT_MS', 'deadline in ms of one getService() read')
 });
 
 registryClient.on(EVENTS.HEARTBEAT_SENT, (msg) => {
-  console.log(`[Heartbeat] Sent at ${msg.timestamp} for ${msg.serviceName}@${msg.version}`);
-});
-
-registryClient.on(EVENTS.REGISTER_CONFIRMED, (msg) => {
-  console.log(`[Register] Confirmed for ${msg.serviceName || registryClient.serviceName}`);
-});
-
-registryClient.on(EVENTS.REGISTER_REJECTED, (msg) => {
-  console.error('[Register] Rejected', msg);
+  console.log(`[Heartbeat] Sent at ${msg.timestamp} for ${msg.serviceName}@${msg.version} (${msg.instance_id})`);
 });
 
 registryClient.on(EVENTS.REVALIDATE, (payload) => {
@@ -68,8 +53,15 @@ registryClient.on(EVENTS.ERROR, (err) => {
     await registryClient.init();
     console.log('RegistryClient initialized: queues are ready.');
 
-    await registryClient.register(await loadServiceSpec());
-    console.log('Register message published.');
+    // register() resolves with the registry's verdict; `errorCode` is the machine
+    // reason of a refusal (registration-wire.md §8).
+    const verdict = await registryClient.register(serviceSpecification(registryClient.version));
+    if (verdict.success !== true) {
+      console.error(`[Register] Refused: ${verdict.errorCode} - ${verdict.message}`);
+      await registryClient.close();
+      process.exit(1);
+    }
+    console.log(`[Register] Confirmed for ${verdict.serviceName}@${verdict.version}`);
 
     registryClient.startHeartbeat({
       maxFailures: 5,
@@ -82,53 +74,55 @@ registryClient.on(EVENTS.ERROR, (err) => {
 
     const shutdown = async () => {
       console.log('Shutting down RegistryClient...');
+      // deregister() stops the heartbeat first; the registry deletes only the
+      // registration whose instance_id matches this copy.
+      await registryClient.deregister();
       await registryClient.close();
       process.exit(0);
     };
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
   } catch (err) {
-    console.error('Failed to initialize RegistryClient', err);
+    console.error('Failed to run RegistryClient', err);
     process.exit(1);
   }
 })();
 
 /**
- * Helper: assemble the service specification published in the register message.
- * In a real service this is typically loaded from config/service/operations.json
- * plus the endpoint manifest.
+ * The service specification the register message carries. A real service sends the
+ * `operations` map of its config/service/operations.json; every operation is a v3
+ * declaration.
  *
- * @see api/docs/biz/30-operations/registration-wire.md §3 Operation schema
+ * @param {string} version - the service version the metadata repeats
+ * @see api/docs/biz/30-operations/schema-v3.md § Per-operation keys
+ * @see api/docs/biz/30-operations/registration-wire.md §2.1
  */
-async function loadServiceSpec() {
+function serviceSpecification(version) {
   return {
-    endpoints: [
-      { path: '/invoices', method: 'POST' },
-      { path: '/invoices/:id', method: 'GET' }
-    ],
+    endpoints: [],
     operations: {
       'create-invoice': {
         description: 'Create a new invoice',
-        endpoint: '/invoices',
-        method: 'POST',
+        handler: 'handlers/invoices#createInvoice',
+        bundle_scope: 'workspace',
         mutates: true,
         resource_type: 'invoice',
         minRole: 'EDITOR',
-        input: {},
-        output: {}
+        input: { type: 'object' },
+        output: { type: 'object' }
       },
       'get-invoice': {
-        description: 'Retrieve invoice by ID',
-        endpoint: '/invoices/:id',
-        method: 'GET',
+        description: 'Retrieve an invoice by id',
+        handler: 'handlers/invoices#getInvoice',
+        bundle_scope: 'workspace',
         mutates: false,
-        resource_type: null,
+        resource_type: 'invoice',
         minRole: 'VIEWER',
-        input: {},
-        output: {}
+        input: { type: 'object' },
+        output: { type: 'object' }
       }
     },
-    metadata: {},
+    metadata: { version, description: 'Invoice example' },
     health: '/health'
   };
 }

package/examples/env.js

@@ -0,0 +1,59 @@
+'use strict';
+
+/**
+ * env.js — how the examples read their settings: by key name, and a key that is
+ * missing or malformed stops the example naming the key and the fix. No default
+ * stands in for an unset key (architecture-principles.md §3, §5).
+ *
+ * The key names are the platform's own (`config/env-templates/shared.env`), so an
+ * example runs with the same environment a biz service gets.
+ */
+
+/**
+ * @param {string} name - environment key
+ * @param {string} description - what the value is, for the error message
+ * @returns {string} the trimmed value
+ * @throws {Error} when the key is unset or blank
+ */
+function requireEnv(name, description) {
+  const value = process.env[name];
+  if (value === undefined) {
+    throw new Error(
+      `[conn-orch-registry][example] Missing environment variable - ${name} is required (${description}). `
+      + `Fix: export ${name} before running the example.`
+    );
+  }
+  if (value.trim() === '') {
+    throw new Error(
+      `[conn-orch-registry][example] Empty environment variable - ${name} is set but blank (${description}). `
+      + `Fix: export ${name} with a value.`
+    );
+  }
+  return value.trim();
+}
+
+/**
+ * @param {string} name - environment key
+ * @param {string} description - what the value is, for the error message
+ * @returns {number} a positive whole number
+ * @throws {Error} when the key is unset, blank, not a whole number or not positive
+ */
+function requirePositiveIntegerEnv(name, description) {
+  const raw = requireEnv(name, description);
+  const value = Number(raw);
+  if (!Number.isInteger(value)) {
+    throw new Error(
+      `[conn-orch-registry][example] Invalid environment variable - ${name} is ${JSON.stringify(raw)}. `
+      + `Expected: a positive whole number (${description}). Fix: export ${name} as a whole number.`
+    );
+  }
+  if (value <= 0) {
+    throw new Error(
+      `[conn-orch-registry][example] Invalid environment variable - ${name} is ${value}. `
+      + `Expected: a positive whole number (${description}). Fix: export ${name} above zero.`
+    );
+  }
+  return value;
+}
+
+module.exports = { requireEnv, requirePositiveIntegerEnv };

package/examples/event-consumer-example.js

@@ -1,81 +1,85 @@
 /**
- * Example: Using ServiceRegistryClient with event consumption
+ * event-consumer-example.js
  *
- * Demonstrates opt-in subscription to registry change events. The events are an
- * invalidation hint ("something changed"), not a read path: to read another
- * service's spec, use createRegistryReader from @onlineapps/service-common.
+ * What this example shows: a client that registers, beats, and opts in to the
+ * registry change events through subscribeToChanges(), with listeners for them.
  *
- * @see api/docs/biz/30-operations/registration-wire.md §5, §7
+ * The consumer runs in index-only mode: no storageConfig, because
+ * subscribeToChanges() (src/registryClient.js) builds it without a StorageConnector
+ * and the RegistryEventConsumer constructor refuses a complete storageConfig
+ * without one. Redis persists the local service index.
+ *
+ * Environment: RABBITMQ_URL, REDIS_URL, SERVICE_NAME, SERVICE_VERSION,
+ * SPECIFICATION_ENDPOINT, SERVICE_INSTANCE_ID, BIZ_HEARTBEAT_INTERVAL_MS,
+ * REGISTRY_DISCOVERY_TIMEOUT_MS.
+ *
+ * @see README.md § Configuration
+ * @see api/docs/biz/30-operations/registration-wire.md §7
  */
 
+const { createClient } = require('redis');
 const { ServiceRegistryClient } = require('../src/index');
-const Redis = require('ioredis');
+const { requireEnv, requirePositiveIntegerEnv } = require('./env');
 
 async function main() {
-  // Optional Redis for index persistence
-  const redis = new Redis({
-    host: process.env.REDIS_HOST || 'localhost',
-    port: process.env.REDIS_PORT || 6379
+  // node-redis, the client getService() reads the registry projection with.
+  const redis = createClient({
+    url: requireEnv('REDIS_URL', 'Redis URL, redis://:password@host:port'),
+    disableOfflineQueue: true
   });
+  await redis.connect();
 
-  // Initialize client with storage configuration
-  // The logger is a hard requirement of every constructor in this package
-  // (README § Logger contract). An example script has no service logger, so it passes
-  // `console` explicitly — it implements info/warn/error/debug, and choosing it here is
-  // the caller's decision, not a fallback inside the library.
+  // The logger is required by every constructor in this package (README § Logger
+  // contract). An example script has no service logger, so it passes `console`
+  // explicitly — it implements info/warn/error/debug.
   const client = new ServiceRegistryClient({
     logger: console,
-    amqpUrl: process.env.AMQP_URL || 'amqp://localhost',
-    serviceName: 'example-service',
-    version: '1.0.0',
-    redis: redis,
-    storageConfig: {
-      endPoint: process.env.MINIO_ENDPOINT || 'localhost',
-      port: parseInt(process.env.MINIO_PORT || 9000),
-      useSSL: process.env.MINIO_USE_SSL === 'true',
-      accessKey: process.env.MINIO_ACCESS_KEY || 'minioadmin',
-      secretKey: process.env.MINIO_SECRET_KEY || 'minioadmin'
-    }
+    amqpUrl: requireEnv('RABBITMQ_URL', 'RabbitMQ URL, amqp://user:pass@host:port'),
+    serviceName: requireEnv('SERVICE_NAME', 'service logical name'),
+    version: requireEnv('SERVICE_VERSION', 'service version, SemVer'),
+    specificationEndpoint: requireEnv('SPECIFICATION_ENDPOINT', 'path the register and heartbeat messages carry, e.g. /api/v1/specification'),
+    instanceId: requireEnv('SERVICE_INSTANCE_ID', 'id of THIS running copy, one value per process'),
+    heartbeatInterval: requirePositiveIntegerEnv('BIZ_HEARTBEAT_INTERVAL_MS', 'milliseconds between heartbeats'),
+    discoveryTimeoutMs: requirePositiveIntegerEnv('REGISTRY_DISCOVERY_TIMEOUT_MS', 'deadline in ms of one getService() read'),
+    redis
   });
 
-  // Initialize connection
   await client.init();
 
-  // Register ourselves with the registry. The full spec (endpoints +
-  // operations) is published as part of the register message — see
-  // api/docs/biz/30-operations/registration-wire.md §2.
-  await client.register({
-    endpoints: [{ path: '/hello', method: 'GET' }],
+  // register() resolves with the registry's verdict (registration-wire.md §2.4, §8).
+  const verdict = await client.register({
+    endpoints: [],
     operations: {
       'say-hello': {
         description: 'Say hello',
-        endpoint: '/hello',
-        method: 'GET',
+        handler: 'handlers/hello#sayHello',
+        bundle_scope: 'platform',
         mutates: false,
         resource_type: null,
         minRole: 'VIEWER',
-        input: {},
-        output: {}
+        input: { type: 'object' },
+        output: { type: 'object' }
       }
     },
-    metadata: {},
+    metadata: { version: client.version, description: 'Event consumer example' },
     health: '/health'
   });
+  if (verdict.success !== true) {
+    throw new Error(`[conn-orch-registry][example] Registration refused - ${verdict.errorCode}: ${verdict.message}`);
+  }
 
-  // Start heartbeat
   client.startHeartbeat({
     maxFailures: 5,
     onFatal: (err) => {
       console.error(err.message);
-      process.exit(1);
+      process.exit(1); // the restart policy boots it again and it re-registers
     }
   });
 
-  // OPT-IN: Subscribe to registry changes
+  // OPT-IN: subscribe to registry changes.
   console.log('Subscribing to registry changes...');
   await client.subscribeToChanges();
 
-  // Listen for events
   client.on('serviceUpdated', ({ service, fingerprint, version }) => {
     console.log(`Service updated: ${service} v${version} (${fingerprint})`);
   });
@@ -88,14 +92,22 @@ async function main() {
     console.log(`Received snapshot with ${count} services`);
   });
 
-  // Graceful shutdown
+  client.on('error', (err) => {
+    console.error('[RegistryClient Error]', err);
+  });
+
   process.on('SIGINT', async () => {
     console.log('\nShutting down...');
+    // deregister() stops the heartbeat first; the registry deletes only the
+    // registration whose instance_id matches this copy.
+    await client.deregister();
     await client.close();
     await redis.quit();
     process.exit(0);
   });
 }
 
-// Run example
-main().catch(console.error);
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-registry",
-  "version": "6.0.3",
+  "version": "8.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,14 +39,14 @@
   },
   "dependencies": {
     "@onlineapps/logger-contract": "2.0.0",
-    "@onlineapps/mq-client-core": "4.2.0",
+    "@onlineapps/mq-client-core": "5.1.0",
     "uuid": "^9.0.1"
   },
   "devDependencies": {
     "amqplib": "0.10.9",
-    "ioredis": "^5.8.0",
     "jest": "^29.6.1",
-    "jsdoc-to-markdown": "^8.0.0"
+    "jsdoc-to-markdown": "^8.0.0",
+    "redis": "4.7.1"
   },
   "engines": {
     "node": ">=24.0.0 <25"