comq 0.19.0 → 0.20.1

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.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)

package/types/channel.d.ts

@@ -22,6 +22,9 @@ declare namespace comq {
     /** consumes `queue`, bound to a routed `exchange` under `key` */
     bound (exchange: string, queue: string, key: string, consumer: channels.Consumer): Promise<void>
 
+    /** consumes `queue`, exclusive to this connection and bound to a routed `exchange` under `key` */
+    held (exchange: string, queue: string, key: string, consumer: channels.Consumer): Promise<void>
+
     send (queue: string, buffer: Buffer, options?: Options.Publish): Promise<void>
 
     publish (exchange: string, buffer: Buffer, options?: Options.Publish): Promise<void>

package/types/diagnostic.d.ts

@@ -1,7 +1,7 @@
 declare namespace comq.diagnostics {
 
   type Event = 'open' | 'close' | 'error' | 'reconnect' | 'exhausted' | 'flow' | 'drain' |
-    'remove' | 'lost' | 'recover' | 'discard' | 'retry' | 'pause' | 'resume' | 'return'
+    'remove' | 'lost' | 'recover' | 'discard' | 'retry' | 'pause' | 'resume' | 'return' | 'taken'
 
   interface Diagnosable {
     diagnose(event: Event, listener: Function): void

package/types/index.d.ts

@@ -21,3 +21,12 @@ export class Retry extends Error {}
  * the count like any other failure.
  */
 export class Park extends Error {}
+
+/**
+ * A Request `IO.call` sent under a key nobody holds. The broker returned it, so it reached no
+ * one and was not processed.
+ */
+export class Unroutable extends Error {
+  readonly exchange: string
+  readonly key: string
+}

package/types/io.d.ts

@@ -34,14 +34,52 @@ declare namespace comq {
   interface Request {
     emitter: ReplyEmitter
     properties: _amqp.Properties
+    signal?: AbortSignal
+  }
+
+  /** How long a caller waits for a Reply. */
+  interface RequestOptions {
+    encoding?: _encoding.Encoding
+
+    /**
+     * Milliseconds to wait for the Reply. A Request nobody has taken by then is dropped by the
+     * broker; one already taken may still be processed, and its Reply is discarded.
+     */
+    timeout?: number
+
+    /**
+     * Ends the wait when aborted, within the timeout. The Request stays in its queue until the
+     * timeout passes, or, without one, until a Producer takes it.
+     */
+    signal?: AbortSignal
+  }
+
+  /** The options of a Request, settled once for all its attempts. */
+  interface Terms {
+    encoding?: _encoding.Encoding
+    expires?: number
+    signal?: AbortSignal
   }
 
   interface IO extends _diagnostics.Diagnosable {
     reply(queue: string, produce: Producer): Promise<void>
 
-    request<Reply = any, Request = any>(queue: string, payload: Request, encoding?: _encoding.Encoding): Promise<Reply> | Promise<Readable>
+    request<Reply = any, Request = any>(queue: string, payload: Request, options?: _encoding.Encoding | RequestOptions): Promise<Reply> | Promise<Readable>
+
+    request(queue: string, stream: Readable, options?: _encoding.Encoding | RequestOptions): Promise<Readable>
+
+    /**
+     * Sends a Request to whoever holds `key` on the routed `exchange`, through `back`. One that
+     * nobody holds is refused with `Unroutable`.
+     */
+    call<Reply = any, Request = any>(exchange: string, key: string, payload: Request, options?: _encoding.Encoding | RequestOptions): Promise<Reply> | Promise<Readable>
 
-    request(queue: string, stream: Readable, encoding?: _encoding.Encoding): Promise<Readable>
+    /**
+     * Answers the Requests `call` sends under `key`, from a queue this connection alone holds.
+     * While another connection holds it on a broker, claims it there again and again, emitting
+     * `taken`. Resolves once a broker holds it.
+     */
+    back(exchange: string, key: string, produce: Producer): Promise<void>
 
     consume<T = any>(exchange: string, group: string, consumer: Consumer<T>): Promise<void>
 
@@ -107,6 +145,8 @@ declare namespace comq {
 
     diagnose(event: 'retry', listener: (channel: _topology.type, message: any, error: Error, attempt: number, index?: number) => void): void
 
+    diagnose(event: 'taken', listener: (channel: _topology.type, queue: string, index?: number) => void): void
+
     diagnose(event: 'pause', listener: (channel: _topology.type) => void): void
 
     diagnose(event: 'resume', listener: (channel: _topology.type) => void): void