@onlineapps/conn-orch-validator 2.0.33 → 2.0.34

package/docs/DESIGN.md

@@ -1,134 +1,80 @@
-# Connector-Testing Design Document
+# conn-orch-validator — Design
 
 ## Purpose
 
-The conn-orch-validator package provides a unified testing and validation framework for OA Drive microservices. It serves three critical functions:
+Validation framework for OA Drive microservices. Drives two flows:
 
-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
+1. **Pre-validation** (Tier 1) — runs during `service-wrapper` startup. Verifies
+   structure (config files, package.json), readiness (endpoints respond, health
+   works) and produces a signed `validation-proof.json` stored under
+   `conn-runtime/`.
+2. **Readiness checks** — reusable probes (`createServiceReadinessTests`,
+   `createPreValidationTests`) consumable from unit/component test suites
+   of individual biz services.
 
-## Key Principles
+The single source of truth for service endpoint metadata is
+[`operations.json`](../../../docs/standards/operations-registry-contract.md).
+OpenAPI iteration (`paths`/`operationId`) is NOT supported — that legacy
+surface was removed together with the now-retired `ServiceValidator` /
+`TestOrchestrator` / `ServiceTestHarness` classes.
 
-### No Duplication
-- Does NOT duplicate tests from individual connectors
-- Uses existing connector functionality where available
-- Focuses on integration and orchestration
+## Key Principles
 
-### Production-Ready
-- Same code used in development AND production
-- Validates services before they join the ecosystem
-- Ensures cookbook compatibility
+- **No duplication** — does not re-test individual connector logic; focuses on
+  integration, readiness and proof generation.
+- **Production-ready** — the exact same code runs locally, in CI and during
+  wrapper startup.
+- **Fail-fast** — missing logger, missing serviceUrl, missing operations.json:
+  immediate throw.
 
 ## Components
 
-### 1. Mock Infrastructure (Development)
-- `MockMQClient` - In-memory message queue simulation
-- `MockRegistry` - Service registry simulation
-- `MockStorage` - Object storage simulation
+### Mock Infrastructure (for unit tests)
+
+- `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
+### Production Validation
 
-### 3. Integration Framework
-- `ServiceTestHarness` - Complete test environment orchestration
+- `ValidationOrchestrator` — 6-step pre-validation pipeline, emits proof
+- `ServiceReadinessValidator` — score-based readiness checks (operations /
+  endpoints / health / cookbook / registry)
+- `ServiceStructureValidator` — config layout checks (config/service/*)
+- `ValidationProofGenerator` — fingerprint + codec helpers
+- `CookbookTestRunner` / `WorkflowTestRunner` — cookbook execution probes
+- `CookbookTestUtils` — static cookbook-structure validators
 
-## Use Cases
+### Test Suite Helpers
 
-### Development Workflow
-```javascript
-// Developer testing their service
-const harness = new ServiceTestHarness({
-  service: myExpressApp,
-  serviceName: 'my-service',
-  openApiSpec: spec,
-  mockInfrastructure: true  // Use mocks
-});
+- `createServiceReadinessTests(options)` — Jest suite generator
+- `createPreValidationTests(options)` — Jest suite generator
 
