@onlineapps/service-wrapper 3.4.7 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/service-wrapper",
-  "version": "3.4.7",
+  "version": "4.1.0",
   "description": "Thin orchestration layer for microservices - delegates all infrastructure concerns to specialized connectors",
   "main": "src/index.js",
   "scripts": {
@@ -33,7 +33,7 @@
     "@onlineapps/conn-orch-cookbook": "2.1.4",
     "@onlineapps/conn-orch-orchestrator": "2.1.7",
     "@onlineapps/conn-orch-registry": "1.2.2",
-    "@onlineapps/conn-orch-validator": "3.3.2",
+    "@onlineapps/conn-orch-validator": "4.0.0",
     "@onlineapps/infrastructure-tools": "1.2.6",
     "@onlineapps/monitoring-core": "1.0.26",
     "@onlineapps/runtime-config": "1.0.2",

package/src/ErrorMapper.js

@@ -9,6 +9,8 @@
  * modules, no third-party deps. Logger is injected via constructor (DI).
  *
  * Exports:
+ *   - BUSINESS_ERROR_BRAND   — Symbol.for('onlineapps.businessError'), the mark.
+ *   - isBusinessError(err)   — brand + shape predicate (the contract itself).
  *   - ErrorMapper            — maps exceptions to { status, error: {...} } envelopes.
  *   - BusinessError          — base class for handler-authored errors (code + status required).
  *   - ValidationError        — 400 VALIDATION_FAILED. Thrown by SchemaValidator
@@ -22,6 +24,32 @@
  *   - UnknownOperationError  — thrown by HandlerRegistry for unregistered ops.
  *   - AbortError             — thrown when ctx.abortSignal aborts the invocation.
  *
+ * THE CONTRACT IS A BRAND PLUS A SHAPE, NOT A CLASS IDENTITY (DÁVKA 50).
+ * Owner decision: api/docs/governance/confirmations/business-error-contract.md
+ * (20260829-1500-business-error-contract-001).
+ *
+ * An error is a business error when it carries ALL of:
+ *   - the brand `Symbol.for('onlineapps.businessError')` with value `true`
+ *     (a GLOBAL registry symbol, so it survives two copies of this package in
+ *     node_modules and can be claimed by a service's own class);
+ *   - `code`    — string matching /^[A-Z][A-Z0-9_]*$/;
+ *   - `status`  — number in [100, 599];
+ *   - `message` — non-empty string.
+ *
+ * `map()` therefore dispatches on `code`, never on `instanceof`. `instanceof`
+ * remains true for our own classes but is no longer what decides anything.
+ *
+ * The two outcomes for an error that is not a business error are deliberately
+ * different, and that difference is the point:
+ *   - BRANDED but malformed → OUR defect. 500 `MALFORMED_BUSINESS_ERROR` and an
+ *     `error` log naming the offending field. Loud, never anonymous.
+ *   - UNBRANDED            → a genuinely unknown error. 500 `INTERNAL_ERROR`,
+ *     message and details masked. Unchanged.
+ *
+ * A service may throw its own class as long as it declares the brand and the
+ * shape. Extending `BusinessError` is the easy way to get both; it is not the
+ * only permitted one.
+ *
  * Two constructor shapes, because the parameter sets genuinely differ:
  *   - `BusinessError` takes `{ code, status, message, details }` — the author
  *     must supply code + status, so they are named.
@@ -36,6 +64,88 @@
  * base class fail-fasts instead.
  */
 
+/**
+ * The business-error brand. `Symbol.for` puts it in the GLOBAL symbol registry,
+ * so two independently loaded copies of this file resolve to the SAME symbol —
+ * which is exactly the case `instanceof` used to lose.
+ */
+const BUSINESS_ERROR_BRAND = Symbol.for('onlineapps.businessError');
+
+/** `code` must be an uppercase SNAKE_CASE identifier. */
+const BUSINESS_ERROR_CODE_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+
+const BUSINESS_ERROR_STATUS_MIN = 100;
+const BUSINESS_ERROR_STATUS_MAX = 599;
+
+/** Render a value for an operator-facing defect line: `"404" (string)`. */
+function describeValue(value) {
+  const rendered = typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+    ? JSON.stringify(value)
+    : String(value);
+  return `${rendered} (${typeof value})`;
+}
+
+/**
+ * Does the error claim to be one of ours? Claiming is not being — see
+ * {@link describeBusinessErrorDefects}.
+ *
+ * @param {*} err
+ * @returns {boolean}
+ */
+function hasBusinessErrorBrand(err) {
+  return !!err && (typeof err === 'object' || typeof err === 'function') && err[BUSINESS_ERROR_BRAND] === true;
+}
+
+/**
+ * Every way a branded error breaks the shape, named field by field. Empty array
+ * = the contract holds.
+ *
+ * @param {Object} err
+ * @returns {string[]}
+ */
+function describeBusinessErrorDefects(err) {
+  const defects = [];
+
+  if (typeof err.code !== 'string' || !BUSINESS_ERROR_CODE_PATTERN.test(err.code)) {
+    defects.push(`code is ${describeValue(err.code)}, expected a string matching ${BUSINESS_ERROR_CODE_PATTERN.source}`);
+  }
+  if (typeof err.status !== 'number' || !Number.isFinite(err.status) ||
+      err.status < BUSINESS_ERROR_STATUS_MIN || err.status > BUSINESS_ERROR_STATUS_MAX) {
+    defects.push(`status is ${describeValue(err.status)}, expected a number between ${BUSINESS_ERROR_STATUS_MIN} and ${BUSINESS_ERROR_STATUS_MAX}`);
+  }
+  if (typeof err.message !== 'string' || err.message.length === 0) {
+    defects.push(`message is ${describeValue(err.message)}, expected a non-empty string`);
+  }
+
+  return defects;
+}
+
+/**
+ * THE contract. A service's own class passes this by declaring the brand and
+ * the three fields — it does not have to extend `BusinessError`.
+ *
+ * @param {*} err
+ * @returns {boolean}
+ */
+function isBusinessError(err) {
+  return hasBusinessErrorBrand(err) && describeBusinessErrorDefects(err).length === 0;
+}
+
+/**
+ * Stamp the brand on a class prototype: non-enumerable and non-writable, so it
+ * never reaches a JSON payload and cannot be unset by accident.
+ *
+ * @param {Function} Cls
+ */
+function brand(Cls) {
+  Object.defineProperty(Cls.prototype, BUSINESS_ERROR_BRAND, {
+    value: true,
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+}
+
 class BusinessError extends Error {
   constructor({ code, status, message, details } = {}) {
     if (!code) {
@@ -163,6 +273,12 @@ class AbortError extends Error {
   }
 }
 
+// `UnknownOperationError` and `AbortError` do not extend `BusinessError` (their
+// constructor shape differs), so each is branded on its own prototype.
+brand(BusinessError);
+brand(UnknownOperationError);
+brand(AbortError);
+
 class ErrorMapper {
   /**
    * @param {Object} options
@@ -179,6 +295,10 @@ class ErrorMapper {
    * Map a handler exception to an MQ response envelope.
    * Never throws. Always returns `{ status, error: { code, message, [details], [correlation_id] } }`.
    *
+   * Recognition is by the brand + shape contract (see the file header), never by
+   * `instanceof`. Branded + malformed → 500 `MALFORMED_BUSINESS_ERROR` with the
+   * offending field named in the log; unbranded → 500 `INTERNAL_ERROR`, masked.
+   *
    * @param {Error} err
    * @param {Object} meta
    * @param {string} [meta.operation]
@@ -188,8 +308,34 @@ class ErrorMapper {
   map(err, meta = {}) {
     const { operation, correlation_id } = meta;
 
-    if (err instanceof ValidationError) {
-      if (err.phase === 'output') {
+    if (hasBusinessErrorBrand(err)) {
+      const defects = describeBusinessErrorDefects(err);
+      if (defects.length > 0) {
+        // Branded but malformed = a defect in OUR code (or in a service that
+        // claimed the brand and then broke the shape). It gets a named, loud
+        // 500 instead of the anonymous one an unknown error gets, so the log
+        // says which field is wrong rather than "something threw".
+        this._logger.error(
+          `[ErrorMapper] branded error has invalid shape - ${defects.join('; ')}. ` +
+          'Fix: a branded business error must carry code (' + BUSINESS_ERROR_CODE_PATTERN.source + '), ' +
+          `status (number ${BUSINESS_ERROR_STATUS_MIN}-${BUSINESS_ERROR_STATUS_MAX}) and a non-empty message.`,
+          {
+            err,
+            operation,
+            correlation_id,
+            code: 'MALFORMED_BUSINESS_ERROR',
+            status: 500,
+            stack: err && err.stack,
+            defects
+          }
+        );
+        return this._buildError(500, 'MALFORMED_BUSINESS_ERROR', 'An internal error occurred', undefined, correlation_id);
+      }
+
+      // From here on the shape is guaranteed. Branches key on `code`, so a
+      // class from a second copy of this package — or a service's own class
+      // declaring the same code — takes exactly the same branch as ours.
+      if (err.code === 'VALIDATION_FAILED' && err.phase === 'output') {
         this._logger.error(
           'output schema validation failed - server bug',
           { err, operation, correlation_id, code: 'INTERNAL_ERROR', status: 500 }
@@ -197,23 +343,7 @@ class ErrorMapper {
         return this._buildError(500, 'INTERNAL_ERROR', 'Internal validation error', undefined, correlation_id);
       }
 
-      this._logger.info(
-        'input schema validation failed',
-        { err, operation, correlation_id, code: 'VALIDATION_FAILED', status: 400 }
-      );
-      return this._buildError(400, 'VALIDATION_FAILED', err.message, err.details, correlation_id);
-    }
-
-    if (err instanceof UnknownOperationError) {
-      this._logger.warn(
-        'unknown operation requested',
-        { err, operation, correlation_id, code: 'UNKNOWN_OPERATION', status: 404 }
-      );
-      return this._buildError(404, 'UNKNOWN_OPERATION', err.message, undefined, correlation_id);
-    }
-
-    if (err instanceof BusinessError) {
-      // A BusinessError with a 5xx status is a server fault wearing a business
+      // A business error with a 5xx status is a server fault wearing a business
       // class. It is logged like one — `error` level WITH the stack — and the
       // caller gets the same neutral text as any other internal error, so the
       // original message (which may name a tenant, a column or a credential)
@@ -226,6 +356,30 @@ class ErrorMapper {
         return this._buildError(err.status, err.code, 'An internal error occurred', undefined, correlation_id);
       }
 
+      if (err.code === 'UNKNOWN_OPERATION') {
+        this._logger.warn(
+          'unknown operation requested',
+          { err, operation, correlation_id, code: err.code, status: err.status }
+        );
+        return this._buildError(err.status, err.code, err.message, undefined, correlation_id);
+      }
+
+      if (err.code === 'CLIENT_CANCELLED') {
+        this._logger.info(
+          'invocation aborted by client',
+          { err, operation, correlation_id, code: err.code, status: err.status }
+        );
+        return this._buildError(err.status, err.code, err.message, undefined, correlation_id);
+      }
+
+      if (err.code === 'VALIDATION_FAILED') {
+        this._logger.info(
+          'input schema validation failed',
+          { err, operation, correlation_id, code: err.code, status: err.status }
+        );
+        return this._buildError(err.status, err.code, err.message, err.details, correlation_id);
+      }
+
       this._logger.info(
         'handler raised BusinessError',
         { err, operation, correlation_id, code: err.code, status: err.status }
@@ -233,8 +387,11 @@ class ErrorMapper {
       return this._buildError(err.status, err.code, err.message, err.details, correlation_id);
     }
 
-    if (err instanceof AbortError || (err && err.name === 'AbortError')) {
-      const message = err && err.message ? err.message : 'Invocation aborted';
+    // Deliberately NOT the brand contract: an abort is a platform signal, not a
+    // business error, and the one we must recognise is Node's own DOMException
+    // from AbortController, which we do not construct and cannot brand.
+    if (err && err.name === 'AbortError') {
+      const message = err.message ? err.message : 'Invocation aborted';
       this._logger.info(
         'invocation aborted by client',
         { err, operation, correlation_id, code: 'CLIENT_CANCELLED', status: 499 }
@@ -265,6 +422,8 @@ class ErrorMapper {
 }
 
 module.exports = {
+  BUSINESS_ERROR_BRAND,
+  isBusinessError,
   ErrorMapper,
   BusinessError,
   ValidationError,

package/src/ServiceWrapper.js

@@ -326,7 +326,8 @@ class ServiceWrapper {
   /**
    * Fail-fast validation of naming conventions and workspaceScoped invariants.
    *
-   * Enforced rules (all normative — see OPERATIONS.md, biz-service-onboarding.md):
+   * Enforced rules (all normative — see api/docs/biz/30-operations/schema-v3.md and
+   * api/docs/biz/60-templates/onboarding-checklist.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).
@@ -379,12 +380,14 @@ class ServiceWrapper {
     }
 
     // Rules 3 & 4: workspaceScoped consistency with list-workspaces
+    // @see api/docs/biz/60-templates/onboarding-checklist.md §4 (workspace discovery convention)
+    // @see api/docs/biz/30-operations/schema-v3.md § Reserved operation names
     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/biz/60-templates/onboarding-checklist.md §4 and OPERATIONS.md §Reserved operation names.`
+          `Workspace-scoped services MUST expose list-workspaces (workspace discovery convention) - ` +
+          `Fix: declare a 'list-workspaces' operation in config/service/operations.json, or set service.workspaceScoped to false.`
       );
     }
     if (ws === false && hasListWorkspaces) {

package/src/index.js

@@ -124,6 +124,8 @@ const { OperationContext } = require('./OperationContext');
 const { ContextBuilder } = require('./ContextBuilder');
 const { SchemaValidator } = require('./SchemaValidator');
 const {
+  BUSINESS_ERROR_BRAND,
+  isBusinessError,
   ErrorMapper,
   BusinessError,
   ValidationError,
@@ -161,6 +163,18 @@ module.exports.ErrorMapper = ErrorMapper;
 // biz service throws; the retired @onlineapps/service-common hierarchy used the
 // same `(message, options)` signature, so migration is an import-line change.
 // Contract + per-class status/code: src/ErrorMapper.js header.
+//
+// The contract itself (DÁVKA 50, confirmation 20260829-1500-business-error-contract-001)
+// is the BRAND plus the SHAPE, not the class identity: an error is a business
+// error when it carries `BUSINESS_ERROR_BRAND` === true, a `code` matching
+// /^[A-Z][A-Z0-9_]*$/, a numeric `status` in [100, 599] and a non-empty
+// `message`. ErrorMapper dispatches on `code`, never on `instanceof`, so a
+// service may throw its OWN class as long as it declares the brand and the
+// shape — `isBusinessError()` is the predicate that decides. Branded but
+// malformed is a named 500 MALFORMED_BUSINESS_ERROR; unbranded stays a masked
+// 500 INTERNAL_ERROR.
+module.exports.BUSINESS_ERROR_BRAND = BUSINESS_ERROR_BRAND;
+module.exports.isBusinessError = isBusinessError;
 module.exports.BusinessError = BusinessError;
 module.exports.ValidationError = ValidationError;
 module.exports.NotFoundError = NotFoundError;