@toa.io/bindings.amqp 0.2.1-dev.3 → 0.3.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@toa.io/bindings.amqp",
-  "version": "0.2.1-dev.3",
+  "version": "0.3.0",
   "description": "Toa AMQP Binding",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
-  "main": "src/index.js",
+  "main": "source/index.js",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/toa-io/toa.git"
@@ -27,7 +27,7 @@
     "@toa.io/core": "*",
     "@toa.io/generic": "*",
     "@toa.io/pointer": "*",
-    "amqplib": "0.10.0"
+    "comq": "*"
   },
   "gitHead": "2be07592325b2e4dc823e81d882a4e50bf50de24"
 }

package/readme.md

@@ -1,45 +1,54 @@
-# AMQP Binding
+# Toa AMQP Binding
 
-AMQP binding is asynchronous, broadcast and *systemic*, that is being used by the runtime.
-See [Bindings](#).
+AMQP asynchronous binding on top of [ComQ](/libraries/comq).
 
 ## Deployment
 
-AMQP binding requires RabbitMQ broker(s) available from the cluster. As AMQP is a systemic binding,
-so at least one `system` or `default` broker must be provisioned.
+AMQP deployment must be declared with
+the [Pointer annotation](/libraries/pointer/readme.md#annotation). Either `system` or `default`
+pointers must be defined.
 
-### Declaration
-
-AMQP deployment must be declared by [URI Set annotation](#) with a `system` extension, which value
-must be the host of the broker to be used by the runtime. Either `system` or `default` hosts must be
-defined.
+Well-known annotation shortcut `amqp` is available.
 
 ```yaml
 # context.toa.yaml
 annotations:
-  @toa.io/bindings.amqp:
-     system: host0          # the runtime 
-     default: host1         # all undeclared
-     dummies: host2         # namespace-wide
-     dummies.dummy1: host3  # component exclusive
+  "@toa.io/bindings.amqp":
+    system: url0          # the runtime 
+    default: url1         # all undeclared
+    dummies: url2         # namespace-wide
+    dummies.dummy1: url  # component exclusive
 ```
 
 ### Concise Declaration
 
-> Well-known shortcut `amqp` is available.
+Well-known shortcut `amqp` is available. The next two declarations are equivalent:
 
-String annotation value is considered as `default`.
+```yaml
+# context.toa.yaml
+annotations:
+  "@toa.io/bindings.amqp":
+    system: url0
+    dummies: url1
+```
+
+```yaml
+# context.toa.yaml
+amqp:
+  system: url0
+  dummies: url1
+```
 
-The next two declarations are equivalent.
+`string` annotation value is considered as `default`. The next two declarations are equivalent:
 
 ```yaml
 # context.toa.yaml
 annotations:
-  @toa.io/bindings.amqp:
-     default: host1
+  "@toa.io/bindings.amqp":
+    default: url1
 ``` 
 
 ```yaml
 # context.toa.yaml
-amqp: host1
+amqp: url1
 ``` 

package/source/broadcast.js

@@ -0,0 +1,49 @@
+'use strict'
+
+const { Connector } = require('@toa.io/core')
+const { newid } = require('@toa.io/generic')
+
+const { name } = require('./queues')
+
+/**
+ * @implements {toa.core.bindings.Broadcast}
+ */
+class Broadcast extends Connector {
+  /** @type {toa.amqp.Communication} */
+  #comm
+
+  /** @type {toa.core.Locator} */
+  #locator
+
+  /** @type {string} */
+  #group
+
+  /**
+   * @param {toa.amqp.Communication} comm
+   * @param {toa.core.Locator} locator
+   * @param {string} [group]
+   */
+  constructor (comm, locator, group) {
+    super()
+
+    this.#comm = comm
+    this.#locator = locator
+    this.#group = group ?? newid()
+
+    this.depends(comm)
+  }
+
+  async transmit (label, payload) {
+    const exchange = name(this.#locator, label)
+
+    await this.#comm.emit(exchange, payload)
+  }
+
+  async receive (label, callback) {
+    const exchange = name(this.#locator, label)
+
+    await this.#comm.consume(exchange, this.#group, callback)
+  }
+}
+
+exports.Broadcast = Broadcast

package/source/communication.js

@@ -0,0 +1,54 @@
+'use strict'
+
+const { connect } = require('comq')
+const { Connector } = require('@toa.io/core')
+
+/**
+ * @implements {toa.amqp.Communication}
+ */
+class Communication extends Connector {
+  /** @type {toa.pointer.Pointer} */
+  #pointer
+
+  /** @type {comq.IO} */
+  #io
+
+  /**
+   * @param {toa.pointer.Pointer} pointer
+   */
+  constructor (pointer) {
+    super()
+
+    this.#pointer = pointer
+  }
+
+  async open () {
+    this.#io = await connect(this.#pointer.reference)
+  }
+
+  async close () {
+    await this.#io.seal()
+  }
+
+  async dispose () {
+    await this.#io.close()
+  }
+
+  async reply (queue, process) {
+    await this.#io.reply(queue, process)
+  }
+
+  async request (queue, request) {
+    return this.#io.request(queue, request)
+  }
+
+  async emit (exchange, message) {
+    await this.#io.emit(exchange, message)
+  }
+
+  async consume (exchange, group, consumer) {
+    await this.#io.consume(exchange, group, consumer)
+  }
+}
+
+exports.Communication = Communication

package/source/consumer.js

@@ -0,0 +1,35 @@
+'use strict'
+
+const { Connector } = require('@toa.io/core')
+const { name } = require('./queues')
+
+/**
+ * @implements {toa.core.bindings.Consumer}
+ */
+class Consumer extends Connector {
+  /** @type {string} */
+  #queue
+
+  /** @type {toa.amqp.Communication} */
+  #comm
+
+  /**
+   * @param {toa.amqp.Communication} comm
+   * @param {toa.core.Locator} locator
+   * @param {string} endpoint
+   */
+  constructor (comm, locator, endpoint) {
+    super()
+
+    this.#queue = name(locator, endpoint)
+    this.#comm = comm
+
+    this.depends(comm)
+  }
+
+  async request (request) {
+    return this.#comm.request(this.#queue, request)
+  }
+}
+
+exports.Consumer = Consumer

package/source/emitter.js

@@ -0,0 +1,36 @@
+'use strict'
+
+const { Connector } = require('@toa.io/core')
+
+const { name } = require('./queues')
+
+/**
+ * @implements {toa.core.bindings.Emitter}
+ */
+class Emitter extends Connector {
+  /** @type {string} */
+  #exchange
+
+  /** @type {toa.amqp.Communication} */
+  #comm
+
+  /**
+   * @param {toa.amqp.Communication} comm
+   * @param {toa.core.Locator} locator
+   * @param {string} label
+   */
+  constructor (comm, locator, label) {
+    super()
+
+    this.#exchange = name(locator, label)
+    this.#comm = comm
+
+    this.depends(comm)
+  }
+
+  async emit (message) {
+    await this.#comm.emit(this.#exchange, message)
+  }
+}
+
+exports.Emitter = Emitter

package/source/factory.js

@@ -0,0 +1,62 @@
+'use strict'
+
+const { Locator } = require('@toa.io/core')
+
+const { Pointer } = require('./pointer')
+const { Communication } = require('./communication')
+const { Producer } = require('./producer')
+const { Consumer } = require('./consumer')
+const { Emitter } = require('./emitter')
+const { Receiver } = require('./receiver')
+const { Broadcast } = require('./broadcast')
+
+const { SYSTEM } = require('./constants')
+
+/**
+ * @implements {toa.core.bindings.Factory}
+ */
+class Factory {
+  producer (locator, endpoints, component) {
+    const comm = this.#getCommunication(locator)
+
+    return new Producer(comm, locator, endpoints, component)
+  }
+
+  consumer (locator, endpoint) {
+    const comm = this.#getCommunication(locator)
+
+    return new Consumer(comm, locator, endpoint)
+  }
+
+  emitter (locator, label) {
+    const comm = this.#getCommunication(locator)
+
+    return new Emitter(comm, locator, label)
+  }
+
+  receiver (locator, label, group, receiver) {
+    const comm = this.#getCommunication(locator)
+
+    return new Receiver(comm, locator, label, group, receiver)
+  }
+
+  broadcast (name, group) {
+    const locator = new Locator(name, SYSTEM)
+    const comm = this.#getCommunication(locator)
+
+    return new Broadcast(comm, locator, group)
+  }
+
+  /**
+   *
+   * @param {toa.core.Locator} locator
+   * @return {toa.amqp.Communication}
+   */
+  #getCommunication (locator) {
+    const pointer = /** @type {toa.pointer.Pointer} */ new Pointer(locator)
+
+    return new Communication(pointer)
+  }
+}
+
+exports.Factory = Factory

package/{src → source}/index.js

@@ -1,10 +1,13 @@
 'use strict'
 
-const { Factory } = require('./factory')
 const { deployment } = require('./deployment')
 const { annotation } = require('./annotation')
+const { Factory } = require('./factory')
+
+/** @type {toa.core.bindings.Properties} */
+const properties = { async: true }
 
-exports.properties = { async: true }
+exports.properties = properties
 exports.annotation = annotation
 exports.deployment = deployment
 exports.Factory = Factory

package/{src → source}/pointer.js

@@ -1,13 +1,8 @@
 'use strict'
 
 const { Pointer: Base } = require('@toa.io/pointer')
-
 const { PREFIX } = require('./constants')
 
-// noinspection JSClosureCompilerSyntax
-/**
- * @implements {toa.amqp.Pointer}
- */
 class Pointer extends Base {
   /**
    * @param {toa.core.Locator} locator

package/source/producer.js

@@ -0,0 +1,49 @@
+'use strict'
+
+const { Connector } = require('@toa.io/core')
+
+const { name } = require('./queues')
+
+class Producer extends Connector {
+  /** @type {toa.amqp.Communication} */
+  #comm
+
+  /** @type {toa.core.Locator} */
+  #locator
+
+  /** @type {string[]} */
+  #endpoints
+
+  /** @type {toa.core.Component} */
+  #component
+
+  /**
+   * @param {toa.amqp.Communication} comm
+   * @param {toa.core.Locator} locator
+   * @param {string[]} endpoints
+   * @param {toa.core.Component} component
+   */
+  constructor (comm, locator, endpoints, component) {
+    super()
+
+    this.#comm = comm
+    this.#locator = locator
+    this.#endpoints = endpoints
+    this.#component = component
+
+    this.depends(comm)
+    this.depends(component)
+  }
+
+  async open () {
+    await Promise.all(this.#endpoints.map((endpoint) => this.#endpoint(endpoint)))
+  }
+
+  async #endpoint (endpoint) {
+    const queue = name(this.#locator, endpoint)
+
+    await this.#comm.reply(queue, (request) => this.#component.invoke(endpoint, request))
+  }
+}
+
+exports.Producer = Producer

package/source/queues.js

@@ -0,0 +1,13 @@
+'use strict'
+
+const { concat } = require('@toa.io/generic')
+
+/**
+ * @param {toa.core.Locator} locator
+ * @param {string} endpoint
+ * @returns {string}
+ */
+const name = (locator, endpoint) =>
+  locator.namespace + '.' + concat(locator.name, '.') + endpoint
+
+exports.name = name

package/source/receiver.js

@@ -0,0 +1,42 @@
+'use strict'
+
+const { Connector } = require('@toa.io/core')
+const { name } = require('./queues')
+
+class Receiver extends Connector {
+  /** @type {string} */
+  #exchange
+
+  /** @type {string} */
+  #group
+
+  /** @type {toa.amqp.Communication} */
+  #comm
+
+  /** @type {toa.core.Receiver} */
+  #receiver
+
+  /**
+   * @param {toa.amqp.Communication} comm
+   * @param {toa.core.Locator} locator
+   * @param {string} label
+   * @param {string} group
+   * @param {toa.core.Receiver} receiver
+   */
+  constructor (comm, locator, label, group, receiver) {
+    super()
+
+    this.#exchange = name(locator, label)
+    this.#group = group
+    this.#comm = comm
+    this.#receiver = receiver
+
+    this.depends(comm)
+  }
+
+  async open () {
+    await this.#comm.consume(this.#exchange, this.#group, (message) => this.#receiver.receive(message))
+  }
+}
+
+exports.Receiver = Receiver

package/test/annotations.test.js

@@ -4,6 +4,7 @@ const { generate } = require('randomstring')
 const mock = { uris: { construct: () => generate() }, Pointer: class {} }
 
 jest.mock('@toa.io/pointer', () => mock)
+
 const { annotation } = require('../')
 
 it('should export annotations', () => {

package/test/broadcast.test.js

@@ -0,0 +1,83 @@
+'use strict'
+
+// region setup
+
+const { generate } = require('randomstring')
+const { Connector } = require('@toa.io/core')
+
+const mock = {
+  communication: require('./communication.mock').communication,
+  queues: require('./queues.mock')
+}
+
+jest.mock('../source/queues', () => mock.queues)
+
+const { Broadcast } = require('../source/broadcast')
+
+it('should be', async () => {
+  expect(Broadcast).toBeDefined()
+})
+
+const comm = mock.communication()
+const locator = /** @type {toa.core.Locator} */ { namespace: generate(), name: generate() }
+const group = generate()
+
+/** @type {toa.core.bindings.Broadcast} */
+let broadcast
+
+beforeEach(() => {
+  jest.clearAllMocks()
+
+  broadcast = new Broadcast(comm, locator, group)
+})
+
+// endregion
+
+it('should be instance of Connector', async () => {
+  expect(broadcast).toBeInstanceOf(Connector)
+})
+
+it('should depend on communication', async () => {
+  expect(comm.link).toHaveBeenCalledWith(broadcast)
+})
+
+it('should transmit', async () => {
+  const label = generate()
+  const message = generate()
+
+  await broadcast.transmit(label, message)
+
+  expect(mock.queues.name).toHaveBeenCalledWith(locator, label)
+
+  const exchange = mock.queues.name.mock.results[0].value
+
+  expect(comm.emit).toHaveBeenCalledWith(exchange, message)
+})
+
+it('should receive', async () => {
+  const label = generate()
+  const process = jest.fn(async () => undefined)
+
+  await broadcast.receive(label, process)
+
+  expect(mock.queues.name).toHaveBeenCalledWith(locator, label)
+
+  const exchange = mock.queues.name.mock.results[0].value
+
+  expect(comm.consume).toHaveBeenCalledWith(exchange, group, expect.any(Function))
+})
+
+it('should create unique group if not provided', async () => {
+  jest.clearAllMocks()
+
+  broadcast = new Broadcast(comm, locator)
+
+  const label = generate()
+  const process = jest.fn(async () => undefined)
+
+  await broadcast.receive(label, process)
+
+  const group = comm.consume.mock.calls[0][1]
+
+  expect(group).toBeDefined()
+})

package/test/communication.mock.js

@@ -0,0 +1,20 @@
+'use strict'
+
+const { generate } = require('randomstring')
+
+/**
+ * @return {jest.MockedObject<toa.amqp.Communication>}
+ */
+const communication = () => (
+  /** @type {jest.MockedObject<toa.amqp.Communication>} */ {
+    connect: jest.fn(async () => undefined),
+    request: jest.fn(async () => generate()),
+    reply: jest.fn(async () => undefined),
+    emit: jest.fn(async () => undefined),
+    consume: jest.fn(async () => undefined),
+
+    link: jest.fn()
+  }
+)
+
+exports.communication = communication

package/test/communication.test.js

@@ -0,0 +1,97 @@
+'use strict'
+
+const { generate } = require('randomstring')
+const { Connector } = require('@toa.io/core')
+const mock = require('./comq.mock')
+
+jest.mock('comq', () => mock.comq)
+
+const { Communication } = require('../source/communication')
+
+it('should be', async () => {
+  expect(Communication).toBeDefined()
+})
+
+/** @type {toa.pointer.Pointer} */
+let pointer
+
+/** @type {toa.amqp.Communication} */
+let comm
+
+beforeEach(() => {
+  jest.clearAllMocks()
+
+  pointer = /** @type {toa.pointer.Pointer} */ { reference: generate() }
+  comm = new Communication(pointer)
+})
+
+it('should be instance of Connector', async () => {
+  expect(comm).toBeInstanceOf(Connector)
+})
+
+it('should connect to a given pointer reference', async () => {
+  await comm.open()
+
+  expect(mock.comq.connect).toHaveBeenCalledWith(pointer.reference)
+})
+
+describe('connected', () => {
+  /** @type {jest.MockedObject<comq.IO>} */
+  let io
+
+  beforeEach(async () => {
+    await comm.open()
+
+    io = await mock.comq.connect.mock.results[0].value
+  })
+
+  it('should close', async () => {
+    await comm.close()
+
+    expect(io.seal).toHaveBeenCalled()
+  })
+
+  it('should dispose', async () => {
+    await comm.dispose()
+
+    expect(io.close).toHaveBeenCalled()
+  })
+
+  it('should bind reply', async () => {
+    const queue = generate()
+    const producer = jest.fn(async () => undefined)
+
+    await comm.reply(queue, producer)
+
+    expect(io.reply).toHaveBeenCalledWith(queue, producer)
+  })
+
+  it('should send request', async () => {
+    const queue = generate()
+    const request = generate()
+
+    const reply = await comm.request(queue, request)
+
+    expect(io.request).toHaveBeenCalledWith(queue, request)
+    expect(reply).toStrictEqual(await io.request.mock.results[0].value)
+  })
+
+  it('should emit', async () => {
+    const exchange = generate()
+    const message = generate()
+
+    await comm.emit(exchange, message)
+
+    expect(io.emit).toHaveBeenCalledWith(exchange, message)
+  })
+
+  it('should consume', async () => {
+    const exchange = generate()
+    const group = generate()
+    const consumer = jest.fn(async () => undefined)
+
+    await comm.consume(exchange, group, consumer)
+
+    expect(io.consume).toHaveBeenCalledWith(exchange, group, consumer)
+  })
+})