@onlineapps/service-wrapper 2.0.0

package/docs/PROCESS_FLOWS.md

@@ -0,0 +1,389 @@
+# Service Wrapper - Process Flows
+
+## Complete Message Processing Flow
+
+### 1. Message Arrival
+```javascript
+// Message structure from RabbitMQ
+{
+  properties: {
+    headers: {
+      workflowId: 'wf-550e8400-e29b',
+      spanId: 'span-7d3f-4b2a',
+      parentSpanId: 'span-6c2e-3a1b',
+      userId: 'user-456',
+      tenantId: 'tenant-789',
+      priority: 'normal'
+    }
+  },
+  content: Buffer.from(JSON.stringify({
+    cookbook: { /* workflow definition */ },
+    current_step: 2,
+    context: { /* accumulated results */ }
+  }))
+}
+```
+
+### 2. Context Extraction
+```javascript
+// Extract correlation context from headers
+const context = {
+  workflowId: msg.properties.headers.workflowId,
+  spanId: msg.properties.headers.spanId,
+  parentSpanId: msg.properties.headers.parentSpanId,
+  userId: msg.properties.headers.userId
+};
+
+// Set context in logger for all subsequent operations
+logger.setContext(context);
+logger.info('message.received', { queue: 'hello-service.workflow' });
+```
+
+### 3. Cookbook Processing
+```javascript
+// Parse message body
+const body = JSON.parse(msg.content.toString());
+const cookbook = body.cookbook;
+const currentStep = cookbook.steps[body.current_step];
+
+// Check if this service should handle this step
+if (currentStep.service !== this.serviceName) {
+  // Route to correct service
+  const targetQueue = `${currentStep.service}.workflow`;
+  await mqClient.publish(targetQueue, msg);
+  return;
+}
+```
+
+### 4. Cache Check
+```javascript
+// Generate cache key from operation and parameters
+const cacheKey = generateCacheKey(currentStep);
+// Format: "cache:api:hello-service:sayGoodDay:hash(John)"
+
+// Check cache
+const startTime = Date.now();
+const cached = await cache.get(cacheKey);
+
+if (cached) {
+  logger.info('cache.hit', {
+    key: cacheKey,
+    latency: Date.now() - startTime
+  });
+
+  // Skip API call, use cached result
+  return processNextStep(cached);
+}
+
+logger.info('cache.miss', { key: cacheKey });
+```
+
+### 5. API Call Mapping
+```javascript
+// Map cookbook operation to HTTP endpoint
+const endpoint = mapOperationToEndpoint(currentStep.operation);
+// Example: "sayGoodDay" → GET /good-day
+
+// Transform parameters
+const httpParams = transformParameters(currentStep.params);
+// Example: {name: "John"} → ?name=John
+
+// Make HTTP call to service
+const apiStart = Date.now();
+const response = await axios({
+  method: endpoint.method,
+  url: `${this.serviceUrl}${endpoint.path}`,
+  params: httpParams
+});
+
+logger.info('api.call.completed', {
+  operation: currentStep.operation,
+  latency: Date.now() - apiStart,
+  status: response.status
+});
+```
+
+### 6. Cache Storage
+```javascript
+// Store successful response in cache
+if (response.status === 200) {
+  await cache.set(cacheKey, response.data, {
+    ttl: this.config.cache.ttl || 300  // 5 minutes default
+  });
+
+  logger.info('cache.stored', {
+    key: cacheKey,
+    ttl: 300
+  });
+}
+```
+
+### 7. Context Update
+```javascript
+// Add result to workflow context
+body.context.results = body.context.results || {};
+body.context.results[currentStep.id] = response.data;
+
+// Update step index
+body.current_step++;
+
+// Add trace information
+body.trace = body.trace || [];
+body.trace.push({
+  step: body.current_step - 1,
+  service: this.serviceName,
+  timestamp: new Date().toISOString(),
+  duration: Date.now() - startTime
+});
+```
+
+### 8. Next Step Routing
+```javascript
+// Determine next action
+if (body.current_step >= cookbook.steps.length) {
+  // Workflow complete
+  await mqClient.publish('workflow.completed', {
+    headers: msg.properties.headers,
+    body: body
+  });
+
+  logger.info('workflow.completed', {
+    workflowId: context.workflowId,
+    totalSteps: cookbook.steps.length
+  });
+} else {
+  // Route to next service
+  const nextStep = cookbook.steps[body.current_step];
+  const nextQueue = `${nextStep.service}.workflow`;
+
+  // Create new span for next step
+  const newHeaders = {
+    ...msg.properties.headers,
+    parentSpanId: context.spanId,
+    spanId: generateSpanId()
+  };
+
+  await mqClient.publish(nextQueue, {
+    headers: newHeaders,
+    body: body
+  });
+
+  logger.info('message.routed', {
+    nextQueue,
+    nextService: nextStep.service
+  });
+}
+```
+
+## Fork-Join Flow
+
+### 1. Fork Detection
+```javascript
+if (currentStep.type === 'fork_join') {
+  const branches = currentStep.branches;
+  const accumulatorQueue = `fork.${context.workflowId}.${currentStep.id}`;
+
+  // Create accumulator metadata
+  const metadata = {
+    expectedResults: branches.length,
+    receivedResults: 0,
+    results: {}
+  };
+
+  await cache.set(`fork:${accumulatorQueue}`, metadata, { ttl: 300 });
+```
+
+### 2. Branch Distribution
+```javascript
+  // Send to each branch
+  for (const branch of branches) {
+    const branchMessage = {
+      ...body,
+      current_step: 0,
+      cookbook: branch,
+      fork_metadata: {
+        accumulatorQueue,
+        branchId: branch.id
+      }
+    };
+
+    const firstService = branch.steps[0].service;
+    await mqClient.publish(`${firstService}.workflow`, {
+      headers: {
+        ...headers,
+        parentSpanId: context.spanId,
+        spanId: generateSpanId()
+      },
+      body: branchMessage
+    });
+  }
+}
+```
+
+### 3. Result Collection
+```javascript
+// When branch completes, it sends to accumulator
+if (body.fork_metadata) {
+  const { accumulatorQueue, branchId } = body.fork_metadata;
+
+  // Update accumulator
+  const metadata = await cache.get(`fork:${accumulatorQueue}`);
+  metadata.results[branchId] = body.context.results;
+  metadata.receivedResults++;
+
+  if (metadata.receivedResults === metadata.expectedResults) {
+    // All branches complete - join results
+    const joinedResults = joinStrategy(metadata.results);
+
+    // Continue main workflow
+    const mainMessage = {
+      ...originalBody,
+      context: {
+        ...originalBody.context,
+        results: {
+          ...originalBody.context.results,
+          [currentStep.id]: joinedResults
+        }
+      },
+      current_step: originalBody.current_step + 1
+    };
+
+    // Route to next step in main workflow
+    routeToNext(mainMessage);
+  } else {
+    // Save updated metadata and wait for more results
+    await cache.set(`fork:${accumulatorQueue}`, metadata);
+  }
+}
+```
+
+## Error Handling Flows
+
+### 1. Transient Error (Retry)
+```javascript
+try {
+  const response = await axios.get(url);
+} catch (error) {
+  if (isTransientError(error)) {
+    // Network timeout, 503, etc.
+    message.retry_count = (message.retry_count || 0) + 1;
+
+    if (message.retry_count <= 3) {
+      // Retry with exponential backoff
+      const delay = Math.pow(2, message.retry_count) * 1000;
+
+      setTimeout(() => {
+        mqClient.publish(currentQueue, message);
+      }, delay);
+
+      logger.warn('message.retry', {
+        attempt: message.retry_count,
+        delay,
+        error: error.message
+      });
+    } else {
+      // Max retries exceeded - send to DLQ
+      await mqClient.publish(`${currentQueue}.dlq`, message);
+      logger.error('message.dlq', {
+        reason: 'max_retries',
+        attempts: message.retry_count
+      });
+    }
+  }
+}
+```
+
+### 2. Business Error (Continue)
+```javascript
+if (error.response && error.response.status === 400) {
+  // Business validation error - include in workflow
+  body.context.results[currentStep.id] = {
+    error: true,
+    message: error.response.data.message,
+    code: 'VALIDATION_ERROR'
+  };
+
+  // Continue to next step
+  body.current_step++;
+  routeToNext(body);
+
+  logger.info('business.error', {
+    step: currentStep.id,
+    error: error.response.data.message
+  });
+}
+```
+
+### 3. Fatal Error (Stop)
+```javascript
+if (error.code === 'SERVICE_NOT_FOUND') {
+  // Service doesn't exist - can't continue
+  await mqClient.publish('workflow.failed', {
+    headers: context,
+    body: {
+      ...body,
+      error: {
+        step: currentStep.id,
+        service: currentStep.service,
+        message: 'Service not found in registry'
+      }
+    }
+  });
+
+  logger.error('workflow.failed', {
+    workflowId: context.workflowId,
+    reason: 'service_not_found',
+    service: currentStep.service
+  });
+}
+```
+
+## Performance Tracking
+
+### Metrics Collection
+```javascript
+class PerformanceTracker {
+  constructor() {
+    this.metrics = {
+      queue_wait: 0,
+      cache_check: 0,
+      api_call: 0,
+      cache_store: 0,
+      routing: 0,
+      total: 0
+    };
+  }
+
+  async trackOperation(name, fn) {
+    const start = Date.now();
+    try {
+      const result = await fn();
+      this.metrics[name] = Date.now() - start;
+      return result;
+    } catch (error) {
+      this.metrics[name] = Date.now() - start;
+      throw error;
+    }
+  }
+
+  getMetrics() {
+    this.metrics.total = Object.values(this.metrics)
+      .reduce((sum, val) => sum + val, 0);
+    return this.metrics;
+  }
+}
+
+// Usage in message processing
+const tracker = new PerformanceTracker();
+
+const cached = await tracker.trackOperation('cache_check',
+  () => cache.get(cacheKey));
+
+const response = await tracker.trackOperation('api_call',
+  () => axios.get(url));
+
+logger.info('performance.metrics', tracker.getMetrics());
+```
+
+---
+*For configuration and setup, see main [Service Wrapper documentation](../README.md)*

