@onlineapps/conn-orch-validator 2.0.32 → 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.32",
+  "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/CookbookTestRunner.js

@@ -14,12 +14,24 @@ const { resolveHeaders } = require('./utils/resolveHeaders');
  */
 class CookbookTestRunner {
   constructor(options = {}) {
+    if (!options.serviceName) {
+      throw new Error('[CookbookTestRunner] serviceName is required');
+    }
+    if (!options.serviceUrl) {
+      throw new Error('[CookbookTestRunner] serviceUrl is required');
+    }
+    if (!options.logger || typeof options.logger.warn !== 'function') {
+      throw new Error('[CookbookTestRunner] Logger is required — Expected object with warn() method');
+    }
     this.serviceName = options.serviceName;
-    this.serviceUrl = options.serviceUrl || 'http://127.0.0.1:3000';
+    this.serviceUrl = options.serviceUrl;
     this.servicePath = options.servicePath;
-    this.mockInfrastructure = options.mockInfrastructure !== false; // default true
-    this.timeout = options.timeout || 30000;
-    this.logger = options.logger || console;
+    this.mockInfrastructure = options.mockInfrastructure !== false;
+    this.timeout = options.timeout;
+    if (!this.timeout || typeof this.timeout !== 'number' || this.timeout <= 0) {
+      throw new Error('[CookbookTestRunner] timeout is required — Expected positive number (ms)');
+    }
+    this.logger = options.logger;
 
     // Initialize mocked infrastructure
     if (this.mockInfrastructure) {

package/src/ServiceReadinessValidator.js

@@ -1,19 +1,25 @@
 '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 = {}) {
-    this.validator = new ServiceValidator(options);
-    this.logger = options.logger || console;
+    if (!options.logger || typeof options.logger.warn !== 'function') {
+      throw new Error('[ServiceReadinessValidator] Logger is required — Expected object with warn() method');
+    }
+    this.logger = options.logger;
 
     // Readiness checks: core (80 points) + optional (20 points) = 100 points max
     // Core checks ALWAYS run, optional checks run if testCookbook/registry provided
@@ -347,64 +353,44 @@ class ServiceReadinessValidator {
   }
 
   /**
-   * Generate test input based on operation input schema
-   * Supports Content Descriptor types (content, file) with proper test values
+   * Generate test input based on operation input schema.
+   *
+   * Resolution order per field: example > default > enum[0]
+   * If none found for a required field, throws with actionable message.
+   *
+   * Contract: every required field in operations.json MUST have 'example' or 'default'.
+   * See: docs/standards/validation-probe-contract.md
    */
   generateTestInput(inputSchema) {
     const testData = {};
 
     for (const [fieldName, fieldSpec] of Object.entries(inputSchema)) {
-      if (fieldSpec.required) {
-        // Generate appropriate test value based on type
-        switch (fieldSpec.type) {
-          case 'string':
-            testData[fieldName] = fieldSpec.default || 'Test';
-            break;
-          case 'number':
-            testData[fieldName] = fieldSpec.default || 0;
-            break;
-          case 'boolean':
-            testData[fieldName] = fieldSpec.default || false;
-            break;
-          case 'array':
-            testData[fieldName] = fieldSpec.default || [];
-            break;
-          case 'object':
-            testData[fieldName] = fieldSpec.default || {};
-            break;
-          // Content Descriptor types - generate valid test content
-          case 'content':
-            // Generate content based on field name hints
-            if (fieldName.toLowerCase().includes('html')) {
-              testData[fieldName] = fieldSpec.default || '<html><body><h1>Test Validation</h1><p>Auto-generated test content.</p></body></html>';
-            } else if (fieldName.toLowerCase().includes('markdown') || fieldName.toLowerCase().includes('md')) {
-              testData[fieldName] = fieldSpec.default || '# Test Validation\n\nAuto-generated test content.';
-            } else {
-              testData[fieldName] = fieldSpec.default || 'Test content for validation';
-            }
-            break;
-          case 'file':
-            // For file types, generate a VALID Content Descriptor object (type=file)
-            // This keeps endpoint checks predictable and avoids service-specific file upload flows.
-            testData[fieldName] = fieldSpec.default || {
-              _descriptor: true,
-              type: 'file',
-              storage_ref: 'minio://test/validation/placeholder.txt',
-              filename: 'placeholder.txt',
-              content_type: 'text/plain',
-              size: 1,
-              fingerprint: 'test-fingerprint'
-            };
-            break;
-          default:
-            testData[fieldName] = null;
-        }
-      }
+      if (!fieldSpec.required) continue;
+
+      const value = this._resolveTestValue(fieldName, fieldSpec);
+      testData[fieldName] = value;
     }
 
     return testData;
   }
 
+  /**
+   * Resolve a single test value for a required input field.
+   * Throws if no value can be determined — forces service authors to provide examples.
+   * @private
+   */
+  _resolveTestValue(fieldName, fieldSpec) {
+    if (fieldSpec.example !== undefined) return fieldSpec.example;
+    if (fieldSpec.default !== undefined) return fieldSpec.default;
+    if (Array.isArray(fieldSpec.enum) && fieldSpec.enum.length > 0) return fieldSpec.enum[0];
+
+    throw new Error(
+      `[ServiceReadinessValidator] No test value for required field '${fieldName}' ` +
+      `(type: ${fieldSpec.type}) — Add 'example' or 'default' to operations.json input schema. ` +
+      `See: docs/standards/validation-probe-contract.md`
+    );
+  }
+
   /**
    * Get recommendation based on results
    */

package/src/ValidationOrchestrator.js

@@ -22,11 +22,13 @@ class ValidationOrchestrator {
     this.serviceName = options.serviceName;
     this.serviceVersion = options.serviceVersion;
     this.serviceUrl = options.serviceUrl; // NEW: Service URL for HTTP calls
-    this.logger = options.logger || console;
+    if (!options.logger || typeof options.logger.warn !== 'function') {
+      throw new Error('[ValidationOrchestrator] Logger is required — Expected object with warn() method');
+    }
+    this.logger = options.logger;
 
-    // Validate required options
     if (!this.serviceUrl) {
-      throw new Error('serviceUrl is required for ValidationOrchestrator');
+      throw new Error('[ValidationOrchestrator] serviceUrl is required');
     }
 
     // Paths — prefer new config/service/ layout, fall back to legacy conn-config/
@@ -39,11 +41,13 @@ class ValidationOrchestrator {
 
     // Validators
     this.structureValidator = new ServiceStructureValidator(this.serviceRoot);
-    this.readinessValidator = new ServiceReadinessValidator();
+    this.readinessValidator = new ServiceReadinessValidator({ logger: this.logger });
     this.cookbookRunner = new CookbookTestRunner({
       servicePath: this.serviceRoot,
       serviceName: this.serviceName,
-      serviceUrl: this.serviceUrl // Pass serviceUrl to CookbookTestRunner
+      serviceUrl: this.serviceUrl,
+      logger: this.logger,
+      timeout: 30000
     });
   }
 

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/helpers/createServiceReadinessTests.js

@@ -138,7 +138,7 @@ function createServiceReadinessTests(testsDir, options = {}) {
       }
 
       // Run readiness validation
-      const validator = new ServiceReadinessValidator();
+      const validator = new ServiceReadinessValidator({ logger: console });
       const result = await validator.validateReadiness({
         name: serviceName,
         version: serviceVersion,

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()
-};
+};