@onlineapps/conn-orch-registry 3.0.1 → 4.0.0

package/README.md

@@ -1,9 +1,28 @@
+> Status: current
+> Owns: a service's side of the services registry — heartbeats, API-description submission, and the registry events it consumes
+
+<!-- BEGIN GENERATED: library-uniform — regenerate: npx oa-sync-template readme-uniform --all -->
+Uniform: [library/orchestration](../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/conn-orch-registry
 
-[![Build Status](https://img.shields.io/github/actions/workflow/status/onlineapps/conn-orch-registry/nodejs.yml?branch=main)](https://github.com/onlineapps/conn-orch-registry/actions)
-[![Coverage Status](https://codecov.io/gh/onlineapps/conn-orch-registry/branch/main/graph/badge.svg)](https://codecov.io/gh/onlineapps/conn-orch-registry)
 [![npm version](https://img.shields.io/npm/v/@onlineapps/conn-orch-registry)](https://www.npmjs.com/package/@onlineapps/conn-orch-registry)
 
+<!--
+  The GitHub Actions and Codecov badges that used to sit here pointed at
+  github.com/onlineapps/conn-orch-registry, which does not exist — this package lives
+  in gitlab.com/onlineapps/oadrive/infra-mono under shared/connector/conn-orch-registry.
+  A build badge for a pipeline nobody runs is a green light with nothing behind it,
+  so it was removed rather than repointed — same treatment as conn-infra-mq (a4808857).
+  The npm badge stays: the package IS published under that name.
+-->
+
+
 > 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).
@@ -16,6 +35,13 @@
 * Event-driven API using `EventEmitter`
 * Fully configurable via environment variables or constructor options
 
+> **This client registers; it does not read.** Reading another service's spec goes
+> through `createRegistryReader` from `@onlineapps/service-common`, which reads the
+> Redis projection — see
+> [registration-wire.md §7 Consumer contract](../../../docs/biz/30-operations/registration-wire.md).
+> The `registry.changes` events this client can subscribe to are an invalidation
+> hint, not a read path (§5).
+
 ## 📦 Installation
 
 ```bash
@@ -34,7 +60,10 @@ const { ServiceRegistryClient, EVENTS } = require('@onlineapps/conn-orch-registr
 const client = new ServiceRegistryClient({
   amqpUrl: process.env.AMQP_URL,
   serviceName: 'invoicing',
-  version: '1.0.0'
+  version: '1.0.0',
+  specificationEndpoint: '/api/v1/specification', // required — see § Configuration
+  heartbeatInterval: 30000,                        // required — see § Configuration
+  logger // required — see § Logger contract below
 });
 
 await client.init();
@@ -60,14 +89,94 @@ process.on('SIGINT', async () => {
 
 Configuration can be provided via environment variables or constructor options:
 
-| Variable             | Description                                   | Default              |
-| -------------------- | --------------------------------------------- | -------------------- |
-| `AMQP_URL`           | RabbitMQ connection string (required)         | —                    |
-| `SERVICE_NAME`       | Logical name of your service (required)       | —                    |
-| `SERVICE_VERSION`    | Service version in SemVer format (required)   | —                    |
-| `HEARTBEAT_INTERVAL` | Interval in ms between heartbeats             | `10000`              |
-| `API_QUEUE`          | Queue name for heartbeat/API messages         | `api_services_queuer` |
-| `REGISTRY_QUEUE`     | Queue name for registry requests/descriptions | `registry.register`  |
+| Option                  | Description                                   | Default              |
+| ----------------------- | --------------------------------------------- | -------------------- |
+| `amqpUrl`               | RabbitMQ connection string (required)         | —                    |
+| `serviceName`           | Logical name of your service (required)       | —                    |
+| `version`               | Service version in SemVer format (required)   | —                    |
+| `specificationEndpoint` | Path the `register`/`heartbeat` messages carry (**required**) | —    |
+| `heartbeatInterval`     | Milliseconds between heartbeats (**required**) | —                   |
+| `apiQueue`              | Queue name for heartbeat/API messages         | `api_services_queuer` |
+| `registryQueue`         | Queue name for registry requests              | `registry.register`  |
+
+**`specificationEndpoint` and `heartbeatInterval` carry no default** (d.278c). Both are
+decisions somebody else owns, and a library default is a second decision that fires
+whenever the caller forgets the first (architecture-principles §3):
+
+* the specification path is REQUIRED on the wire
+  ([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
+  [`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.
+
+`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/mq-client-core`, which drops the userinfo (`user:password@`) and keeps
+scheme, host, port and vhost. The connection itself uses the URL you passed — the
+redaction applies only to what gets written out. (The helper was a local copy until
+d.446b, from the days when that package masked the password alone; 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
+[`@onlineapps/mq-client-core`](https://www.npmjs.com/package/@onlineapps/mq-client-core)
+(§ `consume()` — the delivery contract), registered with `requeueOnError: false`.
+
+| The handler | What happens to the message |
+| --- | --- |
+| returns | acked, once |
+| throws | rejected into `<service>.dlq` over `dlx`, on the first failure, with a `message_dlq` event |
+
+There is no hand-written `ack`/`nack` here any more and no raw amqplib channel leaves
+`QueueManager` (d.198b-3). The queue declarations — durability, TTL, cap and the
+dead-letter route — come from `queueConfig` in that package; this one names its queues
+and declares nothing of its own.
+
+## 🪵 Logger contract
+
+Every constructor in this package — `ServiceRegistryClient`, `RegistryEventConsumer`
+and `QueueManager` — **requires** a `logger` and validates it on the spot. A logger is
+an object with all four of `info`, `warn`, `error` and `debug` as functions. Anything
+else fails at construction, naming the method that is missing:
+
+```
+[RegistryClient] logger is incomplete - Expected: info, warn, error, debug as functions;
+missing: debug. Fix: pass a logger implementing all four.
+```
+
+There is no fallback to `console` (architecture-principles §3), and no delayed check:
+a service that boots with half a logger learns it at construction, not on the first
+registration failure (§4).
+
+What the package writes through it:
+
+| Level | Events |
+| --- | --- |
+| `info` | client initialized · validation proof present · registration message sent · registration resolved (with certificate id) · deregistration request published · revalidation requested · registry subscription, snapshot, status change, spec published, service removed |
+| `warn` | no validation proof (registry falls back to Tier 2) · registration response with no matching pending request · unknown registry event type · index-only mode |
+| `debug` | inbound registry message · registry verdict payload · heartbeat sent · queue asserted · spec download |
+| `error` | resolve threw · heartbeat failed · index persist/load failure |
+
+`ServiceRegistryClient` passes its logger down to the `QueueManager` and
+`RegistryEventConsumer` it constructs, so one service gets one sink.
+
+Errors that are **thrown** are not also logged: the thrown message carries the context
+and the caller decides. A delivery this package cannot handle is reported the same way
+— the handler throws and the core dead-letters the message, logging that move once.
+
+Owner confirmation:
+[`docs/governance/confirmations/connector-logger-contract.md`](/api/docs/governance/confirmations/connector-logger-contract.md)
+001 (all four methods, validated in the constructor) and 002 (a logger a component
+demands is a logger that component writes to). Standard:
+[`docs/standards/ERROR_HANDLING.md`](/api/docs/standards/ERROR_HANDLING.md)
+§ Logger Configuration.
 
 ## 📨 Message Formats
 
@@ -94,10 +203,17 @@ Configuration can be provided via environment variables or constructor options:
     signature: "cryptographic-signature",
     validUntil: "ISO-8601"
   },
+  errorCode: null,
   cached: false
 }
 ```
 
+`errorCode` is the registry's machine reason for a refusal, and `register()` hands it to
+the caller unchanged as `result.errorCode` — branch on it, never on `message`, whose
+wording is not a contract. It is `null` on a confirmed registration, and `undefined` for
+the two failure replies that carry no code at all. The codes, who emits each and what
+fixes it: `api/docs/biz/30-operations/registration-wire.md` §8.
+
 ### Heartbeat
 ```javascript
 {
@@ -110,13 +226,21 @@ Configuration can be provided via environment variables or constructor options:
 
 ## 🛠️ API Reference
 
-See [docs/api.md](https://github.com/onlineapps/conn-orch-registry/blob/main/docs/api.md) for full details on classes, methods, and events.
+See [API.md](API.md) for full details on classes, methods, and events. It is generated
+from the JSDoc in `src/` by `npm run docs` — do not edit it by hand.
+
+<!--
+  The three links that used to stand here pointed at github.com/onlineapps — at
+  docs/api.md and docs/architecture.md in a repo that does not exist, and neither
+  file has ever existed in this package. Replaced with the files that do exist,
+  by relative path, which resolves both on GitLab and on npmjs.com.
+-->
 
 ## 📖 Documentation
 
-* Architecture overview: [docs/architecture.md](https://github.com/onlineapps/conn-orch-registry/blob/main/docs/architecture.md)
-* API reference: [docs/api.md](https://github.com/onlineapps/conn-orch-registry/blob/main/docs/api.md)
-* Examples: [examples/basicUsage.js](https://github.com/onlineapps/agent-registry-client/blob/main/examples/basicUsage.js)
+* API reference (generated): [API.md](API.md)
+* Usage guide: [docs/REGISTRY_CLIENT_GUIDE.md](docs/REGISTRY_CLIENT_GUIDE.md)
+* Examples: [examples/basicUsage.js](examples/basicUsage.js), [examples/event-consumer-example.js](examples/event-consumer-example.js)
 
 ## 🔗 Related Documentation
 
@@ -139,13 +263,19 @@ npm test
 * **Formatting**: Prettier
 * **Testing**: Jest
 
-## 🤝 Contributing
-
-Please read [CONTRIBUTING.md](https://github.com/onlineapps/agent-registry-client/blob/main/CONTRIBUTING.md) for details on submitting issues and pull requests.
+<!--
+  A "Contributing" section used to stand here, linking to CONTRIBUTING.md on
+  github.com/onlineapps/agent-registry-client — a repo that does not exist and never
+  held this package; there is no CONTRIBUTING.md in this package either, and the
+  fork/PR flow is not how this monorepo is developed. Removed rather than repointed:
+  the workspace rules that actually govern changes here load automatically from
+  .claude/rules/. The now-orphaned "CONTRIBUTING.md" entry in package.json `files`
+  went with it, in the same commit.
+-->
 
 ## 📜 License
 
-This project is licensed under the MIT License. See [LICENSE](https://github.com/onlineapps/agent-registry-client/blob/main/LICENSE) for details.
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
 
 ## 📚 Documentation
 

package/docs/REGISTRY_CLIENT_GUIDE.md

@@ -38,7 +38,7 @@ Microservice                Registry                  Backend
 ### 1. Basic Setup
 
 ```javascript
-const { ServiceRegistryClient } = require('@onlineapps/connector-registry-client');
+const { ServiceRegistryClient } = require('@onlineapps/conn-orch-registry');
 
 const registryClient = new ServiceRegistryClient({
   amqpUrl: 'amqp://localhost:5672',
@@ -113,8 +113,8 @@ async function shutdown() {
 | `amqpUrl` | string | required | AMQP connection URL |
 | `serviceName` | string | required | Unique service identifier |
 | `version` | string | required | Service version (semver) |
-| `specificationEndpoint` | string | '/api/v1/specification' | Endpoint for API spec |
-| `heartbeatInterval` | number | 10000 | Heartbeat interval in ms |
+| `specificationEndpoint` | string | required | Path the register/heartbeat messages carry; no default (d.278c) |
+| `heartbeatInterval` | number | required | Milliseconds between heartbeats; no default — the cadence has one owner (d.278c) |
 | `apiQueue` | string | 'api_services_queuer' | Queue for API traffic |
 | `registryQueue` | string | 'registry.register' | Registry queue name |
 
@@ -216,13 +216,13 @@ Verify:
 
 ### Unit Tests
 ```bash
-npm test:unit
+npm run test:unit
 ```
 
 ### Integration Tests
 ```bash
 # Requires RabbitMQ and MinIO running
-npm test:integration
+npm run test:integration
 ```
 
 ### Full Test Suite

package/examples/basicUsage.js

@@ -20,14 +20,25 @@ function requireEnv(name, description) {
   return String(value).trim();
 }
 
-const { ServiceRegistryClient, EVENTS } = require('@onlineapps/connector-registry-client');
+// 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.
+const { ServiceRegistryClient, EVENTS } = require('../src/index');
 
+// 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.
 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)'),
-  specificationEndpoint: process.env.SPECIFICATION_ENDPOINT,
-  heartbeatInterval: process.env.HEARTBEAT_INTERVAL ? parseInt(process.env.HEARTBEAT_INTERVAL, 10) : undefined,
+  // 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
 });

package/examples/event-consumer-example.js

@@ -1,7 +1,11 @@
 /**
  * Example: Using ServiceRegistryClient with event consumption
  *
- * Demonstrates opt-in subscription to registry change events
+ * 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.
+ *
+ * @see api/docs/biz/30-operations/registration-wire.md §5, §7
  */
 
 const { ServiceRegistryClient } = require('../src/index');
@@ -15,7 +19,12 @@ async function main() {
   });
 
   // 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.
   const client = new ServiceRegistryClient({
+    logger: console,
     amqpUrl: process.env.AMQP_URL || 'amqp://localhost',
     serviceName: 'example-service',
     version: '1.0.0',
@@ -71,30 +80,8 @@ async function main() {
 
   client.on('snapshotReceived', ({ count }) => {
     console.log(`Received snapshot with ${count} services`);
-
-    // Show active services
-    const activeServices = client.getActiveServices();
-    console.log('Active services:', activeServices);
   });
 
-  // Example: Check if another service is active
-  setTimeout(() => {
-    if (client.isServiceActive('invoicing')) {
-      console.log('Invoicing service is active');
-
-      // Load its spec
-      client.getServiceSpec('invoicing')
-        .then(spec => {
-          console.log('Invoicing API:', spec.info?.title);
-        })
-        .catch(err => {
-          console.error('Failed to load invoicing spec:', err.message);
-        });
-    } else {
-      console.log('Invoicing service is not active');
-    }
-  }, 5000);
-
   // Graceful shutdown
   process.on('SIGINT', async () => {
     console.log('\nShutting down...');

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@onlineapps/conn-orch-registry",
-  "version": "3.0.1",
+  "version": "4.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.",
+  "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": [
     "microservice",
     "connector",
@@ -18,41 +18,35 @@
     "docs/",
     "examples/",
     "README.md",
-    "LICENSE",
-    "CONTRIBUTING.md"
+    "LICENSE"
   ],
+  "oa": {
+    "category": "orchestration"
+  },
   "main": "src/index.js",
   "scripts": {
-    "test": "jest --coverage",
-    "test:unit": "jest --testPathPattern=unit --coverage",
-    "test:component": "jest --testPathPattern=component --coverage",
+    "test": "npm run test:unit && npm run test:integration",
+    "test:unit": "jest tests/unit --coverage",
     "test:integration": "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 tests examples --ext .js --cache --cache-location .eslintcache",
-    "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)"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@onlineapps/mq-client-core": "2.0.1",
-    "amqplib": "^0.10.9",
+    "@onlineapps/logger-contract": "1.1.0",
+    "@onlineapps/mq-client-core": "3.0.0",
     "uuid": "^9.0.1"
   },
   "devDependencies": {
-    "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/commit-analyzer": "^11.1.0",
-    "@semantic-release/git": "^10.0.1",
-    "@semantic-release/npm": "^11.0.3",
-    "@semantic-release/release-notes-generator": "^12.1.0",
-    "eslint": "^8.44.0",
+    "amqplib": "0.10.9",
     "ioredis": "^5.8.0",
     "jest": "^29.6.1",
-    "semantic-release": "^22.0.12"
+    "jsdoc-to-markdown": "^8.0.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=24.0.0 <25"
   }
 }

package/src/events.js

@@ -1,7 +1,7 @@
 /**
  * events.js
  *
- * List of events used in the connector-registry-client module.
+ * List of events used in the conn-orch-registry module.
  * Acts as a central place for constants to avoid typos
  * when emitting and listening for events.
  *
@@ -9,7 +9,7 @@
  * the full service specification travels as part of the `register` message.
  *
  * @see api/docs/biz/30-operations/registration-wire.md §2 MQ wire format
- * @module @onlineapps/connector-registry-client/src/events
+ * @module @onlineapps/conn-orch-registry/src/events
  */
 
 /**

package/src/index.js

@@ -3,7 +3,6 @@
  * @description Service registry connector for dynamic service discovery, health monitoring,
  * and OpenAPI specification management in OA Drive microservices architecture.
  *
- * @see {@link https://github.com/onlineapps/oa-drive/tree/main/shared/connector/conn-orch-registry|GitHub Repository}
  * @author OA Drive Team
  * @license MIT
  * @since 1.0.0