@onlineapps/error-handler-core 3.0.0 → 4.0.0

package/CHANGELOG.md

@@ -4,6 +4,101 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [4.0.0] — 2026-09-27
+
+### Changed — BREAKING — `ErrorClassifier.classify()` už nečte `error.message`: třídu dává jen `type`, `code` a `status` (d.761)
+
+Vydaná 3.1.0 měla ve `classify()` čtvrtý krok, který po `type`, `code` a `status`
+hledal v `error.message` (převedeném na malá písmena) podřetězce: `timeout` →
+`TIMEOUT`; `rate limit` / `rate_limit` → `RATE_LIMIT`; `validation` / `invalid` →
+`VALIDATION`; `fatal` / `critical` → `FATAL`; `connection` / `network` / `econn` →
+`TRANSIENT`. Ten krok je pryč. Chyba, kterou nedeklaruje žádné z těch tří polí, je
+`UNKNOWN` bez ohledu na znění — a `UNKNOWN` se neopakuje a loguje se se závažností
+`error`.
+
+Důvod: hláška je lidský řetězec, podle kterého kontrakt chyby neklasifikuje, a čtení
+znění byla druhá kolej vedle tabulky kódů (`change-discipline.md` § One rail per
+concern) — každé přeformulování hlášky tiše měnilo třídu. Měření živých producentů
+nenašlo nikoho, kdo by na krok dosáhl (`DeliveryDispatcher._canRetry` skládá
+`{ status, code }` bez hlášky, orchestrátor posílá `type`/`status`/`code`,
+`conn-infra-error-handler` jen deleguje). Jediný zásah byla vnitřní výjimka služby:
+`TypeError` se slovem „invalid" se zařadil jako `VALIDATION`, a tím dostal závažnost
+`warn` — vada našeho kódu podaná jako varování o vstupu. Teď je `UNKNOWN`, tedy
+`error`.
+
+Migrace: volající, který chce konkrétní třídu, ji deklaruje strojově — `error.type`
+(hodnota z `ErrorTypes`), `error.code` z tabulky `ErrorCodes`, nebo `error.status`.
+Kontrolní případy drží: `CIRCUIT_OPEN` → `TRANSIENT`, `422` → `VALIDATION`,
+`503` → `TRANSIENT`.
+
+### Fixed — čtyři změřené tvary chyb přenosu mají kategorii (d.774)
+
+V tabulce `ErrorCodes` chyběly, takže odpovídaly `UNKNOWN` — a `UNKNOWN` se
+neopakuje, doručení tedy skončilo bez jediného dalšího pokusu:
+
+- `EAI_AGAIN` (resolver říká „zeptej se znovu", `getaddrinfo`), `ENETUNREACH`,
+  `EHOSTUNREACH` (směrování) → `TRANSIENT` — tatáž rodina jako `ECONNREFUSED`:
+  protistrana tam příště být může;
+- `ECONNABORTED` (vypršená lhůta axiosu, který požadavek přeruší sám, proto bez
+  `cause` a bez syscallu) → `TIMEOUT`.
+
+Tvary jsou změřené na skutečných socketech
+(`infra/api_delivery_dispatcher/tests/unit/transportErrorShapes.test.js`). Nic jiného
+se v tabulce nehnulo: `ECONNREFUSED`, `ENOTFOUND`, `ETIMEDOUT`, `ECONNRESET`, `EPIPE`
+a `CIRCUIT_OPEN` drží svou třídu; trvalé tvary (`EPROTO`, `ERR_INVALID_URL`,
+`ERR_BAD_REQUEST`, certifikátové) a `ERR_CANCELED` zůstávají `UNKNOWN`.
+
+### Documentation — neznámý business kód se neoznačuje ani neodmítá (d.804)
+
+README (§ A business code this table does not know) a JSDoc `classify()` říkají
+pravidlo, které kód už měl: jméno business kódu, které tabulka nezná (např.
+`REFERENCE_RECORD_MISSING`), mine vyhledání podle `code` a třídu dá další deklarované
+pole — `error.type`, `error.code` v tabulce, `error.status`. Neznámé jméno na `422` je
+tedy `VALIDATION` jako holé `422`, na `503` `TRANSIENT`; `error.retryable` klasifikátor
+nečte. Slovník jmen business kódů tomuto balíčku nepatří — vlastní ho
+`api/docs/biz/70-contracts/error-handling.md` §1.
+
+### Documentation — `handleError()` bere záznam, ne holou chybu (d.804b)
+
+README říká, že `handleError()` vyžaduje tatáž tři pole jako `logError()` —
+`moduleName`, `operation` a `error` (`context` je jediný nepovinný klíč) — a že chybějící
+pole schéma odmítne jménem, v pořadí `moduleName` → `operation` → `error`. Volající,
+který předá zachycenou chybu samotnou, dostane doslova:
+`[UnifiedLogSchema] Missing required field - "moduleName" must be a non-empty string naming the module that failed; it is the caller's to provide and is never invented. Fix: pass params.moduleName (ErrorHandlerCore takes it from errorData.moduleName).`
+
+### Documentation — tabulka kódů je doména HTTP a Node, verdikt AMQP má jiného vlastníka (d.718)
+
+README (§ Which codes the classifier answers for): `ErrorClassifier` čte jen vlastní
+`ErrorTypes` (`error.type`), síťové kódy Node (`ECONNREFUSED`, `ETIMEDOUT`, …) a stavové
+kódy HTTP (`error.code` / `error.status`) — `502`, `503` a `504` tu mají význam HTTP.
+Selhání publikace klasifikuje transport, než chyba opustí
+`@onlineapps/mq-client-core` (`src/utils/publishErrors.js`).
+
+### Documentation — README nepíše verzi balíčku rukou (d.730)
+
+Patička README tvrdila `*Version: 1.0.0 | License: MIT*`; verzi vlastní
+`package.json`, patička je teď `*License: MIT*`.
+
+## [3.1.0] — 2026-09-25
+
+### Added — třída `ErrorTypes.DECLINED`: pravidlo práci zakázalo (d.831)
+
+Každá dosavadní třída pojmenovává způsob, jakým se práce NEPOVEDLA. `DECLINED` říká,
+že se dělat neměla: doklad už odeslaný byl, položku zdroj neprojednává. Je koncová,
+není to selhání, neopakuje se a nejde do DLQ — `ErrorHandlerCore` pro ni vrací verdikt
+`declined`, který je (stejně jako `dlq`) klasifikací pro volajícího, ne cestou, kterou
+by tenhle balíček sám šel.
+
+Deklaruje ji VYHAZUJÍCÍ přes `error.type`; ze stavového kódu se neodvozuje. Tabulka
+kódů zůstává beze změny — každé jiné `409` je dál `BUSINESS`, protože týž stav nese
+oba významy a jen vyhazující ví, který z nich myslel.
+
+Rozhodnutí vlastníka:
+`api/docs/governance/confirmations/workflow-failed-status-projection.md` 004
+(odmítnutí bránou komba není selhání běhu). Závažnost logu `info`, protože to není
+incident; mapa kategorií v `UnifiedLogSchema` ji kontroluje při načtení, takže třída
+bez závažnosti balíček neprojde.
+
 ## [3.0.0] — 2026-09-16
 
 ### Removed — **BREAKING** `DLQRouter`: dead-lettering má jednu kolej, a není v tomto balíčku

package/README.md

@@ -108,6 +108,27 @@ try {
 }
 ```
 
+**It takes the RECORD above, not a bare error.** `handleError(error)` is not a
+shorter spelling of `handleError({ error })`: the same three fields `logError()`
+requires are required here too — `moduleName`, `operation` and `error` — because
+`handleError()` logs before it classifies, through the same `UnifiedLogSchema`.
+`context` is the only optional key.
+
+A missing one is REFUSED, not defaulted, and the refusal comes from the schema by
+the name of the field, checked in that order (`moduleName` → `operation` →
+`error`):
+
+```
+[UnifiedLogSchema] Missing required field - "moduleName" must be a non-empty string
+naming the module that failed; it is the caller's to provide and is never invented.
+Fix: pass params.moduleName (ErrorHandlerCore takes it from errorData.moduleName).
+```
+
+So a caller that hands `handleError()` the caught error itself gets that message
+about `moduleName` — which names the real defect, but only if the reader knows the
+call takes a record. Measured by
+`tests/unit/business-code-outside-the-dictionary.test.js` § the call contract.
+
 ### Execute with Retry
 
 ```javascript
@@ -151,6 +172,64 @@ Branch on `error.code`, never on `error.message`: the wording follows
 `.claude/rules/architecture-principles.md` §5 and may be improved, the code and
 `details.name` are the contract.
 
+## `DECLINED` — a rule forbade the work
+
+Every class in `ErrorTypes` names a way the work FAILED, except this one. `DECLINED`
+says the work was refused: the domain rule that was asked says it must not happen —
+a document already sent, an item the source will not discuss. It is terminal, it is
+not a failure, it is not retried and it is not dead-lettered; `ErrorHandlerCore`
+answers it with the verdict `declined`, which — like `dlq` — is a classification
+returned to the caller, not a route this package takes.
+
+It is declared by the THROWER, through `error.type`, and never derived from a status:
+every other `409` stays `BUSINESS`, table and all. That is deliberate, because the
+same status carries both meanings and only the thrower knows which one it meant.
+
+@see api/docs/governance/confirmations/workflow-failed-status-projection.md — 004
+@see api/docs/biz/70-contracts/error-handling.md — the error classes
+
+## Which codes the classifier answers for
+
+`ErrorClassifier` reads three things and nothing else: this package's own
+`ErrorTypes` (`error.type`), Node's network codes (`ECONNREFUSED`, `ETIMEDOUT`, …)
+and **HTTP status codes** (`error.code` / `error.status`) — so `502`, `503` and
+`504` carry their HTTP meaning here. AMQP reply codes share those numbers with a
+different meaning, and they have a different owner: a publish failure is
+classified inside the transport, before the error leaves it.
+
+@see api/shared/mq-client-core/src/utils/publishErrors.js
+
+Measured by `tests/unit/classified-domains-one-owner.test.js`: the table's numeric
+keys are HTTP status codes, and the AMQP reply codes HTTP does not use (`406`,
+`530`, `405`, …) are not keys of it.
+
+### A business code this table does not know
+
+**The classifier neither labels nor refuses it.** A business name it has never heard
+of — `REFERENCE_RECORD_MISSING`, say — simply misses the `code` lookup, and the class
+comes from the next thing the error declares: `error.type`, then `error.code` in the
+table, then `error.status`. So an unknown name at `422` is `VALIDATION`, exactly like
+a bare `422`; the same unknown name at `503` is `TRANSIENT`. Two different unknown
+names with one status get one class, because **the name is not read at all**.
+
+`retryable` is not read here either. It belongs to the error contract and is consumed
+elsewhere (`ErrorMapper.CONTRACT_RETRYABLE_CODES`, the dispatcher's `_canRetry`); on
+this classifier it changes nothing, and whether a retry happens follows from the
+CLASS (`ErrorHandlerCore._decideAction`: `TRANSIENT`/`TIMEOUT`/`RATE_LIMIT` retry,
+`BUSINESS`/`VALIDATION` do not).
+
+This is a rule, not an omission: **the dictionary of business code NAMES is not this
+package's to own.** It lives in `api/docs/biz/70-contracts/error-handling.md` §1
+(BIZ-DOCS), and a new name is agreed through the process `error-code-dictionary` 002.
+A name branch here would make the class depend on a dictionary this package cannot
+see, which is two owners of one fact (`change-discipline.md` § One rail per concern).
+Measured 2026-09-22 (d.803): nothing in the workspace marks a business code as
+"unknown" — the only machine-readable code list is `CONTRACT_RETRYABLE_CODES`, which
+is the retryable set and nothing else.
+
+Measured by `tests/unit/business-code-outside-the-dictionary.test.js`, including the
+control that the table really does not carry the name.
+
 ## API Reference
 
 See [ERROR_HANDLING.md](/docs/standards/ERROR_HANDLING.md) for the cross-cutting standard (classification table, fail-loudly rules).
@@ -167,5 +246,5 @@ See [ERROR_HANDLING.md](/docs/standards/ERROR_HANDLING.md) for the cross-cutting
 
 ---
 
-*Version: 1.0.0 | License: MIT*
+*License: MIT*
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/error-handler-core",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Core error handling functionality for OA Drive microservices - classification, retry, circuit breaker, DLQ routing",
   "oa": {
     "category": "connector"

package/src/ErrorClassifier.js

@@ -11,6 +11,13 @@ const ErrorTypes = {
   VALIDATION: 'VALIDATION',    // Input validation - DLQ
   TIMEOUT: 'TIMEOUT',          // Operation timeout - RETRY
   RATE_LIMIT: 'RATE_LIMIT',    // Rate limiting - RETRY with backoff
+  // A rule forbade the work. TERMINAL and NOT a failure: the caller asked for
+  // something the domain says must not happen — a document already sent, an
+  // item the source will not discuss — so there is nothing to retry and nothing
+  // to dead-letter. It is declared by the thrower through `error.type`, never
+  // derived from a status: every other 409 stays BUSINESS.
+  // @see api/docs/governance/confirmations/workflow-failed-status-projection.md 004
+  DECLINED: 'DECLINED',        // Refused by a rule - TERMINAL, no retry, no DLQ
   UNKNOWN: 'UNKNOWN'           // Unclassified - LOG and THROW
 };
 
@@ -22,6 +29,24 @@ const ErrorCodes = {
   ETIMEDOUT: ErrorTypes.TRANSIENT,
   ECONNRESET: ErrorTypes.TRANSIENT,
   EPIPE: ErrorTypes.TRANSIENT,
+
+  // The same family, measured on real sockets and missing from this table until d.774:
+  // `EAI_AGAIN` is the resolver saying "ask again" (node `dns`, `getaddrinfo`), and
+  // `ENETUNREACH` / `EHOSTUNREACH` are routing (node `net`). All three describe a peer
+  // that may be reachable on the next attempt, which is what TRANSIENT means here.
+  // Until d.774 they were not in the table at all, so they answered UNKNOWN and the
+  // delivery was NOT retried.
+  // Measured shapes: infra/api_delivery_dispatcher/tests/unit/transportErrorShapes.test.js
+  EAI_AGAIN: ErrorTypes.TRANSIENT,
+  ENETUNREACH: ErrorTypes.TRANSIENT,
+  EHOSTUNREACH: ErrorTypes.TRANSIENT,
+
+  // axios's own deadline (it aborts the request itself, so there is no `cause` and no
+  // syscall underneath) — and the most common real shape of a failed delivery. TIMEOUT
+  // is the category this table already has for "the deadline ran out"; UNKNOWN, which is
+  // what it answered until d.774, meant the message went to the DLQ without one retry.
+  ECONNABORTED: ErrorTypes.TIMEOUT,
+
   
   // HTTP status codes
   408: ErrorTypes.TIMEOUT,
@@ -33,8 +58,6 @@ const ErrorCodes = {
   
   // Circuit breaker refusal (CircuitOpenError) -> TRANSIENT: the state heals
   // itself once the breaker's resetTimeout elapses, so retrying is allowed.
-  // Pinned by code, never by message wording — the word "resetTimeout" in the
-  // fix hint would otherwise read as TIMEOUT via the patterns below.
   // @see api/docs/governance/confirmations/circuit-open-classification.md
   CIRCUIT_OPEN: ErrorTypes.TRANSIENT,
 
@@ -50,7 +73,25 @@ const ErrorCodes = {
 class ErrorClassifier {
   /**
    * Classify error into type for appropriate handling
-   * 
+   *
+   * A BUSINESS CODE THIS TABLE DOES NOT KNOW IS NEITHER LABELLED NOR REFUSED (d.804).
+   * A name it has never heard of — `REFERENCE_RECORD_MISSING`, say — misses the `code`
+   * lookup below and the class comes from the next thing the error declares: `type`,
+   * then `code`, then `status`. So an unknown name at `422` is `VALIDATION`, exactly
+   * like a bare `422`, and two different unknown names with one status get one class:
+   * the NAME is not read at all. `error.retryable` is not read here either — it belongs
+   * to the error contract and is consumed elsewhere
+   * (`ErrorMapper.CONTRACT_RETRYABLE_CODES`, the dispatcher's `_canRetry`).
+   *
+   * That is a rule, not a gap. The dictionary of business code NAMES is not this
+   * package's to own: it lives in `api/docs/biz/70-contracts/error-handling.md` §1
+   * (BIZ-DOCS, process `error-code-dictionary` 002). A name branch here would make the
+   * class depend on a dictionary this package cannot see — two owners of one fact
+   * (`change-discipline.md` § One rail per concern).
+   *
+   * @see ../README.md § A business code this table does not know
+   * @see ../tests/unit/business-code-outside-the-dictionary.test.js
+   *
    * @param {Error} error - Error to classify
    * @returns {string} Error type from ErrorTypes enum
    */
@@ -81,30 +122,18 @@ class ErrorClassifier {
       return ErrorCodes[error.status];
     }
     
-    // 4. Check message patterns
-    const message = (error.message || '').toLowerCase();
-    
-    if (message.includes('timeout')) {
-      return ErrorTypes.TIMEOUT;
-    }
-    
-    if (message.includes('rate limit') || message.includes('rate_limit')) {
-      return ErrorTypes.RATE_LIMIT;
-    }
-    
-    if (message.includes('validation') || message.includes('invalid')) {
-      return ErrorTypes.VALIDATION;
-    }
-    
-    if (message.includes('fatal') || message.includes('critical')) {
-      return ErrorTypes.FATAL;
-    }
-    
-    if (message.includes('connection') || message.includes('network') || message.includes('econn')) {
-      return ErrorTypes.TRANSIENT;
-    }
-    
-    // 5. Default
+    // 4. Nothing declared it. The message is NOT consulted: it is a human
+    // string the error contract does not classify by, and reading it was a
+    // second rail beside the table above (`change-discipline.md` § One rail per
+    // concern). Removed in d.761 after measuring every live producer — none
+    // reached it: `DeliveryDispatcher._canRetry` classifies a `{ status, code }`
+    // with no message at all, the orchestrator sends `type`/`status`/`code` and
+    // routes a failed publish around this classifier entirely, and
+    // `conn-infra-error-handler` only delegates. The one shape it did answer
+    // for was a service's own internal exception, which it mis-filed: a
+    // `TypeError` saying "invalid" became VALIDATION, and with it the log
+    // severity `warn` — a defect of our code filed as a warning about input.
+    // An unclassified error is UNKNOWN, and UNKNOWN is not retried.
     return ErrorTypes.UNKNOWN;
   }
   

package/src/ErrorHandlerCore.js

@@ -316,6 +316,14 @@ class ErrorHandlerCore {
       case ErrorTypes.FATAL:
         // Fatal errors, throw immediately
         return { type: 'throw' };
+
+      case ErrorTypes.DECLINED:
+        // A rule forbade the work: terminal, and neither a retry nor a failure.
+        // Its own verdict rather than `dlq`, because dead-lettering says "look at
+        // this", and there is nothing to look at — the refusal IS the outcome
+        // (conf `workflow-failed-status-projection` 004). Like `dlq`, this is a
+        // CLASSIFICATION returned to the caller; this class routes nothing.
+        return { type: 'declined' };
         
       default:
         // Unknown errors, log and throw

package/src/UnifiedLogSchema.js

@@ -25,6 +25,11 @@ const SEVERITY_BY_TYPE = {
   [ErrorTypes.VALIDATION]: 'warn',
   [ErrorTypes.TIMEOUT]: 'error',
   [ErrorTypes.RATE_LIMIT]: 'warn',
+  // Not an incident: a rule said no, and the run ended on that. `info` is the
+  // severity of a thing that happened as designed — filing it as `error` would
+  // put every refused send into the operator's error stream, which is the noise
+  // conf `workflow-failed-status-projection` 004 exists to remove.
+  [ErrorTypes.DECLINED]: 'info',
   [ErrorTypes.UNKNOWN]: 'error'
 };