@onlineapps/infrastructure-tools 1.0.0

package/README.md

@@ -0,0 +1,133 @@
+# @onlineapps/infrastructure-tools
+
+Infrastructure orchestration utilities for OA Drive infrastructure services.
+
+## Purpose
+
+This library provides utilities for infrastructure services to coordinate their initialization, health tracking, and queue management. It is **NOT** intended for business services.
+
+## Installation
+
+```bash
+npm install @onlineapps/infrastructure-tools
+```
+
+## Usage
+
+### Health Publisher
+
+Publish health checks to `infrastructure.health.checks` queue:
+
+```javascript
+const { createBaseClientAdapter } = require('@onlineapps/infrastructure-tools');
+const BaseClient = require('@onlineapps/mq-client-core');
+
+const mqClient = new BaseClient({ ... });
+await mqClient.connect();
+
+const healthPublisher = createBaseClientAdapter(
+  mqClient,
+  'gateway',
+  () => ({
+    mq: mqClient.isConnected() ? 'healthy' : 'unhealthy',
+    redis: 'healthy',
+    http: 'healthy'
+  }),
+  config.infrastructureHealth,
+  logger
+);
+
+await healthPublisher.start();
+```
+
+### Wait for Infrastructure Ready
+
+Wait for all infrastructure services to be ready before creating queues:
+
+```javascript
+const { waitForInfrastructureReady } = require('@onlineapps/infrastructure-tools');
+
+await waitForInfrastructureReady({
+  redisUrl: 'redis://api_node_cache:6379',
+  maxWait: 300000, // 5 minutes
+  checkInterval: 5000, // 5 seconds
+  logger: logger
+});
+```
+
+### Initialize Infrastructure Queues
+
+Initialize infrastructure queues with correct parameters:
+
+```javascript
+const { initInfrastructureQueues } = require('@onlineapps/infrastructure-tools');
+
+await initInfrastructureQueues(channel, {
+  queues: ['workflow.init'], // Only create specific queues
+  connection: connection,
+  logger: logger
+});
+```
+
+## API
+
+### `waitForInfrastructureReady(options)`
+
+Waits for all infrastructure services to be reported as healthy by Registry.
+
+**Options:**
+- `redisUrl` (string): Redis URL (default: from ENV or `redis://api_node_cache:6379`)
+- `maxWait` (number): Maximum wait time in ms (default: 300000 = 5 minutes)
+- `checkInterval` (number): Check interval in ms (default: 5000 = 5 seconds)
+- `logger` (Object): Logger instance (default: console)
+
+**Returns:** `Promise<boolean>`
+
+### `initInfrastructureQueues(channel, options)`
+
+Initializes infrastructure queues with correct parameters from `queueConfig`.
+
+**Options:**
+- `queues` (Array<string>): Specific queues to create (default: all infrastructure queues)
+- `connection` (Object): RabbitMQ connection (for channel recreation)
+- `logger` (Object): Logger instance (default: console)
+- `queueConfig` (Object): Queue config instance (default: from mq-client-core)
+
+**Returns:** `Promise<void>`
+
+### `createHealthPublisher(options)`
+
+Creates a health publisher instance with custom publish function.
+
+**Options:**
+- `serviceName` (string): Service name (required)
+- `version` (string): Service version (default: '1.0.0')
+- `publishFunction` (Function): Function to publish message (required)
+- `getHealthData` (Function): Function to get health data (required)
+- `config` (Object): Configuration with `infrastructureHealth` settings
+- `logger` (Object): Logger instance (default: console)
+
+**Returns:** Health publisher instance with `start()`, `stop()`, `publishNow()` methods
+
+### `createBaseClientAdapter(baseClient, serviceName, getHealthData, config, logger)`
+
+Creates health publisher adapter for BaseClient (from mq-client-core).
+
+### `createAmqplibAdapter(connection, channel, serviceName, getHealthData, config, logger)`
+
+Creates health publisher adapter for amqplib (direct connection + channel).
+
+## Dependencies
+
+- `@onlineapps/mq-client-core` - For queue configuration
+- `redis` - For health status checking
+
+## Related Libraries
+
+- `@onlineapps/mq-client-core` - Core MQ operations and queue configuration
+- `@onlineapps/monitoring-core` - Business monitoring (traces, metrics, logs)
+
+## License
+
+MIT
+

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@onlineapps/infrastructure-tools",
+  "version": "1.0.0",
+  "description": "Infrastructure orchestration utilities for OA Drive infrastructure services (health tracking, queue initialization, service discovery)",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "jest",
+    "test:unit": "jest --testPathPattern=tests/unit",
+    "test:component": "jest --testPathPattern=tests/component",
+    "test:integration": "jest --testPathPattern=tests/integration"
+  },
+  "keywords": [
+    "infrastructure",
+    "orchestration",
+    "health-tracking",
+    "service-discovery"
+  ],
+  "author": "OnlineApps",
+  "license": "MIT",
+  "dependencies": {
+    "@onlineapps/mq-client-core": "^1.0.24",
+    "redis": "^4.6.0"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+

package/src/health/healthPublisher.js

@@ -0,0 +1,209 @@
+'use strict';
+
+/**
+ * Infrastructure Health Publisher
+ * 
+ * Publishes health check messages to infrastructure.health.checks queue.
+ * Used by infrastructure services to report their health status to Registry.
+ * 
+ * Supports multiple MQ abstractions via adapter pattern:
+ * - BaseClient (from mq-client-core)
+ * - amqplib directly (connection + channel)
+ * - Custom publish function
+ */
+
+/**
+ * Create infrastructure health publisher
+ * @param {Object} options - Configuration options
+ * @param {string} options.serviceName - Service name (e.g., 'gateway', 'registry', 'validator')
+ * @param {string} [options.version] - Service version (default: '1.0.0')
+ * @param {Function} options.publishFunction - Function to publish message: async (queueName, data) => void
+ * @param {Function} options.getHealthData - Function to get current health status: () => Object
+ * @param {Object} [options.config] - Configuration object with infrastructureHealth settings
+ * @param {string} [options.config.queueName] - Queue name (default: 'infrastructure.health.checks')
+ * @param {number} [options.config.publishInterval] - Publish interval in ms (default: 5000)
+ * @param {Object} [options.logger] - Logger instance (default: console)
+ * @returns {Object} Health publisher instance
+ */
+function createHealthPublisher(options) {
+  const {
+    serviceName,
+    version = '1.0.0',
+    publishFunction,
+    getHealthData,
+    config = {},
+    logger = console
+  } = options;
+
+  if (!serviceName) {
+    throw new Error('serviceName is required');
+  }
+  if (typeof publishFunction !== 'function') {
+    throw new Error('publishFunction must be a function');
+  }
+  if (typeof getHealthData !== 'function') {
+    throw new Error('getHealthData must be a function');
+  }
+
+  let healthCheckInterval = null;
+  let isPublishing = false;
+
+  const queueName = config.queueName || config.infrastructureHealth?.queueName || process.env.INFRASTRUCTURE_HEALTH_QUEUE || 'infrastructure.health.checks';
+  const publishInterval = config.publishInterval || config.infrastructureHealth?.publishInterval || parseInt(process.env.INFRASTRUCTURE_HEALTH_PUBLISH_INTERVAL) || 5000;
+
+  /**
+   * Publish health check to infrastructure.health.checks queue
+   * @returns {Promise<void>}
+   */
+  async function publishHealthCheck() {
+    if (isPublishing) {
+      logger.warn(`[InfrastructureHealth:${serviceName}] Health check already in progress, skipping`);
+      return;
+    }
+
+    try {
+      isPublishing = true;
+      const healthData = {
+        serviceName,
+        version,
+        status: 'UP',
+        timestamp: new Date().toISOString(),
+        components: getHealthData()
+      };
+      
+      await publishFunction(queueName, healthData);
+      
+      logger.debug(`[InfrastructureHealth:${serviceName}] Published health check`, {
+        queue: queueName,
+        status: healthData.status
+      });
+    } catch (error) {
+      logger.error(`[InfrastructureHealth:${serviceName}] Failed to publish health check`, {
+        error: error.message,
+        stack: error.stack
+      });
+    } finally {
+      isPublishing = false;
+    }
+  }
+
+  /**
+   * Start publishing health checks periodically
+   * @returns {Promise<void>}
+   */
+  async function start() {
+    if (healthCheckInterval) {
+      logger.warn(`[InfrastructureHealth:${serviceName}] Health check publisher already started`);
+      return;
+    }
+
+    // Publish initial health check immediately
+    await publishHealthCheck();
+    
+    // Then publish periodically
+    healthCheckInterval = setInterval(() => {
+      publishHealthCheck().catch(err => {
+        logger.error(`[InfrastructureHealth:${serviceName}] Error in health check publisher interval`, {
+          error: err.message
+        });
+      });
+    }, publishInterval);
+    
+    logger.info(`[InfrastructureHealth:${serviceName}] Health check publisher started`, {
+      interval: publishInterval,
+      queue: queueName
+    });
+  }
+
+  /**
+   * Stop publishing health checks
+   */
+  function stop() {
+    if (healthCheckInterval) {
+      clearInterval(healthCheckInterval);
+      healthCheckInterval = null;
+      logger.info(`[InfrastructureHealth:${serviceName}] Health check publisher stopped`);
+    }
+  }
+
+  /**
+   * Publish health check immediately (manual trigger)
+   * @returns {Promise<void>}
+   */
+  async function publishNow() {
+    await publishHealthCheck();
+  }
+
+  return {
+    start,
+    stop,
+    publishNow,
+    isRunning: () => healthCheckInterval !== null
+  };
+}
+
+/**
+ * Create health publisher adapter for BaseClient (from mq-client-core)
+ * @param {Object} baseClient - BaseClient instance
+ * @param {string} serviceName - Service name
+ * @param {Function} getHealthData - Function to get health data
+ * @param {Object} config - Configuration
+ * @param {Object} logger - Logger instance
+ * @returns {Object} Health publisher instance
+ */
+function createBaseClientAdapter(baseClient, serviceName, getHealthData, config, logger) {
+  const publishFunction = async (queueName, data) => {
+    if (!baseClient || typeof baseClient.publish !== 'function') {
+      throw new Error('BaseClient instance must have publish() method');
+    }
+    await baseClient.publish(queueName, data);
+  };
+
+  return createHealthPublisher({
+    serviceName,
+    publishFunction,
+    getHealthData,
+    config,
+    logger
+  });
+}
+
+/**
+ * Create health publisher adapter for amqplib (connection + channel)
+ * @param {Object} connection - AMQP connection
+ * @param {Object} channel - AMQP channel
+ * @param {string} serviceName - Service name
+ * @param {Function} getHealthData - Function to get health data
+ * @param {Object} config - Configuration
+ * @param {Object} logger - Logger instance
+ * @returns {Object} Health publisher instance
+ */
+function createAmqplibAdapter(connection, channel, serviceName, getHealthData, config, logger) {
+  const publishFunction = async (queueName, data) => {
+    if (!channel || channel.closed) {
+      throw new Error('AMQP channel is not available or closed');
+    }
+    // Ensure queue exists (it should be created by Registry, but assert just in case)
+    await channel.assertQueue(queueName, { durable: true });
+    await channel.sendToQueue(
+      queueName,
+      Buffer.from(JSON.stringify(data)),
+      { persistent: true }
+    );
+  };
+
+  return createHealthPublisher({
+    serviceName,
+    publishFunction,
+    getHealthData,
+    config,
+    logger
+  });
+}
+
+module.exports = {
+  createHealthPublisher,
+  createBaseClientAdapter,
+  createAmqplibAdapter
+};
+

package/src/index.js

@@ -0,0 +1,31 @@
+'use strict';
+
+/**
+ * @onlineapps/infrastructure-tools
+ * 
+ * Infrastructure orchestration utilities for OA Drive infrastructure services.
+ * Provides health tracking, queue initialization, and service discovery utilities.
+ * 
+ * NOTE: This library is for infrastructure services only.
+ * Business services should NOT use this library.
+ */
+
+const { waitForInfrastructureReady } = require('./orchestration/waitForInfrastructureReady');
+const { initInfrastructureQueues } = require('./orchestration/initInfrastructureQueues');
+const {
+  createHealthPublisher,
+  createBaseClientAdapter,
+  createAmqplibAdapter
+} = require('./health/healthPublisher');
+
+module.exports = {
+  // Orchestration utilities
+  waitForInfrastructureReady,
+  initInfrastructureQueues,
+  
+  // Health tracking utilities
+  createHealthPublisher,
+  createBaseClientAdapter,
+  createAmqplibAdapter
+};
+

package/src/orchestration/initInfrastructureQueues.js

@@ -0,0 +1,145 @@
+'use strict';
+
+/**
+ * initInfrastructureQueues.js
+ * 
+ * Utility for infrastructure services to initialize infrastructure queues.
+ * Uses queueConfig from @onlineapps/mq-client-core for configuration.
+ * 
+ * NOTE: This is for infrastructure services (gateway, monitoring, etc.)
+ * Business services should use @onlineapps/conn-infra-mq connector instead.
+ */
+
+/**
+ * Initialize all infrastructure queues
+ * @param {Object} channel - RabbitMQ channel
+ * @param {Object} options - Options
+ * @param {Array<string>} [options.queues] - Specific queues to create (default: all infrastructure queues)
+ * @param {Object} [options.logger] - Logger instance (default: console)
+ * @param {Object} [options.connection] - RabbitMQ connection (for channel recreation)
+ * @param {Object} [options.queueConfig] - Queue config instance (default: from mq-client-core)
+ * @returns {Promise<void>}
+ */
+async function initInfrastructureQueues(channel, options = {}) {
+  if (!channel) {
+    throw new Error('initInfrastructureQueues requires a valid channel');
+  }
+
+  const logger = options.logger || console;
+  const connection = options.connection || channel.connection;
+  
+  // Load queueConfig from mq-client-core
+  // NOTE: queueConfig is part of mq-client-core because it's used by both:
+  // - Infrastructure services (via infrastructure-tools)
+  // - Business services (via conn-infra-mq connector)
+  const queueConfig = options.queueConfig || require('@onlineapps/mq-client-core/src/config/queueConfig');
+
+  const queuesToCreate = options.queues || [
+    // Workflow infrastructure queues
+    'workflow.init',
+    'workflow.completed',
+    'workflow.failed',
+    'workflow.dlq',
+    // Registry infrastructure queues
+    'registry.register',
+    'registry.heartbeats'
+  ];
+
+  const watchChannel = (ch) => {
+    if (!ch) return ch;
+    if (!ch.__queueInitLinked) {
+      ch.__queueInitLinked = true;
+      ch.once('close', () => {
+        ch.__queueInitClosed = true;
+        logger.warn('[QueueInit] Queue channel closed');
+      });
+      ch.on('error', (err) => {
+        ch.__queueInitClosed = true;
+        logger.warn(`[QueueInit] Queue channel error: ${err.message}`);
+      });
+    }
+    return ch;
+  };
+
+  let workingChannel = watchChannel(channel);
+
+  const getChannel = async (forceNew = false) => {
+    if (!forceNew && workingChannel && !workingChannel.__queueInitClosed) {
+      return workingChannel;
+    }
+    if (!connection) {
+      throw new Error('Queue channel closed and no connection reference available to recreate it');
+    }
+    workingChannel = watchChannel(await connection.createChannel());
+    return workingChannel;
+  };
+
+  logger.log(`[QueueInit] Initializing ${queuesToCreate.length} infrastructure queues...`);
+
+  for (const queueName of queuesToCreate) {
+    try {
+      // Verify it's an infrastructure queue
+      if (!queueConfig.isInfrastructureQueue(queueName)) {
+        logger.warn(`[QueueInit] Skipping ${queueName} - not an infrastructure queue`);
+        continue;
+      }
+
+      // Get unified configuration
+      const config = queueConfig.getInfrastructureQueueConfig(queueName);
+      
+      // CRITICAL: Check if queue exists with different arguments (406 error)
+      // If so, delete it and recreate with correct parameters
+      const ensureQueue = async () => {
+        const activeChannel = await getChannel();
+        return activeChannel.assertQueue(queueName, {
+          durable: config.durable !== false,
+          arguments: { ...config.arguments }
+        });
+      };
+
+      try {
+        await ensureQueue();
+        logger.log(`[QueueInit] ✓ Created/verified infrastructure queue: ${queueName}`);
+      } catch (assertError) {
+        if (assertError.code === 406) {
+          logger.warn(
+            `[QueueInit] ⚠ Queue ${queueName} exists with different arguments - deleting and recreating...`
+          );
+          try {
+            const deleteChannel = await getChannel(true);
+            await deleteChannel.deleteQueue(queueName);
+            logger.log(`[QueueInit] ✓ Deleted queue ${queueName} with incorrect parameters`);
+          } catch (deleteError) {
+            logger.error(
+              `[QueueInit] ✗ Failed to delete queue ${queueName}:`,
+              deleteError.message
+            );
+            throw new Error(
+              `Cannot delete queue ${queueName} with incorrect parameters: ${deleteError.message}`
+            );
+          }
+
+          // Recreate with correct parameters (force fresh channel to avoid closed state)
+          await getChannel(true);
+          await ensureQueue();
+          logger.log(
+            `[QueueInit] ✓ Recreated infrastructure queue: ${queueName} with correct parameters`
+          );
+        } else {
+          logger.error(`[QueueInit] ✗ Failed to create ${queueName}:`, assertError.message);
+          throw assertError;
+        }
+      }
+    } catch (error) {
+      logger.error(`[QueueInit] ✗ Failed to initialize queue ${queueName}:`, error.message);
+      throw error;
+    }
+  }
+
+  logger.log(`[QueueInit] Infrastructure queues initialization complete`);
+}
+
+module.exports = {
+  initInfrastructureQueues
+};
+

package/src/orchestration/waitForInfrastructureReady.js

@@ -0,0 +1,125 @@
+'use strict';
+
+/**
+ * waitForInfrastructureReady.js
+ * 
+ * Waits for all infrastructure services to be verified as running and healthy.
+ * Used by infrastructure services before creating queues to ensure system consistency.
+ * 
+ * This prevents race conditions where queues are created before all services are ready.
+ * 
+ * **How it works:**
+ * 1. Connects to Redis (where Registry stores infrastructure health status)
+ * 2. Checks `infrastructure:health:all` key every 5 seconds
+ * 3. If key is `"true"` → all infrastructure services are UP → return success
+ * 4. If key is `"false"` or missing → wait and retry
+ * 5. If timeout reached → throw error
+ * 
+ * **Why Redis (not HTTP):**
+ * - Fast: In-memory lookup, no network overhead
+ * - Reliable: Redis is already required infrastructure
+ * - Low latency: Direct key lookup, no HTTP parsing
+ * - Consistent: Same data source as Registry uses
+ * - No single point of failure: Redis can be clustered
+ */
+
+/**
+ * Wait for all infrastructure services to be ready
+ * @param {Object} options - Options
+ * @param {string} [options.redisUrl] - Redis URL (default: REDIS_URL env or redis://api_node_cache:6379)
+ * @param {number} [options.maxWait] - Maximum wait time in ms (default: INFRASTRUCTURE_HEALTH_WAIT_MAX_TIME env or 300000 = 5 minutes)
+ * @param {number} [options.checkInterval] - Check interval in ms (default: INFRASTRUCTURE_HEALTH_WAIT_CHECK_INTERVAL env or 5000 = 5 seconds)
+ * @param {Object} [options.logger] - Logger instance (default: console)
+ * @returns {Promise<boolean>} - True if all infrastructure services are ready
+ * @throws {Error} - If timeout is reached
+ * 
+ * Note: Default values can be overridden via ENV variables or options parameter.
+ * Registry config (config.infrastructureHealth) is the source of truth for these defaults.
+ */
+async function waitForInfrastructureReady(options = {}) {
+  const redisUrl = options.redisUrl || process.env.REDIS_URL || 'redis://api_node_cache:6379';
+  const maxWait = options.maxWait || parseInt(process.env.INFRASTRUCTURE_HEALTH_WAIT_MAX_TIME) || 300000; // 5 minutes
+  const checkInterval = options.checkInterval || parseInt(process.env.INFRASTRUCTURE_HEALTH_WAIT_CHECK_INTERVAL) || 5000; // 5 seconds
+  const logger = options.logger || console;
+
+  const startTime = Date.now();
+  let attemptCount = 0;
+  let redis = null;
+
+  logger.log('[InfrastructureReady] Waiting for all infrastructure services to be ready...');
+  logger.log(`[InfrastructureReady] Redis URL: ${redisUrl}`);
+  logger.log(`[InfrastructureReady] Max wait: ${maxWait}ms, Check interval: ${checkInterval}ms`);
+
+  try {
+    // Connect to Redis
+    const { createClient } = require('redis');
+    redis = createClient({ url: redisUrl });
+    
+    redis.on('error', (err) => {
+      logger.log(`[InfrastructureReady] Redis error: ${err.message}`);
+    });
+    
+    await redis.connect();
+    logger.log('[InfrastructureReady] Connected to Redis');
+
+    while (Date.now() - startTime < maxWait) {
+      attemptCount++;
+      
+      try {
+        // Check Redis key: infrastructure:health:all
+        const allHealthy = await redis.get('infrastructure:health:all');
+        
+        if (allHealthy === 'true') {
+          // All services are UP, we can proceed
+          const elapsed = Date.now() - startTime;
+          logger.log(`[InfrastructureReady] ✓ All infrastructure services are ready (took ${elapsed}ms, ${attemptCount} attempts)`);
+          
+          // Optionally log individual service status
+          // Note: Service names should match config.infrastructureServices in Registry
+          const serviceKeys = ['gateway', 'registry', 'validator', 'delivery', 'monitoring'];
+          const statuses = {};
+          for (const serviceName of serviceKeys) {
+            const status = await redis.get(`infrastructure:health:${serviceName}`);
+            if (status) {
+              statuses[serviceName] = JSON.parse(status);
+            }
+          }
+          logger.log(`[InfrastructureReady] Infrastructure status:`, JSON.stringify(statuses, null, 2));
+          
+          return true;
+        }
+
+        // Not all services ready yet
+        logger.log(`[InfrastructureReady] Attempt ${attemptCount}: Not all services ready (allHealthy: ${allHealthy || 'null'})`);
+        logger.log(`[InfrastructureReady] Waiting ${checkInterval}ms before next check...`);
+
+      } catch (error) {
+        // Redis might not be ready yet, or connection issue
+        logger.log(`[InfrastructureReady] Attempt ${attemptCount}: Redis check failed (${error.message})`);
+        logger.log(`[InfrastructureReady] Waiting ${checkInterval}ms before retry...`);
+      }
+
+      // Wait before next check
+      await new Promise(resolve => setTimeout(resolve, checkInterval));
+    }
+
+    // Timeout reached
+    const elapsed = Date.now() - startTime;
+    throw new Error(
+      `Infrastructure services not ready within ${maxWait}ms (${elapsed}ms elapsed, ${attemptCount} attempts). ` +
+      `Check Redis keys: infrastructure:health:*`
+    );
+
+  } finally {
+    // Clean up Redis connection
+    if (redis && redis.isReady) {
+      await redis.quit();
+      logger.log('[InfrastructureReady] Redis connection closed');
+    }
+  }
+}
+
+module.exports = {
+  waitForInfrastructureReady
+};
+