@onlineapps/service-wrapper 4.1.1 → 4.1.3

package/CHANGELOG.md

@@ -4,11 +4,50 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
-**Patch.** No exported API moves: `BUSINESS_ERROR_BRAND`, `isBusinessError`, the
+**Minor.** No exported API moves: `BUSINESS_ERROR_BRAND`, `isBusinessError`, the
 error classes, `ServiceWrapper` and `bootstrap` are untouched. What changes is
-startup behaviour and one field inside `conn-runtime/validation-failure.json`,
-a runtime file this package writes and reads alone — not a contract any consumer
-compiles against.
+startup behaviour, one field inside `conn-runtime/validation-failure.json` — a
+runtime file this package writes and reads alone — and one field that disappears
+from the loaded config (below).
+
+### Removed — the `|| ''` fallback on `specificationEndpoint` (DÁVKA 79 B)
+
+`_initializeRegistry` read `this.config.service?.specificationEndpoint || ''`.
+The branch could never fire: `ConfigLoader.js:360-365` refuses a config that does
+not declare the field, and all eight biz services build their config through
+`ConfigLoader.loadAll` (`src/config/index.js` in converter, emailer,
+hello-service, ingest, invoicing, meta, pdfgen, property), with `bootstrap()`
+passing it straight through (`src/index.js:81`).
+
+A fallback that cannot fire is not harmless — it tells the reader that an empty
+endpoint is an expected state, while the registry warns about exactly that case
+(`api/infra/api_services_registry/src/listeners/registry.listener.js:474-477`).
+`architecture-principles.md` §3.
+
+Behaviour is unchanged, which is the point: the new control suite
+`tests/unit/ServiceWrapper.specificationEndpoint.test.js` is green before and
+after, and asserts the value reaching the registry client verbatim.
+
+### Removed — `config.service.port` is no longer parsed (DÁVKA 77 B)
+
+ADR 0005 removed the HTTP surface from biz containers. `ConfigLoader` parsed
+`service.port` into the loaded config anyway, and nothing read it back: measured
+2026-08-30, the only `.port` reads in `src/` are the Redis/state URL ports at
+`ServiceWrapper.js:1495`, `:1525`, `:1530`. A declaration nothing reads tells the
+reader something depends on it — `change-discipline.md` § "Removing something
+removes its declaration".
+
+- `cfg.service.port` is gone. A config that still declares one loads fine; the
+  field is simply not carried forward. `conn-orch-validator` is the component
+  that tells the author to delete it (`ORPHANED_CONFIG_FIELD`, warning).
+- `service.specificationEndpoint` stays REQUIRED and is UNCHANGED. It looked like
+  the same class of orphan — `ServiceWrapper.js:1295` even says ADR 0005 left it
+  without a consumer — but it has one: `api_services_registry` reads it off the
+  register payload (`listeners/registry.listener.js:354`, `:474-477`, `:542`,
+  `:626`, `:730`, `:813`, `:1108`) and stores it in the Redis summary entry
+  (`models/microservice.model.js:166-177`); the heartbeat listener reads it too
+  (`listeners/heartbeat.listener.js:30`, `:49`). The comment at `:1295` is wrong
+  about that, and the requirement stands.
 
 ### Fixed — the restart cooldown is keyed on the CAUSE, not on time alone
 
@@ -83,8 +122,44 @@ failure — measured by the lead: five minutes, no output. The test now records
 the scheduling instead of arming it, and asserts the success path never reaches
 the scheduler at all. Under the mutation it fails in 2 ms.
 
