@onlineapps/conn-orch-validator 2.0.0

package/README.md

@@ -0,0 +1,78 @@
+# @onlineapps/conn-orch-validator
+
+**Validation Orchestrator for OA Drive Microservices**
+
+Coordinates validation across ALL layers (base, infra, orch, business) to ensure service + connectors work correctly together.
+
+## Purpose
+
+This is **NOT** a development testing tool. This is a **production validation orchestrator** that:
+
+1. **Validates service structure** - directories, files, configuration
+2. **Validates configuration** - config.json, operations.json compliance
+3. **Validates business logic** - cookbook tests with mocked infrastructure
+4. **Validates HTTP API** - endpoints respond correctly
+5. **Validates connector integration** - all connectors work with service
+6. **Generates validation proof** - cryptographic SHA256 proof for registry
+
+Used in **Tier 1 Pre-Validation** (offline, before registration) and invoked automatically by ServiceWrapper.
+
+## Quick Start
+
+**You don't use this directly!** ServiceWrapper handles validation automatically:
+
+```javascript
+// services/my-service/index.js
+const { ServiceWrapper } = require('@onlineapps/service-wrapper');
+
+const wrapper = new ServiceWrapper({
+  service: app,
+  serviceRoot: __dirname
+});
+
+// Validation happens automatically
+await wrapper.initialize();
+```
+
+**No test files needed in business service!**
+
+---
+
+## Validation Process (6 Steps)
+
+1. **Service Structure** - directories and files exist
+2. **Config Files** - valid JSON, required fields
+3. **Operations Compliance** - follows OPERATIONS.md standard
+4. **Cookbook Tests** - business logic + integration (MOCKED infra)
+5. **Service Readiness** - HTTP API works
+6. **Connector Integration** - all connectors functional
+
+**Output:** Validation proof saved to `conn-runtime/validation-proof.json`
+
+---
+
+## Runtime Directory Structure
+
+```
+services/my-service/
+├── conn-config/              ← Static (gitignored: NO)
+│   ├── config.json
+│   └── operations.json
+├── conn-runtime/             ← Runtime (gitignored: YES)
+│   ├── validation-proof.json
+│   └── cache/
+└── .gitignore
+```
+
+---
+
+## Related Documentation
+
+- [SERVICE_REGISTRATION_FLOW.md](/services/hello-service/docs/SERVICE_REGISTRATION_FLOW.md)
+- [/docs/architecture/validator.md](/docs/architecture/validator.md)
+- [/docs/standards/OPERATIONS.md](/docs/standards/OPERATIONS.md)
+- [@onlineapps/service-validator-core](/shared/service-validator-core/README.md)
+
+---
+
+*Last updated: 2025-10-21*

package/TESTING_STRATEGY.md

@@ -0,0 +1,92 @@
+# Integration Testing Strategy Analysis
+
+## 📋 Testing Scope Analysis
+
+### ✅ DÁVÁ SMYSL - Rozsáhlé E2E testy
+1. **ServiceWrapper E2E testy**
+   - Kompletní flow: MQ → Wrapper → HTTP → Response
+   - Multi-step workflows
+   - Error handling & retry logic
+   - Circuit breaker testing
+   - Performance & load testing
+
+2. **conn-orch-validator package**
+   - Orchestruje všechny E2E testy
+   - Testuje kompletní workflow scenarios
+   - Simuluje reálné use cases
+
+3. **Infrastrukturní uzly**
+   - RabbitMQ integration (message flow, dead letter queues)
+   - Redis integration (caching, session management)
+   - Registry integration (service discovery, health checks)
+
+### ❓ ZVÁŽIT - Unit testy jednotlivých balíčků
+- Jednotlivé connectors už mají unit testy ✅
+- Integration testy jednotlivých connectors možná redundantní
+- Lepší je testovat je jako součást větších E2E testů
+
+## 🎯 Priority Testing Areas
+
+### 1. Critical Path Testing
+- **hello-service complete flow** ✅ DONE
+  - HTTP server running
+  - MQ wrapper listening
+  - Message processing working
+
+### 2. ServiceWrapper Integration
+- Registry registration/heartbeat
+- MQ message consumption
+- HTTP service invocation
+- Response handling
+- Error scenarios
+
+### 3. Workflow Orchestration
+- Multi-step workflows
+- Conditional branching
+- Parallel execution
+- Error recovery
+
+### 4. Infrastructure Resilience
+- Service failures & recovery
+- Network partitions
+- Message queue failures
+- Cache misses
+
+## 📝 Implementation Progress
+
+### Completed
+- ✅ hello-service hybrid architecture implemented
+- ✅ MQ wrapper successfully starts and listens
+- ✅ Fixed all initialization issues:
+  - ServiceWrapper consume() parameter order
+  - RegistryClient queueManager.init()
+  - Redis cache singleton issues
+  - LoggerConnector initialization in ServiceWrapper
+- ✅ ServiceWrapper E2E test suite created
+- ✅ Test infrastructure setup (Jest, Express for mock services)
+- ✅ Fixed message parsing from AMQP buffer to JSON
+- ✅ Created test-mq-flow.js for testing message flow
+- ✅ Fixed cookbook validation (added type field to steps)
+
+### In Progress
+- 🔧 Verifying complete E2E message flow
+- 🔧 Testing workflow orchestration with real services
+
+### TODO
+- [ ] Implement response queue listener for capturing results
+- [ ] Complete E2E test suite with all scenarios
+- [ ] Load testing scenarios
+- [ ] Chaos engineering tests
+- [ ] Performance benchmarks
+
+## 🚀 Next Session Actions
+
+1. **Complete conn-orch-validator package**
+2. **Run full E2E test suite**
+3. **Document test results**
+4. **Fix any issues found**
+5. **Performance optimization based on test results**
+
+---
+*Last updated: 2025-09-26*
+*Session ending at 5hr limit*

