@onlineapps/service-wrapper 2.0.6 → 2.0.8

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/service-wrapper",
-  "version": "2.0.6",
+  "version": "2.0.8",
   "description": "Thin orchestration layer for microservices - delegates all infrastructure concerns to specialized connectors",
   "main": "src/index.js",
   "scripts": {
@@ -24,17 +24,19 @@
   "author": "OA Drive Team",
   "license": "MIT",
   "dependencies": {
-    "@onlineapps/conn-base-logger": "^1.0.0",
+    "@onlineapps/conn-base-cache": "^1.0.0",
+    "@onlineapps/conn-base-monitoring": "file:../conn-base-monitoring/onlineapps-conn-base-monitoring-1.0.0.tgz",
+    "@onlineapps/conn-infra-error-handler": "^1.0.0",
     "@onlineapps/conn-infra-mq": "^1.1.0",
-    "@onlineapps/conn-orch-registry": "^1.1.4",
+    "@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-api-mapper": "^1.0.0",
-    "@onlineapps/conn-base-cache": "^1.0.0",
-    "@onlineapps/conn-infra-error-handler": "^1.0.0"
+    "@onlineapps/conn-orch-registry": "^1.1.4",
+    "@onlineapps/monitoring-core": "file:../../../api/shared/monitoring-core/onlineapps-monitoring-core-1.0.0.tgz"
   },
   "devDependencies": {
-    "jest": "^29.5.0",
+    "express": "^5.1.0",
+    "jest": "^29.7.0",
     "jsdoc": "^4.0.2",
     "jsdoc-to-markdown": "^8.0.0"
   },

package/src/ServiceWrapper.js

@@ -13,7 +13,7 @@
 // Import connectors
 const MQConnector = require('@onlineapps/conn-infra-mq');
 const RegistryConnector = require('@onlineapps/conn-orch-registry');
-const LoggerConnector = require('@onlineapps/conn-base-logger');
+const MonitoringConnector = require('@onlineapps/conn-base-monitoring');
 const OrchestratorConnector = require('@onlineapps/conn-orch-orchestrator');
 const ApiMapperConnector = require('@onlineapps/conn-orch-api-mapper');
 const CookbookConnector = require('@onlineapps/conn-orch-cookbook');
@@ -69,7 +69,8 @@ class ServiceWrapper {
     this.config = options.config || {};
 
     // Initialize connectors
-    this.logger = LoggerConnector.create(this.serviceName);
+    this.logger = MonitoringConnector; // Singleton, will be initialized later
+    this.monitoring = MonitoringConnector; // Also expose as monitoring for clarity
     this.mqClient = null;
     this.registryClient = null;
     this.orchestrator = null;
@@ -109,11 +110,14 @@ class ServiceWrapper {
    */
   async start() {
     if (this.isRunning) {
-      this.logger.warn('Service wrapper already running');
+      console.warn('Service wrapper already running');
       return;
     }
 
     try {
+      // Initialize monitoring first
+      await this.monitoring.init({ serviceName: this.serviceName });
+
       this.logger.info(`Starting service wrapper for ${this.serviceName}`);
 
       // 1. Initialize infrastructure connectors
@@ -298,8 +302,37 @@ class ServiceWrapper {
     // Subscribe to workflow messages
     await this.mqClient.consume(
       queueName,
-      async (message) => {
+      async (rawMessage) => {
         try {
+          // Parse message content if it's a buffer (AMQP message)
+          let message;
+          if (rawMessage && rawMessage.content) {
+            // This is an AMQP message with content buffer
+            const messageContent = rawMessage.content.toString();
+            try {
+              message = JSON.parse(messageContent);
+            } catch (parseError) {
+              this.logger.error('Failed to parse message content', {
+                error: parseError.message,
+                content: messageContent
+              });
+              throw parseError;
+            }
+          } else {
+            // Already parsed or direct message
+            message = rawMessage;
+          }
+
+          // DEBUG: Log the actual message structure
+          this.logger.info('DEBUG: Received message structure', {
+            workflow_id: message.workflow_id,
+            has_cookbook: !!message.cookbook,
+            cookbook_name: message.cookbook?.name,
+            cookbook_steps: message.cookbook?.steps?.length,
+            first_step: message.cookbook?.steps?.[0],
+            current_step: message.current_step
+          });
+
           // Delegate ALL processing to orchestrator
           const result = await this.orchestrator.processWorkflowMessage(
             message,
@@ -314,8 +347,8 @@ class ServiceWrapper {
 
         } catch (error) {
           this.logger.error('Message processing failed', {
-            workflow_id: message.workflow_id,
-            step: message.current_step,
+            workflow_id: message?.workflow_id || 'unknown',
+            step: message?.current_step || 'unknown',
             error: error.message
           });
         }