package/jest.config.js

@@ -0,0 +1,34 @@
+module.exports = {
+  testEnvironment: 'node',
+  coverageDirectory: 'coverage',
+  collectCoverageFrom: [
+    'src/**/*.js',
+    '!src/**/*.test.js',
+    '!src/**/index.js'
+  ],
+  testMatch: [
+    '**/test/**/*.test.js'
+  ],
+  testPathIgnorePatterns: [
+    '/node_modules/'
+  ],
+  coverageThresholds: {
+    global: {
+      branches: 80,
+      functions: 80,
+      lines: 80,
+      statements: 80
+    }
+  },
+  moduleNameMapper: {
+    // Map connector imports to mocks in unit tests
+    '@onlineapps/conn-infra-mq': '<rootDir>/test/mocks/connectors.js',
+    '@onlineapps/conn-orch-registry': '<rootDir>/test/mocks/connectors.js',
+    '@onlineapps/conn-base-logger': '<rootDir>/test/mocks/connectors.js',
+    '@onlineapps/conn-orch-orchestrator': '<rootDir>/test/mocks/connectors.js',
+    '@onlineapps/conn-orch-api-mapper': '<rootDir>/test/mocks/connectors.js',
+    '@onlineapps/conn-orch-cookbook': '<rootDir>/test/mocks/connectors.js'
+  },
+  setupFilesAfterEnv: ['<rootDir>/test/setup.js'],
+  verbose: true
+};