package/docs/DESIGN.md

@@ -0,0 +1,134 @@
+# Connector-Testing Design Document
+
+## Purpose
+
+The conn-orch-validator package provides a unified testing and validation framework for OA Drive microservices. It serves three critical functions:
+
+1. **Development Testing** - Mock infrastructure for isolated service testing
+2. **Production Validation** - On-the-fly validation of new services during registration
+3. **Service Readiness** - Complete verification before deployment
+
+## Key Principles
+
+### No Duplication
+- Does NOT duplicate tests from individual connectors
+- Uses existing connector functionality where available
+- Focuses on integration and orchestration
+
+### Production-Ready
+- Same code used in development AND production
+- Validates services before they join the ecosystem
+- Ensures cookbook compatibility
+
+## Components
+
+### 1. Mock Infrastructure (Development)
+- `MockMQClient` - In-memory message queue simulation
+- `MockRegistry` - Service registry simulation
+- `MockStorage` - Object storage simulation
+
+### 2. Validation Tools (Production)
+- `ServiceValidator` - OpenAPI compliance and endpoint testing
+- `WorkflowTestRunner` - Cookbook execution testing
+- `CookbookTestUtils` - Cookbook structure validation
+
+### 3. Integration Framework
+- `ServiceTestHarness` - Complete test environment orchestration
+
+## Use Cases
+
+### Development Workflow
+```javascript
+// Developer testing their service
+const harness = new ServiceTestHarness({
+  service: myExpressApp,
+  serviceName: 'my-service',
+  openApiSpec: spec,
+  mockInfrastructure: true  // Use mocks
+});
+
+await harness.start();
+// Run tests...
+await harness.stop();
+```
+
+### Production Validation
+```javascript
+// Registry validating new service
+const validator = new ServiceValidator();
+const result = await validator.validateService(
+  serviceUrl,
+  openApiSpec
+);
+
+if (!result.valid) {
+  // Reject registration
+}
+```
+
+### Service-Wrapper Integration
+```javascript
+// Service-wrapper using connector-testing
+class ServiceWrapper {
+  async validateBeforeStart() {
+    const validator = new ServiceValidator();
+    const validation = await validator.validateService(
+      `http://localhost:${this.port}`,
+      this.openApiSpec
+    );
+
+    if (!validation.valid) {
+      throw new Error('Service validation failed');
+    }
+  }
+}
+```
+
+## Testing Strategy
+
+### What We Test
+1. **Service Contract** - OpenAPI compliance
+2. **Workflow Capability** - Can process cookbooks
+3. **Infrastructure Integration** - Registry, MQ, Storage connectivity
+4. **Health & Status** - Monitoring endpoints
+
+### What We DON'T Test
+1. Individual connector functionality (tested in connector packages)
+2. Business logic correctness (service's responsibility)
+3. Performance metrics (separate concern)
+
+## Production Validation Flow
+
+```
+New Service Registration
+         ↓
+    [Registry]
+         ↓
+    Uses connector-testing
+         ↓
+    1. Validate OpenAPI
+    2. Test all endpoints
+    3. Execute test cookbook
+    4. Verify health check
+         ↓
+    Pass? → Accept : Reject
+```
+
+## Integration with Existing System
+
+### Uses Existing Connectors
+- Leverages real connector implementations where possible
+- Only mocks what's necessary for isolation
+- Validates against actual connector interfaces
+
+### Complements Existing Tests
+- Individual connectors have unit tests
+- Services have business logic tests
+- Connector-testing provides integration validation
+
+## Future Enhancements
+
+1. **Performance Benchmarking** - Baseline performance requirements
+2. **Security Validation** - Authentication/authorization checks
+3. **Chaos Testing** - Fault injection and recovery
+4. **Compliance Checking** - Regulatory requirement validation

package/examples/service-wrapper-usage.js

@@ -0,0 +1,250 @@
+'use strict';
+
+/**
+ * Example: How service-wrapper uses connector-testing
+ * Shows the integration between service-wrapper and testing framework
+ */
+
+const { ServiceReadinessValidator, TestOrchestrator } = require('../src');
+
+/**
+ * Enhanced ServiceWrapper with integrated testing
+ */
+class ServiceWrapperWithTesting {
+  constructor(options) {
+    this.service = options.service;
+    this.serviceName = options.serviceName;
+    this.openApiSpec = options.openApiSpec;
+    this.config = options.config;
+
+    // Testing configuration
+    this.testingEnabled = options.testingEnabled !== false;
+    this.testLevel = options.testLevel || 'component'; // unit, component, or integration
+    this.validator = new ServiceReadinessValidator();
+  }
+
+  /**
+   * Start service with validation
+   */
+  async start() {
+    console.log(`Starting ${this.serviceName}...`);
+
+    // Step 1: Pre-start validation
+    if (this.testingEnabled) {
+      const validation = await this.validateBeforeStart();
+
+      if (!validation.ready) {
+        throw new Error(`Service validation failed: ${validation.recommendation}`);
+      }
+
+      console.log(`Validation passed with score: ${validation.score}/100`);
+    }
+
+    // Step 2: Start the actual service
+    await this.startService();
+
+    // Step 3: Post-start verification
+    if (this.testingEnabled) {
+      await this.verifyAfterStart();
+    }
+
+    console.log(`${this.serviceName} started successfully`);
+  }
+
+  /**
+   * Validate service before starting
+   */
+  async validateBeforeStart() {
+    console.log('Running pre-start validation...');
+
+    // Use TestOrchestrator for comprehensive testing
+    const orchestrator = new TestOrchestrator({
+      service: this.service,
+      serviceName: this.serviceName,
+      openApiSpec: this.openApiSpec
+    });
+
+    // Run tests based on configured level
+    let testResults;
+    switch (this.testLevel) {
+      case 'unit':
+        testResults = await orchestrator.runUnitTests();
+        break;
+      case 'component':
+        testResults = await orchestrator.runComponentTests();
+        break;
+      case 'integration':
+        testResults = await orchestrator.runIntegrationTests();
+        break;
+      default:
+        testResults = await orchestrator.runComponentTests();
+    }
+
+    // Convert test results to readiness format
+    return {
+      ready: testResults.passed,
+      score: testResults.coverage || 0,
+      recommendation: testResults.passed
+        ? 'Service passed validation'
+        : 'Service failed validation tests',
+      details: testResults
+    };
+  }
+
+  /**
+   * Start the actual service
+   */
+  async startService() {
+    // This would contain the actual service startup logic
+    // - Start Express server
+    // - Connect to MQ
+    // - Register with registry
+    // - etc.
+
+    return new Promise((resolve) => {
+      const PORT = this.config.port || 3000;
+      this.server = this.service.listen(PORT, () => {
+        console.log(`Service listening on port ${PORT}`);
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Verify service after start
+   */
+  async verifyAfterStart() {
+    console.log('Running post-start verification...');
+
+    const serviceUrl = `http://localhost:${this.config.port || 3000}`;
+
+    // Quick readiness check
+    const readiness = await this.validator.validateReadiness({
+      name: this.serviceName,
+      url: serviceUrl,
+      openApiSpec: this.openApiSpec,
+      healthEndpoint: '/health'
+    });
+
+    if (!readiness.ready) {
+      console.warn('Post-start verification found issues:', readiness.errors);
+    }
+
+    return readiness;
+  }
+
+  /**
+   * Stop service
+   */
+  async stop() {
+    if (this.server) {
+      await new Promise((resolve) => {
+        this.server.close(resolve);
+      });
+    }
+  }
+}
+
+// === Example Usage ===
+
+async function demonstrateUsage() {
+  const express = require('express');
+
+  // Create a simple service
+  const app = express();
+  app.use(express.json());
+
+  app.get('/health', (req, res) => {
+    res.json({ status: 'healthy' });
+  });
+
+  app.post('/api/process', (req, res) => {
+    res.json({ processed: true, data: req.body });
+  });
+
+  // OpenAPI spec
+  const openApiSpec = {
+    openapi: '3.0.0',
+    info: { title: 'Demo Service', version: '1.0.0' },
+    paths: {
+      '/health': {
+        get: {
+          operationId: 'healthCheck',
+          responses: {
+            '200': {
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      status: { type: 'string' }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      '/api/process': {
+        post: {
+          operationId: 'processData',
+          requestBody: {
+            content: {
+              'application/json': {
+                schema: { type: 'object' }
+              }
+            }
+          },
+          responses: {
+            '200': {
+              content: {
+                'application/json': {
+                  schema: { type: 'object' }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  };
+
+  // Create wrapper with testing
+  const wrapper = new ServiceWrapperWithTesting({
+    service: app,
+    serviceName: 'demo-service',
+    openApiSpec,
+    config: {
+      port: 3333
+    },
+    testingEnabled: true,
+    testLevel: 'unit' // Start with unit tests for speed
+  });
+
+  try {
+    // Start service (will run validation first)
+    await wrapper.start();
+
+    console.log('\nService is running with validation!');
+    console.log('Try: curl http://localhost:3333/health');
+
+    // Keep running for demo
+    await new Promise(resolve => setTimeout(resolve, 5000));
+
+    // Stop service
+    await wrapper.stop();
+    console.log('\nService stopped');
+
+  } catch (error) {
+    console.error('Failed to start service:', error.message);
+    process.exit(1);
+  }
+}
+
+// Run demonstration
+if (require.main === module) {
+  demonstrateUsage().catch(console.error);
+}
+
+module.exports = { ServiceWrapperWithTesting };

package/examples/three-tier-testing.js

@@ -0,0 +1,144 @@
+'use strict';
+
+/**
+ * Example: Three-tier testing strategy
+ * Shows how to use connector-testing for comprehensive service validation
+ */
+
+const { TestOrchestrator } = require('../src');
+const express = require('express');
+
+// Example service
+const app = express();
+app.use(express.json());
+
+app.get('/health', (req, res) => {
+  res.json({ status: 'healthy', service: 'example-service' });
+});
+
+app.post('/process', (req, res) => {
+  res.json({
+    processed: true,
+    input: req.body,
+    timestamp: Date.now()
+  });
+});
+
+app.get('/status', (req, res) => {
+  res.json({
+    running: true,
+    uptime: process.uptime()
+  });
+});
+
+// OpenAPI specification
+const openApiSpec = {
+  openapi: '3.0.0',
+  info: {
+    title: 'Example Service',
+    version: '1.0.0'
+  },
+  paths: {
+    '/health': {
+      get: {
+        operationId: 'healthCheck',
+        responses: {
+          '200': {
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    status: { type: 'string' },
+                    service: { type: 'string' }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    '/process': {
+      post: {
+        operationId: 'processData',
+        requestBody: {
+          content: {
+            'application/json': {
+              schema: { type: 'object' }
+            }
+          }
+        },
+        responses: {
+          '200': {
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    processed: { type: 'boolean' },
+                    input: { type: 'object' },
+                    timestamp: { type: 'number' }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    '/status': {
+      get: {
+        operationId: 'getStatus',
+        responses: {
+          '200': {
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    running: { type: 'boolean' },
+                    uptime: { type: 'number' }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+};
+
+async function runExample() {
+  console.log('=== Three-Tier Testing Example ===\n');
+
+  // Create test orchestrator
+  const orchestrator = new TestOrchestrator({
+    service: app,
+    serviceName: 'example-service',
+    openApiSpec,
+    logger: console
+  });
+
+  // Run all three levels of testing
+  console.log('Starting comprehensive test suite...\n');
+  const results = await orchestrator.runAllTests();
+
+  // Generate and display report
+  const report = orchestrator.generateReport(results);
+  console.log('\n' + report);
+
+  // Return exit code based on results
+  process.exit(results.passed ? 0 : 1);
+}
+
+// Run if executed directly
+if (require.main === module) {
+  runExample().catch(error => {
+    console.error('Test failed:', error);
+    process.exit(1);
+  });
+}
+
+module.exports = { app, openApiSpec, runExample };