@onlineapps/conn-orch-orchestrator 1.0.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@onlineapps/conn-orch-orchestrator",
+  "version": "1.0.0",
+  "description": "Workflow orchestration connector for OA Drive - handles message routing and workflow execution",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src/",
+    "docs": "jsdoc2md --files src/**/*.js > API.md"
+  },
+  "keywords": [
+    "workflow",
+    "orchestration",
+    "message-routing",
+    "cookbook",
+    "connector"
+  ],
+  "author": "OA Drive Team",
+  "license": "MIT",
+  "dependencies": {
+    "@onlineapps/conn-base-logger": "^1.0.0",
+    "@onlineapps/conn-infra-mq": "^1.0.0",
+    "@onlineapps/conn-orch-registry": "^1.0.0",
+    "@onlineapps/conn-orch-cookbook": "^1.0.0",
+    "@onlineapps/conn-orch-api-mapper": "^1.0.0"
+  },
+  "devDependencies": {
+    "jest": "^29.5.0",
+    "eslint": "^8.30.0",
+    "jsdoc-to-markdown": "^8.0.0"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "coverageDirectory": "coverage",
+    "collectCoverageFrom": [
+      "src/**/*.js"
+    ]
+  }
+}

package/src/WorkflowOrchestrator.js

@@ -0,0 +1,341 @@
+'use strict';
+
+/**
+ * @class WorkflowOrchestrator
+ * @description Main orchestration class that coordinates all workflow execution.
+ * Handles message routing, step execution, and workflow state management.
+ *
+ * This is the core logic moved from service-wrapper's WorkflowProcessor to make
+ * service-wrapper a true thin orchestration layer.
+ */
+class WorkflowOrchestrator {
+  /**
+   * Create a new WorkflowOrchestrator instance
+   * @constructor
+   * @param {Object} config - Configuration object
+   * @param {Object} config.mqClient - MQ client for message operations
+   * @param {Object} config.registryClient - Registry client for service discovery
+   * @param {Object} config.apiMapper - API mapper for cookbook to HTTP mapping
+   * @param {Object} config.cookbook - Cookbook connector for validation and execution
+   * @param {Object} [config.cache] - Cache connector for caching
+   * @param {Object} [config.errorHandler] - Error handler connector
+   * @param {Object} [config.logger] - Logger instance
+   * @param {number} [config.defaultTimeout=30000] - Default timeout for operations
+   */
+  constructor(config) {
+    if (!config.mqClient) throw new Error('mqClient is required');
+    if (!config.registryClient) throw new Error('registryClient is required');
+    if (!config.apiMapper) throw new Error('apiMapper is required');
+    if (!config.cookbook) throw new Error('cookbook is required');
+
+    this.mqClient = config.mqClient;
+    this.registryClient = config.registryClient;
+    this.apiMapper = config.apiMapper;
+    this.cookbook = config.cookbook;
+    this.cache = config.cache;
+    this.errorHandler = config.errorHandler;
+    this.logger = config.logger || console;
+    this.defaultTimeout = config.defaultTimeout || 30000;
+
+    // Create cookbook router
+    this.router = this.cookbook.createRouter(this.mqClient, this.registryClient, {
+      logger: this.logger
+    });
+  }
+
+  /**
+   * Process a workflow message
+   * @async
+   * @method processWorkflowMessage
+   * @param {Object} message - Workflow message from queue
+   * @param {string} message.workflow_id - Workflow ID
+   * @param {Object} message.cookbook - Cookbook definition
+   * @param {string} message.current_step - Current step ID
+   * @param {Object} message.context - Workflow context
+   * @param {string} serviceName - Name of the service processing this
+   * @returns {Promise<Object>} Processing result
+   *
+   * @example
+   * const result = await orchestrator.processWorkflowMessage({
+   *   workflow_id: 'wf-123',
+   *   cookbook: cookbookDef,
+   *   current_step: 'step1',
+   *   context: {}
+   * }, 'hello-service');
+   */
+  async processWorkflowMessage(message, serviceName) {
+    const { workflow_id, cookbook: cookbookDef, current_step, context } = message;
+
+    try {
+      // Validate cookbook structure
+      this.cookbook.validateCookbook(cookbookDef);
+
+      // Find current step
+      const step = cookbookDef.steps.find(s => s.id === current_step);
+      if (!step) {
+        throw new Error(`Step not found: ${current_step}`);
+      }
+
+      // Check if this step is for this service
+      if (step.type === 'task' && step.service !== serviceName) {
+        this.logger.warn(`Step ${current_step} is for ${step.service}, not ${serviceName}`);
+        await this.router.routeToService(step.service, message);
+        return { skipped: true, reason: 'wrong_service' };
+      }
+
+      // Check cache if available
+      let result;
+      if (this.cache && step.type === 'task') {
+        const cacheKey = this._getCacheKey(step, context);
+        result = await this.cache.get(cacheKey);
+
+        if (result) {
+          this.logger.info('Cache hit', { step: step.id, cacheKey });
+        } else {
+          // Execute the step
+          result = await this._executeStep(step, context, cookbookDef);
+          await this.cache.set(cacheKey, result, { ttl: 300 });
+        }
+      } else {
+        // Execute without cache
+        result = await this._executeStep(step, context, cookbookDef);
+      }
+
+      // Update context with result
+      const updatedContext = {
+        ...context,
+        steps: {
+          ...context.steps,
+          [current_step]: result
+        }
+      };
+
+      // Find next step
+      const currentIndex = cookbookDef.steps.findIndex(s => s.id === current_step);
+      const nextStep = cookbookDef.steps[currentIndex + 1];
+
+      if (nextStep) {
+        // Route to next step
+        await this._routeToNextStep(nextStep, cookbookDef, updatedContext, workflow_id);
+      } else {
+        // Workflow completed
+        await this._completeWorkflow(workflow_id, updatedContext);
+      }
+
+      return {
+        success: true,
+        workflow_id,
+        step_id: current_step,
+        result
+      };
+
+    } catch (error) {
+      this.logger.error(`Workflow processing failed: ${error.message}`, {
+        workflow_id,
+        current_step,
+        error: error.stack
+      });
+
+      // Handle error
+      if (this.errorHandler) {
+        await this.errorHandler.handleError(error, {
+          workflow_id,
+          current_step,
+          service: serviceName,
+          context
+        });
+      } else {
+        // Fallback to router DLQ
+        await this.router.routeToDLQ(cookbookDef, context, error, serviceName);
+      }
+
+      throw error;
+    }
+  }
+
+  /**
+   * Execute a single step
+   * @private
+   * @async
+   * @param {Object} step - Step to execute
+   * @param {Object} context - Execution context
+   * @param {Object} cookbookDef - Full cookbook definition
+   * @returns {Promise<Object>} Step result
+   */
+  async _executeStep(step, context, cookbookDef) {
+    if (step.type === 'task') {
+      // Task step - call service API
+      return await this._executeTaskStep(step, context);
+    } else {
+      // Control flow step - use cookbook executor
+      return await this._executeControlFlowStep(step, context, cookbookDef);
+    }
+  }
+
+  /**
+   * Execute a task step by calling service API
+   * @private
+   * @async
+   * @param {Object} step - Task step
+   * @param {Object} context - Execution context
+   * @returns {Promise<Object>} API call result
+   */
+  async _executeTaskStep(step, context) {
+    // Use API mapper to call the service
+    const result = await this.apiMapper.callOperation(
+      step.operation || step.id,
+      step.input,
+      context
+    );
+
+    this.logger.info(`Task step executed`, {
+      step: step.id,
+      service: step.service,
+      operation: step.operation
+    });
+
+    return result;
+  }
+
+  /**
+   * Execute control flow step (foreach, switch, fork_join, etc)
+   * @private
+   * @async
+   * @param {Object} step - Control flow step
+   * @param {Object} context - Execution context
+   * @param {Object} cookbookDef - Full cookbook definition
+   * @returns {Promise<Object>} Control flow result
+   */
+  async _executeControlFlowStep(step, context, cookbookDef) {
+    const { CookbookExecutor } = this.cookbook;
+
+    // Create executor for control flow
+    const executor = new CookbookExecutor(
+      { steps: [step] },
+      {
+        logger: this.logger,
+        defaultTimeout: this.defaultTimeout
+      }
+    );
+
+    // Set context
+    executor.context.setInput(context.api_input || {});
+    executor.context.data.steps = context.steps || {};
+
+    // Execute the control flow step
+    const result = await executor.executeStep(step);
+
+    this.logger.info(`Control flow step executed`, {
+      step: step.id,
+      type: step.type
+    });
+
+    return result;
+  }
+
+  /**
+   * Route to next step in workflow
+   * @private
+   * @async
+   * @param {Object} nextStep - Next step to execute
+   * @param {Object} cookbookDef - Full cookbook definition
+   * @param {Object} context - Updated context
+   * @param {string} workflow_id - Workflow ID
+   */
+  async _routeToNextStep(nextStep, cookbookDef, context, workflow_id) {
+    const message = {
+      workflow_id,
+      cookbook: cookbookDef,
+      current_step: nextStep.id,
+      context
+    };
+
+    if (nextStep.type === 'task') {
+      // Route to specific service
+      await this.router.routeToService(nextStep.service, message);
+      this.logger.info(`Routed to service: ${nextStep.service}`, {
+        step: nextStep.id
+      });
+    } else {
+      // Control flow steps handled by workflow init queue
+      await this.mqClient.publish('workflow.init', message);
+      this.logger.info(`Routed control flow to workflow.init`, {
+        step: nextStep.id
+      });
+    }
+  }
+
+  /**
+   * Complete workflow
+   * @private
+   * @async
+   * @param {string} workflow_id - Workflow ID
+   * @param {Object} finalContext - Final workflow context
+   */
+  async _completeWorkflow(workflow_id, finalContext) {
+    await this.mqClient.publish('workflow.completed', {
+      workflow_id,
+      result: finalContext,
+      completed_at: new Date().toISOString()
+    });
+
+    this.logger.info(`Workflow completed: ${workflow_id}`);
+  }
+
+  /**
+   * Generate cache key for a step
+   * @private
+   * @param {Object} step - Step object
+   * @param {Object} context - Execution context
+   * @returns {string} Cache key
+   */
+  _getCacheKey(step, context) {
+    const crypto = require('crypto');
+    const data = JSON.stringify({
+      service: step.service,
+      operation: step.operation || step.id,
+      input: step.input,
+      contextInput: context.api_input
+    });
+    const hash = crypto.createHash('sha256').update(data).digest('hex');
+    return `workflow:step:${step.service}:${step.operation || step.id}:${hash}`;
+  }
+
+  /**
+   * Generate cookbook from OpenAPI spec (utility method)
+   * @method generateCookbook
+   * @param {Object} openApiSpec - OpenAPI specification
+   * @returns {Object} Generated cookbook
+   *
+   * @example
+   * const cookbook = orchestrator.generateCookbook(openApiSpec);
+   */
+  generateCookbook(openApiSpec) {
+    const { CookbookGenerator } = this.cookbook;
+
+    const generator = new CookbookGenerator({
+      defaultTimeout: 10000,
+      defaultRetry: {
+        maxAttempts: 3,
+        delayMs: 2000
+      }
+    });
+
+    return generator.generate(openApiSpec);
+  }
+
+  /**
+   * Transform API response using cookbook mapping
+   * @method transformResponse
+   * @param {Object} response - API response
+   * @param {Object} mapping - Output mapping
+   * @returns {Object} Transformed response
+   */
+  transformResponse(response, mapping) {
+    const { ResponseMapper } = this.cookbook;
+    const mapper = new ResponseMapper();
+    return mapper.mapResponse(response, mapping);
+  }
+}
+
+module.exports = WorkflowOrchestrator;

