@onlineapps/service-wrapper 2.0.8 → 2.0.9

package/README.md

@@ -1,8 +1,10 @@
 # @onlineapps/service-wrapper
 
-**Main orchestration package for microservices - NO prefix as it's the primary integration point**
+**Collection of connectors providing all infrastructure components for business services**
 
-Infrastructure wrapper that handles all workflow processing, message queue operations, and service registration for microservices.
+Service Wrapper is a set of reusable connector components that handle message queue operations, service registration, monitoring, and health checks for microservices in a single-process architecture.
+
+> **For complete architecture documentation, see [docs/FINAL_ARCHITECTURE.md](./docs/FINAL_ARCHITECTURE.md)**
 
 ## Naming Convention
 
@@ -41,32 +43,43 @@ This package provides the infrastructure layer that sits between:
 
 ## Usage
 
-### 1. Wrap Your Service
+### 1. Install Service Wrapper
+
+```bash
+npm install @onlineapps/service-wrapper
+```
+
+### 2. Create Service Entry Point
 
 ```javascript
-const ServiceWrapper = require('@onlineapps/service-wrapper');
+// index.js
 const express = require('express');
+const { ServiceWrapper } = require('@onlineapps/service-wrapper');
 
-// Your pure business logic service
-const app = express();
-app.get('/hello', (req, res) => {
-  res.json({ message: `Hello ${req.query.name}` });
-});
+// Load your Express app (business logic only)
+const app = require('./src/app');
 
-// Wrap with infrastructure
-const wrapper = new ServiceWrapper({
-  service: app,
-  serviceName: 'hello-service',
-  openApiSpec: require('./openapi.json'),
-  config: {
-    rabbitmq: process.env.RABBITMQ_URL,
-    registry: process.env.REGISTRY_URL,
-    port: process.env.PORT || 3000
-  }
-});
+// Load configuration
+const config = require('./conn-config/config.json');
+const operations = require('./conn-config/operations.json');
+
+async function start() {
+  // 1. Start Express server
+  const server = app.listen(process.env.PORT || 3000);
+
+  // 2. Initialize wrapper components
+  const wrapper = new ServiceWrapper({
+    app,
+    server,
+    config,
+    operations
+  });
+
+  await wrapper.initialize();
+  console.log('Service ready with all infrastructure components');
+}
 
-// Start wrapped service
-wrapper.start();
+start().catch(console.error);
 ```
 
 ### 2. Service Receives
@@ -88,25 +101,37 @@ NO infrastructure code needed in your service!
 
 ## Configuration
 
