@onlineapps/service-wrapper 3.0.15 → 3.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/service-wrapper",
-  "version": "3.0.15",
+  "version": "3.0.17",
   "description": "Thin orchestration layer for microservices - delegates all infrastructure concerns to specialized connectors",
   "main": "src/index.js",
   "scripts": {
@@ -29,10 +29,10 @@
     "@onlineapps/conn-base-state": "1.0.1",
     "@onlineapps/conn-infra-error-handler": "1.0.11",
     "@onlineapps/conn-infra-mq": "1.1.70",
-    "@onlineapps/conn-orch-cookbook": "2.1.2",
-    "@onlineapps/conn-orch-orchestrator": "2.0.2",
+    "@onlineapps/conn-orch-cookbook": "2.1.3",
+    "@onlineapps/conn-orch-orchestrator": "2.0.3",
     "@onlineapps/conn-orch-registry": "1.2.1",
-    "@onlineapps/conn-orch-validator": "^3.1.2",
+    "@onlineapps/conn-orch-validator": "3.1.2",
     "@onlineapps/monitoring-core": "1.0.23",
     "@onlineapps/runtime-config": "1.0.2",
     "@onlineapps/service-common": "1.1.2",

package/src/ServiceWrapper.js

@@ -156,6 +156,11 @@ class ServiceWrapper {
     this._revalidationState = REVALIDATION_STATE.IDLE;
     this._revalidationAttempt = 0;
     this._revalidationTimer = null;
+
+    // Runtime connector contract + probes (loaded from config/service/integration-contract.json)
+    this.integrationContract = null;
+    this.requiredConnectors = null;
+    this._dbHealthConnector = null;
   }
 
   /**
@@ -438,6 +443,160 @@ class ServiceWrapper {
     return processObject(config);
   }
 
+  /**
+   * Load and validate runtime integration contract used by health checks.
+   * @private
+   */
+  _loadIntegrationContract() {
+    if (!this.serviceRoot) {
+      throw new Error(
+        '[ServiceWrapper] Missing dependency - serviceRoot is required to load config/service/integration-contract.json for runtime health checks'
+      );
+    }
+
+    const fs = require('fs');
+    const path = require('path');
+    const contractPath = path.join(this.serviceRoot, 'config', 'service', 'integration-contract.json');
+
+    if (!fs.existsSync(contractPath)) {
+      throw new Error(
+        `[ServiceWrapper] Missing integration contract - Expected file at ${contractPath}. ` +
+        'Fix: add config/service/integration-contract.json with requiredConnectors booleans.'
+      );
+    }
+
+    let raw;
+    try {
+      raw = JSON.parse(fs.readFileSync(contractPath, 'utf8'));
+    } catch (error) {
+      throw new Error(
+        `[ServiceWrapper] Invalid integration contract - Cannot parse JSON at ${contractPath}. ${error.message}`
+      );
+    }
+
+    const requiredConnectors = raw?.requiredConnectors;
+    if (!requiredConnectors || typeof requiredConnectors !== 'object' || Array.isArray(requiredConnectors)) {
+      throw new Error(
+        `[ServiceWrapper] Invalid integration contract - requiredConnectors object is required in ${contractPath}`
+      );
+    }
+
+    const keys = ['db', 'redis', 'mq', 'minio'];
+    const normalized = {};
+    for (const key of keys) {
+      if (typeof requiredConnectors[key] !== 'boolean') {
+        throw new Error(
+          `[ServiceWrapper] Invalid integration contract - requiredConnectors.${key} must be boolean in ${contractPath}`
+        );
+      }
+      normalized[key] = requiredConnectors[key];
+    }
+
+    this.integrationContract = raw;
+    this.requiredConnectors = normalized;
+  }
+
+  /**
+   * Resolve DB connector used for runtime health checks.
+   * @private
+   * @returns {Object}
+   */
+  _loadDatabaseHealthConnector() {
+    if (this._dbHealthConnector) {
+      return this._dbHealthConnector;
+    }
+
+    const path = require('path');
+    const dbModulePath = path.join(this.serviceRoot, 'src', 'config', 'database');
+
+    let dbConnector;
+    try {
+      dbConnector = require(dbModulePath);
+    } catch (error) {
+      throw new Error(
+        `[ServiceWrapper] Database connector unavailable - Failed to load ${dbModulePath}.js. ${error.message}`
+      );
+    }
+
+    if (!dbConnector || typeof dbConnector.authenticate !== 'function') {
+      throw new Error(
+        `[ServiceWrapper] Database connector invalid - Expected Sequelize-compatible module with authenticate() at ${dbModulePath}.js`
+      );
+    }
+
+    this._dbHealthConnector = dbConnector;
+    return dbConnector;
+  }
+
+  /**
+   * Check required DB dependency according to integration-contract.
+   * @private
+   * @returns {Promise<{status: string, reason: (string|null)}>}
+   */
+  async _checkDatabaseDependency() {
+    if (!this.requiredConnectors?.db) {
+      return { status: 'not_required', reason: null };
+    }
+
+    try {
+      const dbConnector = this._loadDatabaseHealthConnector();
+      await dbConnector.authenticate();
+      return { status: 'healthy', reason: null };
+    } catch (error) {
+      return { status: 'unhealthy', reason: error.message };
+    }
+  }
+
+  /**
+   * Check required Redis dependency according to integration-contract.
+   * Uses available cache/state connectors and requires at least one healthy probe.
+   * @private
+   * @returns {Promise<{status: string, reason: (string|null)}>}
+   */
+  async _checkRedisDependency() {
+    if (!this.requiredConnectors?.redis) {
+      return { status: 'not_required', reason: null };
+    }
+
+    const checks = [];
+    const failures = [];
+
+    const runProbe = async (name, connector) => {
+      if (!connector || typeof connector.healthCheck !== 'function') {
+        failures.push(`${name}: connector missing healthCheck()`);
+        return;
+      }
+      try {
+        const healthy = await connector.healthCheck();
+        checks.push({ name, healthy: healthy === true });
+        if (healthy !== true) {
+          failures.push(`${name}: healthCheck returned false`);
+        }
+      } catch (error) {
+        failures.push(`${name}: ${error.message}`);
+      }
+    };
+
+    await runProbe('cache', this.cacheConnector);
+    await runProbe('state', this.stateConnector);
+
+    if (checks.some((entry) => entry.healthy === true)) {
+      return { status: 'healthy', reason: null };
+    }
+
+    if (checks.length === 0) {
+      return {
+        status: 'unhealthy',
+        reason: 'Redis is required but no Redis connector is initialized (cache/state missing)'
+      };
+    }
+
+    return {
+      status: 'unhealthy',
+      reason: failures.length > 0 ? failures.join('; ') : 'Redis health probes failed'
+    };
+  }
+
   /**
    * Initialize all wrapper components
    * @async
@@ -638,6 +797,19 @@ class ServiceWrapper {
       // See RFC api/docs/architecture/biz-service-invocation-model.md §5.9 step 5.
       this._logPhase('0.1b', 'Operations-Routes Alignment', 'SKIPPED', null, 0);
 
+      // FÁZE 0.15: Runtime integration connector contract (health + readiness source of truth)
+      if (this.config.wrapper?.health?.enabled !== false) {
+        const contractStartTime = Date.now();
+        try {
+          this._loadIntegrationContract();
+          this._logPhase('0.15', 'Integration Contract Load', 'PASSED', null, Date.now() - contractStartTime);
+        } catch (error) {
+          return await this._handleInitializationError('0.15', 'Integration Contract Load', error, false); // Trvalá chyba
+        }
+      } else {
+        this._logPhase('0.15', 'Integration Contract Load', 'SKIPPED', null, 0);
+      }
+
       // FÁZE 0.2: Tier 1 validace (PŘED MQ připojením)
       if (this.serviceRoot && this.config.wrapper?.validation?.enabled !== false) {
         const validationStartTime = Date.now();
@@ -1299,16 +1471,20 @@ class ServiceWrapper {
     const healthEndpoint = this.config.wrapper?.health?.endpoint || '/health';
 
     const healthHandler = async (req, res) => {
+      const dependencyIssues = [];
       const health = {
         status: 'healthy',
         service: this.config.service?.name || 'unnamed-service',
         timestamp: new Date().toISOString(),
+        requiredConnectors: this.requiredConnectors || null,
         components: {
           http: 'healthy',
           mq: 'disabled',
           registry: this.registryClient ? 'healthy' : 'disabled',
           cache: this.cacheConnector ? 'healthy' : 'disabled',
-          state: this.stateConnector ? 'healthy' : 'disabled'
+          state: this.stateConnector ? 'healthy' : 'disabled',
+          database: this.requiredConnectors?.db === true ? 'unknown' : 'not_required',
+          redis: this.requiredConnectors?.redis === true ? 'unknown' : 'not_required'
         }
       };
 
@@ -1330,6 +1506,30 @@ class ServiceWrapper {
         }
       }
 
+      if (!this.requiredConnectors) {
+        health.components.database = 'unhealthy';
+        health.components.redis = 'unhealthy';
+        dependencyIssues.push(
+          'Integration contract was not loaded - expected config/service/integration-contract.json during initialization'
+        );
+      } else {
+        const dbDependency = await this._checkDatabaseDependency();
+        health.components.database = dbDependency.status;
+        if (dbDependency.status === 'unhealthy' && dbDependency.reason) {
+          dependencyIssues.push(`[db] ${dbDependency.reason}`);
+        }
+
+        const redisDependency = await this._checkRedisDependency();
+        health.components.redis = redisDependency.status;
+        if (redisDependency.status === 'unhealthy' && redisDependency.reason) {
+          dependencyIssues.push(`[redis] ${redisDependency.reason}`);
+        }
+      }
+
+      if (dependencyIssues.length > 0) {
+        health.dependencyIssues = dependencyIssues;
+      }
+
       const statuses = Object.values(health.components);
       if (statuses.includes('unhealthy')) {
         health.status = 'unhealthy';