comq 0.18.0 → 0.20.0

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/connection.mock.js

@@ -10,6 +10,7 @@ const channel = /** @type {jest.MockedFunction<(sharded?: boolean, index?: numbe
     fire: jest.fn(async () => undefined),
     subscribe: jest.fn(async () => undefined),
     bound: jest.fn(async () => undefined),
+    held: jest.fn(async () => undefined),
     publish: jest.fn(async () => undefined),
     route: jest.fn(async () => undefined),
     diagnose: jest.fn(async () => undefined),

package/test/io.call.test.js

@@ -0,0 +1,161 @@
+'use strict'
+
+// region setup
+
+const { randomBytes } = require('node:crypto')
+const { generate } = require('randomstring')
+const { immediate } = require('./helpers')
+const { encode } = require('../source/encode')
+const { Unroutable } = require('../source/unroutable')
+
+const mock = require('./connection.mock')
+const { IO } = require('../source/io')
+
+/** @type {comq.IO} */
+let io
+
+/** @type {jest.MockedObject<comq.Connection>} */
+let connection
+
+/** @type {jest.MockedObject<comq.Channel>} */
+let requests
+
+/** @type {jest.MockedObject<comq.Channel>} */
+let replies
+
+const exchange = generate()
+const key = generate()
+const payload = { [generate()]: generate() }
+
+beforeEach(async () => {
+  jest.clearAllMocks()
+
+  connection = mock.connection()
+  io = new IO(connection)
+})
+
+// endregion
+
+describe('call', () => {
+  /** @type {Promise<any>} */
+  let promise
+
+  beforeEach(async () => {
+    promise = io.call(exchange, key, payload)
+
+    // allows initializers to run
+    await immediate()
+
+    requests = await findChannel('request')
+    replies = await findChannel('reply')
+  })
+
+  it('should publish to the exchange under the key', async () => {
+    expect(requests.route).toHaveBeenCalledWith(exchange, key, expect.any(Buffer),
+      expect.objectContaining({ mandatory: true }))
+  })
+
+  it('should declare no queue to publish to', async () => {
+    expect(requests.send).not.toHaveBeenCalled()
+  })
+
+  it('should consume the queue it is answered to', async () => {
+    const properties = requests.route.mock.calls[0][3]
+
+    expect(replies.consume).toHaveBeenCalledWith(properties.replyTo, expect.any(Function))
+  })
+
+  it('should resolve with the reply', async () => {
+    const content = randomBytes(8)
+    const { correlationId } = requests.route.mock.calls[0][3]
+    const deliver = replies.consume.mock.calls[0][1]
+
+    await deliver({ content, properties: { correlationId } })
+
+    await expect(promise).resolves.toStrictEqual(content)
+  })
+
+  it('should reject with Unroutable once the broker returns it', async () => {
+    const properties = requests.route.mock.calls[0][3]
+
+    emit(requests, 'return', { content: randomBytes(8), fields: { exchange, routingKey: key }, properties })
+
+    await expect(promise).rejects.toBeInstanceOf(Unroutable)
+    await expect(promise).rejects.toMatchObject({ exchange, key })
+  })
+
+  it('should leave it waiting when another Request is returned', async () => {
+    const settled = jest.fn()
+    const properties = { ...requests.route.mock.calls[0][3], correlationId: generate() }
+
+    promise.then(settled, settled)
+
+    emit(requests, 'return', { content: randomBytes(8), fields: { exchange, routingKey: key }, properties })
+
+    await immediate()
+
+    expect(settled).not.toHaveBeenCalled()
+  })
+})
+
+describe('timeout', () => {
+  it('should stop waiting while the channels are being created', async () => {
+    connection.createChannel.mockImplementation(() => new Promise(() => undefined))
+
+    const promise = io.call(exchange, key, payload, { timeout: 20 })
+
+    await expect(promise).rejects.toMatchObject({ name: 'TimeoutError' })
+  })
+})
+
+describe('back', () => {
+  const producer = jest.fn(() => generate())
+
+  beforeEach(async () => {
+    await io.back(exchange, key, producer)
+
+    requests = await findChannel('request')
+  })
+
+  it('should hold a queue named after the exchange and the key', async () => {
+    expect(requests.held).toHaveBeenCalledWith(exchange, `${exchange}.${key}`, key, expect.any(Function))
+  })
+
+  it('should answer a Request', async () => {
+    const consumer = requests.held.mock.calls[0][3]
+    const contentType = 'application/json'
+    const properties = { contentType, correlationId: generate(), replyTo: generate() }
+
+    await consumer({ content: encode(payload, contentType), properties })
+
+    replies = await findChannel('reply')
+
+    expect(producer).toHaveBeenCalledWith(payload)
+
+    expect(replies.fire).toHaveBeenCalledWith(properties.replyTo, expect.any(Buffer),
+      expect.objectContaining({ correlationId: properties.correlationId }))
+  })
+})
+
+/**
+ * @param {comq.topology.type} type
+ * @returns {jest.MockedObject<comq.Channel>}
+ */
+const findChannel = (type) => {
+  const index = connection.createChannel.mock.calls.findIndex(([t]) => (t === type))
+
+  if (index === -1) throw new Error(`${type} channel hasn't been created`)
+
+  return connection.createChannel.mock.results[index].value
+}
+
+/**
+ * @param {jest.MockedObject<comq.Channel>} channel
+ * @param {string} event
+ * @param {...any} args
+ */
+function emit (channel, event, ...args) {
+  for (const [name, listener] of channel.diagnose.mock.calls) {
+    if (name === event) listener(...args)
+  }
+}

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/io.request.terms.test.js

