@onlineapps/conn-orch-orchestrator 2.0.2 → 2.1.0

package/README.md

@@ -44,6 +44,78 @@ const stats = orchestrator.getStats();
 console.log(`Processed: ${stats.processed}, Failed: ${stats.failed}`);
 ```
 
+## Cache Invalidation for Mutating Operations (`operationMutatesLookup`)
+
+The orchestrator memoizes successful task-step results in the optional `cache` connector under
+keys of the form `workflow:step:<step.service>:<operation>:<hash>` so that idempotent reads
+inside the same workflow can be reused. Mutating operations (writes, deletes, RPC side effects)
+must NOT be served from this cache, and any cached reads against the same target service must
+be purged the moment a write succeeds.
+
+To enable that behavior, pass an `operationMutatesLookup` hook to the constructor. The hook is
+typically wired by `@onlineapps/service-wrapper` from each service's `operations.json` map.
+
+### Signature
+
+```js
+/**
+ * @param {string} executingServiceName Name of the service running the cookbook.
+ * @param {Object} step                 The cookbook step about to execute.
+ * @returns {{ mutates?: boolean, resource_type?: string|null }|null|undefined}
+ */
+operationMutatesLookup(executingServiceName, step)
+```
+
+### Return shape
+
+- `{ mutates: true }` &mdash; force a read-cache bypass for this step AND, after the handler
+  returns success (`status` 2xx), invoke
+  `cache.deleteByPattern('workflow:step:<step.service>:*')` to purge stale reads.
+- `{ mutates: false }` (or `undefined` / `null`) &mdash; treat as a read; the orchestrator may
+  reuse `cache.get` and store fresh results via `cache.set`.
+- The `resource_type` field is informational and is not consumed by the orchestrator (yet).
+
+### Error contract
+
+If the hook throws, `_stepMutatesFlag` re-throws the same error. The orchestrator does NOT
+silently swallow lookup failures &mdash; per
+[architecture-principles.mdc](/docs/architecture/architecture-principles.md) §4 we fail
+loudly so misconfigured `operations.json` is caught at workflow runtime, not by data drift.
+
+### Fallback behavior without the hook
+
+If `operationMutatesLookup` is omitted or is not a function, the orchestrator only treats a
+step as mutating when the cookbook step itself sets `step.mutates === true`. Otherwise every
+task step is eligible for read-cache reuse.
+
+### Example
+
+```javascript
+const WorkflowOrchestrator = require('@onlineapps/conn-orch-orchestrator');
+
+const operations = {
+  'get-invoice': { mutates: false, resource_type: 'invoice' },
+  'update-invoice': { mutates: true, resource_type: 'invoice' }
+};
+
+const orchestrator = new WorkflowOrchestrator({
+  mqClient,
+  registryClient,
+  invoker,
+  cookbook,
+  cache,
+  logger,
+  defaultTimeout: 30000,
+  operationMutatesLookup: (executingServiceName, step) => {
+    const spec = operations[step.operation];
+    return {
+      mutates: !!(spec && spec.mutates === true),
+      resource_type: spec ? spec.resource_type : null
+    };
+  }
+});
+```
+
 ## Configuration
 
 | Variable | Description | Default |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-orchestrator",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "Workflow orchestration connector for OA Drive - handles message routing and workflow execution",
   "main": "src/index.js",
   "scripts": {
@@ -24,7 +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-cookbook": "2.1.3"
   },
   "devDependencies": {
     "jest": "^29.5.0",

package/src/WorkflowOrchestrator.js

@@ -24,6 +24,11 @@ class WorkflowOrchestrator {
    * @param {Object} [config.errorHandler] - Error handler connector
    * @param {Object} [config.logger] - Logger instance
    * @param {number} [config.defaultTimeout=30000] - Default timeout for operations
+   * @param {(executingServiceName: string, step: Object) =>
+   *   {mutates?: boolean}|null|undefined} [config.operationMutatesLookup]
+   * Optional hook (usually service-wrapper bound to operations.json map). Returning
+   * `{ mutates: true }` forces task executions to bypass read-through cache reuse and
+   * deletes `workflow:step:<step.service>:*` after successful handler completion.
    */
   constructor(config) {
     if (!config.mqClient) throw new Error('mqClient is required');
@@ -49,6 +54,10 @@ class WorkflowOrchestrator {
       throw new Error('[WorkflowOrchestrator] defaultTimeout is required — Expected number (ms)');
     }
     this.defaultTimeout = config.defaultTimeout;
+    this._operationMutatesLookup =
+      typeof config.operationMutatesLookup === 'function'
+        ? config.operationMutatesLookup
+        : null;
 
     // INTENTIONAL FALLBACK: operational defaults — see docs/standards/FALLBACKS_INVENTORY.md §5.2
     this.retryConfig = {
@@ -79,6 +88,8 @@ class WorkflowOrchestrator {
    * 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.
+   *
+   * @see api/docs/standards/workflow-message-contract.md
    * @private
    * @param {Object} message - Inbound workflow message
    * @returns {string|undefined}
@@ -176,6 +187,7 @@ class WorkflowOrchestrator {
     // correlation_id is required by RFC §5.8 — validated below inside the
     // try block so malformed messages flow through the retry/DLQ pipeline
     // and a `failed` monitoring event is emitted (no silent redelivery).
+    // @see api/docs/standards/workflow-message-contract.md
     const correlationId = this._extractCorrelationId(message);
 
     try {
@@ -274,8 +286,13 @@ class WorkflowOrchestrator {
         delivery: cookbookDef.delivery
       };
       
+      const stepMutates = this._stepMutatesFlag(step, serviceName);
+
       let result;
-      if (this.cache && step.type === 'task') {
+      const useReadCache =
+        Boolean(this.cache) && step.type === 'task' && !stepMutates;
+
+      if (useReadCache) {
         const cacheKey = this._getCacheKey(step, stepContext);
         result = await this.cache.get(cacheKey);
         if (!result) {
@@ -635,7 +652,8 @@ class WorkflowOrchestrator {
       data: context,
       workflow_id: context?.workflow_id || null,
       step_id: stepId,
-      service: serviceName || null
+      service: serviceName || null,
+      logger: this.logger
     };
 
     const resolvedInput = await this._resolveInputReferencesAsync(step.input, context, helperContext);
@@ -657,6 +675,12 @@ class WorkflowOrchestrator {
     });
 
     if (envelope && envelope.status >= 200 && envelope.status < 300) {
+      const mutated = this._stepMutatesFlag(step, serviceName);
+      const targetService = step.service || serviceName;
+      if (mutated && this.cache && typeof this.cache.deleteByPattern === 'function') {
+        await this._invalidateWorkflowStepCaches(targetService);
+      }
+
       this.logger.info(`Task step executed`, {
         step: stepId,
         service: step.service,
@@ -967,7 +991,8 @@ class WorkflowOrchestrator {
       data: context,
       workflow_id: context?.workflow_id || null,
       step_id: stepId,
-      service: serviceName || null
+      service: serviceName || null,
+      logger: this.logger
     };
 
     const iteratorResolved = await this._resolveInputReferencesAsync(step.iterator, context, helperContext);
@@ -1021,7 +1046,8 @@ class WorkflowOrchestrator {
       data: context,
       workflow_id: context?.workflow_id || null,
       step_id: stepId,
-      service: serviceName || null
+      service: serviceName || null,
+      logger: this.logger
     };
 
     const value = await this._evaluateSwitchExpression(step.expression, context, helperContext);
@@ -1297,6 +1323,61 @@ class WorkflowOrchestrator {
     return `workflow:step:${step.service}:${step.operation || stepId}:${hash}`;
   }
 
+  /**
+   * Whether the task writes domain state and MUST bust cached reads for sibling operations.
+   * @private
+   * @param {Object} step
+   * @param {string} executingServiceName consumer service running the cookbook step
+   * @returns {boolean}
+   */
+  _stepMutatesFlag(step, executingServiceName) {
+    if (!step || step.type !== 'task') return false;
+    if (step.mutates === true) return true;
+    if (this._operationMutatesLookup) {
+      try {
+        const meta = this._operationMutatesLookup(executingServiceName, step);
+        if (meta && meta.mutates === true) return true;
+      } catch (e) {
+        this.logger.warn('[WorkflowOrchestrator] operationMutatesLookup failed', {
+          error: e.message,
+          executingServiceName,
+          step_id: step.step_id
+        });
+        throw e;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Remove cached orchestrator outputs for non-mutating task steps targeting a service queue.
+   * @private
+   * @param {string} serviceName cookbook step.service (routing target name)
+   * @returns {Promise<void>}
+   */
+  async _invalidateWorkflowStepCaches(serviceName) {
+    if (
+      !serviceName ||
+      !this.cache ||
+      typeof this.cache.deleteByPattern !== 'function'
+    ) {
+      return;
+    }
+
+    const pattern = `workflow:step:${serviceName}:*`;
+
+    await this.cache.deleteByPattern(pattern);
+
+    if (typeof this.logger?.info === 'function') {
+      this.logger.info(
+        '[WorkflowOrchestrator] Invalidated Redis workflow-step cache after mutate',
+        {
+          service: serviceName,
+          pattern
+        }
+      );
+    }
+  }
 }
 
 module.exports = WorkflowOrchestrator;