@onlineapps/conn-orch-registry 1.1.4

package/src/config.js

@@ -0,0 +1,52 @@
+/**
+ * config.js
+ *
+ * Loads and validates configuration variables via environment variables.
+ * Uses dotenv to load the .env file and Joi for validation.
+ *
+ * @module @onlineapps/connector-registry-client/src/config
+ */
+
+// Load .env (if it exists)
+require('dotenv').config();
+
+const Joi = require('joi');
+
+// Define schema for environment variables
+const envSchema = Joi.object({
+  AMQP_URL: Joi.string().uri().required()
+    .description('AMQP URI for connecting to RabbitMQ'),
+
+  SERVICE_NAME: Joi.string().required()
+    .description('Name of the service to register'),
+
+  SERVICE_VERSION: Joi.string().required()
+    .description('Service version in SemVer format'),
+
+  HEARTBEAT_INTERVAL: Joi.number().integer().min(1000).default(10000)
+    .description('Interval for sending heartbeat messages in ms'),
+
+  API_QUEUE: Joi.string().default('api_services_queuer')
+    .description('Name of the queue for heartbeat and API requests'),
+
+  REGISTRY_QUEUE: Joi.string().default('registry.register')
+    .description('Name of the queue for registry messages')
+})
+  .unknown() // allow additional variables
+  .required();
+
+// Validate variables
+const { error, value: envVars } = envSchema.validate(process.env);
+if (error) {
+  throw new Error(`Config validation error: ${error.message}`);
+}
+
+// Export configuration
+module.exports = {
+  amqpUrl: envVars.AMQP_URL,
+  serviceName: envVars.SERVICE_NAME,
+  version: envVars.SERVICE_VERSION,
+  heartbeatInterval: envVars.HEARTBEAT_INTERVAL,
+  apiQueue: envVars.API_QUEUE,
+  registryQueue: envVars.REGISTRY_QUEUE
+};

package/src/events.js

@@ -0,0 +1,28 @@
+/**
+ * events.js
+ *
+ * List of events used in the connector-registry-client module.
+ * Acts as a central place for constants to avoid typos
+ * when emitting and listening for events.
+ *
+ * @module @onlineapps/connector-registry-client/src/events
+ */
+
+/**
+ * Named EventEmitter events for ServiceRegistryClient.
+ */
+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 on internal errors. Payload: Error instance or error description. */
+    ERROR: 'error'
+};
+  
+module.exports = EVENTS;

package/src/index.js

@@ -0,0 +1,37 @@
+/**
+ * @module @onlineapps/conn-orch-registry
+ * @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
+ */
+
+// Core client
+const { ServiceRegistryClient } = require('./registryClient');
+// Events for use with EventEmitter
+const EVENTS = require('./events');
+// Event consumer for registry changes
+const RegistryEventConsumer = require('./registryEventConsumer');
+
+module.exports = {
+  /**
+   * Class for registering a service and sending heartbeats to the central registry.
+   * @type {Function}
+   */
+  ServiceRegistryClient,
+
+  /**
+   * Class for consuming registry change events (opt-in).
+   * @type {Function}
+   */
+  RegistryEventConsumer,
+
+  /**
+   * Constant containing the list of events emitted by ServiceRegistryClient.
+   * @type {Object}
+   */
+  EVENTS
+};

package/src/queueManager.js

