comq 0.18.0 → 0.19.0

package/discussions/poison-message-handling.md

@@ -6,9 +6,8 @@
 > became shared and delay-named, the delay became configurable, and message provenance moved to
 > where it survives a retry.
 >
-> **Parts 1 and 2 are implemented.** Part 3 — the `Retry` / `Park` verdict API — is decided but
-> not yet scheduled; see the end. Text below is written as a proposal because that is what it
-> was; it describes what the code now does, except where Part 3 says otherwise.
+> **All three parts are implemented.** Text below is written as a proposal because that is what
+> it was; it describes what the code now does.
 
 When a consumer callback rejects, comq is supposed to retry the message a few times and then
 give up on it. What it actually does is kill the process, and take every other consumer in that
@@ -1111,10 +1110,15 @@ Nothing blocking. The three questions this document opened are resolved:
 - **The noun** — `Park` / `comq.parked.<queue>`. See Part 1.
 - **`Park` on an `io.reply` producer** — rejected as a category error, treated at runtime as a
   bare rejection plus a diagnostic. See Part 3.
-- **Whether Part 3 is built** — **decided, not yet scheduled.** Parts 1 and 2 are the emergency
-  and do not depend on it; a consumer of comq gets retry-then-park by upgrading and writing no
-  code. But the parking queue takes its noun from a verdict class that would not otherwise
-  exist, and without verdicts a message a contract has already refused costs every attempt —
-  two minutes at the event default — and then lands in the parking queue beside the
-  messages that genuinely failed. "Decided, not yet scheduled" rather than "open", because
-  people read this deciding whether to build on it.
+- **Whether Part 3 is built** — built. Parts 1 and 2 shipped first as the emergency, and a
+  consumer of comq got retry-then-park by upgrading and writing no code; the verdicts followed
+  as an additive minor.
+
+One thing the design did not settle, found while building it: it placed the `Park`-from-a-Producer
+rejection in `#failed`, which cannot implement it — `Channel` takes a topology but not its type
+([channel.js:64](../source/channel.js#L64)), so it cannot tell the request channel from the event
+one. It lives in `#getRequestConsumer` ([io.js:297](../source/io.js#L297)) instead, which knows by
+construction that it is wrapping a `Producer`. And rather than emit a diagnostic nobody may be
+subscribed to, it rethrows with an explanation, which reaches the parked message as its
+`x-comq-reason` and both existing diagnostics as their exception — louder, and no new event name
+to document.

package/docs/headers.md

@@ -28,6 +28,7 @@ the message properties.
 | `x-comq-key` | a retried or parked message | The routing key it was originally published with. |
 | `x-comq-queue` | a parked message | The queue it was consumed from. |
 | `x-comq-reason` | a parked message | The `message` of the exception that ended its attempts. |
+| `x-comq-cause` | a parked message | The `message` of that exception's `cause`, when it has one — a verdict is usually thrown with the failure that prompted it. |
 | `x-comq-at` | a parked message | When it was parked, as `Date.now()`. |
 
 `x-comq-exchange` and `x-comq-key` are recorded on the first failure rather than read at parking

package/features/events.poison.feature

@@ -40,3 +40,14 @@ Feature: Poison events
     When an event is emitted to the `poison_open` exchange
     And after 1000ms
     Then `bystander` has received 1 event
+
+  Scenario: A consumer refusing a message parks it at once
+
+    A `Park` says the consumer will never process this message, so climbing the
+    ladder would only delay the inevitable.
+
+    Given that events from the `poison_refused` exchange are refused as poison
+    When an event is emitted to the `poison_refused` exchange
+    Then the event is attempted 1 time
+    And the message is parked
+    And the parked message is kept, and says it came from the `poison_refused` exchange

package/features/steps/events.js

@@ -38,6 +38,21 @@ Given('(that )events are exclusively consumed from the {token} exchange',
     this.consumptionPromise = consume.call(this, undefined, exchange)
   })
 
+Given('(that )events from the {token} exchange are refused as poison',
+  /**
+   * @param {string} exchange
+   * @this {comq.features.Context}
+   */
+  async function (exchange) {
+    const { Park } = require('../../')
+
+    await this.io.consume(exchange, 'exceptions', (payload, properties) => {
+      this.attempts.push(properties.headers?.['x-comq-attempt'] ?? 1)
+
+      throw new Park('Expected refusal')
+    })
+  })
+
 Given('(that )events from the {token} exchange are causing exceptions',
   /**
    * @param {string} exchange

package/features/steps/poison.js

@@ -57,9 +57,10 @@ Then('the parked message is kept, and says it came from the {token} exchange',
     assert.equal(headers['x-comq-exchange'], exchange,
       `The parked message says it came from '${headers['x-comq-exchange']}'`)
 
+    // absent on a message parked from its first delivery, exactly as a consumer reads it;
     // derived rather than stated, so it cannot drift from the configured ladder
-    assert.equal(headers['x-comq-attempt'], this.attempts.length,
-      'The parked message was not retried to exhaustion')
+    assert.equal(headers['x-comq-attempt'] ?? 1, this.attempts.length,
+      'The parked message did not have as many attempts as the consumer saw')
   })
 
 Then('{token} has received {int} event(s)',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comq",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "ComQ",
   "author": {
     "name": "Artem Gurtovoi",

package/readme.md

@@ -515,6 +515,41 @@ One retry queue and one exchange are declared per distinct wait and shared by ev
 uses them, so their number grows with the length of the ladder rather than with the number of
 queues.
 
+#### Saying how it failed
+
+A consumer can classify its failure, which decides whether the message is worth another
+attempt at all:
+
+```javascript
+const { Retry, Park } = require('comq')
+
+await io.consume('orders', 'billing', async (order) => {
+  if (typeof order.total !== 'number') throw new Park('no total on order')
+
+  try {
+    await billing.charge(order)
+  } catch (e) {
+    throw new Retry('billing unavailable', { cause: e })
+  }
+})
+```
+
+- `Park` says this consumer will never process this message, however many times it is handed
+  over. It is [parked](#parked-messages) at once, without climbing the ladder.
+- `Retry` says whatever was missing may be back shortly. This is what an unclassified rejection
+  already means, so throwing it changes nothing but the reader's certainty.
+
+**A bare rejection means `Retry`** — a failure nobody classified is a failure nobody chose — so
+consumers written before this behave exactly as they did.
+
+Both are `Error`s and both take a `cause`, which is recorded on the parked message alongside the
+verdict's own message.
+
+> **`Park` is not applicable to a `Producer` given to [`IO.reply`](#reply).** A Request
+> has a caller awaiting a reply, so what happens to a failed one is not a policy choice. A `Park`
+> thrown there is treated as an ordinary failure — retried, then parked on the count — and the
+> parked message says so as its reason.
+
 #### Parked messages
 
 A message that has run out of attempts is published to `comq.parked.<queue>` and acknowledged

package/source/channel.js

@@ -2,6 +2,7 @@
 
 const { Promex } = require('promex')
 const { failsafe, lazy, recall } = require('./attributes')
+const { verdictOf, PARK } = require('./verdicts')
 const emitter = require('./emitter')
 
 /**
@@ -490,8 +491,11 @@ class Channel {
       // the header is which attempt this delivery is, and the first does not carry one
       const attempt = message.properties.headers?.[ATTEMPT_HEADER] ?? 1
 
-      // one rung per retry: a message that has climbed the ladder has nowhere left to wait
-      if (attempt > this.#delays.length) await this.#park(queue, message, exception)
+      // a consumer that says the message will never work is taken at its word; otherwise
+      // one rung per retry, and a message that has climbed the ladder has nowhere left to wait
+      const parking = verdictOf(exception) === PARK || attempt > this.#delays.length
+
+      if (parking) await this.#park(queue, message, exception)
       else await this.#retry(queue, message, attempt, exception)
     } catch {
       // the message could not be moved: give the delivery back rather than lose it
@@ -527,6 +531,9 @@ class Channel {
     const properties = this.#carry(message, {
       [PARKED_QUEUE_HEADER]: queue,
       [PARKED_REASON_HEADER]: exception?.message,
+      // a verdict is usually thrown with the exception that prompted it, and that one
+      // says what actually went wrong
+      [PARKED_CAUSE_HEADER]: exception?.cause?.message,
       [PARKED_AT_HEADER]: Date.now()
     })
 
@@ -659,6 +666,7 @@ const ORIGIN_EXCHANGE_HEADER = 'x-comq-exchange'
 const ORIGIN_KEY_HEADER = 'x-comq-key'
 const PARKED_QUEUE_HEADER = 'x-comq-queue'
 const PARKED_REASON_HEADER = 'x-comq-reason'
+const PARKED_CAUSE_HEADER = 'x-comq-cause'
 const PARKED_AT_HEADER = 'x-comq-at'
 
 function noop () {}

package/source/index.js

@@ -1,6 +1,10 @@
 'use strict'
 
 const { connect, assert } = require('./connect')
+const { Retry, Park } = require('./verdicts')
 
 exports.connect = connect
 exports.assert = assert
+
+exports.Retry = Retry
+exports.Park = Park

package/source/io.js

@@ -4,6 +4,7 @@ const stream = require('node:stream')
 const { setTimeout } = require('node:timers/promises')
 const { Promex } = require('promex')
 const { memo, failsafe, lazy, track } = require('./attributes')
+const { verdictOf, PARK } = require('./verdicts')
 
 const { decode } = require('./decode')
 const { encode } = require('./encode')
@@ -302,7 +303,7 @@ class IO {
        */
       async (request) => {
         const payload = decode(request)
-        const reply = await producer(payload)
+        const reply = await produce(producer, payload)
 
         if (request.properties.replyTo === undefined) return
 
@@ -549,4 +550,29 @@ const DEFAULT = 'application/json'
 
 const RETRANSMISSION = /** @type {Error} */ Symbol('retransmission')
 
+/**
+ * A verdict answers what should happen to a message now that it has failed and nobody
+ * is waiting for it. A Producer has a caller waiting, and what it is owed is a reply,
+ * so `Park` is a category error there rather than a policy choice — comq's own type
+ * vocabulary already draws the line between a Consumer and a Producer.
+ *
+ * It cannot be caught at wiring time, since nothing there knows what a producer will
+ * throw. Caught here instead and re-thrown as an ordinary rejection, which retries and
+ * eventually parks, carrying an explanation the parked message keeps as its reason.
+ *
+ * @param {comq.Producer} producer
+ * @param {any} payload
+ */
+async function produce (producer, payload) {
+  try {
+    return await producer(payload)
+  } catch (exception) {
+    if (verdictOf(exception) !== PARK) throw exception
+
+    throw new Error('Park is not applicable to a reply producer: a Request has a caller ' +
+      'awaiting a reply, so it is retried and parked on the count like any other failure',
+    { cause: exception })
+  }
+}
+
 exports.IO = IO

package/source/verdicts.js

@@ -0,0 +1,54 @@
+'use strict'
+
+/**
+ * How a consumer says what should happen to a message it could not handle.
+ *
+ * The brand is a registered symbol rather than the class identity: comq is a library,
+ * and a dependency that pins it while the application resolves its own tree makes two
+ * copies of it the ordinary outcome. `instanceof` is silently `false` across those,
+ * which would read a `Park` as an unclassified rejection and retry it to exhaustion
+ * before parking it anyway. The global symbol registry is shared; a class is not.
+ */
+const VERDICT = Symbol.for('comq.verdict')
+
+const RETRY = 'retry'
+const PARK = 'park'
+
+/**
+ * Whatever the consumer needed was briefly not there. This is what an unclassified
+ * rejection already means, so throwing it changes nothing but the reader's certainty.
+ */
+class Retry extends Error {
+  [VERDICT] = RETRY
+
+  name = 'Retry'
+}
+
+/**
+ * This consumer will never process this message, however many times it is handed over.
+ * The message is kept rather than retried.
+ */
+class Park extends Error {
+  [VERDICT] = PARK
+
+  name = 'Park'
+}
+
+/**
+ * A rejection nobody classified is a rejection nobody chose: it means Retry.
+ *
+ * @param {any} exception
+ * @returns {'retry' | 'park'}
+ */
+const verdictOf = (exception) => {
+  const verdict = exception?.[VERDICT]
+
+  return verdict === PARK || verdict === RETRY ? verdict : RETRY
+}
+
+exports.Retry = Retry
+exports.Park = Park
+exports.verdictOf = verdictOf
+exports.VERDICT = VERDICT
+exports.RETRY = RETRY
+exports.PARK = PARK

package/test/channel.test.js

@@ -10,6 +10,7 @@ const backpressure = require('./backpressure')
 const { amqplib } = require('./amqplib.mock')
 const fixtures = require('./channel.fixtures')
 const { create } = require('../source/channel')
+const { Retry, Park } = require('../source/verdicts')
 
 it('should be', async () => {
   expect(create).toBeDefined()
@@ -1584,6 +1585,109 @@ describe('failed messages', () => {
     })
   })
 
+  describe('verdicts', () => {
+    it('should park on the first delivery when the consumer says to', async () => {
+      await channel.consume(queue, consumer)
+
+      consumer.mockImplementationOnce(async () => { throw new Park(generate()) })
+
+      await deliver(delivery({}))
+
+      const [exchange, key] = publications()[0]
+
+      expect(exchange).toStrictEqual('')
+      expect(key).toStrictEqual('comq.parked.' + queue)
+      expect(publications()).toHaveLength(1)
+    })
+
+    it('should not retry a parked message even with the ladder untouched', async () => {
+      await channel.consume(queue, consumer)
+
+      consumer.mockImplementationOnce(async () => { throw new Park(generate()) })
+
+      await deliver(delivery({}))
+
+      const [, , , options] = publications()[0]
+
+      // parked on the first delivery, so it never climbed a rung
+      expect(options.headers['x-comq-attempt']).toBeUndefined()
+    })
+
+    it('should treat Retry exactly as a bare rejection', async () => {
+      await channel.consume(queue, consumer)
+
+      consumer.mockImplementationOnce(async () => { throw new Retry(generate()) })
+
+      await deliver(delivery({}))
+
+      const [exchange] = publications()[0]
+
+      expect(exchange).toStrictEqual('comq.retry.' + DELAY)
+    })
+
+    it('should record the verdict message as the reason', async () => {
+      await channel.consume(queue, consumer)
+
+      const reason = generate()
+
+      consumer.mockImplementationOnce(async () => { throw new Park(reason) })
+
+      await deliver(delivery({}))
+
+      const [, , , options] = publications()[0]
+
+      expect(options.headers['x-comq-reason']).toStrictEqual(reason)
+    })
+
+    it('should record the cause alongside the reason', async () => {
+      await channel.consume(queue, consumer)
+
+      const reason = generate()
+      const cause = new Error(generate())
+
+      consumer.mockImplementationOnce(async () => { throw new Park(reason, { cause }) })
+
+      await deliver(delivery({}))
+
+      const [, , , options] = publications()[0]
+
+      expect(options.headers['x-comq-reason']).toStrictEqual(reason)
+      expect(options.headers['x-comq-cause']).toStrictEqual(cause.message)
+    })
+
+    it('should emit `discard` for a parked verdict', async () => {
+      const listener = jest.fn()
+
+      channel.diagnose('discard', listener)
+
+      await channel.consume(queue, consumer)
+
+      const park = new Park(generate())
+
+      consumer.mockImplementationOnce(async () => { throw park })
+
+      const message = delivery({})
+
+      await deliver(message)
+
+      expect(listener).toHaveBeenCalledWith(message, park)
+    })
+
+    it('should honour a Park thrown by another copy of comq', async () => {
+      await channel.consume(queue, consumer)
+
+      const foreign = new Error(generate())
+
+      foreign[Symbol.for('comq.verdict')] = 'park'
+
+      consumer.mockImplementationOnce(async () => { throw foreign })
+
+      await deliver(delivery({}))
+
+      expect(publications()[0][1]).toStrictEqual('comq.parked.' + queue)
+    })
+  })
+
   describe('when the message cannot be moved', () => {
     it('should give the delivery back', async () => {
       await channel.consume(queue, consumer)

package/test/io.reply.test.js

@@ -10,6 +10,7 @@ const mock = require('./connection.mock')
 const { encodings } = require('./encodings')
 
 const { IO } = require('../source/io')
+const { Retry, Park } = require('../source/verdicts')
 
 /** @type {comq.IO} */
 let io
@@ -240,3 +241,68 @@ const findChannel = (type) => {
 
   return connection.createChannel.mock.results[index].value
 }
+
+describe('verdicts', () => {
+  /** @type {jest.MockedObject<comq.Channel>} */
+  let requests
+
+  const message = () => /** @type {comq.amqp.Message} */ ({
+    content: randomBytes(10),
+    properties: { replyTo: generate(), contentType: 'text/plain' }
+  })
+
+  const findChannel = async (type) => {
+    const index = connection.createChannel.mock.calls.findIndex(([argument]) => argument === type)
+
+    return await connection.createChannel.mock.results[index].value
+  }
+
+  beforeEach(async () => {
+    await io.reply(queue, produce)
+
+    requests = await findChannel('request')
+  })
+
+  it('should refuse Park from a producer', async () => {
+    // a Request has a caller awaiting a reply, so a verdict is a category error there
+    const park = new Park(generate())
+
+    produce.mockImplementationOnce(async () => { throw park })
+
+    const consumer = requests.consume.mock.calls[0][1]
+
+    await expect(consumer(message())).rejects.toThrow(/not applicable to a reply producer/)
+  })
+
+  it('should keep the Park as the cause of what it throws instead', async () => {
+    const park = new Park(generate())
+
+    produce.mockImplementationOnce(async () => { throw park })
+
+    const consumer = requests.consume.mock.calls[0][1]
+    const exception = await consumer(message()).catch((error) => error)
+
+    // the explanation reaches the parked message as its reason, and this as its cause
+    expect(exception.cause).toStrictEqual(park)
+  })
+
+  it('should pass an ordinary rejection through untouched', async () => {
+    const failure = new Error(generate())
+
+    produce.mockImplementationOnce(async () => { throw failure })
+
+    const consumer = requests.consume.mock.calls[0][1]
+
+    await expect(consumer(message())).rejects.toStrictEqual(failure)
+  })
+
+  it('should pass Retry through untouched', async () => {
+    const retry = new Retry(generate())
+
+    produce.mockImplementationOnce(async () => { throw retry })
+
+    const consumer = requests.consume.mock.calls[0][1]
+
+    await expect(consumer(message())).rejects.toStrictEqual(retry)
+  })
+})

package/test/verdicts.test.js

@@ -0,0 +1,57 @@
+'use strict'
+
+const { generate } = require('randomstring')
+const { Retry, Park, verdictOf, RETRY, PARK, VERDICT } = require('../source/verdicts')
+
+it('should be', async () => {
+  expect(Retry).toBeDefined()
+  expect(Park).toBeDefined()
+})
+
+describe('verdictOf', () => {
+  it.each([
+    ['undefined', undefined],
+    ['null', null],
+    ['a string', 'nope'],
+    ['a plain Error', new Error(generate())],
+    ['an object branded with something else', { [Symbol.for('other.verdict')]: 'park' }],
+    ['an object whose brand is not a verdict', { [VERDICT]: generate() }]
+  ])('should read %s as a retry', async (_, exception) => {
+    expect(verdictOf(exception)).toStrictEqual(RETRY)
+  })
+
+  it('should read Retry as a retry', async () => {
+    expect(verdictOf(new Retry(generate()))).toStrictEqual(RETRY)
+  })
+
+  it('should read Park as a park', async () => {
+    expect(verdictOf(new Park(generate()))).toStrictEqual(PARK)
+  })
+
+  it('should read a Park thrown by another copy of comq', async () => {
+    // a dependency pinning comq while the application resolves its own tree makes two
+    // copies the ordinary outcome, and `instanceof` is silently false across them
+    const foreign = { [Symbol.for('comq.verdict')]: 'park' }
+
+    expect(verdictOf(foreign)).toStrictEqual(PARK)
+    expect(foreign instanceof Park).toStrictEqual(false)
+  })
+})
+
+describe('the classes', () => {
+  it.each([['Retry', Retry], ['Park', Park]])('should make %s an Error', async (name, Verdict) => {
+    const message = generate()
+    const verdict = new Verdict(message)
+
+    expect(verdict).toBeInstanceOf(Error)
+    expect(verdict.message).toStrictEqual(message)
+    expect(verdict.name).toStrictEqual(name)
+    expect(typeof verdict.stack).toStrictEqual('string')
+  })
+
+  it.each([['Retry', Retry], ['Park', Park]])('should let %s carry a cause', async (_, Verdict) => {
+    const cause = new Error(generate())
+
+    expect(new Verdict(generate(), { cause }).cause).toStrictEqual(cause)
+  })
+})

package/types/index.d.ts

@@ -4,3 +4,20 @@ export type { IO, Consumer, Producer } from './io'
 
 export const connect: Connect
 export const assert: Connect
+
+/**
+ * Thrown by a consumer to say that whatever it needed was briefly not there. This is
+ * what an unclassified rejection already means, so throwing it changes nothing but the
+ * reader's certainty.
+ */
+export class Retry extends Error {}
+
+/**
+ * Thrown by a consumer to say that it will never process this message, however many
+ * times it is handed over. The message is kept rather than retried.
+ *
+ * Not applicable to a `Producer` given to `IO.reply`: a Request has a caller awaiting a
+ * reply, so a verdict is a category error there and the message is retried and parked on
+ * the count like any other failure.
+ */
+export class Park extends Error {}