@toa.io/bindings.amqp 0.2.0-dev.1 → 0.2.1-dev.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/bindings.amqp",
-  "version": "0.2.0-dev.1",
+  "version": "0.2.1-dev.2",
   "description": "Toa AMQP Binding",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -18,9 +18,16 @@
   "scripts": {
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
+  "devDependencies": {
+    "@toa.io/mock": "*",
+    "@types/amqplib": "0.8.2"
+  },
   "dependencies": {
-    "amqplib": "0.8.0",
-    "execa": "5.1.1"
+    "@toa.io/console": "*",
+    "@toa.io/core": "*",
+    "@toa.io/generic": "*",
+    "@toa.io/pointer": "*",
+    "amqplib": "0.10.0"
   },
-  "gitHead": "a0df6f203bca3e26e3a4a791a213e418d2b65764"
+  "gitHead": "2be07592325b2e4dc823e81d882a4e50bf50de24"
 }

package/readme.md

@@ -0,0 +1,45 @@
+# AMQP Binding
+
+AMQP binding is asynchronous, broadcast and *systemic*, that is being used by the runtime.
+See [Bindings](#).
+
+## 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.
+
+### 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.
+
+```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
+```
+
+### Concise Declaration
+
+> Well-known shortcut `amqp` is available.
+
+String annotation value is considered as `default`.
+
+The next two declarations are equivalent.
+
+```yaml
+# context.toa.yaml
+annotations:
+  @toa.io/bindings.amqp:
+     default: host1
+``` 
+
+```yaml
+# context.toa.yaml
+amqp: host1
+``` 

package/src/annotation.js

@@ -0,0 +1,5 @@
+'use strict'
+
+const { uris } = require('@toa.io/pointer')
+
+exports.annotation = uris.construct

package/src/{broadcast.js → broadcaster.js}

@@ -1,9 +1,12 @@
 'use strict'
 
 const { Connector } = require('@toa.io/core')
-const { newid } = require('@toa.io/gears')
+const { newid } = require('@toa.io/generic')
 
-class Broadcast extends Connector {
+/**
+ * @implements {toa.core.bindings.Broadcaster}
+ */
+class Broadcaster extends Connector {
   #group
   #channel
   #prefix
@@ -20,7 +23,10 @@ class Broadcast extends Connector {
   }
 
   async send (label, payload) {
-    await this.#channel.publish(this.#prefix + label, payload, { expiration: 10, persistent: false })
+    await this.#channel.publish(this.#prefix + label, payload, {
+      expiration: 10,
+      persistent: false
+    })
   }
 
   async receive (label, callback) {
@@ -28,4 +34,4 @@ class Broadcast extends Connector {
   }
 }
 
-exports.Broadcast = Broadcast
+exports.Broadcaster = Broadcaster

package/src/channel.js

@@ -1,7 +1,8 @@
 'use strict'
 
 const { Connector } = require('@toa.io/core')
-const { console, newid } = require('@toa.io/gears')
+const { newid, timeout } = require('@toa.io/generic')
+const { console } = require('@toa.io/console')
 
 const { pack, unpack } = require('./message')
 
@@ -24,6 +25,12 @@ class Channel extends Connector {
 
   async connection () {
     this.#channel = await this.#connection.channel()
+    this.#channel.prefetch(100)
+  }
+
+  async disconnection () {
+    // solves 'Channel ended, no reply will be forthcoming'
+    await timeout(50)
   }
 
   async request (label, request) {
@@ -54,37 +61,43 @@ class Channel extends Connector {
       const content = unpack(received.content)
       const reply = await invocation(content)
 
-      const message = pack(reply)
+      const buffer = pack(reply)
       const properties = { correlationId: received.properties.correlationId }
 
-      await this.#channel.publish(exchange, received.properties.replyTo, message, properties)
+      await this.#channel.publish(exchange, received.properties.replyTo, buffer, properties)
       await this.#channel.ack(received)
     })
   }
 
-  async publish (label, payload, options) {
+  async publish (label, content, options) {
     const exchange = 'event.' + label
 
+    // TODO: assert once per exchange
     await this.#channel.assertExchange(exchange, 'fanout', EXCHANGE)
 
-    const message = pack(payload)
+    const buffer = pack(content)
 
-    await this.#channel.publish(exchange, '', message, options)
+    await this.#channel.publish(exchange, '', buffer, options)
   }
 
   async subscribe (label, id, callback) {
     const exchange = 'event.' + label
     const queue = exchange + '..' + id
+    const options = { consumerTag: id }
 
     await this.#channel.assertExchange(exchange, 'fanout', EXCHANGE)
     await this.#channel.assertQueue(queue, QUEUE)
     await this.#channel.bindQueue(queue, exchange, '')
 
-    await this.#channel.consume(queue, async (received) => {
-      const content = unpack(received.content)
+    await this.#channel.consume(queue, async (message) => {
+      const content = unpack(message.content)
       await callback(content)
-      await this.#channel.ack(received)
-    })
+      await this.#channel.ack(message)
+    }, options)
+  }
+
+  async unsubscribe (id) {
+    await this.#channel.cancel(id)
   }
 
   async #bind (label) {

