comq 0.5.3-dev.1 → 0.6.0-dev.1

package/docs/headers.md

@@ -0,0 +1,17 @@
+# Message Properties
+
+Events may be emitted and consumed with custom properties using an optional `properties` argument.
+
+## Emission
+
+`async IO.emit(exchange: string, payload: any, [properties: comq.amqp.Properties]): void`
+
+`properties` are passed
+to [amqplib.publish](https://amqp-node.github.io/amqplib/channel_api.html#channel_publish).
+
+## Consumption
+
+`async IO.consume(exchange: string, [group: string], consumer): void`
+
+`consumer` function's signature
+is `async? (payload: any, [properties: comq.amqp.Properties]): void`

package/features/properties.feature

@@ -0,0 +1,29 @@
+Feature: Message properties
+
+  Background:
+    Given an active connection to the broker
+
+  Scenario: Sending and receiving an event with headers
+    Given that `checker` is consuming events from the `numbers_added` exchange
+    When an event is emitted to the `numbers_added` exchange with properties:
+      """yaml
+      headers:
+        foo: bar
+      """
+    Then `checker` receives the event with properties:
+      """yaml
+      contentType: application/octet-stream # standard properties are available
+      headers:
+        foo: bar
+      """
+
+  Scenario: Sending and receiving an event with AMQP properties
+    Given that `checker` is consuming events from the `numbers_added` exchange
+    When an event is emitted to the `numbers_added` exchange with properties:
+      """yaml
+      appId: test
+      """
+    Then `checker` receives the event with properties:
+      """yaml
+      appId: test
+      """

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

@@ -1,9 +1,11 @@
 'use strict'
 
 const { AssertionError } = require('node:assert')
+const { randomBytes } = require('node:crypto')
 const { generate } = require('randomstring')
 const { promex, timeout, random } = require('@toa.io/generic')
 const tomato = require('@toa.io/tomato')
+const { dump } = require('@toa.io/yaml')
 const { io } = require('./io.mock')
 const mock = { tomato }
 
@@ -47,7 +49,16 @@ describe('Given (that ){token} is consuming events from the {token} exchange', (
 
     await consumer(payload)
 
-    expect(context.consumed[group]).toStrictEqual(payload)
+    expect(context.consumed[group]).toStrictEqual(expect.objectContaining({ payload }))
+  })
+
+  it('should store event properties', async () => {
+    const payload = generate()
+    const properties = generate()
+
+    await consumer(payload, properties)
+
+    expect(context.consumed[group]).toStrictEqual({ payload, properties })
   })
 })
 
@@ -79,13 +90,13 @@ describe('When an event is emitted to the {token} exchange', () => {
   })
 
   it('should emit event', async () => {
-    expect(io.emit).toHaveBeenCalledWith(exchange, expect.anything())
+    expect(io.emit.mock.calls[0][0]).toStrictEqual(exchange)
   })
 
   it('should wait for context.expected', async () => {
     jest.clearAllMocks()
 
-    context.expected = promex()
+    context.consumptionPromise = promex()
 
     let resolved = false
 
@@ -93,7 +104,7 @@ describe('When an event is emitted to the {token} exchange', () => {
       expect(io.emit).not.toHaveBeenCalled()
 
       resolved = true
-      context.expected.resolve()
+      context.consumptionPromise.resolve()
     })
 
     await step.call(context, exchange)
@@ -103,20 +114,42 @@ describe('When an event is emitted to the {token} exchange', () => {
   })
 })
 
