@onlineapps/conn-orch-registry 1.1.54 → 1.2.1

package/README.md

@@ -4,13 +4,15 @@
 [![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)
 
-> A lightweight client for microservice registration, heartbeat, and API description exchange via RabbitMQ.
+> 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).
 
 ## 🚀 Features
 
 * Automatic queue management (`workflow`, `<serviceName>.registry`, `api_services_queuer`, `registry.register`)
 * Periodic heartbeat messages with metadata
-* API description request/response flow
+* Full specification (endpoints + operations) published inside `register`
 * Event-driven API using `EventEmitter`
 * Fully configurable via environment variables or constructor options
 
@@ -35,14 +37,16 @@ const client = new ServiceRegistryClient({
   version: '1.0.0'
 });
 
-// Listen for API description requests
-client.on(EVENTS.API_DESCRIPTION_REQUEST, async () => {
-  const apiSpec = await loadOpenApiSpec();
-  await client.sendApiDescription(apiSpec);
+await client.init();
+
+// Publish full service spec in the register message (single round-trip).
+await client.register({
+  endpoints: [/* ... */],
+  operations: await loadOperationsJson(), // see operations-registry-contract.md §3
+  metadata: { /* ... */ },
+  health: '/health'
 });
 
-// Initialize and start heartbeats
-await client.init();
 client.startHeartbeat();
 
 // Graceful shutdown

package/docs/REGISTRY_CLIENT_GUIDE.md

@@ -17,20 +17,22 @@ Microservice                Registry                  Backend
     |   (setup connection)      |                         |
     |                          |                         |
     |-- register() ----------->|                         |
-    |   (send service info)    |                         |
-    |                          |-- validate() --------->|
+    |   (full spec: endpoints |                         |
+    |    + operations + meta) |-- validate() --------->|
     |                          |   (check if tested)    |
     |                          |<-- validation result --|
     |                          |                         |
-    |<-- registration result --|                         |
+    |<-- register.confirmed ---|                         |
     |                          |                         |
     |-- startHeartbeat() ----->|                         |
     |   (if validated OK)      |                         |
-    |                          |                         |
-    |-- sendApiDescription() ->|                         |
-    |   (on request)          |                         |
 ```
 
+> 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).
+
 ## Usage
 
 ### 1. Basic Setup
@@ -83,17 +85,7 @@ async function initializeService() {
 }
 ```
 
-### 3. Handling API Description Requests
-
-```javascript
-// Listen for requests to send API specification
-registryClient.on('apiDescriptionRequest', async (request) => {
-  const apiSpec = await loadApiSpecification();
-  await registryClient.sendApiDescription(apiSpec);
-});
-```
-
-### 4. Event Subscription (Optional)
+### 3. Event Subscription (Optional)
 
 For services that need to be notified about registry changes:
 
@@ -132,13 +124,14 @@ async function shutdown() {
 Initializes the connection to RabbitMQ and sets up queues.
 
 #### `async register(serviceInfo)`
-Registers the service with the registry. The registry will validate that the service is properly tested and approved before activation.
+Registers the service with the registry. The registry validates the service
+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.metadata` - Service metadata object
 - `serviceInfo.health` - Health check endpoint
-- `serviceInfo.spec` - OpenAPI specification (optional)
 
 **Returns:** Registration result object with `success` status
 
@@ -148,9 +141,6 @@ Starts sending periodic heartbeat messages. Should only be called after successf
 #### `stopHeartbeat()`
 Stops the heartbeat timer.
 
-#### `async sendApiDescription(description)`
-Sends the API specification to the registry when requested.
-
 #### `async subscribeToChanges()`
 Subscribes to registry change events (optional).
 
@@ -162,9 +152,10 @@ Closes all connections and cleans up resources.
 | Event | Payload | Description |
 |-------|---------|-------------|
 | `registerSent` | Registration message | Emitted when registration is sent |
+| `registerConfirmed` | Confirmation payload | Registry accepted the registration |
+| `registerRejected` | Rejection payload | Registry rejected the registration |
 | `heartbeatSent` | Heartbeat message | Emitted on each heartbeat |
-| `apiDescriptionRequest` | Request details | Registry requests API spec |
-| `apiDescriptionSent` | Description message | API spec was sent |
+| `revalidate` | Request payload | Registry asks service to revalidate |
 | `error` | Error object | Error occurred |
 
 ## Registration Validation

package/examples/basicUsage.js

@@ -4,10 +4,12 @@
  * Example demonstrating full lifecycle of ServiceRegistryClient:
  * 1. Load environment variables
  * 2. Instantiate client
- * 3. Initialize (setup queues and start listening for requests)
- * 4. Register event listeners (apiDescriptionRequest, heartbeatSent, apiDescriptionSent, error)
+ * 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
+ *
+ * See: api/docs/standards/operations-registry-contract.md §2 MQ wire format
  */
 
 function requireEnv(name, description) {
@@ -20,7 +22,6 @@ function requireEnv(name, description) {
 
 const { ServiceRegistryClient, EVENTS } = require('@onlineapps/connector-registry-client');
 
-// Step 1: Create a new ServiceRegistryClient instance
 const registryClient = new ServiceRegistryClient({
   amqpUrl: requireEnv('AMQP_URL', 'RabbitMQ URL (IPv4-only recommended: amqp://user:pass@127.0.0.1:PORT)'),
   serviceName: requireEnv('SERVICE_NAME', 'Service logical name'),
@@ -31,20 +32,20 @@ const registryClient = new ServiceRegistryClient({
   registryQueue: process.env.REGISTRY_QUEUE
 });
 
-// Step 2: Register event listeners
 registryClient.on(EVENTS.HEARTBEAT_SENT, (msg) => {
   console.log(`[Heartbeat] Sent at ${msg.timestamp} for ${msg.serviceName}@${msg.version}`);
 });
 
-registryClient.on(EVENTS.API_DESCRIPTION_REQUEST, async (payload) => {
-  console.log(`[API Description Request] for ${payload.serviceName}@${payload.version}`);
-  // Load local API description (from file or in-memory)
-  const apiDesc = await loadLocalApiDescription();
-  await registryClient.sendApiDescription(apiDesc);
+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);
 });
 
-registryClient.on(EVENTS.API_DESCRIPTION_SENT, (msg) => {
-  console.log(`[API Description Sent] at ${msg.timestamp} for ${msg.serviceName}@${msg.version}`);
+registryClient.on(EVENTS.REVALIDATE, (payload) => {
+  console.log('[Revalidate] Registry asked us to revalidate', payload.reason);
 });
 
 registryClient.on(EVENTS.ERROR, (err) => {
@@ -53,15 +54,15 @@ registryClient.on(EVENTS.ERROR, (err) => {
 
 (async () => {
   try {
-    // Step 3: Initialize client (setup queues and listeners)
     await registryClient.init();
     console.log('RegistryClient initialized: queues are ready.');
 
-    // Step 4: Start heartbeat loop
+    await registryClient.register(await loadServiceSpec());
+    console.log('Register message published.');
+
     registryClient.startHeartbeat();
     console.log('Heartbeat loop started.');
 
-    // Step 5: Graceful shutdown on SIGINT/SIGTERM
     const shutdown = async () => {
       console.log('Shutting down RegistryClient...');
       await registryClient.close();
@@ -76,15 +77,41 @@ registryClient.on(EVENTS.ERROR, (err) => {
 })();
 
 /**
- * Helper: Load local API description
- * In a real application, this could read from a JSON file,
- * introspect OpenAPI spec, or build dynamically.
+ * 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.
+ *
+ * @see api/docs/standards/operations-registry-contract.md §3 Operation schema
  */
-async function loadLocalApiDescription() {
+async function loadServiceSpec() {
   return {
     endpoints: [
-      { path: '/invoices', method: 'POST', description: 'Create a new invoice' },
-      { path: '/invoices/:id', method: 'GET', description: 'Retrieve invoice by ID' }
-    ]
+      { path: '/invoices', method: 'POST' },
+      { path: '/invoices/:id', method: 'GET' }
+    ],
+    operations: {
+      'create-invoice': {
+        description: 'Create a new invoice',
+        endpoint: '/invoices',
+        method: 'POST',
+        mutates: true,
+        resource_type: 'invoice',
+        minRole: 'EDITOR',
+        input: {},
+        output: {}
+      },
+      'get-invoice': {
+        description: 'Retrieve invoice by ID',
+        endpoint: '/invoices/:id',
+        method: 'GET',
+        mutates: false,
+        resource_type: null,
+        minRole: 'VIEWER',
+        input: {},
+        output: {}
+      }
+    },
+    metadata: {},
+    health: '/health'
   };
 }

package/examples/event-consumer-example.js

@@ -32,25 +32,25 @@ async function main() {
   // Initialize connection
   await client.init();
 
-  // Register ourselves with registry
-  await client.sendApiDescription({
-    openapi: '3.0.0',
-    info: {
-      title: 'Example Service',
-      version: '1.0.0'
-    },
-    paths: {
-      '/hello': {
-        get: {
-          summary: 'Say hello',
-          responses: {
-            '200': {
-              description: 'Success'
-            }
-          }
-        }
+  // 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.
+  await client.register({
+    endpoints: [{ path: '/hello', method: 'GET' }],
+    operations: {
+      'say-hello': {
+        description: 'Say hello',
+        endpoint: '/hello',
+        method: 'GET',
+        mutates: false,
+        resource_type: null,
+        minRole: 'VIEWER',
+        input: {},
+        output: {}
       }
-    }
+    },
+    metadata: {},
+    health: '/health'
   });
 
   // Start heartbeat

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-registry",
-  "version": "1.1.54",
+  "version": "1.2.1",
   "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": [
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "@onlineapps/conn-base-storage": "1.0.9",
-    "@onlineapps/mq-client-core": "1.0.82",
+    "@onlineapps/mq-client-core": "1.0.83",
     "@onlineapps/runtime-config": "1.0.2",
     "amqplib": "^0.10.9",
     "axios": "^1.12.2",

package/src/events.js

@@ -5,6 +5,10 @@
  * Acts as a central place for constants to avoid typos
  * when emitting and listening for events.
  *
+ * 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
  * @module @onlineapps/connector-registry-client/src/events
  */
 
@@ -14,15 +18,18 @@
 const EVENTS = {
     /** Emitted after a successful heartbeat is sent. Payload: { id, type, serviceName, version, timestamp } */
     HEARTBEAT_SENT: 'heartbeatSent',
-  
-    /** Emitted when the registryOffice requests the API description. Payload: { id, type, serviceName, version, timestamp } */
-    API_DESCRIPTION_REQUEST: 'apiDescriptionRequest',
-  
-    /** Emitted after sending the API description. Payload: { id, type, serviceName, version, description, timestamp } */
-    API_DESCRIPTION_SENT: 'apiDescriptionSent',
-  
+
+    /** Emitted when the registry confirms a successful registration. Payload: { requestId, certificate, ... } */
+    REGISTER_CONFIRMED: 'registerConfirmed',
+
+    /** Emitted when the registry rejects a registration. Payload: { requestId, reason, errors, ... } */
+    REGISTER_REJECTED: 'registerRejected',
+
+    /** Emitted when the registry asks the service to revalidate (e.g. infra fingerprint change). */
+    REVALIDATE: 'revalidate',
+
     /** Emitted on internal errors. Payload: Error instance or error description. */
     ERROR: 'error'
 };
-  
+
 module.exports = EVENTS;

package/src/registryClient.js

@@ -1,17 +1,27 @@
 /**
  * registryClient.js
  *
- * ServiceRegistryClient for communication between a microservice (via Agent) and the central registry.
- * Sends heartbeat messages, listens for API description requests, and sends API descriptions.
- * Uses QueueManager to manage AMQP queues.
- * Emits events through EventEmitter.
+ * ServiceRegistryClient for communication between a microservice (via Agent)
+ * and the central registry. Sends the full service specification in the
+ * `register` message (including the `operations` map) and periodic heartbeat
+ * messages. Receives registration responses (register.confirmed /
+ * register.rejected) and revalidation requests from the registry.
+ *
+ * Legacy `apiDescription` / `apiDescriptionRequest` round-trips have been
+ * removed — the full spec is part of the `register` message itself.
+ *
+ * Uses QueueManager to manage AMQP queues. Emits events through EventEmitter.
  *
  * Events (see src/events.js):
  *  - 'heartbeatSent'
- *  - 'apiDescriptionRequest'
- *  - 'apiDescriptionSent'
+ *  - 'revalidate'
+ *  - 'registerConfirmed'
+ *  - 'registerRejected'
  *  - 'error'
  *
+ * @see api/docs/standards/operations-registry-contract.md §2 MQ wire format
+ * @see api/docs/standards/OPERATIONS.md
+ *
  * @module @onlineapps/connector-registry-client/src/registryClient
  */
 
@@ -147,8 +157,7 @@ class ServiceRegistryClient extends EventEmitter {
 
   /**
    * Internal handler for incoming messages from the registry queue.
-   * Emits 'apiDescriptionRequest' when appropriate.
-   * Handles registration responses.
+   * Handles registration responses and revalidation requests.
    * @param {Object} msg - AMQP message
    * @private
    */
@@ -181,12 +190,13 @@ class ServiceRegistryClient extends EventEmitter {
       return;
     }
 
-    // Handle API description request from registry
-    if (payload.type === 'apiDescriptionRequest' &&
-        payload.serviceName === this.serviceName &&
-        payload.version === this.version) {
-      // Emit API description request event
-      this.emit('apiDescriptionRequest', payload);
+    // Handle revalidation request from registry (infra version change)
+    if (payload.type === 'revalidate') {
+      console.log(`[RegistryClient] ${this.serviceName}: Received revalidation request`, {
+        reason: payload.reason,
+        infraFingerprint: payload.infraFingerprint?.substring(0, 16)
+      });
+      this.emit('revalidate', payload);
     }
 
     // Handle registration response from registry
@@ -376,6 +386,7 @@ class ServiceRegistryClient extends EventEmitter {
     }
 
     const msgId = uuidv4();
+    // @see api/docs/standards/operations-registry-contract.md §2 MQ wire format
     const msg = {
       id: msgId,
       type: 'register',
@@ -383,6 +394,7 @@ class ServiceRegistryClient extends EventEmitter {
       version: this.version,
       specificationEndpoint: this.specificationEndpoint,
       endpoints: serviceInfo.endpoints || [],
+      operations: serviceInfo.operations || {},
       metadata: serviceInfo.metadata || {},
       health: serviceInfo.health || '/health',
       spec: serviceInfo.spec || null,
@@ -392,6 +404,12 @@ class ServiceRegistryClient extends EventEmitter {
       timestamp: new Date().toISOString()
     };
 
+    // Propagate workspaceScoped flag to the registry so consumers can discover
+    // which services are workspace-scoped. See biz-service-onboarding.md §4.
+    if (typeof serviceInfo.workspaceScoped === 'boolean') {
+      msg.workspaceScoped = serviceInfo.workspaceScoped;
+    }
+
     // Include validation proof if loaded
     // Structure: { validationProof: "hash", validationData: { ... } }
     // See: @onlineapps/service-validator-core/README.md#validation-proof-structure
@@ -604,60 +622,6 @@ class ServiceRegistryClient extends EventEmitter {
     }
   }
 
-  /**
-   * Sends an API description message to the registry queue.
-   * Emits 'apiDescriptionSent'.
-   * @param {Object} apiDescription - JSON object describing the API
-   * @returns {Promise<void>}
-   */
-  async sendApiDescription(apiDescription) {
-    const msg = {
-      id: uuidv4(),
-      type: 'apiDescription',
-      serviceName: this.serviceName,
-      version: this.version,
-      description: apiDescription,
-      timestamp: new Date().toISOString()
-    };
-    // CRITICAL: Use queueConfig.js to get correct parameters (TTL, max-length, etc.)
-    console.log(`[RegistryClient] [PUBLISH] Preparing to publish to ${this.registryQueue} (apiDescription)`);
-    await this._ensureInfrastructureQueue(this.registryQueue);
-    this.queueManager.channel.sendToQueue(
-      this.registryQueue,
-      Buffer.from(JSON.stringify(msg)),
-      { persistent: true }
-    );
-    this.emit('apiDescriptionSent', msg);
-  }
-
-  /**
-   * Alias for sendApiDescription - sends specification to registry
-   * @param {Object} spec - API specification (optional, will fetch if not provided)
-   * @returns {Promise<void>}
-   */
-  async sendSpecification(spec) {
-    // If no spec provided, try to fetch it
-    if (!spec) {
-      try {
-        const resolved = runtimeCfg.resolve({ specificationEndpoint: this.specificationEndpoint });
-        if (!resolved.servicePort) {
-          throw new Error('[RegistryClient] Missing required config - Expected PORT (servicePort) to auto-fetch specification, or pass spec explicitly');
-        }
-        const url = `${resolved.specProtocol}://${resolved.specHost}:${resolved.servicePort}${resolved.specificationEndpoint}`;
-        const response = await fetch(url);
-        if (response.ok) {
-          spec = await response.json();
-        }
-      } catch (error) {
-        console.error('Failed to fetch specification:', error);
-        return;
-      }
-    }
-
-    // Use existing method
-    return this.sendApiDescription(spec);
-  }
-
   /**
    * Subscribe to registry change events (opt-in)
    * Creates event consumer and starts listening to registry.changes exchange