@onlineapps/service-wrapper 2.0.7 → 2.0.9

package/docs/CONFIGURATION_GUIDE.md

@@ -0,0 +1,261 @@
+# Service Configuration Guide
+
+## Configuration Directory Structure
+
+Every service must have a `conn-config/` directory with these configuration files:
+
+```
+/service-root
+  /conn-config
+    config.json         # Main service configuration
+    operations.json     # Operations specification
+    middleware.json     # Middleware stack configuration
+```
+
+## Configuration Files
+
+### 1. config.json - Main Configuration
+
+Primary service configuration with environment overrides:
+
+```json
+{
+  "service": {
+    "name": "hello-service",
+    "version": "1.0.0",
+    "description": "Greeting service",
+    "environment": "${NODE_ENV:development}"
+  },
+  "server": {
+    "port": "${PORT:3000}",
+    "host": "${HOST:0.0.0.0}",
+    "timeout": 30000
+  },
+  "api": {
+    "versions": {
+      "available": ["v1"],
+      "current": "v1",
+      "deprecated": []
+    },
+    "rateLimit": {
+      "enabled": true,
+      "windowMs": 60000,
+      "max": 100
+    }
+  },
+  "monitoring": {
+    "healthCheck": {
+      "interval": 30000,
+      "timeout": 5000
+    },
+    "metrics": {
+      "enabled": "${METRICS_ENABLED:true}",
+      "port": "${METRICS_PORT:9090}"
+    }
+  },
+  "dependencies": {
+    "rabbitmq": {
+      "url": "${RABBITMQ_URL:amqp://localhost:5672}",
+      "enabled": "${MQ_ENABLED:true}"
+    },
+    "redis": {
+      "url": "${REDIS_URL:redis://localhost:6379}",
+      "enabled": "${CACHE_ENABLED:false}"
+    }
+  }
+}
+```
+
+### 2. operations.json - Service Operations
+
+Defines all operations the service provides:
+
+```json
+{
+  "operations": {
+    "create-greeting": {
+      "description": "Generate a greeting message",
+      "handler": "handlers.greetings.create",
+      "endpoint": "/api/create-greeting",
+      "method": "POST",
+      "input": {
+        "name": {
+          "type": "string",
+          "required": true,
+          "description": "Name to greet"
+        }
+      },
+      "output": {
+        "message": {
+          "type": "string",
+          "description": "Generated greeting"
+        },
+        "timestamp": {
+          "type": "datetime"
+        }
+      }
+    }
+  }
+}
+```
+
+### 3. middleware.json - Middleware Configuration
+
+Middleware stack and configuration:
+
+```json
+{
+  "global": [
+    {
+      "name": "cors",
+      "enabled": true,
+      "config": {
+        "origin": "${CORS_ORIGIN:*}",
+        "credentials": true
+      }
+    },
+    {
+      "name": "helmet",
+      "enabled": true,
+      "config": {}
+    },
+    {
+      "name": "requestLogger",
+      "enabled": true,
+      "config": {
+        "level": "info"
+      }
+    },
+    {
+      "name": "bodyParser",
+      "enabled": true,
+      "config": {
+        "limit": "10mb"
+      }
+    }
+  ],
+  "routes": {
+    "authenticate": {
+      "handler": "middleware/auth.authenticate",
+      "config": {
+        "required": true
+      }
+    },
+    "authorize": {
+      "handler": "middleware/auth.authorize",
+      "config": {
+        "roles": ["admin", "user"]
+      }
+    },
+    "validate": {
+      "handler": "middleware/validation.validate"
+    },
+    "rateLimit": {
+      "handler": "middleware/rateLimit",
+      "config": {
+        "max": 100,
+        "windowMs": 60000
+      }
+    }
+  },
+  "error": [
+    {
+      "name": "notFound",
+      "handler": "middleware/errors.notFound"
+    },
+    {
+      "name": "errorHandler",
+      "handler": "middleware/errors.handler"
+    }
+  ]
+}
+```
+
+
+## Environment Variables
+
+Configuration supports environment variable substitution:
+
+- Format: `${VARIABLE_NAME:default_value}`
+- Example: `${PORT:3000}` uses PORT env var or defaults to 3000
+
+### Standard Environment Variables
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `NODE_ENV` | Environment (development/production) | development |
+| `SERVICE_NAME` | Service name | From config.json |
+| `PORT` | Server port | 3000 |
+| `LOG_LEVEL` | Logging level | info |
+| `RABBITMQ_URL` | RabbitMQ connection | amqp://localhost:5672 |
+| `REDIS_URL` | Redis connection | redis://localhost:6379 |
+| `METRICS_ENABLED` | Enable metrics | true |
+
+## Loading Configuration
+
+Service wrapper automatically loads configuration:
+
+```javascript
+const ServiceWrapper = require('@onlineapps/service-wrapper');
+
+// Automatically loads from ./conn-config/
+const wrapper = new ServiceWrapper();
+
+// Or specify custom path
+const wrapper = new ServiceWrapper({
+  configPath: './custom-config/'
+});
+
+// Access configuration
+const config = wrapper.config;
+console.log(config.service.name);
+```
+
+## Validation
+
+Configuration is validated on startup:
+
+1. Required files exist
+2. JSON syntax is valid
+3. Required fields are present
+4. Environment variables are resolved
+5. Operations schema is valid
+
+## Best Practices
+
+1. **Keep sensitive data in environment variables** - Never commit secrets
+2. **Use defaults** - Provide sensible defaults for all configs
+3. **Document all options** - Include descriptions in configs
+4. **Validate early** - Fail fast on invalid configuration
+5. **Version your configs** - Track configuration changes
+
+## Service Configuration Example
+
+### config.json with Execution Mode
+```json
+{
+  "service": {
+    "name": "hello-service",
+    "version": "1.0.0",
+    "execution": {
+      "mode": "${EXECUTION_MODE:direct}",
+      "direct": {
+        "handler": "./src/handlers"
+      },
+      "http": {
+        "baseUrl": "${SERVICE_URL:http://localhost:3000}"
+      }
+    }
+  },
+  "monitoring": {
+    "healthCheck": {
+      "interval": 30000
+    }
+  }
+}
+```
+
+### Execution Modes
+
+- **direct**: Service Wrapper calls handlers directly (50% memory savings)
+- **http**: Service Wrapper makes HTTP calls (for external services)

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.**