+### Fixed — one owner for "who am I"
+
+`this.config.service?.name || 'unnamed-service'` stood in **thirteen** places.
+Each looked harmless; together they were a policy nobody decided — a wrapper with
+no configured name kept running and told the registry, the MQ layer, the
+heartbeat and every log line that it was `unnamed-service`. Not a missing name: a
+WRONG one, and the same defect the heartbeat fix above removed, twelve more
+times (`architecture-principles.md` §3).
+
+`_serviceName()` and `_serviceVersion()` are now the only readers and they fail
+fast with `[ServiceWrapper] Missing configuration - service.<key> is required` —
+a message that is defined exactly once. Three duplicate guards that said the same
+thing in their own words (`_initializeOrchestrator`, `startHealthHeartbeat`,
+`_ensureValidationProof`'s "Service name is required for validation") now defer
+to it.
+
+Two readers stay direct, and each is named in a test:
+
+- `_logPhase` — **the only path that may not throw.**
+  `_handleInitializationError` reports a failed phase through it, and a phase can
+  fail precisely because the configuration never loaded; throwing there would
+  replace the error being reported with a second one and the operator would never
+  see the first. It uses `this.config?.service?.name ?? '<config not loaded>'` —
+  not an invented identity but a statement ABOUT the configuration, in a message
+  whose subject is the configuration failing.
+- `_initializeState` — `state.serviceName || service.name` is a different
+  contract; its error names both keys.
+
+`service.url || ''` is unchanged: ADR 0005 says a biz service has no URL.
+
 ### Tests
 
+`tests/unit/ServiceWrapper.serviceIdentity.test.js` — 14 cases: the getters
+return and throw by value; the initialization-error path keeps BOTH facts (the
+original cause and that the name was unknown); `unnamed-service` appears nowhere
+in the code; exactly three direct readers, each identified; each message defined
+once; and a control that the ADR 0005 url default survives.
+
 `tests/unit/ServiceWrapper.validationFailureFile.test.js` — 18 cases: the
 fingerprint moves for a cookbook, for `operations.json` and for an added
 cookbook and NOT for an unrelated file; the three cooldown branches; the
@@ -101,7 +176,7 @@ made-up identity, a complete identity starting it under its real name, the older
 `mqClient` guard still firing first, and the retired default absent from the
 source.
 
-Suite: 16 suites, 214 passed (was 189).
+Suite: 17 suites, 228 passed (was 189).
 
 ## [3.4.3] — 2026-08-17
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/service-wrapper",
-  "version": "4.1.1",
+  "version": "4.1.3",
   "description": "Thin orchestration layer for microservices - delegates all infrastructure concerns to specialized connectors",
   "main": "src/index.js",
   "scripts": {
@@ -25,24 +25,25 @@
   "license": "MIT",
   "dependencies": {
     "@onlineapps/conn-base-cache": "1.0.10",
-    "@onlineapps/conn-base-monitoring": "1.0.16",
+    "@onlineapps/conn-base-monitoring": "1.0.17",
     "@onlineapps/conn-base-state": "1.0.2",
     "@onlineapps/conn-infra-error-handler": "1.0.15",
-    "@onlineapps/conn-infra-mq": "2.0.0",
+    "@onlineapps/conn-infra-mq": "2.0.1",
     "@onlineapps/conn-infra-secrets": "1.1.0",
     "@onlineapps/conn-orch-cookbook": "2.1.5",
-    "@onlineapps/conn-orch-orchestrator": "2.1.8",
-    "@onlineapps/conn-orch-registry": "2.0.0",
+    "@onlineapps/conn-orch-orchestrator": "2.1.9",
+    "@onlineapps/conn-orch-registry": "2.0.1",
     "@onlineapps/conn-orch-validator": "4.0.1",
-    "@onlineapps/infrastructure-tools": "1.2.7",
+    "@onlineapps/infrastructure-tools": "1.2.9",
     "@onlineapps/runtime-config": "1.0.3",
-    "@onlineapps/service-common": "2.0.0",
+    "@onlineapps/service-common": "2.0.1",
     "@onlineapps/service-validator-core": "1.0.15",
     "ajv": "8.17.1",
     "ajv-formats": "3.0.1"
   },
   "devDependencies": {
     "express": "^5.1.0",
+    "ioredis": "^5.3.2",
     "jest": "^29.7.0",
     "jsdoc": "^4.0.2",
     "jsdoc-to-markdown": "^8.0.0"

package/src/ConfigLoader.js

@@ -368,7 +368,13 @@ class ConfigLoader {
       service: {
         name: serviceConfig.service.name,
         version: serviceConfig.service.version,
-        port: parseInt(serviceConfig.service.port, 10),
+        // No `port`. ADR 0005 removed the HTTP surface from biz containers, so
+        // nothing listens and nothing read this value back — measured
+        // 2026-08-30. Parsing it into the loaded config only told the reader
+        // that something depends on it (`change-discipline.md` § Removing
+        // something removes its declaration). A config that still declares one
+        // loads fine; `conn-orch-validator` is what tells the author to delete
+        // the field.
         url: serviceConfig.service.url,
         specificationEndpoint: serviceConfig.service.specificationEndpoint,
         description: serviceConfig.service.description,

package/src/ServiceWrapper.js

@@ -343,7 +343,7 @@ class ServiceWrapper {
    * @private
    */
   _validateNamingAndWorkspaceScoped() {
-    const serviceName = this.config?.service?.name || '<unnamed-service>';
+    const serviceName = this._serviceName();
     const kebabRegex = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 
     // Rule 1: every operation key must be kebab-case
@@ -606,12 +606,55 @@ class ServiceWrapper {
    * Initialize all wrapper components
    * @async
    */
+  /**
+   * Who this wrapper is. THE reader of `config.service.name`.
+   *
+   * Thirteen places used to write `this.config.service?.name ||
+   * 'unnamed-service'`. Each looked harmless; together they were a policy
+   * nobody decided — a wrapper with no configured name kept running and told
+   * the registry, the MQ layer, the heartbeat and every log line that it was
+   * `unnamed-service`. That is not a missing name, it is a WRONG one, and it is
+   * the same defect dávka 62 removed from `startHealthHeartbeat`
+   * (architecture-principles.md §3).
+   *
+   * @private
+   * @returns {string}
+   */
+  _serviceName() {
+    const name = this.config?.service?.name;
+    if (!name) {
+      throw new Error('[ServiceWrapper] Missing configuration - service.name is required');
+    }
+    return name;
+  }
+
+  /**
+   * The version this wrapper reports. THE reader of `config.service.version`.
+   *
+   * @private
+   * @returns {string}
+   */
+  _serviceVersion() {
+    const version = this.config?.service?.version;
+    if (!version) {
+      throw new Error('[ServiceWrapper] Missing configuration - service.version is required');
+    }
+    return version;
+  }
+
   /**
    * Log phase with transparent format
    * @private
    */
   _logPhase(phase, phaseName, status, error = null, duration = null) {
-    const serviceName = this.config.service?.name || 'unnamed-service';
+    // THE ONE PLACE that does not use _serviceName(), and the only one that may
+    // not. `_handleInitializationError` reports a failed phase through here, and
+    // a phase can fail precisely because the configuration never loaded — so a
+    // throw would replace the error being reported with a second one and the
+    // operator would never see the first. `<config not loaded>` is not an
+    // invented identity: it is a statement ABOUT the configuration, in a message
+    // whose subject is the configuration failing.
+    const serviceName = this.config?.service?.name ?? '<config not loaded>';
     const logMsg = `[FÁZE ${phase}] ${phaseName} - ${status}`;
     const logData = {
       phase,
@@ -651,7 +694,7 @@ class ServiceWrapper {
    * @private
    */
   async _cleanupBeforeRestart() {
-    const serviceName = this.config.service?.name || 'unnamed-service';
+    const serviceName = this._serviceName();
     console.log(`[CLEANUP] Starting cleanup for ${serviceName} before restart...`);
 
     try {
@@ -800,7 +843,7 @@ class ServiceWrapper {
       return;
     }
 
-    const serviceName = this.config.service?.name || 'unnamed-service';
+    const serviceName = this._serviceName();
     const startTime = Date.now();
 
     try {
@@ -971,7 +1014,7 @@ class ServiceWrapper {
    * @private
    */
   async _initializeMonitoring() {
-    const serviceName = this.config.service?.name || 'unnamed-service';
+    const serviceName = this._serviceName();
     const fs = require('fs');
     const path = require('path');
 
@@ -1128,7 +1171,7 @@ class ServiceWrapper {
       throw new Error('MQ URL is required when MQ is enabled. Set wrapper.mq.url in config');
     }
 
-    const serviceName = this.config.service?.name || 'unnamed-service';
+    const serviceName = this._serviceName();
 
     // Health monitoring and channel close hooks configuration
     // NOTE: Health monitoring is NOT run periodically - it's triggered manually before workflow steps in debug mode
@@ -1232,10 +1275,7 @@ class ServiceWrapper {
       throw new Error('Registry URL is required when registry is enabled. Set wrapper.registry.url in config');
     }
 
-    const serviceName = this.config.service?.name;
-    if (!serviceName) {
-      throw new Error('[ServiceWrapper] Missing configuration - service.name is required');
-    }
+    const serviceName = this._serviceName();
 
     // ADR 0005: biz has no HTTP — no port, no URL. Kept in serviceInfo
     // payload as empty string for Registry-side backward compat with
@@ -1252,17 +1292,26 @@ class ServiceWrapper {
     // FÁZE 0.5 a 0.6: Vytvoření front a spuštění konzumerů se provádí v registryClient.init()
     // FÁZE 0.7: Registrace u Registry
 
-    // ADR 0005: no HTTP surface → specificationEndpoint has no consumer.
-    // Registry receives full operations spec in the register payload
-    // itself. Field kept optional for pre-3.4.1 config files that may
-    // still declare it; ignored if absent.
-    const specificationEndpoint = this.config.service?.specificationEndpoint || '';
+    // specificationEndpoint HAS a consumer, despite ADR 0005 leaving no HTTP
+    // surface behind it. The registry destructures it off this register payload
+    // (api/infra/api_services_registry/src/listeners/registry.listener.js:354),
+    // warns when it is empty (:474-477), passes it into every registerFull call
+    // (:542, :626, :730, :813, :1108), and the model writes it into the Redis
+    // summary entry (src/models/microservice.model.js:166-177). The heartbeat
+    // listener reads it too (src/listeners/heartbeat.listener.js:30, :49).
+    // This comment claimed the opposite until 2026-08-30; measured, it was wrong.
+    // ConfigLoader.js:360-365 therefore keeps the field REQUIRED, and every biz
+    // service builds its config through it (measured 2026-08-30: all eight call
+    // ConfigLoader.loadAll from src/config/index.js). A `|| ''` used to sit here;
+    // it could never fire, and a fallback that cannot fire still tells the
+    // reader an empty endpoint is an expected state (architecture-principles §3).
+    const specificationEndpoint = this.config.service.specificationEndpoint;
 
     // Logger may not be initialized yet at this point - RegistryClient handles null gracefully
     this.registryClient = new RegistryConnector.ServiceRegistryClient({
       amqpUrl: mqUrl,
       serviceName: serviceName,
-      version: this.config.service?.version,
+      version: this._serviceVersion(),
       specificationEndpoint: specificationEndpoint,
       registryQueue: 'registry.register', // Use correct queue name
       registryUrl: registryUrl,
@@ -1285,7 +1334,7 @@ class ServiceWrapper {
       operations: this.operations?.operations || {},
       workspaceScoped: this.config.service?.workspaceScoped,
       metadata: {
-        version: this.config.service?.version,
+        version: this._serviceVersion(),
         description: this.config.service?.description || ''
       }
     };
@@ -1445,7 +1494,7 @@ class ServiceWrapper {
       return;
     }
 
-    const serviceName = this.config.service?.name || 'unnamed-service';
+    const serviceName = this._serviceName();
 
     let host = cacheUrl;
     let port = 6379;
@@ -1599,14 +1648,8 @@ class ServiceWrapper {
     // (below), but it runs only when serviceRoot is set and
     // wrapper.validation.enabled !== false — a service with validation off used
     // to arrive here with neither key ever checked.
-    const serviceName = this.config.service?.name;
-    if (!serviceName) {
-      throw new Error('[ServiceWrapper] Missing configuration - service.name is required');
-    }
-    const serviceVersion = this.config.service?.version;
-    if (!serviceVersion) {
-      throw new Error('[ServiceWrapper] Missing configuration - service.version is required');
-    }
+    const serviceName = this._serviceName();
+    const serviceVersion = this._serviceVersion();
 
     const { createBaseClientAdapter } = require('@onlineapps/infrastructure-tools');
 
@@ -1724,17 +1767,13 @@ class ServiceWrapper {
   async _initializeOrchestrator() {
     assertConnOrchOrchestratorV2Contract();
 
-    const serviceName = this.config.service?.name;
-    const serviceVersion = this.config.service?.version;
+    // Both guards moved into the getters — one owner for the contract and for
+    // its wording (change-discipline.md § one fact, one owner).
+    const serviceName = this._serviceName();
+    const serviceVersion = this._serviceVersion();
     const environment = this.config.service?.env;
     const serviceUrl = this.config.service?.url;
 
-    if (!serviceName) {
-      throw new Error('[ServiceWrapper] Missing configuration - service.name is required');
-    }
-    if (!serviceVersion) {
-      throw new Error('[ServiceWrapper] Missing configuration - service.version is required');
-    }
     if (!environment) {
       throw new Error('[ServiceWrapper] Missing configuration - service.env (NODE_ENV) is required');
     }
@@ -1815,7 +1854,7 @@ class ServiceWrapper {
 
     const queueName = 'workflow.init';
     this.logger?.info(`[ServiceWrapper] [CONSUMER] Starting workflow.init listener for queue: ${queueName}`);
-    this.logger?.info(`[ServiceWrapper] [CONSUMER] Service: ${this.config.service?.name || 'unnamed-service'}`);
+    this.logger?.info(`[ServiceWrapper] [CONSUMER] Service: ${this._serviceName()}`);
     this.logger?.info(`[ServiceWrapper] [CONSUMER] Timestamp: ${new Date().toISOString()}`);
 
     try {
@@ -1847,7 +1886,7 @@ class ServiceWrapper {
 
     const queueName = 'workflow.control';
     this.logger?.info(`[ServiceWrapper] [CONSUMER] Starting workflow.control listener for queue: ${queueName}`);
-    this.logger?.info(`[ServiceWrapper] [CONSUMER] Service: ${this.config.service?.name || 'unnamed-service'}`);
+    this.logger?.info(`[ServiceWrapper] [CONSUMER] Service: ${this._serviceName()}`);
     this.logger?.info(`[ServiceWrapper] [CONSUMER] Timestamp: ${new Date().toISOString()}`);
 
     try {
@@ -1876,7 +1915,7 @@ class ServiceWrapper {
       throw new Error('[ServiceWrapper] Cannot start service workflow listener — MQ client not initialized. Queue infrastructure is required.');
     }
 
-    const serviceName = this.config.service?.name || 'unnamed-service';
+    const serviceName = this._serviceName();
     const serviceQueue = `${serviceName}.workflow`;
 
     this.logger?.info(`[ServiceWrapper] [CONSUMER] Starting service-specific workflow listener for queue: ${serviceQueue}`);
@@ -1984,7 +2023,7 @@ class ServiceWrapper {
       });
 
       // Check if this message is for our service
-      const serviceName = this.config.service?.name || 'unnamed-service';
+      const serviceName = this._serviceName();
       if (message.step?.service && message.step.service !== serviceName) {
         this.logger?.debug(`Message not for this service (target: ${message.step.service})`);
         return;
@@ -2406,8 +2445,8 @@ class ServiceWrapper {
     });
 
     try {
-      const serviceName = this.config.service?.name;
-      const serviceVersion = this.config.service?.version;
+      const serviceName = this._serviceName();
+      const serviceVersion = this._serviceVersion();
       const serviceUrl = this.config.service?.url;
 
       const orchestrator = this._createValidationOrchestrator();
@@ -2599,8 +2638,8 @@ class ServiceWrapper {
     // INTENTIONAL FALLBACK: bootstrap logger — see docs/standards/FALLBACKS_INVENTORY.md §5.1
     return new ValidationOrchestrator({
       serviceRoot: this.serviceRoot,
-      serviceName: this.config.service?.name,
-      serviceVersion: this.config.service?.version,
+      serviceName: this._serviceName(),
+      serviceVersion: this._serviceVersion(),
       serviceUrl: this.config.service?.url || '',
       logger: this.logger || console
     });
@@ -2684,7 +2723,7 @@ class ServiceWrapper {
    * @async
    */
   async shutdown() {
-    const serviceName = this.config.service?.name || 'unnamed-service';
+    const serviceName = this._serviceName();
     this.logger?.info(`Shutting down ServiceWrapper for ${serviceName}`);
 
     try {
@@ -2774,12 +2813,11 @@ class ServiceWrapper {
    * @private
    */
   async _ensureValidationProof() {
-    if (!this.config.service?.name) {
-      throw new Error('Service name is required for validation');
-    }
-    if (!this.config.service?.version) {
-      throw new Error('Service version is required for validation');
-    }
+    // The two guards this method used to carry said the same thing in different
+    // words ("Service name is required for validation"). One contract, one
+    // wording — the getters own both.
+    this._serviceName();
+    this._serviceVersion();
 
     // ADR 0005: biz services have no HTTP surface — no port to bind, no URL to
     // advertise. The two guards above are the contract; the values themselves
@@ -2848,7 +2886,7 @@ class ServiceWrapper {
   getStatus() {
     return {
       initialized: this.isInitialized,
-      service: this.config.service?.name || 'unnamed-service',
+      service: this._serviceName(),
       components: {
         mq: this.mqClient?.isConnected() || false,
         registry: !!this.registryClient,