package/src/connection.js

@@ -3,40 +3,46 @@
 const amqp = require('amqplib')
 
 const { Connector } = require('@toa.io/core')
-const { console } = require('@toa.io/gears')
+const { console } = require('@toa.io/console')
 
 class Connection extends Connector {
-  #url
+  /** @type {toa.amqp.Pointer} */
+  #pointer
+
+  /** @type {import('amqplib').Connection} */
   #connection
 
-  constructor (host) {
+  /**
+   * @param {toa.amqp.Pointer} pointer
+   */
+  constructor (pointer) {
     super()
 
-    this.#url = Connection.#locate(host)
+    this.#pointer = pointer
   }
 
   async connection () {
-    this.#connection = await amqp.connect(this.#url)
-    console.info(`AMQP Binding connected to ${this.#url}`)
+    try {
+      this.#connection = await amqp.connect(this.#pointer.reference)
+    } catch (e) {
+      console.error(`Connection to ${this.#pointer.label} has failed`)
+
+      throw e
+    }
+
+    console.info(`AMQP Binding connected to ${this.#pointer.label}`)
   }
 
   async disconnection () {
     // TODO: handle current operations
     // http://www.squaremobius.net/amqp.node/channel_api.html#model_close
     await this.#connection.close()
-    console.info(`AMQP Binding disconnected from ${this.#url}`)
-  }
 
-  async channel () {
-    return this.#connection.createChannel()
+    console.info(`AMQP Binding disconnected from ${this.#pointer.label}`)
   }
 
-  static #locate (host) {
-    // TODO: read ./deployments.js
-    const user = 'user'
-    const password = 'password'
-
-    return `amqp://${user}:${password}@${host}`
+  async channel () {
+    return await this.#connection.createChannel()
   }
 }
 

package/src/constants.js

@@ -0,0 +1,4 @@
+'use strict'
+
+exports.PREFIX = 'bindings-amqp'
+exports.SYSTEM = 'system'

package/src/consumer.js

@@ -4,6 +4,9 @@ const { Connector } = require('@toa.io/core')
 
 const { name } = require('./queue')
 
+/**
+ * @implements {toa.core.bindings.Consumer}
+ */
 class Consumer extends Connector {
   #channel
   #queue

package/src/deployment.js

@@ -0,0 +1,32 @@
+'use strict'
+
+const connectors = require('@toa.io/pointer')
+
+const { PREFIX } = require('./constants')
+
+/**
+ * @type {toa.deployment.dependency.Constructor}
+ */
+const deployment = (instances, annotation) => {
+  validate(annotation)
+
+  /** @type {toa.pointer.deployment.Options} */
+  const options = { prefix: PREFIX }
+
+  return connectors.deployment(instances, annotation, options)
+}
+
+/**
+ * @param {toa.pointer.URIs} annotation
+ */
+const validate = (annotation) => {
+  const defined = annotation !== undefined
+  const defaults = defined && (typeof annotation === 'string' || annotation.default !== undefined)
+  const correct = defined && (defaults || annotation.system !== undefined)
+
+  if (!correct) {
+    throw new Error('AMQP deployment requires either \'system\' or \'default\' pointer annotation')
+  }
+}
+
+exports.deployment = deployment

package/src/emitter.js

@@ -3,6 +3,9 @@
 const { Connector } = require('@toa.io/core')
 const { name } = require('./queue')
 
+/**
+ * @implements {toa.core.bindings.Emitter}
+ */
 class Emitter extends Connector {
   #channel
   #locator

package/src/factory.js

@@ -7,9 +7,14 @@ const { Consumer } = require('./consumer')
 const { Producer } = require('./producer')
 const { Emitter } = require('./emitter')
 const { Receiver } = require('./receiver')
-const { Broadcast } = require('./broadcast')
+const { Broadcaster } = require('./broadcaster')
 const { Connection } = require('./connection')
+const { Pointer } = require('./pointer')
+const { SYSTEM } = require('./constants')
 
+/**
+ * @implements {toa.core.bindings.Factory}
+ */
 class Factory {
   #connections = {}
 
@@ -37,21 +42,27 @@ class Factory {
     return new Receiver(channel, locator, label, id, receiver)
   }
 
-  broadcast (name, group) {
-    const locator = new Locator()
-    const channel = this.#channel(locator)
+  broadcaster (name, group) {
+    const channel = this.#channel()
 
-    return new Broadcast(channel, name, group)
+    return new Broadcaster(channel, name, group)
   }
 
-  #channel () {
-    const host = 'rabbitmq' // locator.host('rabbitmq')
+  /**
+   * @param {toa.core.Locator} [locator]
+   * @returns {Channel}
+   */
+  #channel (locator) {
+    if (locator === undefined) locator = new Locator(SYSTEM)
+
+    const pointer = new Pointer(locator)
+    const key = pointer.reference
 
-    if (this.#connections[host] === undefined) {
-      this.#connections[host] = new Connection(host)
+    if (this.#connections[key] === undefined) {
+      this.#connections[key] = new Connection(pointer)
     }
 
-    return new Channel(this.#connections[host])
+    return new Channel(this.#connections[key])
   }
 }
 

package/src/index.js

@@ -1,8 +1,10 @@
 'use strict'
 
 const { Factory } = require('./factory')
-const { deployments } = require('./deployments')
+const { deployment } = require('./deployment')
+const { annotation } = require('./annotation')
 
-exports.Factory = Factory
 exports.properties = { async: true }
-exports.deployments = deployments
+exports.annotation = annotation
+exports.deployment = deployment
+exports.Factory = Factory

package/src/pointer.js

@@ -0,0 +1,23 @@
+'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
+   */
+  constructor (locator) {
+    super(PREFIX, locator, OPTIONS)
+  }
+}
+
+/** @type {toa.pointer.Options} */
+const OPTIONS = { protocol: 'amqp:' }
+
+exports.Pointer = Pointer

package/src/producer.js

@@ -6,8 +6,11 @@ const { name } = require('./queue')
 
 class Producer extends Connector {
   #channel
+  /** @type {toa.core.Locator} */
   #locator
+  /** @type {toa.core.Component} */
   #producer
+  /** @type {Array<string>} */
   #endpoints
 
   constructor (channel, locator, endpoints, producer) {
@@ -23,12 +26,11 @@ class Producer extends Connector {
   }
 
   async connection () {
-    return Promise.all(this.#endpoints.map((endpoint) => this.#endpoint(endpoint)))
+    await Promise.all(this.#endpoints.map((endpoint) => this.#endpoint(endpoint)))
   }
 
   async #endpoint (endpoint) {
     const queue = name(this.#locator, endpoint)
-
     await this.#channel.reply(queue, async (request) => this.#producer.invoke(endpoint, request))
   }
 }

package/src/queue.js

@@ -1,7 +1,7 @@
 'use strict'
 
-const { concat } = require('@toa.io/gears')
+const { concat } = require('@toa.io/generic')
 
-const name = (locator, endpoint) => locator.domain + '.' + concat(locator.name, '.') + endpoint
+const name = (locator, endpoint) => locator.namespace + '.' + concat(locator.name, '.') + endpoint
 
 exports.name = name

package/src/receiver.js

@@ -6,8 +6,13 @@ const { name } = require('./queue')
 
 class Receiver extends Connector {
   #channel
+  /** @type {toa.core.Receiver} */
   #receiver
+
+  /** @type {string} */
   #label
+
+  /** @type {string} */
   #id
 
   constructor (channel, locator, label, id, receiver) {
@@ -19,10 +24,15 @@ class Receiver extends Connector {
     this.#id = id
 
     this.depends(channel)
+    this.depends(receiver)
   }
 
   async connection () {
-    await this.#channel.subscribe(this.#label, this.#id, (payload) => this.#receiver.receive(payload))
+    await this.#channel.subscribe(this.#label, this.#id, (message) => this.#receiver.receive(message))
+  }
+
+  async disconnection () {
+    await this.#channel.unsubscribe(this.#id)
   }
 }
 

package/test/annotations.test.js

@@ -0,0 +1,15 @@
+'use strict'
+
+const { generate } = require('randomstring')
+const mock = { uris: { construct: () => generate() }, Pointer: class {} }
+
+jest.mock('@toa.io/pointer', () => mock)
+const { annotation } = require('../')
+
+it('should export annotations', () => {
+  expect(annotation).toBeDefined()
+})
+
+it('should export connectors.uris construct', () => {
+  expect(annotation).toStrictEqual(mock.uris.construct)
+})

package/test/deployment.test.js

@@ -0,0 +1,36 @@
+'use strict'
+
+const { generate } = require('randomstring')
+const { random } = require('@toa.io/generic')
+const mock = require('@toa.io/mock')
+
+const { deployment } = require('../')
+
+/** @type {toa.norm.context.dependencies.Instance[]} */
+let instances
+
+/** @returns {URL} */
+const gen = () => new URL('amqp://host-' + generate() + ':' + (random(1000) + 1000))
+
+beforeEach(() => {
+  instances = mock.dependencies.instances()
+})
+
+it('should exist', () => {
+  expect(deployment).toBeDefined()
+})
+
+it('should throw if annotation is not defined', () => {
+  expect(() => deployment(instances, undefined))
+    .toThrow('AMQP deployment requires either \'system\' or \'default\' pointer annotation')
+})
+
+it('should throw if \'system\' is not defined', () => {
+  const url = gen()
+  const annotation = {}
+
+  for (const instance of instances) annotation[instance.locator.id] = url.href
+
+  expect(() => deployment(instances, annotation))
+    .toThrow('AMQP deployment requires either \'system\' or \'default\' pointer annotation')
+})

package/test/pointer.test.js

@@ -0,0 +1,60 @@
+'use strict'
+
+const { generate } = require('randomstring')
+const { Locator } = require('@toa.io/core')
+const { encode, letters: { up } } = require('@toa.io/generic')
+
+const { Pointer } = require('../src/pointer')
+const { PREFIX } = require('../src/constants')
+
+/** @type {toa.core.Locator} */
+let locator
+
+/** @type {toa.amqp.Pointer} */
+let pointer
+
+const protocol = 'amqp:'
+
+let url
+
+beforeAll(() => {
+  const username = generate()
+  const password = generate()
+
+  url = new URL('amqps://whatever:5672')
+
+  url.username = username
+  url.password = password
+
+  process.env.TOA_BINDINGS_AMQP_DEFAULT_USERNAME = username
+  process.env.TOA_BINDINGS_AMQP_DEFAULT_PASSWORD = password
+})
+
+beforeEach(() => {
+  const name = generate()
+  const namespace = generate()
+  const uris = { default: url.href }
+  const value = encode(uris)
+  const key = `TOA_${up(PREFIX)}_POINTER`
+
+  process.env[key] = value
+
+  locator = new Locator(name, namespace)
+  pointer = new Pointer(locator)
+})
+
+it('should be', () => undefined)
+
+it('should expose reference', () => {
+  expect(pointer.reference).toStrictEqual(url.href)
+})
+
+it('should set amqp: protocol on localhost', () => {
+  process.env.TOA_ENV = 'local'
+
+  pointer = new Pointer(locator)
+
+  expect(pointer.protocol).toStrictEqual(protocol)
+
+  delete process.env.TOA_ENV
+})

package/types/pointer.d.ts

@@ -0,0 +1,8 @@
+import type { Pointer as Base } from '@toa.io/pointer/types'
+
+declare namespace toa.amqp {
+
+  interface Pointer extends Base {
+  }
+
+}

package/LICENSE

@@ -1,22 +0,0 @@
-Copyright (c) 2020-present Artem Gurtovoi
-
-MIT License
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/src/deployments.js

@@ -1,28 +0,0 @@
-'use strict'
-
-const deployments = () => {
-  const fullname = 'rabbitmq'
-
-  // TODO: provide passwords as secrets for component containers
-  const user = 'user'
-  const password = 'password'
-  const erlangCookie = 'cookie'
-
-  return [{
-    chart: {
-      name: 'rabbitmq',
-      version: '8.24.3',
-      repository: 'https://charts.bitnami.com/bitnami'
-    },
-    values: {
-      fullnameOverride: fullname,
-      auth: {
-        user,
-        password,
-        erlangCookie
-      }
-    }
-  }]
-}
-
-exports.deployments = deployments