@@ -0,0 +1,88 @@
+/**
+ * queueManager.js
+ *
+ * Responsible for connecting to RabbitMQ and asserting/confirming the existence of queues
+ * used by the microservice connector.
+ *
+ * Overview:
+ *   - Queues managed by the microservice: 'workflow' and '<serviceName>.registry'
+ *   - On startup: assertQueue for all required queues
+ *   - Provides access to the channel for further operations (send, consume)
+ *
+ * Usage:
+ *   const qm = new QueueManager(amqpUrl, serviceName);
+ *   await qm.init();
+ *   await qm.ensureQueues();
+ *   const { channel } = qm;
+ *
+ * @module @onlineapps/connector-registry-client/src/queueManager
+ */
+
+const amqp = require('amqplib');
+
+/**
+ * Queue manager for the microservice connector.
+ */
+class QueueManager {
+  /**
+   * @param {string} amqpUrl - RabbitMQ server URL (AMQP URI)
+   * @param {string} serviceName - Name of the microservice (e.g. 'invoicing')
+   */
+  constructor(amqpUrl, serviceName) {
+    if (!amqpUrl) throw new Error('amqpUrl is required');
+    if (!serviceName) throw new Error('serviceName is required');
+    this.amqpUrl = amqpUrl;
+    this.serviceName = serviceName;
+    this.conn = null;
+    this.channel = null;
+  }
+
+  /**
+   * Initializes the connection and channel to RabbitMQ.
+   * @returns {Promise<void>} 
+   */
+  async init() {
+    this.conn = await amqp.connect(this.amqpUrl);
+    this.channel = await this.conn.createChannel();
+  }
+
+  /**
+   * Ensures all required queues exist. Creates them if they don't.
+   * @param {Array<string>} [additionalQueues=[]] - Any additional custom queues
+   * @returns {Promise<void>}
+   */
+  async ensureQueues(additionalQueues = []) {
+    if (!this.channel) {
+      throw new Error('Channel is not initialized. Call init() first.');
+    }
+
+    // Default queues for the registry client
+    const baseQueues = [
+      'workflow'
+      // Note: ${serviceName}.registry queue is created by RegistryEventConsumer when needed
+    ];
+
+    const queuesToCreate = baseQueues.concat(additionalQueues);
+
+    for (const q of queuesToCreate) {
+      await this.channel.assertQueue(q, { durable: true });
+    }
+  }
+
+  /**
+   * Closes the channel and connection.
+   * @returns {Promise<void>}
+   */
+  async close() {
+    if (this.channel) {
+      await this.channel.close();
+      this.channel = null;
+    }
+    if (this.conn) {
+      await this.conn.close();
+      this.conn = null;
+    }
+  }
+}
+
+module.exports = QueueManager;

package/src/registryClient.js