@@ -0,0 +1,247 @@
+'use strict'
+
+// region setup
+
+const { randomBytes } = require('node:crypto')
+const { generate } = require('randomstring')
+const { immediate, timeout } = require('./helpers')
+
+const mock = require('./connection.mock')
+const { IO } = require('../source/io')
+
+/** @type {comq.IO} */
+let io
+
+/** @type {jest.MockedObject<comq.Connection>} */
+let connection
+
+/** @type {jest.MockedObject<comq.Channel>} */
+let requests
+
+/** @type {jest.MockedObject<comq.Channel>} */
+let replies
+
+const queue = generate()
+const payload = { [generate()]: generate() }
+
+beforeEach(async () => {
+  jest.clearAllMocks()
+
+  connection = mock.connection()
+  io = new IO(connection)
+})
+
+// endregion
+
+describe('timeout', () => {
+  it('should expire the Request when the caller stops waiting', async () => {
+    io.request(queue, payload, { timeout: 10000 }).catch(noop)
+
+    await initialized()
+
+    const expiration = Number(requests.send.mock.calls[0][2].expiration)
+
+    expect(expiration).toBeGreaterThan(9000)
+    expect(expiration).toBeLessThanOrEqual(10000)
+  })
+
+  it('should keep the encoding', async () => {
+    const encoding = 'application/octet-stream'
+
+    io.request(queue, randomBytes(8), { encoding, timeout: 10000 }).catch(noop)
+
+    await initialized()
+
+    expect(requests.send.mock.calls[0][2].contentType).toStrictEqual(encoding)
+  })
+
+  it('should stop waiting while the channels are being created', async () => {
+    connection.createChannel.mockImplementation(() => new Promise(noop))
+
+    const promise = io.request(queue, payload, { timeout: 20 })
+
+    await expect(promise).rejects.toMatchObject({ name: 'TimeoutError' })
+  })
+
+  it('should reject once it has passed', async () => {
+    const promise = io.request(queue, payload, { timeout: 20 })
+
+    await expect(promise).rejects.toMatchObject({ name: 'TimeoutError' })
+  })
+
+  it('should resolve with a reply that arrives in time', async () => {
+    const promise = io.request(queue, payload, { timeout: 10000 })
+    const content = randomBytes(8)
+
+    await initialized()
+    await answer(0, content)
+
+    await expect(promise).resolves.toStrictEqual(content)
+  })
+
+  it('should re-send with the time that is left', async () => {
+    io.request(queue, payload, { timeout: 10000 }).catch(noop)
+
+    await initialized()
+    await timeout(20)
+
+    emit(requests, 'recover')
+
+    await immediate()
+
+    expect(requests.send).toHaveBeenCalledTimes(2)
+
+    const first = Number(requests.send.mock.calls[0][2].expiration)
+    const second = Number(requests.send.mock.calls[1][2].expiration)
+
+    expect(second).toBeLessThan(first)
+  })
+})
+
+describe('signal', () => {
+  it('should reject with the reason it was aborted for', async () => {
+    const controller = new AbortController()
+    const reason = new Error(generate())
+    const promise = io.request(queue, payload, { signal: controller.signal })
+
+    await initialized()
+
+    controller.abort(reason)
+
+    await expect(promise).rejects.toBe(reason)
+  })
+
+  it('should leave the Request in its queue', async () => {
+    const controller = new AbortController()
+
+    io.request(queue, payload, { signal: controller.signal }).catch(noop)
+
+    await initialized()
+
+    expect(requests.send.mock.calls[0][2].expiration).toBeUndefined()
+  })
+
+  it('should reject at once when aborted before the channels exist', async () => {
+    connection.createChannel.mockImplementation(() => new Promise(noop))
+
+    const controller = new AbortController()
+    const reason = new Error(generate())
+
+    controller.abort(reason)
+
+    await expect(io.request(queue, payload, { signal: controller.signal })).rejects.toBe(reason)
+  })
+
+  it('should send nothing once aborted', async () => {
+    const controller = new AbortController()
+
+    // the channels exist before the aborted Request is made
+    io.request(queue, payload).catch(noop)
+
+    await initialized()
+
+    controller.abort()
+
+    await expect(io.request(queue, payload, { signal: controller.signal })).rejects.toBeDefined()
+
+    expect(requests.send).toHaveBeenCalledTimes(1)
+  })
+
+  it('should not re-send what it abandoned', async () => {
+    const controller = new AbortController()
+    const promise = io.request(queue, payload, { signal: controller.signal })
+
+    await initialized()
+
+    controller.abort()
+
+    await promise.catch(noop)
+
+    emit(requests, 'recover')
+
+    await immediate()
+
+    expect(requests.send).toHaveBeenCalledTimes(1)
+  })
+
+  it('should stop waiting for a publication', async () => {
+    io.request(queue, payload).catch(noop)
+
+    await initialized()
+
+    requests.send.mockImplementationOnce(() => new Promise(noop))
+
+    const controller = new AbortController()
+    const reason = new Error(generate())
+    const promise = io.request(queue, payload, { signal: controller.signal })
+
+    await immediate()
+
+    controller.abort(reason)
+
+    await expect(promise).rejects.toBe(reason)
+  })
+
+  it('should discard a reply that arrives afterwards', async () => {
+    const controller = new AbortController()
+    const promise = io.request(queue, payload, { signal: controller.signal })
+
+    await initialized()
+
+    controller.abort()
+
+    await promise.catch(noop)
+
+    await expect(answer(0)).resolves.toBeUndefined()
+  })
+
+  it('should end the wait within the timeout', async () => {
+    const controller = new AbortController()
+    const promise = io.request(queue, payload, { signal: controller.signal, timeout: 20 })
+
+    await expect(promise).rejects.toMatchObject({ name: 'TimeoutError' })
+  })
+})
+
+async function initialized () {
+  // allows initializers to run
+  await immediate()
+
+  requests = await findChannel('request')
+  replies = await findChannel('reply')
+}
+
+/**
+ * @param {number} index of the publication answered
+ * @param {Buffer} [content]
+ */
+async function answer (index, content = randomBytes(8)) {
+  const { correlationId } = requests.send.mock.calls[index][2]
+  const deliver = replies.consume.mock.calls[0][1]
+
+  await deliver({ content, properties: { correlationId } })
+}
+
+/**
+ * @param {comq.topology.type} type
+ * @returns {jest.MockedObject<comq.Channel>}
+ */
+const findChannel = (type) => {
+  const index = connection.createChannel.mock.calls.findIndex(([t]) => (t === type))
+
+  if (index === -1) throw new Error(`${type} channel hasn't been created`)
+
+  return connection.createChannel.mock.results[index].value
+}
+
+/**
+ * @param {jest.MockedObject<comq.Channel>} channel
+ * @param {string} event
+ */
+function emit (channel, event) {
+  for (const [name, listener] of channel.diagnose.mock.calls) {
+    if (name === event) listener()
+  }
+}
+
+function noop () {}