package/src/index.js

@@ -0,0 +1,43 @@
+'use strict';
+
+/**
+ * @module @onlineapps/conn-orch-orchestrator
+ * @description Workflow orchestration connector that handles message routing and workflow execution.
+ * Coordinates all other connectors to process workflow messages.
+ *
+ * @see {@link https://github.com/onlineapps/oa-drive/tree/main/shared/connector/conn-orch-orchestrator|GitHub Repository}
+ * @author OA Drive Team
+ * @license MIT
+ * @since 1.0.0
+ */
+
+const WorkflowOrchestrator = require('./WorkflowOrchestrator');
+
+/**
+ * Create orchestrator instance
+ * @function create
+ * @param {Object} config - Configuration options
+ * @param {Object} config.mqClient - MQ client instance
+ * @param {Object} config.registryClient - Registry client instance
+ * @param {Object} config.apiMapper - API mapper instance
+ * @param {Object} config.cookbook - Cookbook connector instance
+ * @param {Object} [config.logger] - Logger instance
+ * @returns {WorkflowOrchestrator} New orchestrator instance
+ *
+ * @example
+ * const orchestrator = create({
+ *   mqClient: new MQClient(),
+ *   registryClient: new RegistryClient(),
+ *   apiMapper: new ApiMapper(),
+ *   cookbook: new CookbookConnector()
+ * });
+ */
+function create(config) {
+  return new WorkflowOrchestrator(config);
+}
+
+module.exports = {
+  WorkflowOrchestrator,
+  create,
+  VERSION: '1.0.0'
+};