@onlineapps/service-wrapper 2.3.9 → 2.4.1

package/API.md

@@ -53,7 +53,7 @@ ALL actual functionality is delegated to specialized connectors.
 const wrapper = new ServiceWrapper({
   service: expressApp,
   serviceName: 'hello-service',
-  openApiSpec: require('./openapi.json'),
+  operations: require('./openapi.json'),
   config: {
     rabbitmq: process.env.RABBITMQ_URL,
     redis: process.env.REDIS_HOST,
@@ -78,7 +78,7 @@ Create a new ServiceWrapper instance
 | options | <code>Object</code> |  | Configuration options |
 | options.service | <code>Object</code> |  | Express application instance |
 | options.serviceName | <code>string</code> |  | Name of the service |
-| options.openApiSpec | <code>Object</code> |  | OpenAPI specification |
+| options.operations | <code>Object</code> |  | Operations specification (operations.json; see operations-registry-contract.md §3) |
 | [options.config] | <code>Object</code> | <code>{}</code> | Infrastructure configuration |
 | [options.config.rabbitmq] | <code>string</code> |  | RabbitMQ connection URL |
 | [options.config.redis] | <code>string</code> |  | Redis connection string |
@@ -106,7 +106,7 @@ ALL actual functionality is delegated to specialized connectors.
 const wrapper = new ServiceWrapper({
   service: expressApp,
   serviceName: 'hello-service',
-  openApiSpec: require('./openapi.json'),
+  operations: require('./openapi.json'),
   config: {
     rabbitmq: process.env.RABBITMQ_URL,
     redis: process.env.REDIS_HOST,
@@ -131,7 +131,7 @@ Create a new ServiceWrapper instance
 | options | <code>Object</code> |  | Configuration options |
 | options.service | <code>Object</code> |  | Express application instance |
 | options.serviceName | <code>string</code> |  | Name of the service |
-| options.openApiSpec | <code>Object</code> |  | OpenAPI specification |
+| options.operations | <code>Object</code> |  | Operations specification (operations.json; see operations-registry-contract.md §3) |
 | [options.config] | <code>Object</code> | <code>{}</code> | Infrastructure configuration |
 | [options.config.rabbitmq] | <code>string</code> |  | RabbitMQ connection URL |
 | [options.config.redis] | <code>string</code> |  | Redis connection string |
@@ -214,7 +214,7 @@ ALL actual functionality is delegated to specialized connectors.
 const wrapper = new ServiceWrapper({
   service: expressApp,
   serviceName: 'hello-service',
-  openApiSpec: require('./openapi.json'),
+  operations: require('./openapi.json'),
   config: {
     rabbitmq: process.env.RABBITMQ_URL,
     redis: process.env.REDIS_HOST,
@@ -239,7 +239,7 @@ Create a new ServiceWrapper instance
 | options | <code>Object</code> |  | Configuration options |
 | options.service | <code>Object</code> |  | Express application instance |
 | options.serviceName | <code>string</code> |  | Name of the service |
-| options.openApiSpec | <code>Object</code> |  | OpenAPI specification |
+| options.operations | <code>Object</code> |  | Operations specification (operations.json; see operations-registry-contract.md §3) |
 | [options.config] | <code>Object</code> | <code>{}</code> | Infrastructure configuration |
 | [options.config.rabbitmq] | <code>string</code> |  | RabbitMQ connection URL |
 | [options.config.redis] | <code>string</code> |  | Redis connection string |
@@ -267,7 +267,7 @@ ALL actual functionality is delegated to specialized connectors.
 const wrapper = new ServiceWrapper({
   service: expressApp,
   serviceName: 'hello-service',
-  openApiSpec: require('./openapi.json'),
+  operations: require('./openapi.json'),
   config: {
     rabbitmq: process.env.RABBITMQ_URL,
     redis: process.env.REDIS_HOST,
@@ -292,7 +292,7 @@ Create a new ServiceWrapper instance
 | options | <code>Object</code> |  | Configuration options |
 | options.service | <code>Object</code> |  | Express application instance |
 | options.serviceName | <code>string</code> |  | Name of the service |
-| options.openApiSpec | <code>Object</code> |  | OpenAPI specification |
+| options.operations | <code>Object</code> |  | Operations specification (operations.json; see operations-registry-contract.md §3) |
 | [options.config] | <code>Object</code> | <code>{}</code> | Infrastructure configuration |
 | [options.config.rabbitmq] | <code>string</code> |  | RabbitMQ connection URL |
 | [options.config.redis] | <code>string</code> |  | Redis connection string |

package/examples/cookbook-file-output.json

@@ -4,7 +4,7 @@
     "description": "Operation with file output (MinIO storage)",
     "steps": [
       {
-        "service": "hello-service",
+        "service": "biz-hello",
         "operation": "hello-cert",
         "input": {
           "name": "Igor",

package/examples/cookbook-multi-step.json

@@ -4,14 +4,14 @@
     "description": "Multi-step workflow across services",
     "steps": [
       {
-        "service": "hello-service",
+        "service": "biz-hello",
         "operation": "good-day",
         "input": {
           "name": "Igor"
         }
       },
       {
-        "service": "hello-service",
+        "service": "biz-hello",
         "operation": "hello-cert",
         "input": {
           "name": "Igor",

package/examples/cookbook-single-operation.json

@@ -4,7 +4,7 @@
     "description": "Single operation example",
     "steps": [
       {
-        "service": "hello-service",
+        "service": "biz-hello",
         "operation": "good-day",
         "input": {
           "name": "Igor"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/service-wrapper",
-  "version": "2.3.9",
+  "version": "2.4.1",
   "description": "Thin orchestration layer for microservices - delegates all infrastructure concerns to specialized connectors",
   "main": "src/index.js",
   "scripts": {
@@ -26,16 +26,16 @@
   "dependencies": {
     "@onlineapps/conn-base-cache": "1.0.9",
     "@onlineapps/conn-base-state": "1.0.1",
-    "@onlineapps/conn-base-monitoring": "1.0.11",
-    "@onlineapps/conn-infra-error-handler": "1.0.10",
+    "@onlineapps/conn-base-monitoring": "1.0.12",
+    "@onlineapps/conn-infra-error-handler": "1.0.11",
     "@onlineapps/conn-infra-mq": "1.1.70",
     "@onlineapps/conn-orch-api-mapper": "1.0.33",
-    "@onlineapps/conn-orch-cookbook": "2.0.38",
+    "@onlineapps/conn-orch-cookbook": "2.1.0",
     "@onlineapps/conn-orch-orchestrator": "1.0.110",
     "@onlineapps/conn-orch-registry": "1.1.55",
     "@onlineapps/conn-orch-validator": "2.0.33",
-    "@onlineapps/monitoring-core": "1.0.22",
-    "@onlineapps/service-common": "1.0.19",
+    "@onlineapps/monitoring-core": "1.0.23",
+    "@onlineapps/service-common": "1.1.2",
     "@onlineapps/runtime-config": "1.0.2"
   },
   "devDependencies": {

package/src/ConfigLoader.js

@@ -372,6 +372,7 @@ class ConfigLoader {
         url: serviceConfig.service.url,
         specificationEndpoint: serviceConfig.service.specificationEndpoint,
         description: serviceConfig.service.description,
+        workspaceScoped: serviceConfig.service.workspaceScoped,
         env: nodeEnv
       },
       wrapper: mergedWrapper,

package/src/ServiceWrapper.js

@@ -78,6 +78,12 @@ class ServiceWrapper {
     this.validationProof = options.validationProof || null;
     this._injectedValidationOrchestrator = options._validationOrchestrator || null;
 
+    // Fail-fast: enforce naming conventions and workspaceScoped invariants.
+    // See api/docs/standards/OPERATIONS.md and biz-service-onboarding.md §3.1 / §4.
+    // Rejection here keeps the contract authoritative at the earliest possible
+    // point (before MQ listeners, registry client, or any I/O is touched).
+    this._validateNamingAndWorkspaceScoped();
+
     // Initialize connector placeholders
     this.mqClient = null;
     this.registryClient = null;
@@ -253,6 +259,79 @@ class ServiceWrapper {
     }
   }
 
+  /**
+   * Fail-fast validation of naming conventions and workspaceScoped invariants.
+   *
+   * Enforced rules (all normative — see OPERATIONS.md, biz-service-onboarding.md):
+   *   1. Every key in `operations.operations` matches kebab-case regex
+   *      /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/ (no camelCase, snake_case, or PascalCase).
+   *   2. `config.service.workspaceScoped` is an explicit boolean (no default).
+   *   3. `workspaceScoped: true` ⇒ `operations['list-workspaces']` MUST exist
+   *      (workspace discovery convention per onboarding §4).
+   *   4. `workspaceScoped: false` ⇒ `operations['list-workspaces']` MUST NOT
+   *      exist (flag is the authoritative signal; no ambiguity).
+   *
+   * All violations throw at construction time — service will not register,
+   * not start MQ listeners, will not reach production. Misnamed operations
+   * cannot ship.
+   *
+   * @private
+   */
+  _validateNamingAndWorkspaceScoped() {
+    const serviceName = this.config?.service?.name || '<unnamed-service>';
+    const kebabRegex = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+    // Rule 1: every operation key must be kebab-case
+    const opsMap =
+      this.operations && typeof this.operations === 'object'
+        ? (this.operations.operations && typeof this.operations.operations === 'object'
+          ? this.operations.operations
+          : this.operations)
+        : null;
+    if (!opsMap || typeof opsMap !== 'object') {
+      throw new Error(
+        `[ServiceWrapper][${serviceName}] operations schema is invalid - expected object with 'operations' map of operation definitions; see api/docs/standards/OPERATIONS.md`
+      );
+    }
+    const offenders = Object.keys(opsMap).filter((key) => !kebabRegex.test(key));
+    if (offenders.length > 0) {
+      throw new Error(
+        `[ServiceWrapper][${serviceName}] operation key(s) violate kebab-case convention: ` +
+          `${offenders.map((k) => `'${k}'`).join(', ')} - must match /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/. ` +
+          `See api/docs/standards/OPERATIONS.md §Best Practices - Naming Convention. ` +
+          `Rename the key(s) in operations.json plus every cookbook/test/Admin UI literal; there is no alias layer.`
+      );
+    }
+
+    // Rule 2: workspaceScoped must be explicit boolean
+    const ws = this.config?.service?.workspaceScoped;
+    if (typeof ws !== 'boolean') {
+      throw new Error(
+        `[ServiceWrapper][${serviceName}] service.workspaceScoped is required and MUST be an explicit boolean in config.json (got ${ws === undefined ? 'undefined' : JSON.stringify(ws)}). ` +
+          `See api/docs/standards/biz-service-onboarding.md §3.1. ` +
+          `true = service stores data keyed by workspace_id and implements list-workspaces operation; ` +
+          `false = stateless or cross-workspace.`
+      );
+    }
+
+    // Rules 3 & 4: workspaceScoped consistency with list-workspaces
+    const hasListWorkspaces = Object.prototype.hasOwnProperty.call(opsMap, 'list-workspaces');
+    if (ws === true && !hasListWorkspaces) {
+      throw new Error(
+        `[ServiceWrapper][${serviceName}] service.workspaceScoped is true but 'list-workspaces' operation is not declared. ` +
+          `Workspace-scoped services MUST expose list-workspaces (workspace discovery convention). ` +
+          `See api/docs/standards/biz-service-onboarding.md §4 and OPERATIONS.md §Reserved operation names.`
+      );
+    }
+    if (ws === false && hasListWorkspaces) {
+      throw new Error(
+        `[ServiceWrapper][${serviceName}] service.workspaceScoped is false but 'list-workspaces' operation is declared. ` +
+          `Stateless / cross-workspace services MUST NOT declare list-workspaces - the flag is the authoritative signal. ` +
+          `See api/docs/standards/biz-service-onboarding.md §4.`
+      );
+    }
+  }
+
   /**
    * Process and validate configuration
    * @private
@@ -413,7 +492,7 @@ class ServiceWrapper {
 
       if (this.registryClient?.queueManager) {
         try {
-          await this.registryClient.queueManager.disconnect();
+          await this.registryClient.queueManager.close();
           console.log(`[CLEANUP] ✓ Closed Registry RabbitMQ connection`);
         } catch (err) {
           console.warn(`[CLEANUP] Failed to close Registry RabbitMQ connection:`, err.message);
@@ -931,11 +1010,15 @@ class ServiceWrapper {
     await this.registryClient.init();
     this.logger?.info('Registry client initialized');
 
-    // Register service
+    // Register service.
+    // workspaceScoped propagates verbatim to Redis spec so meta/Admin UI can
+    // filter workspace-aware services without a hardcoded allowlist. Value is
+    // guaranteed boolean by _validateNamingAndWorkspaceScoped().
     const serviceInfo = {
       name: serviceName,
       url: serviceUrl,
       operations: this.operations?.operations || {},
+      workspaceScoped: this.config.service?.workspaceScoped,
       metadata: {
         version: this.config.service?.version,
         description: this.config.service?.description || ''
@@ -1403,7 +1486,8 @@ class ServiceWrapper {
     }
 
     const apiMapper = ApiMapperConnector.create({
-      openApiSpec: this.operations,
+      // operations.json contract (see operations-registry-contract.md §3)
+      operations: this.operations,
       serviceUrl: serviceUrl,
       directCall: false,
       logger: this.logger
@@ -2003,6 +2087,7 @@ class ServiceWrapper {
           name: serviceName,
           url: serviceUrl,
           operations: this.operations?.operations || {},
+          workspaceScoped: this.config.service?.workspaceScoped,
           metadata: {
             version: serviceVersion,
             description: this.config.service?.description || ''

package/src/index.js

@@ -149,6 +149,7 @@ async function bootstrap(serviceRoot, options = {}) {
         url: config.service.url,
         specificationEndpoint: config.service.specificationEndpoint,
         description: config.service.description,
+        workspaceScoped: config.service.workspaceScoped,
         env: config.service.env || runtimeCfg.get('nodeEnv')
       },
       wrapper: config.wrapper