@onlineapps/service-wrapper 2.0.6 → 2.0.8

package/README.md

@@ -1,7 +1,18 @@
 # @onlineapps/service-wrapper
 
+**Main orchestration package for microservices - NO prefix as it's the primary integration point**
+
 Infrastructure wrapper that handles all workflow processing, message queue operations, and service registration for microservices.
 
+## 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
 
 This package provides the infrastructure layer that sits between:

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/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)