-await harness.start();
-// Run tests...
-await harness.stop();
-```
+## Integration Points
 
-### 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
+- `@onlineapps/service-wrapper` instantiates `ValidationOrchestrator` during
+  wrapper startup. Proof is cached under `conn-runtime/validation-proof.json`
+  (30-day validity, invalidated by config fingerprint change — includes
+  operations map, see
+  [operations-registry-contract.md §3](../../../docs/standards/operations-registry-contract.md)).
+- Biz-service templates import `createPreValidationTests` /
+  `createServiceReadinessTests` from this package for their own test suites.
+
+## What We Test
+
+1. **Service contract** — operations.json structure + endpoint reachability
+2. **Workflow capability** — can process cookbooks
+3. **Infrastructure** — registry / MQ / storage connectivity
+4. **Health** — `/health` returns 200
+
+## What We DO NOT Test
+
+1. Individual connector behavior (tested in connector packages)
+2. Business logic correctness (service responsibility)
+3. Performance / load (separate concern)
+
+## Related Documentation
+
+- [operations-registry-contract.md](../../../docs/standards/operations-registry-contract.md) — operations.json schema
+- [validation-probe-contract.md](../../../docs/standards/validation-probe-contract.md) — required `example`/`default` fields for probes
+- [validator.md](../../../docs/architecture/validator.md) — architecture overview

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-validator",
-  "version": "2.0.33",
+  "version": "2.0.34",
   "description": "Validation orchestrator for OA Drive microservices - coordinates validation across all layers (base, infra, orch, business)",
   "main": "src/index.js",
   "scripts": {
@@ -21,7 +21,7 @@
   "author": "OnlineApps",
   "license": "PROPRIETARY",
   "dependencies": {
-    "@onlineapps/service-validator-core": "1.0.12",
+    "@onlineapps/service-validator-core": "1.0.13",
     "@onlineapps/runtime-config": "1.0.2",
     "ajv": "^8.12.0",
     "ajv-formats": "^2.1.1",

package/src/ServiceReadinessValidator.js

@@ -1,21 +1,24 @@
 'use strict';
 
-const ServiceValidator = require('./ServiceValidator');
 const CookbookTestUtils = require('./CookbookTestUtils');
 const { resolveHeaders } = require('./utils/resolveHeaders');
 
 /**
- * ServiceReadinessValidator - Orchestrates complete service validation
- * Used by service-wrapper to verify service is ready for production
+ * ServiceReadinessValidator - Orchestrates complete service validation.
  *
- * IMPORTANT: Only supports operations.json format. OpenAPI is deprecated.
+ * Used by service-wrapper to verify a service is ready for production.
+ * Works exclusively against the operations.json contract — OpenAPI-style
+ * `paths` iteration was removed when the contract became the single source
+ * of truth for endpoint metadata.
+ *
+ * @see /api/docs/standards/operations-registry-contract.md §3
+ * @see /api/docs/standards/validation-probe-contract.md
  */
 class ServiceReadinessValidator {
   constructor(options = {}) {
     if (!options.logger || typeof options.logger.warn !== 'function') {
       throw new Error('[ServiceReadinessValidator] Logger is required — Expected object with warn() method');
     }
-    this.validator = new ServiceValidator(options);
     this.logger = options.logger;
 
     // Readiness checks: core (80 points) + optional (20 points) = 100 points max

package/src/config.js

@@ -4,7 +4,7 @@
  * Runtime configuration schema for @onlineapps/conn-orch-validator.
  *
  * Uses @onlineapps/runtime-config for unified priority:
- * 1. Explicit config (passed to TestOrchestrator options)
+ * 1. Explicit config (passed to ValidationOrchestrator/readiness options)
  * 2. Environment variable
  * 3. Module-owned defaults (none for topology)
  *

package/src/index.js

@@ -1,17 +1,25 @@
 'use strict';
 
-// Mock infrastructure components (load first - no dependencies)
+/**
+ * @module @onlineapps/conn-orch-validator
+ * @description Service validation framework using the operations.json contract.
+ *
+ * Production entry point: {@link ValidationOrchestrator} (6-step pre-validation
+ * driven by operations.json — OpenAPI path iteration is NOT supported).
+ *
+ * @see /api/docs/standards/operations-registry-contract.md §3 (operations.json)
+ * @see /api/docs/standards/validation-probe-contract.md (validation probes)
+ * @see /api/docs/architecture/validator.md (validator architecture)
+ */
+
 const MockMQClient = require('./mocks/MockMQClient');
 const MockRegistry = require('./mocks/MockRegistry');
 const MockStorage = require('./mocks/MockStorage');
 
-// Base test utilities (no circular dependencies)
-const ServiceValidator = require('./ServiceValidator');
 const CookbookTestUtils = require('./CookbookTestUtils');
 const { ServiceStructureValidator } = require('./validators/ServiceStructureValidator');
 const ValidationProofGenerator = require('./validators/ValidationProofGenerator');
 
-// Test runners (depend on mocks)
 let CookbookTestRunner;
 try {
   CookbookTestRunner = require('./CookbookTestRunner');
@@ -20,43 +28,29 @@ try {
 }
 const WorkflowTestRunner = require('./WorkflowTestRunner');
 
-// Orchestrators (depend on validators and runners)
 const ServiceReadinessValidator = require('./ServiceReadinessValidator');
-const TestOrchestrator = require('./TestOrchestrator');
-const ServiceTestHarness = require('./ServiceTestHarness');
 const ValidationOrchestrator = require('./ValidationOrchestrator');
 
-// Test helpers (generic test suite creators)
 const { createServiceReadinessTests } = require('./helpers/createServiceReadinessTests');
 const { createPreValidationTests } = require('./helpers/createPreValidationTests');
 
-// Export all components with getters to avoid circular dependency issues
 module.exports = {
-  // Mocks
   get MockMQClient() { return MockMQClient; },
   get MockRegistry() { return MockRegistry; },
   get MockStorage() { return MockStorage; },
 
-  // Test utilities
-  get ServiceTestHarness() { return ServiceTestHarness; },
-  get ServiceValidator() { return ServiceValidator; },
   get WorkflowTestRunner() { return WorkflowTestRunner; },
   get CookbookTestUtils() { return CookbookTestUtils; },
   get ServiceReadinessValidator() { return ServiceReadinessValidator; },
-  get TestOrchestrator() { return TestOrchestrator; },
   get CookbookTestRunner() { return CookbookTestRunner; },
   get ValidationProofGenerator() { return ValidationProofGenerator; },
   get ServiceStructureValidator() { return ServiceStructureValidator; },
   get ValidationOrchestrator() { return ValidationOrchestrator; },
 
-  // Test helpers (NEW - generic test suite creators)
   get createServiceReadinessTests() { return createServiceReadinessTests; },
   get createPreValidationTests() { return createPreValidationTests; },
 
-  // Convenience factory functions
-  createTestHarness: (options) => new ServiceTestHarness(options),
-  createValidator: (options) => new ServiceValidator(options),
   createMockMQ: () => new MockMQClient(),
   createMockRegistry: () => new MockRegistry(),
   createMockStorage: () => new MockStorage()
-};
+};

package/examples/service-wrapper-usage.js

@@ -1,250 +0,0 @@
-'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 };