@onlineapps/service-wrapper 2.0.8 → 2.0.9

package/docs/WRAPPER_ARCHITECTURE.md

@@ -0,0 +1,218 @@
+# Service Wrapper Architecture
+
+> **NOTE: This document describes initial architecture concepts. For the production-ready decision, see [FINAL_ARCHITECTURE.md](./FINAL_ARCHITECTURE.md)**
+
+## Definition
+
+Service Wrapper is a **collection of connectors** that provides all components necessary for a business service to function within the system.
+
+## Core Principles
+
+1. **Component Collection** - Wrapper is NOT a framework but a set of reusable components
+2. **Central Management** - All services use the same wrapper version for consistency
+3. **Version Independence** - Each service can pin its wrapper version as needed
+4. **Duplicate by Design** - Each service has its own wrapper instance (not shared)
+
+## Architecture Pattern: Enhanced Service
+
+```javascript
+// Business service enhanced with wrapper components
+const express = require('express');
+const { MQConnector, MonitoringConnector, HealthConnector } = require('@onlineapps/service-wrapper');
+
+class EnhancedService {
+  constructor() {
+    // Core business service
+    this.app = express();
+    this.setupBusinessRoutes();
+
+    // Wrapper components
+    this.mq = new MQConnector(this);
+    this.monitoring = new MonitoringConnector(this);
+    this.health = new HealthConnector(this);
+  }
+
+  async start() {
+    // 1. Start HTTP server
+    await this.app.listen(this.config.port);
+
+    // 2. Connect to MQ
+    await this.mq.connect();
+    await this.mq.consume('workflow.init', this.handleWorkflow.bind(this));
+    await this.mq.consume(`${this.config.name}.workflow`, this.handleServiceMessage.bind(this));
+
+    // 3. Start monitoring
+    await this.monitoring.start();
+
+    // 4. Register health checks
+    this.health.register('/health', this.checkHealth.bind(this));
+  }
+
+  handleWorkflow(message) {
+    // Wrapper handles workflow routing
+    const operation = this.config.operations[message.step.operation];
+
+    // Call own HTTP endpoint
+    return this.callHttp(operation.endpoint, message.input);
+  }
+
+  callHttp(endpoint, data) {
+    // Internal HTTP call to business logic
+    return fetch(`http://localhost:${this.config.port}${endpoint}`, {
+      method: 'POST',
+      body: JSON.stringify(data)
+    });
+  }
+}
+```
+
+## Component Responsibilities
+
+### MQ Connector
+- Listen on `workflow.init` queue
+- Listen on service-specific queues
+- Route messages between services
+- Handle dead letter queues
+
+### Monitoring Connector
+- Collect metrics
+- Export to monitoring system
+- Track request/response times
+- Monitor queue depth
+
+### Health Connector
+- Provide `/health` endpoint
+- Check service dependencies
+- Report readiness status
+- Aggregate component health
+
+### Registry Connector
+- Register service on startup
+- Send heartbeat
+- Update capabilities
+- Handle deregistration
+
+## Single Process Architecture
+
+**Decision:** Use single process with embedded wrapper components.
+
+### Rationale:
+1. **Simplicity** - One deployment unit
+2. **Efficiency** - No IPC overhead
+3. **Atomicity** - Components share state
+4. **Debugging** - Single log stream
+
+### Implementation:
+```javascript
+// service/index.js
+const ServiceWrapper = require('@onlineapps/service-wrapper');
+const app = require('./src/app'); // Express app
+const config = require('./conn-config/config.json');
+const operations = require('./conn-config/operations.json');
+
+// Single process startup
+async function start() {
+  // Business service
+  const server = app.listen(config.port);
+
+  // Wrapper components
+  const wrapper = new ServiceWrapper({
+    app,
+    server,
+    config,
+    operations
+  });
+
+  await wrapper.initialize();
+  console.log(`Service ${config.name} running with wrapper components`);
+}
+
+start().catch(console.error);
+```
+
+## Configuration Pattern
+
+### operations.json
+```json
+{
+  "operations": {
+    "operation-name": {
+      "endpoint": "/api/operation",
+      "method": "POST",
+      "input": { "schema": "..." },
+      "output": { "schema": "..." }
+    }
+  }
+}
+```
+
+### config.json
+```json
+{
+  "service": {
+    "name": "my-service",
+    "port": 3000
+  },
+  "wrapper": {
+    "mq": {
+      "url": "${RABBITMQ_URL}"
+    },
+    "monitoring": {
+      "enabled": true
+    }
+  }
+}
+```
+
+## Health Check Strategy
+
+Health checks are **provided by wrapper** but **implemented by service**:
+
+```javascript
+// Wrapper provides endpoint
+app.get('/health', healthConnector.handler);
+
+// Service implements check
+class MyService {
+  checkHealth() {
+    return {
+      status: this.isHealthy() ? 'healthy' : 'unhealthy',
+      database: this.db.isConnected(),
+      dependencies: this.checkDependencies()
+    };
+  }
+}
+```
+
+## Migration Path
+
+### From Standalone Service:
+1. Add `@onlineapps/service-wrapper` dependency
+2. Create `conn-config/operations.json`
+3. Wrap service startup with ServiceWrapper
+4. Remove duplicate infrastructure code
+
+### From Two-Process Architecture:
+1. Merge wrapper.js into service index.js
+2. Remove separate wrapper process
+3. Consolidate configuration
+4. Single deployment unit
+
+## Benefits
+
+1. **No Duplication** - Common components in wrapper
+2. **Central Updates** - Update wrapper version for all services
+3. **Consistent Behavior** - All services work the same way
+4. **Simple Deployment** - One process per service
+5. **Clear Separation** - Business logic vs infrastructure
+
+## Drawbacks
+
+1. **Tight Coupling** - Service depends on wrapper version
+2. **Restart Required** - Any change restarts everything
+3. **Mixed Dependencies** - Business and infrastructure together
+4. **Testing Complexity** - Must mock wrapper components
+
+## Conclusion
+
+Service Wrapper as a **component collection** in a **single process** provides the best balance of simplicity, efficiency, and maintainability for our microservices architecture.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/service-wrapper",
-  "version": "2.0.8",
+  "version": "2.0.9",
   "description": "Thin orchestration layer for microservices - delegates all infrastructure concerns to specialized connectors",
   "main": "src/index.js",
   "scripts": {
@@ -25,14 +25,14 @@
   "license": "MIT",
   "dependencies": {
     "@onlineapps/conn-base-cache": "^1.0.0",
-    "@onlineapps/conn-base-monitoring": "file:../conn-base-monitoring/onlineapps-conn-base-monitoring-1.0.0.tgz",
+    "@onlineapps/conn-base-monitoring": "^1.0.0",
     "@onlineapps/conn-infra-error-handler": "^1.0.0",
     "@onlineapps/conn-infra-mq": "^1.1.0",
     "@onlineapps/conn-orch-api-mapper": "^1.0.0",
     "@onlineapps/conn-orch-cookbook": "^2.0.0",
     "@onlineapps/conn-orch-orchestrator": "^1.0.1",
     "@onlineapps/conn-orch-registry": "^1.1.4",
-    "@onlineapps/monitoring-core": "file:../../../api/shared/monitoring-core/onlineapps-monitoring-core-1.0.0.tgz"
+    "@onlineapps/monitoring-core": "^1.0.0"
   },
   "devDependencies": {
     "express": "^5.1.0",