@onlineapps/mq-client-core 2.0.1 → 3.0.0

package/src/config/deliveryPolicy.js

@@ -0,0 +1,165 @@
+'use strict';
+
+/**
+ * deliveryPolicy.js — the dead-letter policy of `consume()`, declared in one place.
+ *
+ * The policy is the SINGLE rail for every consumer, business and infrastructure
+ * alike (`api/docs/governance/confirmations/mq-consumer-contract.md` 001 and 002
+ * point 3). It answers one question: a handler threw — what happens to the
+ * message?
+ *
+ *   transient error, attempts left  → one more attempt
+ *   transient error, budget spent   → rejected into `<svc>.dlq`
+ *   permanent error                 → rejected into `<svc>.dlq` on the first failure
+ *
+ * ## Why the counter is a header we write, and why an attempt costs a re-publish
+ *
+ * Measured on the live broker (`api_services_queuer`, 2026-09-11):
+ *
+ * | move | what the next delivery carries |
+ * |---|---|
+ * | `nack(requeue=true)` | `headers: {}` — nothing. `fields.redelivered` flips to `true`, which is a boolean, not a count. A requeue is NOT a dead-letter, so the broker stamps no `x-death`. |
+ * | `nack(requeue=false)` | the broker dead-letters and stamps `x-death[0] = { count: 1, reason: 'rejected', queue: <origin>, … }` |
+ *
+ * So `x-death` cannot count attempts: it only ever appears once the message has
+ * already left the queue for good. And a requeue returns the message
+ * byte-for-byte, headers included, so a requeued message cannot carry a counter
+ * either. The only way to advance one is to publish a NEW copy carrying it —
+ * publish the copy first, ack the original second, so a failed publish can never
+ * lose the message.
+ *
+ * ## The header name
+ *
+ * `x-oa-delivery-attempts`, not the `x-retry-count` of the retired
+ * `conn-infra-mq` retry layer: that name counted retries (0-based) on a rail
+ * nothing ever called, and reusing it would make two different countings share
+ * one name. `x-` is the AMQP custom-header space; `oa` says who writes it;
+ * `delivery-attempts` says which attempts are counted — this package also
+ * retries PUBLISHES (`layers/PublishLayer.js`), and a bare `x-oa-attempts`
+ * could not tell the two apart.
+ *
+ * ## What a caller may ask for, and where it is refused
+ *
+ * `maxAttempts` is the number of times the handler may run for ONE message —
+ * the same reading as `maxRetries` in `@onlineapps/error-handler-core`
+ * (`src/RetryHandler.js`, "Max attempts; integer >= 1"). After the
+ * `maxAttempts`-th failure the message is rejected into the dead-letter queue,
+ * so `maxAttempts: 1` means "no second attempt".
+ *
+ * An explicit value is validated exactly as written — never coerced, so a `'3'`
+ * or a `2.5` is refused instead of being silently turned into 3 or 2. Only the
+ * environment form goes through numeric coercion, because an environment
+ * variable has no other shape (`../config.js`, `../defaults.js`).
+ *
+ * Both refusals are raised at the throw site itself
+ * (`transports/rabbitmqClient.js` `consume()`), not here: a message this library
+ * hands a caller must open with the context that produced it
+ * (`architecture-principles.md` §5), and a context passed in as a parameter is
+ * invisible to the guard that checks that
+ * (`tests/unit/error-message-contract.test.js`).
+ *
+ * @see ../../README.md § consume() — the delivery contract
+ */
+
+/** Header carrying how many attempts a message has already cost. Never a literal elsewhere. */
+const ATTEMPTS_HEADER = 'x-oa-delivery-attempts';
+
+/** The error is worth another attempt. */
+const TRANSIENT = 'transient';
+
+/** The error will fail identically on every attempt — more attempts only delay the dead-letter. */
+const PERMANENT = 'permanent';
+
+/**
+ * Not a value a classifier may return: the classification recorded when the
+ * caller's classifier threw or answered with something that is neither
+ * `transient` nor `permanent`, and when the attempts header holds a value this
+ * library did not write. In both cases the message CANNOT be bounded, so it is
+ * rejected into the dead-letter queue rather than retried on a guess.
+ */
+const UNCLASSIFIABLE = 'unclassifiable';
+
+const CLASSIFICATIONS = Object.freeze([TRANSIENT, PERMANENT]);
+
+/**
+ * The classification used when the caller injects no classifier.
+ *
+ * Declared here, as a named module-owned decision with one owner, rather than
+ * as an inline `||` in the consume path — the shape `architecture-principles.md`
+ * §3 bans. What it means is stated, not implied: **without a classifier every
+ * error is treated as worth another attempt**, so a permanently failing message
+ * still reaches `<svc>.dlq`, after `maxAttempts` attempts instead of after one.
+ * The outcome is therefore bounded either way; a classifier only makes it
+ * faster and cheaper.
+ *
+ * The alternative — making `classify` required — was rejected on evidence: the
+ * eleven consumer paths measured for d.198 have no classifier of their own, so
+ * a required parameter would be satisfied at eleven call sites by copies of
+ * this very function (`change-discipline.md` § One rail per concern).
+ *
+ * @returns {'transient'}
+ */
+function defaultClassification() {
+  return TRANSIENT;
+}
+
+/**
+ * How many attempts this message has already cost, read from its header.
+ *
+ * @param {Object} [headers] - `msg.properties.headers`.
+ * @returns {number|null} The count, `0` when the header is absent (first
+ *   delivery), and `null` when the header holds a value this library never
+ *   wrote — which the caller must treat as "cannot be bounded", never as zero:
+ *   a counter reset on a malformed value is a counter an attacker or a bug can
+ *   disable, and the redelivery loop is then unbounded again.
+ */
+function readAttemptsMade(headers) {
+  if (!headers || headers[ATTEMPTS_HEADER] === undefined || headers[ATTEMPTS_HEADER] === null) {
+    return 0;
+  }
+
+  const value = headers[ATTEMPTS_HEADER];
+
+  if (!Number.isInteger(value) || value < 0) {
+    return null;
+  }
+
+  return value;
+}
+
+/**
+ * Apply the caller's classifier to one error, and say plainly when it cannot be
+ * trusted. The library never guesses a classification: an unusable answer is
+ * reported as `unclassifiable`, and an unclassifiable message is dead-lettered.
+ *
+ * @param {function(Error): string} classify
+ * @param {Error} error
+ * @returns {{classification: string, failure: (Error|string|null)}} `failure` names
+ *   why the classifier's answer was refused, for the caller to log; `null` when it held.
+ */
+function classifyError(classify, error) {
+  let answer;
+
+  try {
+    answer = classify(error);
+  } catch (classifyErr) {
+    return { classification: UNCLASSIFIABLE, failure: classifyErr };
+  }
+
+  if (!CLASSIFICATIONS.includes(answer)) {
+    return { classification: UNCLASSIFIABLE, failure: `returned ${JSON.stringify(answer)}` };
+  }
+
+  return { classification: answer, failure: null };
+}
+
+module.exports = {
+  ATTEMPTS_HEADER,
+  TRANSIENT,
+  PERMANENT,
+  UNCLASSIFIABLE,
+  CLASSIFICATIONS,
+  defaultClassification,
+  readAttemptsMade,
+  classifyError,
+};