-```javascript
+### operations.json
+```json
 {
-  service: expressApp,        // Your Express app
-  serviceName: 'my-service',  // Service identifier
-  openApiSpec: {},            // OpenAPI specification
-  config: {
-    rabbitmq: 'amqp://...',   // RabbitMQ connection
-    registry: 'http://...',   // Registry URL
-    redis: 'redis://...',     // Redis connection
-    port: 3000,               // Service port
-    healthPath: '/health',    // Health check path
-    retryPolicy: {            // Retry configuration
-      maxRetries: 3,
-      backoffMs: 1000
+  "operations": {
+    "operation-name": {
+      "description": "Operation description",
+      "endpoint": "/api/operation",
+      "method": "POST",
+      "input": { "name": { "type": "string", "required": true } },
+      "output": { "result": { "type": "string" } }
     }
   }
 }
 ```
 
+### config.json
+```json
+{
+  "service": {
+    "name": "my-service",
+    "port": 3000
+  },
+  "wrapper": {
+    "mq": { "url": "${RABBITMQ_URL}" },
+    "registry": { "url": "${REGISTRY_URL}" },
+    "monitoring": { "enabled": true },
+    "health": { "endpoint": "/health" }
+  }
+}
+```
+
 ## What This Handles
 
 ### Workflow Processing
@@ -144,12 +169,14 @@ Your service should NOT have:
 ```
 my-service/
 ├── src/
-│   ├── index.js          # Express app (business logic only)
+│   ├── app.js            # Express app (business logic only)
 │   ├── routes/           # API endpoints
 │   └── services/         # Business logic
-├── connector-config/
-│   └── openapi.json      # API specification
-└── package.json          # Dependencies (no @onlineapps/connector-*)
+├── conn-config/
+│   ├── config.json       # Service & wrapper configuration
+│   └── operations.json   # Operations specification
+├── index.js              # Main entry point (initializes wrapper)
+└── package.json          # Dependencies including @onlineapps/service-wrapper
 ```
 
 ## Testing

package/docs/ARCHITECTURE_DECISION.md

@@ -0,0 +1,200 @@
+# Architecture Decision: Service Wrapper vs Business Services
+
+> **NOTE: This document describes the evolution of our thinking. For the final decision, see [FINAL_ARCHITECTURE.md](./FINAL_ARCHITECTURE.md)**
+
+## Executive Summary
+
+After critical analysis, we've determined that business services should remain as standard Express applications with Service Wrapper acting as a thin MQ-to-HTTP proxy layer.
+
+## Business Service Requirements
+
+### MUST Have:
+1. **Express HTTP Server** - Full REST API capability
+2. **Own Database Connections** - Direct ORM/query access
+3. **Own Dependencies** - Complete node_modules
+4. **Standalone Operation** - Must run without wrapper
+5. **Standard Testing** - curl/Postman testable
+
+### Service Structure:
+```
+/service-name/
+  /src/
+    app.js           # Express application
+    /models/         # Database models
+    /controllers/    # HTTP controllers
+    /services/       # Business logic
+    /validators/     # Input validation
+  /conn-config/
+    operations.json  # Operation definitions
+    config.json      # Service configuration
+  package.json       # All dependencies
+```
+
+### Operations Specification:
+```json
+{
+  "operations": {
+    "operation-name": {
+      "endpoint": "/api/operation",
+      "method": "POST",
+      "input": { "schema": "..." },
+      "output": { "schema": "..." }
+    }
+  }
+}
+```
+
+## Service Wrapper Responsibilities
+
+### Core Functions:
+1. **MQ Listener** - Consumes from RabbitMQ queues
+2. **HTTP Proxy** - Forwards to service endpoints
+3. **Service Registry** - Registers with discovery
+4. **Cookbook Router** - Routes workflow steps
+
+### What Wrapper Does NOT Do:
+- ❌ Create HTTP server for service
+- ❌ Handle business logic
+- ❌ Manage database connections
+- ❌ Validate business rules
+- ❌ Generate responses
+
+### Wrapper Architecture:
+```javascript
+// wrapper.js
+const ServiceWrapper = require('@onlineapps/service-wrapper');
+
+new ServiceWrapper({
+  serviceName: 'hello-service',
+  serviceUrl: 'http://localhost:3000',
+  mqConfig: { /* RabbitMQ settings */ },
+  mode: 'proxy'  // Just forwards MQ→HTTP
+}).start();
+```
+
+## Communication Flow
+
+```
+[Cookbook Message]
+    ↓
+[Service Wrapper]
+    ├─ Reads operations.json
+    ├─ Maps operation to endpoint
+    ├─ Makes HTTP call
+    ↓
+[Business Service Express]
+    ├─ Handles HTTP request
+    ├─ Executes business logic
+    ├─ Returns HTTP response
+    ↓
+[Service Wrapper]
+    ├─ Transforms response
+    └─ Sends to next queue
+```
+
+## Why This Architecture?
+
+### Separation of Concerns:
+- **Business Service** = Business logic + API
+- **Service Wrapper** = MQ communication only
+
+### Benefits:
+1. **Independence** - Services run standalone
+2. **Simplicity** - No complex handler mapping
+3. **Compatibility** - Works with existing services
+4. **Testability** - Standard HTTP testing
+5. **Flexibility** - Can swap wrapper implementations
+
+### Drawbacks Considered:
+- Extra HTTP hop (acceptable for clarity)
+- Two processes (acceptable for isolation)
+- More memory (acceptable for stability)
+
+## Migration Path
+
+### For New Services:
+1. Build Express API normally
+2. Add operations.json
+3. Add wrapper.js for MQ
+
+### For Existing Services:
+1. Keep service unchanged
+2. Add operations.json
+3. Add wrapper.js for MQ
+
+### No Breaking Changes Required!
+
+## Decision Matrix
+
+| Aspect | Handlers Approach | Express + Wrapper |
+|--------|------------------|-------------------|
+| Complexity | High | Low |
+| Testing | Complex | Simple |
+| Dependencies | Conflicting | Isolated |
+| Database | Problematic | Natural |
+| Debugging | Hard | Easy |
+| **Winner** | ❌ | ✅ |
+
+## Final Decision
+
+**Business services remain as Express applications.**
+**Service Wrapper acts as MQ-to-HTTP proxy only.**
+
+This provides:
+- Maximum compatibility
+- Minimum complexity
+- Clear separation
+- Easy migration
+
+## Implementation Guidelines
+
+1. **Every service has:**
+   - Express app with REST endpoints
+   - operations.json describing operations
+   - Optional wrapper.js for MQ integration
+
+2. **Service Wrapper:**
+   - Reads operations.json
+   - Listens to MQ
+   - Calls HTTP endpoints
+   - Returns responses to MQ
+
+3. **No direct handler execution**
+   - Always through HTTP
+   - Clear contract via operations.json
+   - Standard REST patterns
+
+## Examples
+
+### Hello Service:
+```javascript
+// app.js - Standard Express
+app.post('/api/good-day', (req, res) => {
+  res.json({ message: `Good day, ${req.body.name}!` });
+});
+
+// operations.json - Contract
+{
+  "operations": {
+    "good-day": {
+      "endpoint": "/api/good-day",
+      "method": "POST"
+    }
+  }
+}
+
+// wrapper.js - MQ Bridge
+new ServiceWrapper({
+  serviceUrl: 'http://localhost:33199'
+}).start();
+```
+
+### Invoicing Service:
+- Keeps all controllers, models, validators
+- Adds operations.json
+- Adds wrapper.js
+- NO other changes needed
+
+## Conclusion
+
+The architecture prioritizes **simplicity and compatibility** over theoretical purity. Services remain standard Express apps, making them easy to develop, test, and maintain. Service Wrapper provides the MQ integration layer without disrupting the service internals.

package/docs/FINAL_ARCHITECTURE.md

@@ -0,0 +1,271 @@
+# Service Wrapper - Final Architecture Decision
+
+## Executive Summary
+
+Service Wrapper is a **collection of connectors** that provides all infrastructure components necessary for business services to function within the OA Drive system. It operates as a **single process architecture** where wrapper components run embedded within the service process.
+
+## Core Principles
+
+1. **Component Collection** - Service Wrapper is NOT a framework but a set of reusable connector components
+2. **Single Process** - All components run in the same process as the business service
+3. **Express + HTTP** - Business services remain standard Express applications
+4. **MQ-to-HTTP Proxy** - Wrapper listens on RabbitMQ and makes local HTTP calls
+5. **Zero Infrastructure in Services** - Services contain ONLY business logic
+
+## Architecture Decision
+
+### Why HTTP Pattern Over Handler Pattern
+
+Despite handler pattern being **3.4x faster** (2.1ms vs 7.1ms) and using **67% less memory** (60MB vs 100MB), we chose the HTTP pattern because:
+
+#### Handler Pattern Fatal Issues ❌
+- **Node modules conflicts** - Service needs mongoose 5.x, wrapper needs 6.x = CONFLICT
+- **Database connections broken** - Can't maintain connection pools
+- **Third-party integration failures** - AWS SDK version conflicts
+- **Testing becomes impossible** - Can't test service independently
+
+#### HTTP Pattern Benefits ✅
+- **100% compatibility** - All existing services work unchanged
+- **Standard patterns** - All Express tooling works
+- **Full functionality** - Databases, third-party services all work
+- **Simple testing** - Service can run standalone
+- **Acceptable overhead** - 5ms per request is negligible
+
+### Verdict
+For typical service with 100 req/s:
+- Performance difference: 500ms spread across 100 requests = **5ms per request**
+- **5ms overhead is acceptable price for working solution!**
+
+## Implementation Architecture
+
+### Service Structure
+
+```
+hello-service/
+├── src/
+│   ├── app.js           # Express app - business logic only
+│   ├── routes/          # Business endpoints
+│   └── handlers/        # Business logic
+├── conn-config/         # Wrapper configuration
+│   ├── config.json      # Service & wrapper config
+│   └── operations.json  # Operation to endpoint mapping
+├── index.js             # Main entry point (initializes wrapper)
+├── package.json         # Dependencies including @onlineapps/service-wrapper
+└── .env                 # Environment variables
+```
+
+### Runtime Flow
+
+```javascript
+// index.js - Service entry point
+const express = require('express');
+const { ServiceWrapper } = require('@onlineapps/service-wrapper');
+const app = require('./src/app');
+
+async function start() {
+  // 1. Start Express server
+  const server = app.listen(PORT);
+
+  // 2. Initialize wrapper components
+  const wrapper = new ServiceWrapper({
+    app,
+    server,
+    config: require('./conn-config/config.json'),
+    operations: require('./conn-config/operations.json')
+  });
+
+  await wrapper.initialize();
+  // Service now has all infrastructure components!
+}
+```
+
+### Message Processing
+
+#### HTTP Request Flow
+```
+Client → HTTP → Express Router → Handler → Response
+                     ↓
+              MonitoringConnector (metrics)
+```
+
+#### MQ Message Flow
+```
+RabbitMQ → MQConnector → Parse operations.json → HTTP localhost:3000/api/endpoint
+                                                        ↓
+                                                  Express Router → Handler
+                                                        ↓
+                                                  Response → MQ
+```
+
+## Component Architecture
+
+### Service Wrapper Components
+
+1. **MQConnector** - RabbitMQ integration
+   - Listens on `workflow.init` queue
+   - Listens on `{service-name}.workflow` queue
+   - Routes messages based on operations.json
+
+2. **MonitoringConnector** - Metrics collection
+   - Request tracking
+   - Performance metrics
+   - Error rates
+
+3. **HealthConnector** - Health checks
+   - Provides `/health` endpoint
+   - Aggregates component status
+   - Custom health check support
+
+4. **RegistryConnector** - Service discovery
+   - Registers service on startup
+   - Sends heartbeat
+   - Updates capabilities
+
+## Operations Schema
+
+Replaces OpenAPI with simpler format optimized for workflow processing:
+
+```json
+{
+  "operations": {
+    "operation-name": {
+      "description": "Human-readable description",
+      "endpoint": "/api/operation-name",
+      "method": "POST",
+      "input": {
+        "field1": { "type": "string", "required": true }
+      },
+      "output": {
+        "result": { "type": "string" }
+      }
+    }
+  }
+}
+```
+
+## Benefits of This Architecture
+
+### For Development
+- **Zero infrastructure code** in services
+- **Standard Express patterns** work
+- **Simple debugging** - one process, one log stream
+- **Easy testing** - service runs standalone
+
+### For Operations
+- **Simple deployment** - one process per service
+- **Central management** - update wrapper version for all
+- **Graceful shutdown** - wrapper handles cleanup
+- **No message loss** - RabbitMQ persistent queues
+
+### For Performance
+- **5ms overhead** - acceptable for real-world use
+- **Efficient resource usage** - shared memory in single process
+- **Connection pooling** - wrapper manages MQ connections
+- **Horizontal scaling** - just add more service instances
+
+## What Services DON'T Handle
+
+- ❌ RabbitMQ connection management
+- ❌ Queue subscription logic
+- ❌ Message parsing and validation
+- ❌ Service discovery registration
+- ❌ Health check implementation
+- ❌ Monitoring middleware
+- ❌ Retry and error handling
+
+**All handled by Service Wrapper components!**
+
+## Migration Strategy
+
+### For New Services
+1. Create Express app with business logic
+2. Add `conn-config/operations.json`
+3. Add Service Wrapper dependency
+4. Create `index.js` entry point
+5. Deploy
+
+### For Existing Services
+1. Keep all existing code unchanged
+2. Add configuration files
+3. Wrap with Service Wrapper
+4. Remove infrastructure code
+5. Deploy - no breaking changes!
+
+## Configuration
+
+### Service Configuration (conn-config/config.json)
+```json
+{
+  "service": {
+    "name": "hello-service",
+    "version": "1.0.0",
+    "port": 3000
+  },
+  "wrapper": {
+    "mq": {
+      "url": "${RABBITMQ_URL}",
+      "prefetch": 10
+    },
+    "monitoring": {
+      "enabled": true
+    },
+    "health": {
+      "endpoint": "/health"
+    },
+    "registry": {
+      "url": "${REGISTRY_URL}"
+    }
+  }
+}
+```
+
+## Testing Strategy
+
+### Unit Tests (without wrapper)
+```javascript
+const app = require('./src/app');
+const request = require('supertest');
+
+test('business logic', async () => {
+  const res = await request(app).post('/api/operation');
+  expect(res.status).toBe(200);
+});
+```
+
+### Integration Tests (with wrapper)
+```javascript
+const { start } = require('./index');
+
+beforeAll(async () => {
+  await start();
+});
+
+test('full service', async () => {
+  // Test with all infrastructure
+});
+```
+
+## Performance Characteristics
+
+| Metric | Value | Acceptable? |
+|--------|-------|-------------|
+| Added latency | 5ms per request | ✅ Yes |
+| Memory overhead | 40MB per service | ✅ Yes |
+| CPU overhead | 4% per 1000 req/s | ✅ Yes |
+| Startup time | +2 seconds | ✅ Yes |
+
+## Conclusion
+
+This architecture provides the **optimal balance** between:
+- **Simplicity** - Single process, standard patterns
+- **Compatibility** - Works with all existing services
+- **Performance** - Acceptable overhead for massive benefits
+- **Maintainability** - Central management, no duplication
+
+The 5ms latency overhead is a **small price** for:
+- 100% compatibility
+- Zero infrastructure code in services
+- Central management of all components
+- Full functionality including databases
+
+**This is the final, production-ready architecture for Service Wrapper.**