+describe('When an event is emitted to the {token} exchange with properties:', () => {
+  const step = tomato.steps.Wh('an event is emitted to the {token} exchange with properties:')
+
+  it('should be', async () => undefined)
+
+  const exchange = generate()
+  const properties = { [generate()]: generate() }
+  const yaml = dump(properties)
+
+  beforeEach(async () => {
+    await step.call(context, exchange, yaml)
+  })
+
+  it('should store event', async () => {
+    expect(context.published).toBeDefined()
+  })
+
+  it('should emit event', async () => {
+    expect(io.emit).toHaveBeenCalledWith(exchange, expect.anything(), properties)
+  })
+})
+
 describe('Then {token} receives the event', () => {
   const step = tomato.steps.Th('{token} receives the event')
 
-  const payload = generate()
+  const payload = randomBytes(8)
   const group = generate()
 
   beforeEach(() => {
-    context.consumed = { [group]: payload }
+    context.consumed = { [group]: { payload } }
   })
 
   it('should be', async () => undefined)
 
   it('should throw if not consumed', async () => {
-    context.published = generate()
+    context.published = randomBytes(8)
 
     await expect(step.call(context, group)).rejects.toThrow(AssertionError)
   })
@@ -128,20 +161,47 @@ describe('Then {token} receives the event', () => {
   })
 })
 
