@onlineapps/service-wrapper 2.0.7 → 2.0.9

package/docs/SERVICE_TESTING_STANDARD.md

@@ -0,0 +1,389 @@
+# Service Testing Standard and OpenAPI Generation
+
+## 1. OpenAPI Schema Generation
+
+### Step 1: Analyze Your Service Endpoints
+
+List all your service endpoints and their:
+- HTTP methods (GET, POST, PUT, DELETE)
+- Request parameters (query, path, body)
+- Response structures
+- Error responses
+
+### Step 2: Create openapi.yaml
+
+Create `openapi.yaml` in your service root directory with this structure:
+
+```yaml
+openapi: 3.0.0
+info:
+  title: # Your service name from package.json
+  version: # Your service version from package.json
+  description: # Brief description of what your service does
+
+servers:
+  - url: http://localhost:{your-port}
+    description: Local development
+  - url: http://{container-name}:3000
+    description: Docker container
+
+paths:
+  # Document each endpoint
+  /your-endpoint:
+    get/post/put/delete:
+      summary: # One line description
+      operationId: # Unique identifier (e.g., getUsers, createOrder)
+      parameters: # If applicable
+      requestBody: # If applicable
+      responses:
+        '200':
+          description: # Success response
+          content:
+            application/json:
+              schema:
+                # Define or reference schema
+        '400':
+          # Bad request
+        '500':
+          # Server error
+
+components:
+  schemas:
+    # Define reusable schemas here
+```
+
+### Step 3: Generate Schema from Code (Alternative)
+
+If you have many endpoints, generate initial schema:
+
+```bash
+# Install openapi generator
+npm install --save-dev @apidevtools/swagger-cli
+
+# For Express apps, use express-openapi-generator
+npm install --save-dev express-openapi-generator
+
+# Add generation script to package.json
+"scripts": {
+  "generate:openapi": "node scripts/generate-openapi.js"
+}
+```
+
+Create `scripts/generate-openapi.js`:
+```javascript
+const app = require('../src/app');
+const generator = require('express-openapi-generator');
+
+generator(app, {
+  outputFile: './openapi.yaml',
+  info: {
+    title: process.env.SERVICE_NAME,
+    version: require('../package.json').version
+  }
+});
+```
+
+### Step 4: Validate Your Schema
+
+```bash
+# Install validator
+npm install --save-dev @apidevtools/swagger-parser
+
+# Add validation script
+"scripts": {
+  "validate:openapi": "swagger-cli validate openapi.yaml"
+}
+```
+
+## 2. Test Structure
+
+### Directory Structure
+
+```
+/your-service
+  /test
+    /unit          # Unit tests for individual functions
+    /integration   # Integration tests with mocked dependencies
+    /api           # API endpoint tests
+    /compliance    # OpenAPI compliance tests
+    test.config.js # Shared test configuration
+```
+
+### Test Configuration
+
+Create `test/test.config.js`:
+```javascript
+module.exports = {
+  // Service configuration for tests
+  service: {
+    name: process.env.SERVICE_NAME || 'your-service',
+    port: process.env.PORT || 3000,
+    baseUrl: `http://localhost:${process.env.PORT || 3000}`
+  },
+
+  // Timeouts
+  timeouts: {
+    unit: 5000,
+    integration: 10000,
+    api: 15000
+  },
+
+  // Mock data
+  mocks: {
+    validRequest: { /* valid request data */ },
+    invalidRequest: { /* invalid request data */ }
+  }
+};
+```
+
+## 3. Test Implementation
+
+### Unit Tests (`test/unit/`)
+
+Test individual functions without external dependencies:
+
+```javascript
+describe('Business Logic', () => {
+  test('should process valid input', () => {
+    const result = processFunction(validInput);
+    expect(result).toBeDefined();
+    expect(result.status).toBe('success');
+  });
+
+  test('should handle invalid input', () => {
+    expect(() => processFunction(invalidInput)).toThrow();
+  });
+});
+```
+
+### API Tests (`test/api/`)
+
+Test actual HTTP endpoints:
+
+```javascript
+const request = require('supertest');
+const app = require('../../src/app');
+
+describe('API Endpoints', () => {
+  describe('GET /your-endpoint', () => {
+    test('should return 200 with valid response', async () => {
+      const response = await request(app)
+        .get('/your-endpoint')
+        .expect(200);
+
+      expect(response.body).toHaveProperty('expectedField');
+    });
+
+    test('should return 400 for invalid request', async () => {
+      const response = await request(app)
+        .get('/your-endpoint?invalid=true')
+        .expect(400);
+
+      expect(response.body).toHaveProperty('error');
+    });
+  });
+});
+```
+
+### Compliance Tests (`test/compliance/`)
+
+Test OpenAPI compliance:
+
+```javascript
+const SwaggerParser = require('@apidevtools/swagger-parser');
+const request = require('supertest');
+const app = require('../../src/app');
+const openApiSchema = require('../../openapi.yaml');
+
+describe('OpenAPI Compliance', () => {
+  let api;
+
+  beforeAll(async () => {
+    // Validate and parse schema
+    api = await SwaggerParser.validate(openApiSchema);
+  });
+
+  test('schema should be valid OpenAPI 3.0', () => {
+    expect(api.openapi).toBe('3.0.0');
+  });
+
+  test('all endpoints should match schema', async () => {
+    for (const [path, methods] of Object.entries(api.paths)) {
+      for (const [method, spec] of Object.entries(methods)) {
+        if (['get', 'post', 'put', 'delete'].includes(method)) {
+          const response = await request(app)[method](path);
+          // Validate response matches schema
+          expect(response.status).toBeDefined();
+        }
+      }
+    }
+  });
+});
+```
+
+## 4. NPM Scripts
+
+Add to `package.json`:
+
+```json
+{
+  "scripts": {
+    "test": "npm run test:unit && npm run test:api && npm run test:compliance",
+    "test:unit": "jest test/unit",
+    "test:integration": "jest test/integration",
+    "test:api": "jest test/api",
+    "test:compliance": "jest test/compliance",
+    "test:coverage": "jest --coverage",
+    "validate:openapi": "swagger-cli validate openapi.yaml",
+    "generate:openapi": "node scripts/generate-openapi.js",
+    "serve:docs": "swagger-ui-express openapi.yaml"
+  }
+}
+```
+
+### Coverage Requirements
+
+**Minimum recommended coverage: 80%**
+
+Configure Jest coverage thresholds in `package.json`:
+
+```json
+{
+  "jest": {
+    "coverageThreshold": {
+      "global": {
+        "branches": 80,
+        "functions": 80,
+        "lines": 80,
+        "statements": 80
+      }
+    },
+    "collectCoverageFrom": [
+      "src/**/*.js",
+      "!src/**/*.test.js",
+      "!src/**/*.spec.js"
+    ]
+  }
+}
+```
+
+## 5. Service Wrapper Integration
+
+### Endpoint for OpenAPI Schema
+
+Your service must expose its schema:
+
+```javascript
+// In your app.js or routes
+const fs = require('fs');
+const yaml = require('js-yaml');
+
+app.get('/openapi', (req, res) => {
+  try {
+    const doc = yaml.load(fs.readFileSync('./openapi.yaml', 'utf8'));
+    res.json(doc);
+  } catch (e) {
+    res.status(500).json({ error: 'Schema not available' });
+  }
+});
+```
+
+### Validation Middleware
+
+Use Service Wrapper's validation:
+
+```javascript
+const { validateRequest } = require('@onlineapps/service-wrapper/middleware');
+const openApiSchema = require('./openapi.yaml');
+
+// Apply validation to routes
+app.post('/your-endpoint',
+  validateRequest(openApiSchema, '/your-endpoint', 'post'),
+  (req, res) => {
+    // Request is already validated
+  }
+);
+```
+
+## 6. Continuous Validation
+
+### Pre-commit Hook
+
+`.husky/pre-commit`:
+```bash
+#!/bin/sh
+npm run validate:openapi
+npm run test:compliance
+```
+
+### CI/CD Pipeline
+
+```yaml
+# .github/workflows/test.yml or gitlab-ci.yml
+test:
+  script:
+    - npm install
+    - npm run validate:openapi
+    - npm run test
+    - npm run test:coverage
+  coverage: '/Lines\s*:\s*(\d+\.\d+)%/'
+```
+
+## 7. Validation Checklist
+
+Before deployment, ensure:
+
+- [ ] OpenAPI schema exists at `/openapi.yaml`
+- [ ] Schema validates with `swagger-cli validate`
+- [ ] All endpoints documented in schema
+- [ ] Request/response schemas defined
+- [ ] Error responses documented
+- [ ] Schema version matches package.json
+- [ ] `/openapi` endpoint returns schema
+- [ ] Unit tests pass (>80% coverage)
+- [ ] API tests pass
+- [ ] Compliance tests pass
+- [ ] Service Wrapper can load schema
+- [ ] Validation middleware works
+
+## 8. Common Issues and Solutions
+
+### Issue: Schema doesn't match implementation
+**Solution**: Generate schema from code first, then refine manually
+
+### Issue: Validation too strict
+**Solution**: Use `additionalProperties: true` in schemas during development
+
+### Issue: Complex nested objects
+**Solution**: Break into components and use `$ref`
+
+### Issue: Different environments need different configs
+**Solution**: Use environment variables in schema:
+```yaml
+servers:
+  - url: ${API_BASE_URL}
+    description: Configured base URL
+```
+
+## 9. Testing with conn-e2e-testing
+
+The connector testing framework will:
+1. Load your OpenAPI schema
+2. Start your service
+3. Test each endpoint against schema
+4. Validate requests and responses
+5. Generate compliance report
+
+Ensure your service is ready by:
+1. Exposing `/openapi` endpoint
+2. Having all endpoints documented
+3. Returning proper HTTP status codes
+4. Using consistent error format
+
+## 10. Resources
+
+- [OpenAPI 3.0 Specification](https://swagger.io/specification/)
+- [JSON Schema Validation](https://json-schema.org/draft/2019-09/json-schema-validation.html)
+- [swagger-cli Documentation](https://apitools.dev/swagger-cli/)
+- Service Wrapper documentation: `/shared/connector/service-wrapper/README.md`
+- Testing examples: `/shared/connector/conn-e2e-testing/examples/`

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.7",
+  "version": "2.0.9",
   "description": "Thin orchestration layer for microservices - delegates all infrastructure concerns to specialized connectors",
   "main": "src/index.js",
   "scripts": {
@@ -25,13 +25,14 @@
   "license": "MIT",
   "dependencies": {
     "@onlineapps/conn-base-cache": "^1.0.0",
-    "@onlineapps/conn-base-logger": "^1.0.0",
+    "@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/conn-orch-registry": "^1.1.4",
+    "@onlineapps/monitoring-core": "^1.0.0"
   },
   "devDependencies": {
     "express": "^5.1.0",