@onlineapps/conn-orch-registry 1.1.4

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 ONLINE APPS s.r.o.; info@onlineapps.cz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,151 @@
+# @onlineapps/connector-registry-client
+
+[![Build Status](https://img.shields.io/github/actions/workflow/status/onlineapps/connector-registry-client/nodejs.yml?branch=main)](https://github.com/onlineapps/connector-registry-client/actions)
+[![Coverage Status](https://codecov.io/gh/onlineapps/connector-registry-client/branch/main/graph/badge.svg)](https://codecov.io/gh/onlineapps/connector-registry-client)
+[![npm version](https://img.shields.io/npm/v/@onlineapps/connector-registry-client)](https://www.npmjs.com/package/@onlineapps/connector-registry-client)
+
+> A lightweight client for microservice registration, heartbeat, and API description exchange via RabbitMQ.
+
+## 🚀 Features
+
+* Automatic queue management (`workflow`, `<serviceName>.registry`, `api_services_queuer`, `registry_office`)
+* Periodic heartbeat messages with metadata
+* API description request/response flow
+* Event-driven API using `EventEmitter`
+* Fully configurable via environment variables or constructor options
+
+## 📦 Installation
+
+```bash
+npm install @onlineapps/connector-registry-client
+# or
+yarn add @onlineapps/connector-registry-client
+```
+
+## 🔧 Quick Start
+
+```js
+// Load environment, if using .env
+require('dotenv').config();
+
+const { ServiceRegistryClient, EVENTS } = require('@onlineapps/connector-registry-client');
+
+const client = new ServiceRegistryClient({
+  amqpUrl: process.env.AMQP_URL,
+  serviceName: 'invoicing',
+  version: '1.0.0'
+});
+
+// Listen for API description requests
+client.on(EVENTS.API_DESCRIPTION_REQUEST, async () => {
+  const apiSpec = await loadOpenApiSpec();
+  await client.sendApiDescription(apiSpec);
+});
+
+// Initialize and start heartbeats
+await client.init();
+client.startHeartbeat();
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  await client.close();
+  process.exit(0);
+});
+```
+
+## 📄 Configuration
+
+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_office`    |
+
+## 📨 Message Formats
+
+### Register Request
+```javascript
+{
+  type: "register",
+  serviceName: "hello-service",
+  version: "1.0.0",
+  token: "pre-validation-token",
+  endpoints: [...],
+  timestamp: "ISO-8601"
+}
+```
+
+### Register Confirmed
+```javascript
+{
+  type: "register.confirmed",
+  serviceName: "hello-service",
+  success: true,
+  certificate: {
+    id: "cert-uuid",
+    signature: "cryptographic-signature",
+    validUntil: "ISO-8601"
+  },
+  cached: false
+}
+```
+
+### Heartbeat
+```javascript
+{
+  type: "heartbeat",
+  serviceName: "hello-service",
+  status: "UP",
+  timestamp: "ISO-8601"
+}
+```
+
+## 🛠️ API Reference
+
+See [docs/api.md](https://github.com/onlineapps/connector-registry-client/blob/main/docs/api.md) for full details on classes, methods, and events.
+
+## 📖 Documentation
+
+* Architecture overview: [docs/architecture.md](https://github.com/onlineapps/connector-registry-client/blob/main/docs/architecture.md)
+* API reference: [docs/api.md](https://github.com/onlineapps/connector-registry-client/blob/main/docs/api.md)
+* Examples: [examples/basicUsage.js](https://github.com/onlineapps/agent-registry-client/blob/main/examples/basicUsage.js)
+
+## 🔗 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
+- [api_services_registry](/api/api_services_registry/README.md) - Registry service implementation
+
+## ✅ Testing
+
+```bash
+# Run unit and integration tests
+yarn test
+# or
+npm test
+```
+
+## 🎨 Coding Standards
+
+* **Linting**: ESLint (Airbnb style)
+* **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.
+
+## 📜 License
+
+This project is licensed under the MIT License. See [LICENSE](https://github.com/onlineapps/agent-registry-client/blob/main/LICENSE) for details.
+
+## 📚 Documentation
+
+- [Complete Connectors Documentation](../../../docs/modules/connector.md)
+- [Testing Standards](../../../docs/modules/connector.md#testing-standards)
+

package/docs/REGISTRY_CLIENT_GUIDE.md

@@ -0,0 +1,240 @@
+# Registry Client Guide
+
+## Overview
+
+The `ServiceRegistryClient` is a connector library that enables microservices to communicate with the API Services Registry. It handles service registration, validation, heartbeats, and specification sharing.
+
+## Registration Flow
+
+### New Registration Process (v1.1+)
+
+The registration flow has been updated to include validation before activation:
+
+```
+Microservice                Registry                  Backend
+    |                          |                         |
+    |-- init() --------------->|                         |
+    |   (setup connection)      |                         |
+    |                          |                         |
+    |-- register() ----------->|                         |
+    |   (send service info)    |                         |
+    |                          |-- validate() --------->|
+    |                          |   (check if tested)    |
+    |                          |<-- validation result --|
+    |                          |                         |
+    |<-- registration result --|                         |
+    |                          |                         |
+    |-- startHeartbeat() ----->|                         |
+    |   (if validated OK)      |                         |
+    |                          |                         |
+    |-- sendApiDescription() ->|                         |
+    |   (on request)          |                         |
+```
+
+## Usage
+
+### 1. Basic Setup
+
+```javascript
+const { ServiceRegistryClient } = require('@onlineapps/connector-registry-client');
+
+const registryClient = new ServiceRegistryClient({
+  amqpUrl: 'amqp://localhost:5672',
+  serviceName: 'my-service',
+  version: '1.0.0',
+  specificationEndpoint: '/api/v1/specification',
+  heartbeatInterval: 10000
+});
+```
+
+### 2. Service Initialization and Registration
+
+```javascript
+async function initializeService() {
+  // Step 1: Initialize connection
+  await registryClient.init();
+
+  // Step 2: Register service with registry
+  const registrationResult = await registryClient.register({
+    endpoints: [
+      { path: '/api/users', method: 'GET' },
+      { path: '/api/users', method: 'POST' },
+      { path: '/api/users/:id', method: 'GET' },
+      { path: '/api/users/:id', method: 'PUT' },
+      { path: '/api/users/:id', method: 'DELETE' }
+    ],
+    metadata: {
+      description: 'User management service',
+      author: 'Development Team',
+      documentation: 'https://docs.example.com/users'
+    },
+    health: '/health',
+    spec: openApiSpec  // Optional: OpenAPI specification object
+  });
+
+  // Step 3: If registration successful, start heartbeat
+  if (registrationResult.success) {
+    registryClient.startHeartbeat();
+    console.log('Service registered and activated');
+  } else {
+    console.error('Registration failed:', registrationResult.message);
+    // Handle registration failure (service not tested, invalid config, etc.)
+  }
+}
+```
+
+### 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)
+
+For services that need to be notified about registry changes:
+
+```javascript
+await registryClient.subscribeToChanges();
+
+// Will receive events when services are added/removed/updated
+```
+
+### 5. Cleanup
+
+```javascript
+async function shutdown() {
+  registryClient.stopHeartbeat();
+  await registryClient.close();
+}
+```
+
+## API Reference
+
+### Constructor Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `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 |
+| `apiQueue` | string | 'api_services_queuer' | Queue for API traffic |
+| `registryQueue` | string | 'registry_office' | Registry queue name |
+
+### Methods
+
+#### `async init()`
+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.
+
+**Parameters:**
+- `serviceInfo.endpoints` - Array of API endpoints
+- `serviceInfo.metadata` - Service metadata object
+- `serviceInfo.health` - Health check endpoint
+- `serviceInfo.spec` - OpenAPI specification (optional)
+
+**Returns:** Registration result object with `success` status
+
+#### `startHeartbeat()`
+Starts sending periodic heartbeat messages. Should only be called after successful registration.
+
+#### `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).
+
+#### `async close()`
+Closes all connections and cleans up resources.
+
+### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `registerSent` | Registration message | Emitted when registration is sent |
+| `heartbeatSent` | Heartbeat message | Emitted on each heartbeat |
+| `apiDescriptionRequest` | Request details | Registry requests API spec |
+| `apiDescriptionSent` | Description message | API spec was sent |
+| `error` | Error object | Error occurred |
+
+## Registration Validation
+
+The registry performs several validation checks during registration:
+
+1. **Service Testing Status** - Verifies the service has passed required tests
+2. **Version Compatibility** - Checks version against registry requirements
+3. **Endpoint Validation** - Ensures endpoints follow API standards
+4. **Dependencies Check** - Validates required services are available
+
+Only after passing all validation checks will the service be activated and allowed to send heartbeats.
+
+## Migration from v1.0
+
+If you're upgrading from v1.0 where services immediately started heartbeats:
+
+**Old flow (v1.0):**
+```javascript
+await registryClient.init();
+registryClient.startHeartbeat();  // Started immediately
+```
+
+**New flow (v1.1+):**
+```javascript
+await registryClient.init();
+const result = await registryClient.register(serviceInfo);  // NEW: Registration required
+if (result.success) {
+  registryClient.startHeartbeat();  // Only after validation
+}
+```
+
+## Troubleshooting
+
+### Registration Fails
+
+If registration fails, check:
+- Service has passed all required tests
+- Version number is correctly formatted
+- All required endpoints are documented
+- Service metadata is complete
+
+### No Heartbeats Sent
+
+Ensure:
+- Registration was successful before starting heartbeats
+- RabbitMQ connection is stable
+- Correct queue names are configured
+
+### API Description Not Received
+
+Verify:
+- Event listener is properly set up
+- Service name and version match exactly
+- Queue consumption is active
+
+## Testing
+
+### Unit Tests
+```bash
+npm test:unit
+```
+
+### Integration Tests
+```bash
+# Requires RabbitMQ and MinIO running
+npm test:integration
+```
+
+### Full Test Suite
+```bash
+npm test
+```

package/examples/basicUsage.js

@@ -0,0 +1,85 @@
+/**
+ * basicUsage.js
+ *
+ * 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)
+ * 5. Start heartbeat loop
+ * 6. Graceful shutdown on process signals
+ */
+
+// Load environment variables from .env file
+require('dotenv').config();
+
+const { ServiceRegistryClient, EVENTS } = require('@onlineapps/connector-registry-client');
+
+// Step 1: Create a new ServiceRegistryClient instance
+const registryClient = new ServiceRegistryClient({
+  amqpUrl: process.env.AMQP_URL,
+  serviceName: process.env.SERVICE_NAME || 'invoicing',
+  version: process.env.SERVICE_VERSION || '1.0.0',
+  specificationEndpoint: process.env.SPECIFICATION_ENDPOINT || '/api/v1/specification',
+  heartbeatInterval: parseInt(process.env.HEARTBEAT_INTERVAL, 10) || 10000,
+  apiQueue: process.env.API_QUEUE,
+  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.API_DESCRIPTION_SENT, (msg) => {
+  console.log(`[API Description Sent] at ${msg.timestamp} for ${msg.serviceName}@${msg.version}`);
+});
+
+registryClient.on(EVENTS.ERROR, (err) => {
+  console.error('[RegistryClient 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
+    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();
+      process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+  } catch (err) {
+    console.error('Failed to initialize RegistryClient', err);
+    process.exit(1);
+  }
+})();
+
+/**
+ * Helper: Load local API description
+ * In a real application, this could read from a JSON file,
+ * introspect OpenAPI spec, or build dynamically.
+ */
+async function loadLocalApiDescription() {
+  return {
+    endpoints: [
+      { path: '/invoices', method: 'POST', description: 'Create a new invoice' },
+      { path: '/invoices/:id', method: 'GET', description: 'Retrieve invoice by ID' }
+    ]
+  };
+}

package/examples/event-consumer-example.js

@@ -0,0 +1,108 @@
+/**
+ * Example: Using ServiceRegistryClient with event consumption
+ *
+ * Demonstrates opt-in subscription to registry change events
+ */
+
+const { ServiceRegistryClient } = require('../src/index');
+const Redis = require('ioredis');
+
+async function main() {
+  // Optional Redis for index persistence
+  const redis = new Redis({
+    host: process.env.REDIS_HOST || 'localhost',
+    port: process.env.REDIS_PORT || 6379
+  });
+
+  // Initialize client with storage configuration
+  const client = new ServiceRegistryClient({
+    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'
+    }
+  });
+
+  // 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'
+            }
+          }
+        }
+      }
+    }
+  });
+
+  // Start heartbeat
+  client.startHeartbeat();
+
+  // 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})`);
+  });
+
+  client.on('statusChanged', ({ service, status }) => {
+    console.log(`Service status changed: ${service} -> ${status}`);
+  });
+
+  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...');
+    await client.close();
+    await redis.quit();
+    process.exit(0);
+  });
+}
+
+// Run example
+main().catch(console.error);

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@onlineapps/conn-orch-registry",
+  "version": "1.1.4",
+  "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": [
+    "microservice",
+    "connector",
+    "registry",
+    "rabbitmq",
+    "heartbeat",
+    "api",
+    "environment",
+    "nodejs"
+  ],
+  "files": [
+    "src/",
+    "docs/",
+    "examples/",
+    "README.md",
+    "LICENSE",
+    "CONTRIBUTING.md"
+  ],
+  "main": "src/index.js",
+  "scripts": {
+    "test": "jest --coverage",
+    "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",
+    "docs": "jsdoc2md --files src/**/*.js > API.md"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@onlineapps/conn-base-storage": "file:../conn-base-storage",
+    "amqplib": "^0.10.3",
+    "axios": "^1.5.0",
+    "dotenv": "^16.1.4",
+    "ioredis": "^5.3.2",
+    "joi": "^17.9.2",
+    "uuid": "^9.0.0"
+  },
+  "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",
+    "eslint-config-airbnb-base": "^15.0.0",
+    "eslint-config-prettier": "^10.1.5",
+    "eslint-plugin-import": "^2.30.1",
+    "eslint-plugin-prettier": "^5.4.0",
+    "jest": "^29.6.1",
+    "semantic-release": "^22.0.12"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}