package/test/shards/channel.test.js

@@ -569,6 +569,74 @@ describe('diagnose', () => {
     expect(listener).toHaveBeenCalledWith(message, index)
   })
 
+  it('should re-route a returned Request under a key on another shard', async () => {
+    const listener = /** @type {jest.MockedFunction} */ jest.fn()
+    const index = random(channels.length)
+    const chan = channels[index]
+    const message = returned()
+
+    message.fields.exchange = generate()
+    channel.diagnose('return', listener)
+
+    emitReturn(chan, message)
+
+    const rest = channels.filter((one) => one !== chan)
+
+    const properties = expect.objectContaining(
+      { mandatory: true, headers: { 'x-return': 1 } })
+
+    for (const one of rest) {
+      expect(one.route).toHaveBeenCalledWith(message.fields.exchange, message.fields.routingKey,
+        message.content, properties)
+    }
+
+    expect(listener).not.toHaveBeenCalled()
+  })
+
+  it('should report a returned retry at once', async () => {
+    const listener = /** @type {jest.MockedFunction} */ jest.fn()
+    const index = random(channels.length)
+    const chan = channels[index]
+    const message = returned()
+
+    message.fields.exchange = 'comq.retry.' + random(10000)
+    channel.diagnose('return', listener)
+
+    emitReturn(chan, message)
+
+    for (const one of channels) {
+      expect(one.fire).not.toHaveBeenCalled()
+      expect(one.route).not.toHaveBeenCalled()
+    }
+
+    expect(listener).toHaveBeenCalledWith(message, index)
+  })
+
+  it('should hold a queue on every shard', async () => {
+    const exchange = generate()
+    const queue = generate()
+    const key = generate()
+    const consumer = jest.fn()
+
+    await channel.held(exchange, queue, key, consumer)
+
+    for (const one of channels) expect(one.held).toHaveBeenCalledWith(exchange, queue, key, consumer)
+  })
+
+  it('should hold a queue once any shard holds it', async () => {
+    const [, ...rest] = channels
+
+    for (const one of rest) one.held.mockImplementationOnce(() => new Promise(() => undefined))
+
+    await expect(channel.held(generate(), generate(), generate(), jest.fn())).resolves.toBeUndefined()
+  })
+
+  it('should reject when every shard refuses to hold a queue', async () => {
+    for (const one of channels) one.held.mockImplementationOnce(async () => { throw new Error('refused') })
+
+    await expect(channel.held(generate(), generate(), generate(), jest.fn())).rejects.toBeInstanceOf(AggregateError)
+  })
+
   it('should emit `pause` and `unpause` events', async () => {
     const queue = generate()
     const buffer = randomBytes(8)