package/jsdoc.json

@@ -0,0 +1,22 @@
+{
+  "source": {
+    "include": ["src/"],
+    "includePattern": ".js$",
+    "excludePattern": "(node_modules/|docs/|test/)"
+  },
+  "plugins": ["plugins/markdown"],
+  "templates": {
+    "cleverLinks": false,
+    "monospaceLinks": false,
+    "default": {
+      "outputSourceFiles": true,
+      "includeDate": false
+    }
+  },
+  "opts": {
+    "destination": "docs/html",
+    "recurse": true,
+    "readme": "README.md",
+    "package": "package.json"
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@onlineapps/service-wrapper",
+  "version": "2.0.0",
+  "description": "Thin orchestration layer for microservices - delegates all infrastructure concerns to specialized connectors",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "jest",
+    "test:unit": "jest test/unit",
+    "test:component": "jest test/component",
+    "test:integration": "jest test/integration",
+    "test:coverage": "jest --coverage",
+    "test:mocked": "node test/run-tests.js",
+    "docs": "jsdoc2md --files src/**/*.js > API.md",
+    "docs:html": "jsdoc -c jsdoc.json -d docs/html"
+  },
+  "keywords": [
+    "microservices",
+    "workflow",
+    "infrastructure",
+    "wrapper",
+    "thin-layer",
+    "orchestration"
+  ],
+  "author": "OA Drive Team",
+  "license": "MIT",
+  "dependencies": {
+    "@onlineapps/conn-base-logger": "^1.0.0",
+    "@onlineapps/conn-infra-mq": "^1.1.0",
+    "@onlineapps/conn-orch-registry": "^1.1.4",
+    "@onlineapps/conn-orch-cookbook": "^2.0.0",
+    "@onlineapps/conn-orch-orchestrator": "^1.0.0",
+    "@onlineapps/conn-orch-api-mapper": "^1.0.0",
+    "@onlineapps/conn-base-cache": "^1.0.0",
+    "@onlineapps/conn-infra-error-handler": "^1.0.0"
+  },
+  "devDependencies": {
+    "jest": "^29.5.0",
+    "jsdoc": "^4.0.2",
+    "jsdoc-to-markdown": "^8.0.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}