@@ -0,0 +1,397 @@
+/**
+ * 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.
+ *
+ * Events (see src/events.js):
+ *  - 'heartbeatSent'
+ *  - 'apiDescriptionRequest'
+ *  - 'apiDescriptionSent'
+ *  - 'error'
+ *
+ * @module @onlineapps/connector-registry-client/src/registryClient
+ */
+
+const EventEmitter = require('events');
+const QueueManager = require('./queueManager');
+const RegistryEventConsumer = require('./registryEventConsumer');
+const { v4: uuidv4 } = require('uuid');
+
+class ServiceRegistryClient extends EventEmitter {
+  /**
+   * @param {Object} opts
+   * @param {string} opts.amqpUrl - AMQP URI for connecting to RabbitMQ
+   * @param {string} opts.serviceName - Name of the service (e.g., 'invoicing')
+   * @param {string} opts.version - Version of the service (e.g., '1.2.0')
+   * @param {string} [opts.specificationEndpoint='/api/v1/specification'] - Endpoint where API specification is available
+   * @param {number} [opts.heartbeatInterval=10000] - Heartbeat interval in milliseconds
+   * @param {string} [opts.apiQueue='api_services_queuer'] - Queue name for heartbeat and API traffic
+   * @param {string} [opts.registryQueue='registry_office'] - Queue name for registry messages
+   */
+  constructor({ amqpUrl, serviceName, version, specificationEndpoint = '/api/v1/specification',
+                heartbeatInterval = 10000, apiQueue = 'api_services_queuer', registryQueue = 'registry_office',
+                redis = null, storageConfig = {} }) {
+    super();
+    if (!amqpUrl || !serviceName || !version) {
+      throw new Error('amqpUrl, serviceName, and version are required');
+    }
+    this.serviceName = serviceName;
+    this.version = version;
+    this.specificationEndpoint = specificationEndpoint;
+    this.heartbeatInterval = heartbeatInterval;
+    this.apiQueue = apiQueue;
+    this.registryQueue = registryQueue;
+    this.queueManager = new QueueManager(amqpUrl, serviceName);
+    this.heartbeatTimer = null;
+
+    // Event consumer (optional, activated via subscribeToChanges)
+    this.eventConsumer = null;
+    this.redis = redis;
+    this.storageConfig = storageConfig;
+  }
+
+  /**
+   * Initializes the connection, ensures queues exist, and starts consuming the service response queue.
+   * @returns {Promise<void>}
+   */
+  async init() {
+    await this.queueManager.init();
+
+    // Create service-specific response queue
+    this.serviceResponseQueue = `${this.serviceName}.responses`;
+
+    // Ensure existence of API, registry and service response queues
+    await this.queueManager.ensureQueues([this.apiQueue, this.registryQueue, this.serviceResponseQueue]);
+
+    // Start consuming service response queue for registry responses
+    await this.queueManager.channel.consume(
+      this.serviceResponseQueue,
+      msg => this._handleRegistryMessage(msg),
+      { noAck: false }
+    );
+  }
+
+  /**
+   * Internal handler for incoming messages from the registry queue.
+   * Emits 'apiDescriptionRequest' when appropriate.
+   * Handles registration responses.
+   * @param {Object} msg - AMQP message
+   * @private
+   */
+  _handleRegistryMessage(msg) {
+    let payload;
+    try {
+      payload = JSON.parse(msg.content.toString());
+    } catch (err) {
+      this.emit('error', err);
+      return this.queueManager.channel.nack(msg, false, false);
+    }
+
+    // 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 registration response from registry
+    if (payload.type === 'registerResponse' && payload.requestId) {
+      if (this.pendingRegistrations && this.pendingRegistrations.has(payload.requestId)) {
+        const { resolve } = this.pendingRegistrations.get(payload.requestId);
+        this.pendingRegistrations.delete(payload.requestId);
+
+        // Resolve the registration promise with the response
+        resolve({
+          success: payload.success || false,
+          message: payload.message || 'Registration processed',
+          serviceName: this.serviceName,
+          version: this.version,
+          registrationId: payload.registrationId,
+          validated: payload.validated || false
+        });
+      }
+    }
+
+    // Acknowledge all messages
+    this.queueManager.channel.ack(msg);
+  }
+
+  /**
+   * Registers the service with the registry.
+   * Registry will validate if the service is properly tested and valid.
+   * Upon successful validation, the service will be activated and can start heartbeats.
+   * @param {Object} serviceInfo - Service registration information
+   * @param {Array} serviceInfo.endpoints - API endpoints provided by the service
+   * @param {Object} serviceInfo.metadata - Additional service metadata
+   * @param {string} serviceInfo.health - Health check endpoint
+   * @param {Object} serviceInfo.spec - OpenAPI specification
+   * @param {number} serviceInfo.timeout - Timeout for registration response (default: 30000ms)
+   * @returns {Promise<Object>} Registration result with success status
+   */
+  async register(serviceInfo = {}) {
+    // Validate input
+    if (serviceInfo.endpoints && !Array.isArray(serviceInfo.endpoints)) {
+      throw new Error('endpoints must be an array');
+    }
+
+    const msgId = uuidv4();
+    const msg = {
+      id: msgId,
+      type: 'register',
+      serviceName: this.serviceName,
+      version: this.version,
+      specificationEndpoint: this.specificationEndpoint,
+      endpoints: serviceInfo.endpoints || [],
+      metadata: serviceInfo.metadata || {},
+      health: serviceInfo.health || '/health',
+      spec: serviceInfo.spec || null,
+      validationToken: serviceInfo.token || serviceInfo.validationToken,
+      tokenSecret: serviceInfo.secret || serviceInfo.tokenSecret,
+      responseQueue: this.serviceResponseQueue, // Queue for registry to send response
+      timestamp: new Date().toISOString()
+    };
+
+    // Create promise to wait for registration response
+    const timeout = serviceInfo.timeout || 30000; // 30 seconds default
+    const responsePromise = new Promise((resolve, reject) => {
+      // Store resolver for this registration request
+      this.pendingRegistrations = this.pendingRegistrations || new Map();
+      this.pendingRegistrations.set(msgId, { resolve, reject });
+
+      // Set timeout for registration response
+      setTimeout(() => {
+        if (this.pendingRegistrations.has(msgId)) {
+          this.pendingRegistrations.delete(msgId);
+          reject(new Error(`Registration timeout after ${timeout}ms - no response from registry`));
+        }
+      }, timeout);
+    });
+
+    // Send registration message to registry
+    await this.queueManager.channel.assertQueue(this.registryQueue, { durable: true });
+    this.queueManager.channel.sendToQueue(
+      this.registryQueue,
+      Buffer.from(JSON.stringify(msg)),
+      { persistent: true }
+    );
+
+    this.emit('registerSent', msg);
+
+    // Wait for registration response from registry
+    try {
+      const response = await responsePromise;
+      return response;
+    } catch (error) {
+      return {
+        success: false,
+        message: error.message,
+        serviceName: this.serviceName,
+        version: this.version
+      };
+    }
+  }
+
+  /**
+   * Deregisters the service from the registry.
+   * @returns {Promise<Object>} Deregistration result
+   */
+  async deregister() {
+    const msg = {
+      id: uuidv4(),
+      type: 'deregister',
+      serviceName: this.serviceName,
+      version: this.version,
+      timestamp: new Date().toISOString()
+    };
+
+    // Send deregistration message to registry
+    await this.queueManager.channel.assertQueue(this.registryQueue, { durable: true });
+    this.queueManager.channel.sendToQueue(
+      this.registryQueue,
+      Buffer.from(JSON.stringify(msg)),
+      { persistent: true }
+    );
+
+    this.emit('deregisterSent', msg);
+
+    // Stop heartbeat if running
+    this.stopHeartbeat();
+
+    return {
+      success: true,
+      message: 'Service deregistered successfully',
+      serviceName: this.serviceName,
+      version: this.version
+    };
+  }
+
+  /**
+   * Sends a heartbeat message to the API queue.
+   * Should be called only after successful registration.
+   * Emits 'heartbeatSent'.
+   * @returns {Promise<void>}
+   */
+  async sendHeartbeat() {
+    const msg = {
+      id: uuidv4(),
+      type: 'heartbeat',
+      serviceName: this.serviceName,
+      version: this.version,
+      specificationEndpoint: this.specificationEndpoint,
+      timestamp: new Date().toISOString()
+    };
+    await this.queueManager.channel.assertQueue(this.registryQueue, { durable: true });
+    this.queueManager.channel.sendToQueue(
+      this.registryQueue,
+      Buffer.from(JSON.stringify(msg)),
+      { persistent: true }
+    );
+    this.emit('heartbeatSent', msg);
+  }
+
+  /**
+   * Starts periodic heartbeat messages.
+   */
+  startHeartbeat() {
+    // Send immediately after init
+    this.sendHeartbeat();
+    // Repeat at the configured interval
+    this.heartbeatTimer = setInterval(
+      () => this.sendHeartbeat(),
+      this.heartbeatInterval
+    );
+  }
+
+  /**
+   * Stops periodic heartbeat messages.
+   */
+  stopHeartbeat() {
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+  }
+
+  /**
+   * 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()
+    };
+    await this.queueManager.channel.assertQueue(this.registryQueue, { durable: true });
+    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 response = await fetch(`http://localhost:${process.env.PORT || 3000}${this.specificationEndpoint}`);
+        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
+   * @returns {Promise<void>}
+   */
+  async subscribeToChanges() {
+    if (!this.eventConsumer) {
+      this.eventConsumer = new RegistryEventConsumer({
+        queueManager: this.queueManager,
+        serviceName: this.serviceName,
+        redis: this.redis,
+        storageConfig: this.storageConfig
+      });
+
+      // Forward events from consumer
+      this.eventConsumer.on('serviceUpdated', data => this.emit('serviceUpdated', data));
+      this.eventConsumer.on('statusChanged', data => this.emit('statusChanged', data));
+      this.eventConsumer.on('snapshotReceived', data => this.emit('snapshotReceived', data));
+      this.eventConsumer.on('error', err => this.emit('error', err));
+
+      // Initialize storage and subscribe
+      await this.eventConsumer.initStorage();
+      await this.eventConsumer.subscribeToChanges();
+    }
+  }
+
+  /**
+   * Get service spec from event consumer (requires subscribeToChanges)
+   * @param {string} serviceName - Name of the service
+   * @returns {Promise<Object>} - Service specification
+   */
+  async getServiceSpec(serviceName) {
+    if (!this.eventConsumer) {
+      throw new Error('Event consumer not initialized. Call subscribeToChanges() first.');
+    }
+    return this.eventConsumer.getServiceSpec(serviceName);
+  }
+
+  /**
+   * Check if service is active (requires subscribeToChanges)
+   * @param {string} serviceName - Name of the service
+   * @returns {boolean}
+   */
+  isServiceActive(serviceName) {
+    if (!this.eventConsumer) {
+      throw new Error('Event consumer not initialized. Call subscribeToChanges() first.');
+    }
+    return this.eventConsumer.isServiceActive(serviceName);
+  }
+
+  /**
+   * Get list of active services (requires subscribeToChanges)
+   * @returns {Array<string>}
+   */
+  getActiveServices() {
+    if (!this.eventConsumer) {
+      return [];
+    }
+    return this.eventConsumer.getActiveServices();
+  }
+
+  /**
+   * Releases resources: stops heartbeat and closes connection.
+   * @returns {Promise<void>}
+   */
+  async close() {
+    this.stopHeartbeat();
+    if (this.eventConsumer) {
+      this.eventConsumer.clearCache();
+    }
+    await this.queueManager.close();
+  }
+}
+
+module.exports = { ServiceRegistryClient };