+describe('Then {token} receives the event with properties:', () => {
+  const step = tomato.steps.Th('{token} receives the event with properties:')
+
+  it('should be', async () => undefined)
+
+  const payload = randomBytes(8)
+  const properties = { headers: { [generate()]: generate() } }
+  const yaml = dump(properties)
+  const group = generate()
+
+  beforeEach(() => {
+    context.consumed = { [group]: { payload, properties } }
+    context.published = payload
+  })
+
+  it('should throw if does not match', async () => {
+    const properties = { headers: { [generate()]: generate() } }
+    const yaml = dump(properties)
+
+    await expect(step.call(context, group, yaml)).rejects.toThrow(AssertionError)
+  })
+
+  it('should pass if matches', async () => {
+    await expect(step.call(context, group, yaml)).resolves.not.toThrow()
+  })
+})
+
 describe('Then the event is received', () => {
   const step = tomato.steps.Th('the event is received')
 
-  const payload = generate()
+  const payload = randomBytes(8)
   const group = undefined
 
   beforeEach(() => {
-    context.consumed = { [group]: payload }
+    context.consumed = { [group]: { payload } }
   })
 
   it('should be', async () => undefined)
 
   it('should throw if not consumed', async () => {
-    context.published = generate()
+    context.published = randomBytes(8)
 
     await expect(step.call(context, group)).rejects.toThrow(AssertionError)
   })

package/features/steps/.types/context.d.ts

@@ -1,5 +1,6 @@
 import * as _diagnostics from '../../../types/diagnostic'
 import * as _io from '../../../types/io'
+import * as _amqp from '../../../types/amqp'
 
 declare namespace comq.features {
 
@@ -9,14 +10,14 @@ declare namespace comq.features {
     connecting: Promise<any>
     requestsSent: Promise<any>[]
     reply?: Promise<any>
-    published?: any
+    published?: Buffer
     eventsPublishedCount: number
     eventsConsumedCount: number
-    consumed?: Record<string, any>
+    consumed?: Record<string, { payload: any, properties?: _amqp.Properties }>
     consumedCount: number
     events?: { [K in _diagnostics.event]?: boolean }
     exception?: Error
-    expected?: Promise<any>
+    consumptionPromise?: Promise<any>
     sharded: boolean
     shard: number
     sealing: Promise<any>

package/features/steps/events.js

@@ -1,10 +1,10 @@
 'use strict'
 
 const assert = require('node:assert')
-const { generate } = require('randomstring')
-const { timeout, quantity } = require('@toa.io/generic')
-const { Given, When, Then } = require('@cucumber/cucumber')
 const { randomBytes } = require('node:crypto')
+const { timeout, quantity, match } = require('@toa.io/generic')
+const { parse } = require('@toa.io/yaml')
+const { Given, When, Then } = require('@cucumber/cucumber')
 
 Given('(that ){token} is consuming events from the {token} exchange',
   /**
@@ -25,7 +25,7 @@ Given('{token} consuming events from the {token} exchange is expected',
   async function (group, exchange) {
     await timeout(500) // let it crash
 
-    this.expected = consume.call(this, group, exchange)
+    this.consumptionPromise = consume.call(this, group, exchange)
   })
 
 Given('(that )events are exclusively consumed from the {token} exchange',
@@ -34,7 +34,7 @@ Given('(that )events are exclusively consumed from the {token} exchange',
    * @this {comq.features.Context}
    */
   async function (exchange) {
-    this.expected = consume.call(this, undefined, exchange)
+    this.consumptionPromise = consume.call(this, undefined, exchange)
   })
 
 When('an event is emitted to the {token} exchange',
@@ -43,13 +43,22 @@ When('an event is emitted to the {token} exchange',
    * @this {comq.features.Context}
    */
   async function (exchange) {
-    if (this.expected) await this.expected
+    const message = randomBytes(8)
 
-    const message = generate()
+    await emit.call(this, exchange, message)
+  })
 
-    await this.io.emit(exchange, message)
+When('an event is emitted to the {token} exchange with properties:',
+  /**
+   * @param {string} exchange
+   * @param {string} yaml
+   * @this {comq.features.Context}
+   */
+  async function (exchange, yaml) {
+    const message = randomBytes(8)
+    const properties = parse(yaml)
 
-    this.published = message
+    await emit.call(this, exchange, message, properties)
   })
 
 Then('{token} receives the event',
@@ -61,6 +70,21 @@ Then('{token} receives the event',
     await consumed.call(this, group)
   })
 
+Then('{token} receives the event with properties:',
+  /**
+   * @param {string} group
+   * @param {string} yaml
+   * @this {comq.features.Context}
+   */
+  async function (group, yaml) {
+    await consumed.call(this, group)
+
+    const properties = parse(yaml)
+    const matches = match(this.consumed[group].properties, properties)
+
+    assert.equal(matches, true, 'Consumed event properties doesn\'t match')
+  })
+
 Then('the event is received',
   /**
    * @this {comq.features.Context}
@@ -115,8 +139,8 @@ Then('all events have been received',
 async function consume (group, exchange) {
   this.consumed ??= {}
 
-  const consumer = async (payload) => {
-    this.consumed[group] = payload
+  const consumer = async (payload, properties) => {
+    this.consumed[group] = { payload, properties }
     this.eventsConsumedCount++
   }
 
@@ -133,5 +157,24 @@ 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')
+
+  const consumed = this.consumed[group]
+  const equals = this.published.equals(consumed.payload)
+
+  assert.equal(equals, true, 'Consumed event doesn\'t match')
+}
+
+/**
+ * @param {string} exchange
+ * @param {any} message
+ * @param {import('amqplib').Options.Publish} [properties]
+ * @return {Promise<void>}
+ * @this {comq.features.Context}
+ */
+async function emit (exchange, message, properties) {
+  if (this.consumptionPromise) await this.consumptionPromise
+
+  await this.io.emit(exchange, message, properties)
+
+  this.published = message
 }

package/lerna.json

@@ -1,5 +1,5 @@
 {
   "useWorkspaces": true,
-  "version": "0.5.3-dev.1",
+  "version": "0.6.0-dev.1",
   "conventionalCommits": true
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comq",
-  "version": "0.5.3-dev.1",
+  "version": "0.6.0-dev.1",
   "description": "ComQ",
   "author": {
     "name": "Artem Gurtovoi",
@@ -28,10 +28,10 @@
   "types": "types/index.d.ts",
   "devDependencies": {
     "@cucumber/cucumber": "9.1.0",
-    "@toa.io/command": "0.3.0",
+    "@toa.io/command": "0.4.0",
     "@toa.io/mock": "0.3.0",
     "@toa.io/tomato": "0.4.0-dev.2",
-    "@toa.io/yaml": "0.4.0-dev.2",
+    "@toa.io/yaml": "0.4.0",
     "@types/amqplib": "0.10.1",
     "@types/jest": "29.5.0",
     "husky": "8.0.3",
@@ -41,7 +41,7 @@
     "standard": "17.0.0"
   },
   "dependencies": {
-    "@toa.io/generic": "0.4.0-dev.5",
+    "@toa.io/generic": "0.4.0",
     "amqplib": "0.10.3",
     "msgpackr": "1.8.5"
   },

package/source/io.js

@@ -67,13 +67,13 @@ class IO {
        * @returns {Promise<void>}
        */
       async (queue, payload, encoding, replyToFormatter) => {
-        const [buffer, properties] = this.#encode(payload, encoding)
+        const [buffer, contentType] = this.#encode(payload, encoding)
         const emitter = this.#emitters.get(queue)
         const reply = this.#createReply()
         const correlationId = randomBytes(8).toString('hex')
+        const properties = { contentType, correlationId }
 
         properties.replyTo = replyToFormatter?.(emitter.queue) ?? emitter.queue
-        properties.correlationId = correlationId
 
         emitter.once(correlationId, reply.resolve)
 
@@ -100,11 +100,22 @@ class IO {
     /**
      * @param {string} exchange
      * @param {any} payload
-     * @param {comq.encoding} [encoding]
+     * @param {comq.encoding | comq.amqp.options.Publish} [encoding]
      * @returns {Promise<void>}
      */
     async (exchange, payload, encoding) => {
-      const [buffer, properties] = this.#encode(payload, encoding)
+      /** @type {comq.amqp.options.Publish} */
+      const properties = {}
+
+      if (typeof encoding === 'object') { // properties passed
+        Object.assign(properties, encoding)
+
+        encoding = /** @type {comq.encoding} */ properties.contentType
+      }
+
+      const [buffer, contentType] = this.#encode(payload, encoding)
+
+      properties.contentType = contentType
 
       await this.#events.publish(exchange, buffer, properties)
     })
@@ -127,14 +138,10 @@ class IO {
   // region initializers
 
   async #createRequestReplyChannels () {
-    await this.#createRequestChannel()
-
+    this.#requests = await this.#createChannel('request')
     this.#replies = await this.#createChannel('reply')
-    this.#setupRetransmission()
-  }
 
-  async #createRequestChannel () {
-    this.#requests = await this.#createChannel('request')
+    this.#setupRetransmission()
   }
 
   async #createEventChannel () {
@@ -228,7 +235,7 @@ class IO {
     track(this, async (message) => {
       const payload = decode(message)
 
-      await callback(payload)
+      await callback(payload, message.properties)
     })
 
   /**
@@ -260,7 +267,7 @@ class IO {
   /**
    * @param {any} payload
    * @param {comq.encoding} [contentType]
-   * @returns [Buffer, comq.amqp.options.Publish]
+   * @returns [Buffer, comq.encoding]
    */
   #encode (payload, contentType) {
     const raw = Buffer.isBuffer(payload)
@@ -268,9 +275,8 @@ class IO {
     contentType ??= raw ? OCTETS : DEFAULT
 
     const buffer = raw ? payload : encode(payload, contentType)
-    const properties = { contentType }
 
-    return [buffer, properties]
+    return [buffer, contentType]
   }
 }
 

package/test/io.consume.test.js

@@ -68,7 +68,20 @@ describe('group consumption', () => {
 
     await callback(message)
 
-    expect(consumer).toHaveBeenCalledWith(payload)
+    expect(consumer.mock.calls[0][0]).toStrictEqual(payload)
+  })
+
+  it('should pass properties', async () => {
+    const payload = generate()
+    const contentType = 'text/plain'
+    const content = encode(payload, contentType)
+    const properties = { contentType }
+    const message = /** @type {comq.amqp.Message} */ { content, properties }
+    const callback = events.subscribe.mock.calls[0][2]
+
+    await callback(message)
+
+    expect(consumer).toHaveBeenCalledWith(payload, properties)
   })
 })
 
@@ -94,7 +107,7 @@ describe.each(['omitted', 'undefined'])('exclusive consumption (group is %s)', (
 
     await emit(message)
 
-    expect(consumer).toHaveBeenCalledWith(message.content)
+    expect(consumer.mock.calls[0][0]).toStrictEqual(message.content)
   })
 })
 

package/test/io.emit.test.js

@@ -83,12 +83,38 @@ it('should publish Buffer with specified encoding format', async () => {
   const encoding = 'application/json'
 
   await io.emit(exchange, payload, encoding)
+
   const [, buffer, properties] = events.publish.mock.calls[1]
 
   expect(buffer).toStrictEqual(payload)
   expect(properties.contentType).toStrictEqual(encoding)
 })
 
+it('should publish a message with specified properties', async () => {
+  const payload = randomBytes(8)
+
+  /** @type {comq.amqp.Properties} */
+  const properties = { headers: { [generate()]: generate() } }
+
+  await io.emit(exchange, payload, properties)
+
+  const [, , options] = events.publish.mock.calls[1]
+
+  expect(options).toStrictEqual(expect.objectContaining(properties))
+})
+
+it('should publish a message with headers', async () => {
+  const message = generate()
+  const headers = { [generate()]: generate() }
+  const properties = { headers }
+
+  await io.emit(exchange, message, properties)
+
+  const [, , options] = events.publish.mock.calls[1]
+
+  expect(options.headers).toStrictEqual(headers)
+})
+
 /**
  * @param {comq.topology.type} type
  * @returns {jest.MockedObject<comq.Channel>}

package/types/amqp.d.ts

@@ -12,7 +12,9 @@ declare namespace comq.amqp {
   type Connection = amqplib.Connection
   type Channel = amqplib.Channel | amqplib.ConfirmChannel
   type Message = amqplib.Message
+  type Properties = Partial<amqplib.MessageProperties>
 }
 
 export type Connection = comq.amqp.Connection
 export type Channel = comq.amqp.Channel
+export type Properties = comq.amqp.Properties

package/types/diagnostic.d.ts

@@ -2,6 +2,11 @@ declare namespace comq.diagnostics {
 
   type event = 'open' | 'close' | 'flow' | 'drain' | 'remove' | 'recover' | 'discard'
 
+  interface Diagnosable {
+    diagnose(event: event, listener: Function): void
+  }
+
 }
 
 export type event = comq.diagnostics.event
+export type Diagnosable = comq.diagnostics.Diagnosable

package/types/io.d.ts

@@ -1,10 +1,12 @@
 import * as _diagnostics from './diagnostic'
 import * as _encoding from './encoding'
+import * as _topology from './topology'
+import * as _amqp from './amqp'
 
 declare namespace comq {
 
-  type producer = (message: any) => Promise<any>
-  type consumer = (message: any) => Promise<void>
+  type producer = (message: any) => any | Promise<any>
+  type consumer = (message: any, headers?: _amqp.Properties) => void | Promise<void>
 
   interface ReplyEmitter {
     queue: string
@@ -18,7 +20,7 @@ declare namespace comq {
 
   type ReplyToPropertyFormatter = (queue: string) => string
 
-  interface IO {
+  interface IO extends _diagnostics.Diagnosable {
     reply(queue: string, produce: producer): Promise<void>
 
     request(
@@ -34,13 +36,26 @@ declare namespace comq {
 
     emit(exchange: string, payload: any, encoding?: _encoding.encoding): Promise<void>
 
+    emit(exchange: string, payload: any, properties?: _amqp.Properties): Promise<void>
+
     seal(): Promise<void>
 
     close(): Promise<void>
 
-    diagnose(event: _diagnostics.event, listener: Function): void
-  }
+    diagnose(event: 'open', listener: (index?: number) => void)
+
+    diagnose(event: 'close', listener: (index?: number) => void)
+
+    diagnose(event: 'flow', listener: (channel: _topology.type, index?: number) => void)
 
+    diagnose(event: 'drain', listener: (channel: _topology.type, index?: number) => void)
+
+    diagnose(event: 'remove', listener: (index?: number) => void)
+
+    diagnose(event: 'recover', listener: (channel: _topology.type, index?: number) => void)
+
+    diagnose(event: 'discard', listener: (channel: _topology.type, message: any, index?: number) => void)
+  }
 }
 
 export type producer = comq.producer