comq 0.4.0-dev.5 → 0.4.0-dev.7

package/docs/notes.md

@@ -35,3 +35,13 @@ next Request is consumed from the Request queue*.
 A lightweight Producer (one that produces responses quickly) can result in being "overloaded"
 from the Consumer's perspective (that is, does not consume messages with an expected rate), even
 though the Producer being idle while waiting for response publication confirmations.
+
+## `replyTo` property prefix `direct:///`
+
+`IO.request` accepts `replyTo` property modifier function `(replyTo): string` as fourth argument. It
+is the temporary solution to provide an option for compatibility with
+official [RabbitMQ client for .NET](https://github.com/rabbitmq/rabbitmq-dotnet-client/blob/feceedccd6b81d4b461795390432dc3330fdf596/projects/Unit/TestPublicationAddress.cs).
+
+It is yet to be clarified and implemented correctly. [#6](https://github.com/toa-io/comq/issues/6)
+
+See [Direct Reply-to](https://www.rabbitmq.com/direct-reply-to.html).

package/features/events.feature

@@ -5,12 +5,17 @@ Feature: Events (pub/sub)
 
   Scenario: Sending and receiving an event
     Given that `checker` is consuming events from the `numbers_added` exchange
-    When I emit an event to the `numbers_added` exchange
+    When an event is emitted to the `numbers_added` exchange
     Then `checker` receives the event
 
   Scenario: Receiving an event by two consumer groups
     Given that `first` is consuming events from the `numbers_added` exchange
     And `second` is consuming events from the `numbers_added` exchange
-    When I emit an event to the `numbers_added` exchange
+    When an event is emitted to the `numbers_added` exchange
     Then `first` receives the event
     And `second` receives the event
+
+  Scenario: Receiving an event exclusively
+    Given that events are exclusively consumed from the `numbers_added` exchange
+    When an event is emitted to the `numbers_added` exchange
+    Then the event is received

package/features/steps/.test/events.test.js

@@ -57,8 +57,14 @@ describe('Given {token} consuming events from the {token} exchange is expected',
   it('should be', async () => undefined)
 })
 
-describe('When I emit an event to the {token} exchange', () => {
-  const step = tomato.steps.Wh('I emit an event to the {token} exchange')
+describe('Given that events are exclusively consumed from the {token} exchange', () => {
+  tomato.steps.Gi('that events are exclusively consumed from the {token} exchange')
+
+  it('should be', async () => undefined)
+})
+
+describe('When an event is emitted to the {token} exchange', () => {
+  const step = tomato.steps.Wh('an event is emitted to the {token} exchange')
 
   it('should be', async () => undefined)
 
@@ -121,3 +127,28 @@ describe('Then {token} receives the event', () => {
     await expect(step.call(context, group)).resolves.not.toThrow()
   })
 })
+
+describe('Then the event is received', () => {
+  const step = tomato.steps.Th('the event is received')
+
+  const payload = generate()
+  const group = undefined
+
+  beforeEach(() => {
+    context.consumed = { [group]: payload }
+  })
+
+  it('should be', async () => undefined)
+
+  it('should throw if not consumed', async () => {
+    context.published = generate()
+
+    await expect(step.call(context, group)).rejects.toThrow(AssertionError)
+  })
+
+  it('should pass if consumed', async () => {
+    context.published = payload
+
+    await expect(step.call(context, group)).resolves.not.toThrow()
+  })
+})

package/features/steps/events.js

@@ -12,7 +12,7 @@ Given('(that ){token} is consuming events from the {token} exchange',
    * @this {comq.features.Context}
    */
   async function (group, exchange) {
-    await consume(this, group, exchange)
+    await consume.call(this, group, exchange)
   })
 
 Given('{token} consuming events from the {token} exchange is expected',
@@ -24,10 +24,19 @@ Given('{token} consuming events from the {token} exchange is expected',
   async function (group, exchange) {
     await timeout(500) // let it crash
 
-    this.expected = consume(this, group, exchange)
+    this.expected = consume.call(this, group, exchange)
   })
 
-When('I emit an event to the {token} exchange',
+Given('that events are exclusively consumed from the {token} exchange',
+  /**
+   * @param {string} exchange
+   * @this {comq.features.Context}
+   */
+  async function (exchange) {
+    this.expected = consume.call(this, undefined, exchange)
+  })
+
+When('an event is emitted to the {token} exchange',
   /**
    * @param {string} exchange
    * @this {comq.features.Context}
@@ -48,22 +57,38 @@ Then('{token} receives the event',
    * @this {comq.features.Context}
    */
   async function (group) {
-    await timeout(100)
+    await consumed.call(this, group)
+  })
 
-    assert.notEqual(this.published, undefined, 'No event has been published')
-    assert.equal(this.published, this.consumed[group], `'${group}' haven't consumed event`)
+Then('the event is received',
+  /**
+   * @this {comq.features.Context}
+   */
+  async function () {
+    await consumed.call(this)
   })
 
 /**
- * @param {comq.features.Context} context
+ * @this {comq.features.Context} context
  * @param {string} group
  * @param {string} exchange
  * @return {Promise<void>}
  */
-const consume = async (context, group, exchange) => {
-  context.consumed ??= {}
+async function consume (group, exchange) {
+  this.consumed ??= {}
 
-  return context.io.consume(exchange, group, async (payload) => {
-    context.consumed[group] = payload
+  return this.io.consume(exchange, group, async (payload) => {
+    this.consumed[group] = payload
   })
 }
+
+/**
+ * @param {string} group
+ * @return {Promise<void>}
+ */
+async function consumed (group) {
+  await timeout(100) // let it consume
+
+  assert.notEqual(this.published, undefined, 'No event has been published')
+  assert.equal(this.published, this.consumed[group], 'Event hasn\'t been exclusively consumed')
+}

package/lerna.json

@@ -1,5 +1,5 @@
 {
   "useWorkspaces": true,
-  "version": "0.4.0-dev.0",
+  "version": "0.4.0-dev.7",
   "conventionalCommits": true
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comq",
-  "version": "0.4.0-dev.5",
+  "version": "0.4.0-dev.7",
   "description": "ComQ",
   "author": {
     "name": "Artem Gurtovoi",
@@ -37,7 +37,7 @@
     "standard": "17.0.0"
   },
   "dependencies": {
-    "@toa.io/generic": "0.3.0",
+    "@toa.io/generic": "0.4.0-dev.3",
     "amqplib": "0.10.3",
     "msgpackr": "1.8.5"
   },

package/readme.md

@@ -94,7 +94,7 @@ await io.reply('add_numbers', ({ a, b }) => (a + b))
 
 ## Request
 
-`async IO.request(queue: string, payload: any, [encoding: string, replyTo: string])`
+`async IO.request(queue: string, payload: any, [encoding: string])`
 
 Send encoded Request message with `replyTo` and `correlationId` properties set and
 return decoded Reply content.
@@ -109,19 +109,22 @@ const sum = await io.request('add_numbers', { a: 1, b: 2 })
 
 ## Consumption
 
-`async IO.consume(exchange: string, group: string, consumer)`
+`async IO.consume(exchange: string, [group: string], consumer)`
 
 `consumer` function's signature is `async? (payload: any): void`
 
 Start consuming decoded Events.
 
-Asserts fanout `exchange` (once per unique `exchange`) and queue for the Consumer `group` (once per
-unique `exchange` and `group` pair), and then binds the queue to the exchange. That is, one Event
-message is delivered to a single Consumer within *each group*.
+Asserts fanout `exchange` (once per unique `exchange`) and the queue for the Consumer `group` (once
+per unique `exchange` and `group` pair), and then binds the queue to the exchange. That is, one
+Event message is delivered to a single Consumer within *each group*.
 
 > Typically, the value of `group` refers to the name of a microservice running in multiple
 > instances.
 
+If the `group` is `undefined` or omitted, a unique value is generated and the queue is declared as
+exclusive.
+
 ### Example
 
 ```javascript

package/source/channel.js

@@ -126,12 +126,15 @@ class Channel {
 
   /**
    * @param {string} name
-   * @returns {Promise<void>}
+   * @returns {Promise<string[]>}
    */
   async #assertQueue (name) {
-    const options = this.#topology.durable ? DURABLE : EXCLUSIVE
+    const passed = arguments.length === 2 ? arguments[1] : undefined
+    const options = passed ?? (this.#topology.durable ? DURABLE : EXCLUSIVE)
+
+    const { queue } = await this.#channel.assertQueue(name, options)
 
-    await this.#channel.assertQueue(name, options)
+    return [queue]
   }
 
   /**
@@ -149,11 +152,18 @@ class Channel {
    *
    * @param {string} exchange
    * @param {string} queue
-   * @returns {Promise<void>}
+   * @returns {Promise<string[]>}
    */
   async #assertBoundQueue (exchange, queue) {
-    await this.#assertQueue(queue)
+    /** @type {comq.amqp.options.Consume} */
+    let options
+
+    if (queue === undefined) options = { exclusive: true }
+
+    queue = (await this.#assertQueue(queue, options))[0]
     await this.#channel.bindQueue(queue, exchange, '')
+
+    return [exchange, queue]
   }
 
   // endregion

package/source/io.js

@@ -61,16 +61,14 @@ class IO {
        * @param {string} queue
        * @param {any} payload
        * @param {comq.encoding} [encoding]
-       * @param {string} replyTo
+       * @param {comq.ReplyToPropertyFormatter} replyToFormatter
        * @returns {Promise<void>}
        */
-      async (queue, payload, encoding, replyTo) => {
+      async (queue, payload, encoding, replyToFormatter) => {
         const [buffer, contentType] = this.#encode(payload, encoding)
         const correlationId = randomBytes(8).toString('hex')
         const emitter = this.#emitters[queue]
-
-        replyTo ??= emitter.queue
-
+        const replyTo = replyToFormatter?.(emitter.queue) ?? emitter.queue
         const properties = { contentType, correlationId, replyTo }
         const reply = this.#createReply()
 
@@ -83,7 +81,8 @@ class IO {
 
   consume = lazy(this, this.#createEventChannel,
     async (exchange, group, callback) => {
-      const queue = io.concat(exchange, group)
+      const exclusive = group === undefined || callback === undefined // 2 arguments passed
+      const queue = exclusive ? undefined : io.concat(exchange, group)
       const consumer = this.#getEventConsumer(callback)
 
       await this.#events.subscribe(exchange, queue, consumer)

package/test/amqplib.mock.js

@@ -11,7 +11,7 @@ class Channel extends EventEmitter {
   cancel = jest.fn(async () => undefined)
   ack = jest.fn(() => undefined)
   nack = jest.fn(() => undefined)
-  assertQueue = jest.fn(async () => undefined)
+  assertQueue = jest.fn(async (name) => ({ queue: name ?? generate() }))
   assertExchange = jest.fn(async () => undefined)
   bindQueue = jest.fn(async () => undefined)
   publish = jest.fn((_0, _1, _2, _3, resolve) => resolve?.(null))

package/test/channel.test.js

@@ -293,9 +293,10 @@ describe('throw', () => {
   })
 })
 
-describe('subscribe', () => {
+describe.each(['group', 'exclusive'])('%s subscribe', (option) => {
+  let queue = option === 'group' ? generate() : undefined
+
   const exchange = generate()
-  const queue = generate()
   const consumer = /** @type {comq.channel.consumer} */ jest.fn(() => undefined)
 
   beforeEach(async () => {
@@ -319,13 +320,33 @@ describe('subscribe', () => {
     else expect(options).toMatchObject({ durable: false })
   })
 
-  it('should assert queue', async () => {
-    const options = topology.durable ? { durable: true } : { exclusive: true }
+  if (option === 'group') {
+    it('should assert queue', async () => {
+      const options = topology.durable ? { durable: true } : { exclusive: true }
 
-    expect(chan.assertQueue).toHaveBeenCalledWith(queue, expect.objectContaining(options))
-  })
+      expect(chan.assertQueue).toHaveBeenCalledWith(queue, expect.objectContaining(options))
+    })
+  } else {
+    it.each([true, false])('should assert exclusive queue (topology.durable: %s)', async (durable) => {
+      jest.clearAllMocks()
+
+      topology.durable = durable
+
+      channel = await create(connection, topology)
+      chan = await getCreatedChannel()
+
+      await channel.subscribe(exchange, undefined, consumer)
+
+      expect(chan.assertQueue).toHaveBeenCalledWith(
+        undefined,
+        expect.objectContaining({ exclusive: true })
+      )
+    })
+  }
 
   it('should bind queue to exchange', async () => {
+    const { queue } = await chan.assertQueue.mock.results[0].value
+
     expect(chan.bindQueue).toHaveBeenCalledTimes(1)
     expect(chan.bindQueue).toHaveBeenCalledWith(queue, exchange, '')
   })
@@ -345,6 +366,8 @@ describe('subscribe', () => {
 
     const options = ack ? {} : { noAck: true }
 
+    queue = (await chan.assertQueue.mock.results[0].value).queue
+
     expect(chan.consume).toHaveBeenCalledTimes(1)
     expect(chan.consume).toHaveBeenCalledWith(queue, expect.any(Function), expect.objectContaining(options))
 

package/test/io.consume.test.js

@@ -1,5 +1,7 @@
 'use strict'
 
+// region setup
+
 const { generate } = require('randomstring')
 const { encode } = require('../source/encode')
 
@@ -21,6 +23,8 @@ beforeEach(async () => {
   io = new IO(connection)
 })
 
+// endregion
+
 it('should be', async () => {
   expect(io.consume).toBeDefined()
 })
@@ -32,36 +36,54 @@ const consumer = jest.fn(() => undefined)
 /** @type {jest.MockedObject<comq.Channel>} */
 let events
 
-beforeEach(async () => {
+beforeEach(() => {
   jest.clearAllMocks()
+})
 
-  await io.consume(exchange, group, consumer)
+describe('group consumption', () => {
+  beforeEach(async () => {
+    await io.consume(exchange, group, consumer)
 
-  events = await findChannel('event')
-})
+    events = await findChannel('event')
+  })
 
-it('should create events channel', async () => {
-  expect(connection.createChannel).toHaveBeenCalledWith('event')
-})
+  it('should create events channel', async () => {
+    expect(connection.createChannel).toHaveBeenCalledWith('event')
+  })
+
+  it('should subscribe', async () => {
+    expect(events).toBeDefined()
+
+    const queue = exchange + '..' + group
+
+    expect(events.subscribe).toHaveBeenCalledWith(exchange, queue, expect.any(Function))
+  })
 
-it('should subscribe', async () => {
-  expect(events).toBeDefined()
+  it.each(encodings)('should pass decoded event (%s)', async (contentType) => {
+    const payload = generate()
+    const content = encode(payload, contentType)
+    const properties = { contentType }
+    const message = /** @type {import('amqplib').ConsumeMessage} */ { content, properties }
+    const callback = events.subscribe.mock.calls[0][2]
 
-  const queue = exchange + '..' + group
+    await callback(message)
 
-  expect(events.subscribe).toHaveBeenCalledWith(exchange, queue, expect.any(Function))
+    expect(consumer).toHaveBeenCalledWith(payload)
+  })
 })
 
-it.each(encodings)('should pass decoded event (%s)', async (contentType) => {
-  const payload = generate()
-  const content = encode(payload, contentType)
-  const properties = { contentType }
-  const message = /** @type {import('amqplib').ConsumeMessage} */ { content, properties }
-  const callback = events.subscribe.mock.calls[0][2]
+describe.each(['omitted', 'undefined'])('exclusive consumption (group is %s)', (option) => {
+  beforeEach(async () => {
+    if (option === 'omitted') await io.consume(exchange, consumer)
+    else await io.consume(exchange, undefined, consumer)
 
-  await callback(message)
+    events = await findChannel('event')
+  })
 
-  expect(consumer).toHaveBeenCalledWith(payload)
+  it('should subscribe', async () => {
+    expect(events).toBeDefined()
+    expect(events.subscribe).toHaveBeenCalledWith(exchange, undefined, expect.any(Function))
+  })
 })
 
 /**

package/test/io.request.test.js

@@ -83,21 +83,22 @@ describe('send', () => {
     expect(typeof properties.correlationId).toStrictEqual('string')
   })
 
-  it('should set default replyTo', async () => {
+  it('should set replyTo', async () => {
     const properties = call[2]
     const rx = new RegExp(`^${queue}..[a-z0-9]+`)
 
     expect(properties.replyTo).toMatch(rx)
   })
 
-  it('should set specified replyTo', async () => {
+  it('should set replyTo using specified formatter', async () => {
     jest.clearAllMocks()
 
     /** @type {comq.encoding} */
+    const prefix = generate()
     const encoding = 'application/json'
-    const replyTo = generate()
+    const formatter = (replyTo) => prefix + replyTo
 
-    promise = io.request(queue, payload, encoding, replyTo)
+    promise = io.request(queue, payload, encoding, formatter)
 
     await immediate()
 
@@ -105,7 +106,7 @@ describe('send', () => {
 
     const properties = requests.send.mock.calls[0][2]
 
-    expect(properties.replyTo).toStrictEqual(replyTo)
+    expect(properties.replyTo).toMatch(new RegExp(`${prefix}${queue}..[a-z0-9]+`))
   })
 
   it('should consume replyTo', async () => {

package/types/io.d.ts

@@ -16,13 +16,22 @@ declare namespace comq {
     clear(): void
   }
 
+  type ReplyToPropertyFormatter = (queue: string) => string
+
   interface IO {
     reply(queue: string, produce: producer): Promise<void>
 
-    request(queue: string, payload: any, encoding?: _encoding.encoding, replyTo?: string): Promise<any>
+    request(
+      queue: string,
+      payload: any,
+      encoding?: _encoding.encoding,
+      replyToFormatter?: ReplyToPropertyFormatter)
+      : Promise<any>
 
     consume(exchange: string, group: string, consumer: consumer): Promise<void>
 
+    consume(exchange: string, consumer: consumer): Promise<void>
+
     emit(exchange: string, payload: any, encoding?: _encoding.encoding): Promise<void>
 
     seal(): Promise<void>