@onlineapps/service-wrapper 2.2.9 → 2.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/service-wrapper",
-  "version": "2.2.9",
+  "version": "2.3.1",
   "description": "Thin orchestration layer for microservices - delegates all infrastructure concerns to specialized connectors",
   "main": "src/index.js",
   "scripts": {
@@ -30,10 +30,10 @@
     "@onlineapps/conn-infra-error-handler": "1.0.9",
     "@onlineapps/conn-infra-mq": "1.1.69",
     "@onlineapps/conn-orch-api-mapper": "1.0.30",
-    "@onlineapps/conn-orch-cookbook": "2.0.37",
-    "@onlineapps/conn-orch-orchestrator": "1.0.105",
-    "@onlineapps/conn-orch-registry": "1.1.54",
-    "@onlineapps/conn-orch-validator": "2.0.31",
+    "@onlineapps/conn-orch-cookbook": "2.0.38",
+    "@onlineapps/conn-orch-orchestrator": "1.0.106",
+    "@onlineapps/conn-orch-registry": "1.1.55",
+    "@onlineapps/conn-orch-validator": "2.0.32",
     "@onlineapps/monitoring-core": "1.0.21",
     "@onlineapps/service-common": "1.0.18",
     "@onlineapps/runtime-config": "1.0.2"

package/src/ConfigLoader.js

@@ -44,7 +44,7 @@ const CONFIG_REGISTRY = {
     description: 'Operations specification (API contract)'
   },
   VALIDATION_PROOF: {
-    paths: ['config/runtime/validation-proof.json', 'conn-runtime/validation-proof.json'],
+    paths: ['conn-runtime/validation-proof.json'],
     required: false,
     description: 'Pre-validation proof from cookbook tests'
   }

package/src/ServiceWrapper.js

@@ -25,9 +25,20 @@ const ErrorHandlerConnector = require('@onlineapps/conn-infra-error-handler');
 const { ValidationOrchestrator } = require('@onlineapps/conn-orch-validator');
 const runtimeCfg = require('./config');
 
+const RUNTIME_DIR = 'conn-runtime';
+const PROOF_RELATIVE_PATH = `${RUNTIME_DIR}/validation-proof.json`;
+
 const REVALIDATION_FAST_BACKOFF_MS = [30000, 60000, 120000, 300000, 600000, 1800000];
-const REVALIDATION_DAILY_MS = 86400000;
-const REVALIDATION_STATE = { IDLE: 'idle', FAST_BACKOFF: 'fast_backoff', DAILY_BACKOFF: 'daily_backoff', SUCCEEDED: 'succeeded' };
+const REVALIDATION_HOURLY_MS = 3600000;
+const REVALIDATION_HOURLY_MAX = 24;
+const REVALIDATION_SLOW_MS = 21600000;
+const REVALIDATION_STATE = {
+  IDLE: 'idle',
+  FAST_BACKOFF: 'fast_backoff',
+  HOURLY_BACKOFF: 'hourly_backoff',
+  SLOW_BACKOFF: 'slow_backoff',
+  SUCCEEDED: 'succeeded'
+};
 
 const INFRA_QUEUE_OWNERS = {
   'workflow.init': 'Gateway (api_gateway)',
@@ -82,7 +93,6 @@ class ServiceWrapper {
     this._revalidationState = REVALIDATION_STATE.IDLE;
     this._revalidationAttempt = 0;
     this._revalidationTimer = null;
-    this._infraInvalidationConsumerTag = null;
   }
 
   /**
@@ -163,14 +173,8 @@ class ServiceWrapper {
       throw new Error(`Failed to start workflow listeners for ${serviceName}: ${listenerError.message}`);
     }
 
-    // Phase 0.10: Subscribe to infrastructure invalidation events
-    try {
-      await this._subscribeToInfraInvalidation(serviceName);
-    } catch (subErr) {
-      this.logger?.warn('[ServiceWrapper][infra.invalidation] Failed to subscribe to invalidation events (non-critical)', {
-        error: subErr.message
-      });
-    }
+    // Revalidation requests from Registry are handled via RegistryClient 'revalidate' event
+    // (subscribed in _initializeRegistry after successful registration)
   }
 
   /**
@@ -439,7 +443,6 @@ class ServiceWrapper {
       this.workflowInitConsumerTag = null;
       this.workflowControlConsumerTag = null;
       this.serviceWorkflowConsumerTag = null;
-      this._infraInvalidationConsumerTag = null;
       if (this._revalidationTimer) {
         clearTimeout(this._revalidationTimer);
         this._revalidationTimer = null;
@@ -997,6 +1000,15 @@ class ServiceWrapper {
       throw new Error(`Failed to register service ${serviceName}: ${error.message}`);
     }
 
+    // Listen for revalidation requests from Registry (infra version changes)
+    this.registryClient.on('revalidate', (payload) => {
+      this.logger?.info('[ServiceWrapper][revalidate] Revalidation requested by Registry', {
+        reason: payload.reason,
+        infraFingerprint: payload.infraFingerprint?.substring(0, 16)
+      });
+      this._deleteProofAndRevalidate();
+    });
+
     // Start heartbeat with fail-fast on persistent MQ failure
     const heartbeatInterval = this.config.wrapper?.registry?.heartbeatInterval;
     if (typeof heartbeatInterval !== 'number' || Number.isNaN(heartbeatInterval) || heartbeatInterval <= 0) {
@@ -1271,7 +1283,7 @@ class ServiceWrapper {
       return { status: 'no_service_root' };
     }
 
-    const proofPath = path.join(this.serviceRoot, 'conn-runtime', 'validation-proof.json');
+    const proofPath = path.join(this.serviceRoot, PROOF_RELATIVE_PATH);
 
     if (!fs.existsSync(proofPath)) {
       return { status: 'no_proof' };
@@ -1814,6 +1826,28 @@ class ServiceWrapper {
       }
     }
 
+    // Extension 1: specificationEndpoint must match an Express route
+    // See: docs/standards/api-versioning-contract.md
+    const specEndpoint = this.config.service?.specificationEndpoint;
+    if (specEndpoint && !routeSet.has(`GET:${specEndpoint}`)) {
+      errors.push(
+        `specificationEndpoint '${specEndpoint}' not found in Express routes — ` +
+        `config claims this path but no GET route is registered`
+      );
+    }
+
+    // Extension 3: operations.json endpoints under /api/ must be versioned
+    // See: docs/standards/api-versioning-contract.md
+    const versionPattern = /^\/api\/v\d+\//;
+    for (const [opName, opDef] of Object.entries(ops)) {
+      if (opDef.endpoint?.startsWith('/api') && !versionPattern.test(opDef.endpoint)) {
+        errors.push(
+          `Operation '${opName}' endpoint '${opDef.endpoint}' missing version — ` +
+          `expected /api/v{N}/... (see docs/standards/api-versioning-contract.md)`
+        );
+      }
+    }
+
     if (errors.length > 0) {
       throw new Error(
         `[ServiceWrapper] Operations-Routes alignment failed (${errors.length} issue${errors.length > 1 ? 's' : ''}):\n` +
@@ -1823,67 +1857,23 @@ class ServiceWrapper {
   }
 
   /**
-   * Subscribe to infra.invalidation events on the infrastructure.health.events fanout exchange.
-   * When received, deletes local validation proof and triggers re-validation with backoff.
+   * Delete local validation proof and trigger re-validation.
+   * Called when Registry sends a revalidation request (infra version change).
    * @private
    */
-  async _subscribeToInfraInvalidation(serviceName) {
-    if (!this.mqClient?._transport?.channel) {
-      this.logger?.debug('[ServiceWrapper][infra.invalidation] No MQ channel available — skipping subscription');
-      return;
-    }
-
-    const channel = this.mqClient._transport.channel;
-    const exchangeName = 'infrastructure.health.events';
-
-    await channel.assertExchange(exchangeName, 'fanout', { durable: true });
-
-    const q = await channel.assertQueue('', { exclusive: true, autoDelete: true });
-
-    await channel.bindQueue(q.queue, exchangeName, '');
-
-    const { consumerTag } = await channel.consume(q.queue, async (msg) => {
-      if (!msg) return;
-
-      try {
-        const event = JSON.parse(msg.content.toString());
-
-        if (event.type !== 'infra.invalidation') {
-          channel.ack(msg);
-          return;
-        }
-
-        this.logger?.info('[ServiceWrapper][infra.invalidation] Infrastructure change detected, scheduling re-validation', {
-          fingerprint: event.fingerprint?.substring(0, 16) + '...',
-          timestamp: event.timestamp
-        });
-
-        // Delete local validation proof
-        const fs = require('fs');
-        const path = require('path');
-        if (this.serviceRoot) {
-          const proofPath = path.join(this.serviceRoot, 'conn-runtime', 'validation-proof.json');
-          if (fs.existsSync(proofPath)) {
-            fs.unlinkSync(proofPath);
-            this.logger?.info('[ServiceWrapper][infra.invalidation] Deleted local validation proof', { proofPath });
-          }
-        }
-
-        this._revalidateWithBackoff();
+  _deleteProofAndRevalidate() {
+    const fs = require('fs');
+    const path = require('path');
 
-      } catch (parseErr) {
-        this.logger?.warn('[ServiceWrapper][infra.invalidation] Failed to parse event', { error: parseErr.message });
+    if (this.serviceRoot) {
+      const proofPath = path.join(this.serviceRoot, PROOF_RELATIVE_PATH);
+      if (fs.existsSync(proofPath)) {
+        fs.unlinkSync(proofPath);
+        this.logger?.info('[ServiceWrapper][revalidate] Deleted local validation proof', { proofPath });
       }
+    }
 
-      channel.ack(msg);
-    });
-
-    this._infraInvalidationConsumerTag = consumerTag;
-    this.logger?.info('[ServiceWrapper][infra.invalidation] Subscribed to infrastructure invalidation events', {
-      exchange: exchangeName,
-      queue: q.queue,
-      consumerTag
-    });
+    this._revalidateWithBackoff();
   }
 
   /**
@@ -1893,7 +1883,8 @@ class ServiceWrapper {
    */
   _revalidateWithBackoff() {
     if (this._revalidationState === REVALIDATION_STATE.FAST_BACKOFF ||
-        this._revalidationState === REVALIDATION_STATE.DAILY_BACKOFF) {
+        this._revalidationState === REVALIDATION_STATE.HOURLY_BACKOFF ||
+        this._revalidationState === REVALIDATION_STATE.SLOW_BACKOFF) {
       this.logger?.info('[ServiceWrapper][revalidation] Ignoring duplicate invalidation — re-validation cycle already active', {
         state: this._revalidationState,
         attempt: this._revalidationAttempt
@@ -1903,27 +1894,44 @@ class ServiceWrapper {
 
     this._revalidationState = REVALIDATION_STATE.FAST_BACKOFF;
     this._revalidationAttempt = 0;
+    this._hourlyAttempts = 0;
     this._scheduleRevalidationAttempt();
   }
 
   /**
-   * Schedule the next re-validation attempt based on current state and attempt count.
+   * Schedule the next re-validation attempt.
+   * Backoff phases: 6 fast (30s-30min) -> hourly (max 24h) -> every 6h (forever).
+   * At transition from hourly to slow: deregister + shutdown.
    * @private
    */
   _scheduleRevalidationAttempt() {
     let delayMs;
 
-    if (this._revalidationState === REVALIDATION_STATE.DAILY_BACKOFF) {
-      delayMs = REVALIDATION_DAILY_MS;
-    } else if (this._revalidationAttempt < REVALIDATION_FAST_BACKOFF_MS.length) {
-      delayMs = REVALIDATION_FAST_BACKOFF_MS[this._revalidationAttempt];
+    if (this._revalidationState === REVALIDATION_STATE.FAST_BACKOFF) {
+      if (this._revalidationAttempt < REVALIDATION_FAST_BACKOFF_MS.length) {
+        delayMs = REVALIDATION_FAST_BACKOFF_MS[this._revalidationAttempt];
+      } else {
+        this._revalidationState = REVALIDATION_STATE.HOURLY_BACKOFF;
+        this._hourlyAttempts = 0;
+        delayMs = REVALIDATION_HOURLY_MS;
+        this.logger?.warn(`[ServiceWrapper][revalidation] Fast retries exhausted (${this._revalidationAttempt} attempts) — switching to hourly retry`);
+      }
+    } else if (this._revalidationState === REVALIDATION_STATE.HOURLY_BACKOFF) {
+      if (this._hourlyAttempts < REVALIDATION_HOURLY_MAX) {
+        delayMs = REVALIDATION_HOURLY_MS;
+      } else {
+        this.logger?.error(
+          `[ServiceWrapper][revalidation] All revalidation attempts exhausted ` +
+          `(${REVALIDATION_FAST_BACKOFF_MS.length} fast + ${REVALIDATION_HOURLY_MAX} hourly) — deregistering and shutting down`
+        );
+        this._deregisterAndShutdown();
+        return;
+      }
     } else {
-      this._revalidationState = REVALIDATION_STATE.DAILY_BACKOFF;
-      delayMs = REVALIDATION_DAILY_MS;
-      this.logger?.warn(`[ServiceWrapper][revalidation] Fast retries exhausted (${this._revalidationAttempt} attempts) - switching to daily retry`);
+      delayMs = REVALIDATION_SLOW_MS;
     }
 
-    this.logger?.info(`[ServiceWrapper][revalidation] Next attempt in ${delayMs}ms`, {
+    this.logger?.info(`[ServiceWrapper][revalidation] Next attempt in ${Math.round(delayMs / 1000)}s`, {
       attempt: this._revalidationAttempt + 1,
       state: this._revalidationState,
       delayMs
@@ -1932,16 +1940,37 @@ class ServiceWrapper {
     this._revalidationTimer = setTimeout(() => this._executeRevalidation(), delayMs);
   }
 
+  /**
+   * Deregister from Registry and exit. Container orchestrator will restart.
+   * @private
+   */
+  async _deregisterAndShutdown() {
+    try {
+      if (this.registryClient) {
+        await this.registryClient.deregister();
+        this.logger?.info('[ServiceWrapper][revalidation] Deregistered from registry');
+      }
+    } catch (err) {
+      this.logger?.error('[ServiceWrapper][revalidation] Failed to deregister before shutdown', { error: err.message });
+    }
+
+    process.exit(1);
+  }
+
   /**
    * Execute a single re-validation attempt.
    * @private
    */
   async _executeRevalidation() {
     this._revalidationAttempt++;
-    const maxFast = REVALIDATION_FAST_BACKOFF_MS.length;
+    if (this._revalidationState === REVALIDATION_STATE.HOURLY_BACKOFF) {
+      this._hourlyAttempts++;
+    }
     const startTime = Date.now();
 
-    this.logger?.info(`[ServiceWrapper][revalidation] Attempt ${this._revalidationAttempt}/${maxFast} starting`);
+    this.logger?.info(`[ServiceWrapper][revalidation] Attempt ${this._revalidationAttempt} starting`, {
+      state: this._revalidationState
+    });
 
     try {
       const serviceName = this.config.service?.name;
@@ -1964,7 +1993,6 @@ class ServiceWrapper {
 
       this.validationProof = result.proof;
 
-      // Re-register with fresh proof
       if (this.registryClient) {
         const serviceInfo = {
           name: serviceName,
@@ -1983,26 +2011,15 @@ class ServiceWrapper {
       this._revalidationTimer = null;
       this.logger?.info(`[ServiceWrapper][revalidation] Success after ${this._revalidationAttempt} attempts (${elapsed}ms)`);
 
-      // Clean up failure tracking file
       this._clearValidationFailureFile();
 
     } catch (error) {
       const elapsed = Date.now() - startTime;
-      const nextDelay = this._revalidationState === REVALIDATION_STATE.DAILY_BACKOFF
-        ? REVALIDATION_DAILY_MS
-        : (this._revalidationAttempt < maxFast
-            ? REVALIDATION_FAST_BACKOFF_MS[this._revalidationAttempt]
-            : REVALIDATION_DAILY_MS);
-
-      if (this._revalidationState === REVALIDATION_STATE.DAILY_BACKOFF) {
-        this.logger?.warn(`[ServiceWrapper][revalidation] Daily retry attempt ${this._revalidationAttempt} - ${error.message}`);
-      } else {
-        this.logger?.warn(`[ServiceWrapper][revalidation] Attempt ${this._revalidationAttempt} failed: ${error.message} - next retry in ${nextDelay}ms`, {
-          attempt: this._revalidationAttempt,
-          elapsed,
-          error: error.message
-        });
-      }
+      this.logger?.warn(`[ServiceWrapper][revalidation] Attempt ${this._revalidationAttempt} failed (${elapsed}ms): ${error.message}`, {
+        attempt: this._revalidationAttempt,
+        state: this._revalidationState,
+        error: error.message
+      });
 
       this._scheduleRevalidationAttempt();
     }
@@ -2020,7 +2037,7 @@ class ServiceWrapper {
 
     if (!this.serviceRoot) return null;
 
-    const failurePath = path.join(this.serviceRoot, 'conn-runtime', 'validation-failure.json');
+    const failurePath = path.join(this.serviceRoot, RUNTIME_DIR, 'validation-failure.json');
     try {
       if (!fs.existsSync(failurePath)) return null;
       return JSON.parse(fs.readFileSync(failurePath, 'utf8'));
@@ -2042,12 +2059,12 @@ class ServiceWrapper {
 
     if (!this.serviceRoot) return;
 
-    const runtimeDir = path.join(this.serviceRoot, 'conn-runtime');
-    if (!fs.existsSync(runtimeDir)) {
-      fs.mkdirSync(runtimeDir, { recursive: true });
+    const rtDir = path.join(this.serviceRoot, RUNTIME_DIR);
+    if (!fs.existsSync(rtDir)) {
+      fs.mkdirSync(rtDir, { recursive: true });
     }
 
-    const failurePath = path.join(runtimeDir, 'validation-failure.json');
+    const failurePath = path.join(rtDir, 'validation-failure.json');
     const data = {
       lastAttempt: new Date().toISOString(),
       attemptCount,
@@ -2068,7 +2085,7 @@ class ServiceWrapper {
 
     if (!this.serviceRoot) return;
 
-    const failurePath = path.join(this.serviceRoot, 'conn-runtime', 'validation-failure.json');
+    const failurePath = path.join(this.serviceRoot, RUNTIME_DIR, 'validation-failure.json');
     try {
       if (fs.existsSync(failurePath)) {
         fs.unlinkSync(failurePath);
@@ -2192,15 +2209,15 @@ class ServiceWrapper {
       const lastAttempt = new Date(failureData.lastAttempt).getTime();
       const sinceLastAttempt = Date.now() - lastAttempt;
 
-      if (sinceLastAttempt < REVALIDATION_DAILY_MS) {
-        const remainingMs = REVALIDATION_DAILY_MS - sinceLastAttempt;
+      if (sinceLastAttempt < REVALIDATION_SLOW_MS) {
+        const remainingMs = REVALIDATION_SLOW_MS - sinceLastAttempt;
         const remainingMin = Math.round(remainingMs / 60000);
         this.logger?.info(
           `[ServiceWrapper][startup] Previous validation failures detected (${failureData.attemptCount} attempts since ${failureData.firstFailure}) - waiting ${remainingMin}min before retry`
         );
         await new Promise(resolve => setTimeout(resolve, Math.min(remainingMs, 300000)));
       } else {
-        this.logger?.info('[ServiceWrapper][startup] Previous failures detected, but 24h elapsed - retrying fresh');
+        this.logger?.info('[ServiceWrapper][startup] Previous failures detected, but cooldown elapsed - retrying fresh');
       }
     }
 

package/src/createTenantContextMiddleware.js

@@ -1,5 +1,6 @@
 'use strict';
 
+// See: docs/standards/tenant-context-contract.md
 /**
  * Tenant context middleware — requires x-tenant-id + x-workspace-id headers.
  *