@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:

// 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

Validation Proof Structure

Location: conn-runtime/validation-proof.json

{
  "validationProof": "sha256-hash-of-validationData",
  "validationData": {
    "serviceName": "hello-service",
    "version": "1.0.0",
    "validator": "@onlineapps/conn-orch-validator",
    "validatorVersion": "2.0.6",
    "validatedAt": "2025-10-22T10:30:45.123Z",
    "testsRun": 15,
    "testsPassed": 15,
    "testsFailed": 0,
    "durationMs": 234
  }
}

Proof Lifecycle:

• Valid for: 7 days OR until service fingerprint changes
• Fingerprint: SHA256 hash of (version + operations + dependencies + config)
• Revalidation: Automatic if proof missing/invalid/expired
• Registry: Accepts service with valid proof (skips Tier 2 validation)

Implementation Standard Levels

The validator evaluates each service against cumulative implementation standards. Levels are ordered — each requires all previous to pass:

| Level | Name | Checks | Since | |-------|------|--------|-------| | v1.0 | Base Service Standard | conn-config/, src/app.js, index.js, valid config.json + operations.json, @onlineapps/service-wrapper dep | 2025-06 | | v1.1 | Multitenancy Standard | wrapper.tenantContext configured in config.json | 2026-03 | | v1.2 | Business Error Handling | @onlineapps/service-common dep + businessErrorHandler in src/app.js | 2026-03 |

Key properties:

• Cumulative — v1.2 requires v1.0 + v1.1 to also pass
• Baked into validator — older validator versions naturally know fewer levels (backward compatible)
• Warnings — next unsatisfied level generates STANDARD_LEVEL_GAP warnings with specific missing checks
• Exposed in /info — ServiceWrapper's GET /info endpoint returns the highest satisfied level
• In validation results — validate() returns standardLevel and standardDetails

// Programmatic access
const { ServiceStructureValidator } = require('@onlineapps/conn-orch-validator/src/validators/ServiceStructureValidator');
const validator = new ServiceStructureValidator('/path/to/service');
const { level, details } = validator.determineStandardLevel();
// level = 'v1.2', details = [{ level: 'v1.0', passed: true, checks: [...] }, ...]

// List all known levels
ServiceStructureValidator.getStandardLevels();
// [{ level: 'v1.0', name: 'Base Service Standard', since: '2025-06-01' }, ...]

Related: Service Endpoints — Standard Levels, Error Handling Standard

Related Documentation

• SERVICE_REGISTRATION_FLOW.md
• /docs/architecture/validator.md
• /docs/standards/OPERATIONS.md
• /docs/standards/ERROR_HANDLING.md
• @onlineapps/service-validator-core

Last updated: 2026-03-24