@onlineapps/service-wrapper 2.0.7 → 2.0.9

package/README.md

@@ -1,6 +1,19 @@
 # @onlineapps/service-wrapper
 
-Infrastructure wrapper that handles all workflow processing, message queue operations, and service registration for microservices.
+**Collection of connectors providing all infrastructure components for business services**
+
+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
+
+This package uses `@onlineapps/service-wrapper` WITHOUT any connector prefix because:
+- It's the main orchestration layer, not a specific connector
+- All services depend on it directly
+- It aggregates all other connectors (base, infra, orch)
+
+Directory: `/shared/connector/conn-app-service-wrapper/` (historical, kept for backward compatibility)
 
 ## Purpose
 
@@ -30,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');
 
-// Start wrapped service
-wrapper.start();
+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().catch(console.error);
 ```
 
 ### 2. Service Receives
@@ -77,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
@@ -133,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/API_STRUCTURE_STANDARD.md

@@ -0,0 +1,132 @@
+# API Structure Standard for Microservices
+
+## Endpoint Structure
+
+All microservices follow a simple, unversioned API structure.
+
+### URL Pattern
+
+```
+/                           # Service discovery
+/health                     # Health check
+/status                     # Service status
+/metrics                    # Prometheus metrics
+/specification              # Operations specification
+/api/{operation}            # Business operations
+```
+
+### Endpoint Categories
+
+- **System endpoints**: Health, status, metrics, specification
+- **Business endpoints** (`/api/*`): Application-specific operations
+
+## Standard Endpoints
+
+### Discovery Endpoint
+
+**GET /**
+```json
+{
+  "service": "service-name",
+  "version": "1.0.0",
+  "description": "Service description",
+  "specification": "/specification",
+  "health": "/health",
+  "status": "/status"
+}
+```
+
+### System Endpoints
+
+| Endpoint | Purpose | Response |
+|----------|---------|----------|
+| `GET /health` | Basic health check | `{"status": "healthy", "timestamp": "..."}` |
+| `GET /status` | Detailed service status | Service metrics and dependencies |
+| `GET /specification` | Operations specification | Operations JSON schema |
+| `GET /metrics` | Prometheus metrics | Metrics in Prometheus format |
+
+### Business Endpoints
+
+Service-specific operations under `/api/*`:
+- `POST /api/create-user`
+- `POST /api/process-order`
+- `GET /api/get-product`
+
+## Implementation Guide
+
+### Express.js Structure
+
+```javascript
+const express = require('express');
+const app = express();
+
+// Root endpoint - service discovery
+app.get('/', (req, res) => {
+  res.json({
+    service: process.env.SERVICE_NAME,
+    version: require('./package.json').version,
+    specification: '/specification',
+    health: '/health',
+    status: '/status'
+  });
+});
+
+// System endpoints
+app.get('/health', healthHandler);
+app.get('/status', statusHandler);
+app.get('/specification', specificationHandler);
+app.get('/metrics', metricsHandler);
+
+// Business endpoints under /api
+app.post('/api/create-user', createUserHandler);
+app.post('/api/process-order', processOrderHandler);
+app.get('/api/get-product', getProductHandler);
+```
+
+## Configuration Structure
+
+All service configurations are stored in `conn-config/` directory:
+
+```
+/your-service
+  /conn-config
+    /config.json        # Main configuration
+    /operations.json    # Operations specification
+    /middleware.json    # Middleware configuration
+```
+
+See [Configuration Guide](./CONFIGURATION_GUIDE.md) for details.
+
+## Migration Guide
+
+### From OpenAPI to Operations
+
+| Old | New | Purpose |
+|-----|-----|------|
+| `/api/v1/specification` | `/specification` | Operations schema |
+| `/v1/system/health` | `/health` | Health check |
+| `/v1/system/status` | `/status` | Service status |
+| `/v1/{operation}` | `/api/{operation}` | Business operations |
+
+### Simple Migration Steps
+
+1. Create `operations.json` from OpenAPI
+2. Remove version prefixes from endpoints
+3. Move business endpoints under `/api`
+4. Update service discovery response
+
+## Testing Requirements
+
+Tests must verify:
+
+1. **Discovery endpoint** returns service info and specification link
+2. **System endpoints** work correctly
+3. **Business endpoints** under `/api` process operations
+4. **Operations schema** is valid and complete
+
+## Benefits
+
+1. **Simplicity** - No version complexity
+2. **Clear structure** - System vs business separation
+3. **Direct mapping** - Operations to Cookbook steps
+4. **Lightweight** - Minimal configuration needed

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.