@onlineapps/conn-orch-orchestrator 1.0.115 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-orchestrator",
-  "version": "1.0.115",
+  "version": "2.0.1",
   "description": "Workflow orchestration connector for OA Drive - handles message routing and workflow execution",
   "main": "src/index.js",
   "scripts": {
@@ -24,8 +24,7 @@
     "@onlineapps/conn-base-monitoring": "1.0.12",
     "@onlineapps/conn-infra-mq": "1.1.70",
     "@onlineapps/conn-orch-registry": "1.2.1",
-    "@onlineapps/conn-orch-cookbook": "2.1.2",
-    "@onlineapps/conn-orch-api-mapper": "1.0.34"
+    "@onlineapps/conn-orch-cookbook": "2.1.2"
   },
   "devDependencies": {
     "jest": "^29.5.0",

package/src/WorkflowOrchestrator.js

@@ -15,7 +15,10 @@ class WorkflowOrchestrator {
    * @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.invoker - Intra-service operation invoker exposing
+   *   async invokeOperation({ operation, input, envelope, workflow_id,
+   *   correlation_id, step_id }) -> { status, result } | { status, error }.
+   *   Replaces the retired apiMapper HTTP-loopback path (RFC §5.9, §5.10).
    * @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
@@ -25,12 +28,16 @@ class WorkflowOrchestrator {
   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.invoker || typeof config.invoker.invokeOperation !== 'function') {
+      throw new Error(
+        '[WorkflowOrchestrator] invoker with invokeOperation(message) is required - Expected object exposing async invokeOperation({operation, input, envelope, workflow_id, correlation_id, step_id}) returning {status, result}'
+      );
+    }
     if (!config.cookbook) throw new Error('cookbook is required');
 
     this.mqClient = config.mqClient;
     this.registryClient = config.registryClient;
-    this.apiMapper = config.apiMapper;
+    this._invoker = config.invoker;
     this.cookbook = config.cookbook;
     this.cache = config.cache;
     this.errorHandler = config.errorHandler;
@@ -66,6 +73,35 @@ class WorkflowOrchestrator {
     }
   }
 
+  /**
+   * Extract correlation_id from an inbound MQ message envelope.
+   * Accepts the canonical body-level `correlation_id` and also a few known
+   * legacy placements from transports that move AMQP headers onto the
+   * parsed message object. Returns undefined if none are set - the caller
+   * is responsible for fail-fast.
+   * @private
+   * @param {Object} message - Inbound workflow message
+   * @returns {string|undefined}
+   */
+  _extractCorrelationId(message) {
+    if (!message || typeof message !== 'object') return undefined;
+    if (typeof message.correlation_id === 'string' && message.correlation_id.length > 0) {
+      return message.correlation_id;
+    }
+    if (message.envelope && typeof message.envelope.correlation_id === 'string' && message.envelope.correlation_id.length > 0) {
+      return message.envelope.correlation_id;
+    }
+    if (message.headers) {
+      if (typeof message.headers.correlation_id === 'string' && message.headers.correlation_id.length > 0) {
+        return message.headers.correlation_id;
+      }
+      if (typeof message.headers.correlationId === 'string' && message.headers.correlationId.length > 0) {
+        return message.headers.correlationId;
+      }
+    }
+    return undefined;
+  }
+
   /**
    * Get step identifier (V2.1 only: step_id)
    * @private
@@ -138,6 +174,21 @@ class WorkflowOrchestrator {
     const { workflow_id, cookbook: cookbookDef, current_step } = message;
     const startTime = Date.now();
 
+    // Fail-fast: correlation_id MUST be present on every workflow message.
+    // A workflow without a correlation_id is malformed per RFC §5.8
+    // (ContextBuilder._validateMqMessage rejects empty strings too).
+    // The gateway must publish it; if it does not, that is a gateway bug
+    // we want to surface loudly rather than silently produce 500s inside
+    // invokeOperation's ContextBuilder.
+    const correlationId = this._extractCorrelationId(message);
+    if (typeof correlationId !== 'string' || correlationId.length === 0) {
+      throw new Error(
+        '[WorkflowOrchestrator] message.correlation_id is required - ' +
+        `Expected non-empty string on inbound workflow message (workflow_id='${workflow_id}', step='${current_step}'). ` +
+        'Fix: ensure publisher (gateway / router) sets correlation_id on message body per RFC §5.8.'
+      );
+    }
+
     try {
       // Validate cookbook structure
       this.cookbook.validateCookbook(cookbookDef);
@@ -192,9 +243,24 @@ class WorkflowOrchestrator {
           stepsMap[id] = s;
         }
       });
+      // Extract tenant/workspace/person context.
+      // Canonical source is cookbook._system (set by gateway); top-level
+      // message fields are accepted as an override for direct publishers
+      // that do not carry a _system block.
+      const sys = cookbookDef._system || {};
+      const tenantId = message.tenant_id !== undefined ? message.tenant_id : sys.tenant_id;
+      const workspaceId = message.workspace_id !== undefined
+        ? message.workspace_id
+        : (sys.workspace_id !== undefined ? sys.workspace_id : sys.default_workspace_id);
+      const personId = message.person_id !== undefined ? message.person_id : sys.person_id;
+
       const stepContext = {
         workflow_id: workflow_id,
         step_id: current_step,
+        correlation_id: correlationId,
+        tenant_id: tenantId,
+        workspace_id: workspaceId,
+        person_id: personId,
         api_input: cookbookDef.api_input || {},
         steps: stepsArrayCtx,       // array (legacy consumers expect .map)
         steps_by_id: stepsMap,      // fast lookup by step_id for templating
@@ -267,9 +333,16 @@ class WorkflowOrchestrator {
         });
       }
 
-      // Route to next step or complete workflow
+      // Route to next step or complete workflow.
+      // Propagate correlation_id + tenancy so the next consumer can validate
+      // the envelope (RFC §5.8).
       if (nextStep) {
-        await this._routeToNextStep(nextStep, updatedCookbook, workflow_id);
+        await this._routeToNextStep(nextStep, updatedCookbook, workflow_id, {
+          correlation_id: correlationId,
+          tenant_id: tenantId,
+          workspace_id: workspaceId,
+          person_id: personId
+        });
       } else {
         await this._completeWorkflow(workflow_id, updatedCookbook, serviceName, current_step, currentIndex);
       }
@@ -410,10 +483,19 @@ class WorkflowOrchestrator {
 
         await new Promise(resolve => setTimeout(resolve, delay));
 
-        // Republish with UNIFIED cookbook
+        // Republish with UNIFIED cookbook.
+        // Propagate correlation_id + tenancy so the retry consumer passes
+        // ContextBuilder validation on the next attempt (RFC §5.8).
         const serviceQueue = `${serviceName}.workflow`;
+        const sysRetry = updatedCookbook?._system || {};
         await this.mqClient.publish(serviceQueue, {
           workflow_id,
+          correlation_id: correlationId,
+          tenant_id: message.tenant_id !== undefined ? message.tenant_id : sysRetry.tenant_id,
+          workspace_id: message.workspace_id !== undefined
+            ? message.workspace_id
+            : (sysRetry.workspace_id !== undefined ? sysRetry.workspace_id : sysRetry.default_workspace_id),
+          person_id: message.person_id !== undefined ? message.person_id : sysRetry.person_id,
           cookbook: updatedCookbook,
           current_step
         });
@@ -552,26 +634,46 @@ class WorkflowOrchestrator {
 
     const resolvedInput = await this._resolveInputReferencesAsync(step.input, context, helperContext);
     console.log(`[WorkflowOrchestrator] [RESOLVE] Step ${stepId} input AFTER:`, JSON.stringify(resolvedInput));
-    
-    // Use API mapper to call the service with resolved input
-    const result = await this.apiMapper.callOperation(
-      step.operation || stepId,
-      resolvedInput,
-      {
-        ...context,
-        workflow_id: context?.workflow_id,
-        step_id: stepId
-      }
-    );
 
-    this.logger.info(`Task step executed`, {
-      step: stepId,
-      service: step.service,
-      operation: step.operation,
-      inputResolved: !!resolvedInput
+    // Intra-service handler dispatch via service-wrapper v3.0.0 (RFC §5.9, §5.10).
+    // Replaces the retired apiMapper.callOperation HTTP-loopback path.
+    const envelope = await this._invoker.invokeOperation({
+      operation: step.operation || stepId,
+      input: resolvedInput,
+      envelope: {
+        tenant_id: context?.tenant_id,
+        workspace_id: context?.workspace_id,
+        person_id: context?.person_id
+      },
+      workflow_id: context?.workflow_id,
+      correlation_id: context?.correlation_id,
+      step_id: stepId
     });
 
-    return result;
+    if (envelope && envelope.status >= 200 && envelope.status < 300) {
+      this.logger.info(`Task step executed`, {
+        step: stepId,
+        service: step.service,
+        operation: step.operation,
+        inputResolved: !!resolvedInput
+      });
+      return envelope.result;
+    }
+
+    // Non-2xx: surface the typed error envelope so the outer workflow handler
+    // can record retry_history / DLQ classification per existing logic.
+    const err = new Error(
+      `[WorkflowOrchestrator] Step '${stepId}' (operation '${step.operation}') failed with status ${envelope?.status}`
+    );
+    err.status = envelope?.status;
+    err.statusCode = envelope?.status;
+    err.code = envelope?.error?.code;
+    err.errorCode = envelope?.error?.code;
+    err.details = envelope?.error?.details;
+    if (envelope?.error?.message) {
+      err.message = envelope.error.message;
+    }
+    throw err;
   }
 
   /**
@@ -1057,13 +1159,20 @@ class WorkflowOrchestrator {
    * @param {Object} nextStep - Next step to execute
    * @param {Object} cookbook - UNIFIED cookbook (contains everything)
    * @param {string} workflow_id - Workflow ID
+   * @param {Object} envelope - envelope to propagate (correlation_id, tenant_id, workspace_id, person_id)
    */
-  async _routeToNextStep(nextStep, cookbook, workflow_id) {
+  async _routeToNextStep(nextStep, cookbook, workflow_id, envelope = {}) {
     const nextStepId = this._getStepId(nextStep);
-    
-    // UNIFIED COOKBOOK: no separate context, everything is in cookbook
+
+    // UNIFIED COOKBOOK: no separate context, everything is in cookbook.
+    // correlation_id + tenancy are propagated on the message envelope so
+    // the next consumer's ContextBuilder validation succeeds (RFC §5.8).
     const message = {
       workflow_id,
+      correlation_id: envelope.correlation_id,
+      tenant_id: envelope.tenant_id,
+      workspace_id: envelope.workspace_id,
+      person_id: envelope.person_id,
       cookbook: cookbook,
       current_step: nextStepId
     };

package/src/index.js

@@ -19,7 +19,11 @@ const WorkflowOrchestrator = require('./WorkflowOrchestrator');
  * @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.invoker - Intra-service operation invoker.
+ *   Expected shape: `{ async invokeOperation({ operation, input, envelope,
+ *   workflow_id, correlation_id, step_id }) -> { status, result } | { status, error } }`.
+ *   Typically `{ invokeOperation: serviceWrapper.invokeOperation.bind(serviceWrapper) }`.
+ *   Replaces the retired `apiMapper` HTTP-loopback dep (RFC §5.9, §5.10).
  * @param {Object} config.cookbook - Cookbook connector instance
  * @param {Object} [config.logger] - Logger instance
  * @returns {WorkflowOrchestrator} New orchestrator instance
@@ -28,7 +32,7 @@ const WorkflowOrchestrator = require('./WorkflowOrchestrator');
  * const orchestrator = create({
  *   mqClient: new MQClient(),
  *   registryClient: new RegistryClient(),
- *   apiMapper: new ApiMapper(),
+ *   invoker: { invokeOperation: wrapper.invokeOperation.bind(wrapper) },
  *   cookbook: new CookbookConnector()
  * });
  */