comq 0.7.0 → 0.8.0-dev.0

package/.github/dependabot.yml

@@ -4,13 +4,13 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
-    target-branch: "dev"
+    target-branch: "bumps"
     labels:
       - "Bump"
   - package-ecosystem: "npm"
     directory: "/"
     schedule:
       interval: "daily"
-    target-branch: "dev"
+    target-branch: "bumps"
     labels:
       - "Bump"

package/.github/workflows/release.yaml

@@ -28,8 +28,8 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Run tests
-        run: npm i && npm test
+#      - name: Run tests
+#        run: npm i && npm test
 
       - name: Import GPG key
         id: gpg

package/examples/readme.md

@@ -2,8 +2,6 @@
 
 To run examples please start RabbitMQ server with `docker compose up -d` in the package root.
 
-> Try to run example first.
-
 ## RPC
 
 Run in two terminals:
@@ -20,8 +18,6 @@ $ node exampels/rpc/consumer
 
 [source](rpc/consumer.js)
 
-> Try to run consumer first.
-
 ## Events
 
 Run in multiple terminals:

package/features/singleton.feature

@@ -0,0 +1,23 @@
+Feature: Singleton connection
+
+  Scenario: Establishing singleton connection
+    Given an active singleton connection
+
+  Scenario: Establishing sharded singleton connection
+    Given an active sharded singleton connection
+
+  Scenario: Sending request and getting reply
+    Given an active singleton connection
+    And function replying `add_numbers` queue:
+    """
+    ({ a, b }) => { return a + b }
+    """
+    When the consumer sends the following request to the `add_numbers` queue:
+    """yaml
+    a: 1
+    b: 2
+    """
+    Then the consumer receives the reply:
+    """yaml
+    3
+    """

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

@@ -25,6 +25,7 @@ declare namespace comq.features {
     publishing: any
 
     connect(user?: string, password?: string): Promise<void>
+    join(user?: string, password?: string): Promise<void>
     disconnect(): Promise<void>
   }
 

package/features/steps/connection.js

@@ -26,6 +26,27 @@ Given('an active sharded connection',
     await this.connecting
   })
 
+Given('an active singleton connection',
+  /**
+   * @this {comq.features.Context}
+   */
+  async function () {
+    this.connecting = this.join()
+
+    await this.connecting
+  })
+
+Given('an active sharded singleton connection',
+  /**
+   * @this {comq.features.Context}
+   */
+  async function () {
+    this.sharded = true
+    this.connecting = this.join()
+
+    await this.connecting
+  })
+
 When('I attempt to connect to the broker for {number} second(s)',
   /**
    * @param {number} interval

package/features/steps/context.js

@@ -1,7 +1,7 @@
 'use strict'
 
 const { World } = require('@cucumber/cucumber')
-const { connect } = require('../../')
+const { connect, join } = require('../../')
 
 /**
  * @implements {comq.features.Context}
@@ -26,7 +26,13 @@ class Context extends World {
   async connect (user, password) {
     const urls = this.#urls(user, password)
 
-    await this.#connect(...urls)
+    await this.#connect(urls)
+  }
+
+  async join (user, password) {
+    const urls = this.#urls(user, password)
+
+    await this.#connect(urls, join)
   }
 
   async disconnect () {
@@ -40,13 +46,14 @@ class Context extends World {
   }
 
   /**
-   * @param {...string} urls
+   * @param {string[]} urls
+   * @param {comq.connect} [method]
    * @return {Promise<void>}
    */
-  async #connect (...urls) {
+  async #connect (urls, method = connect) {
     if (this.io !== undefined) await this.disconnect()
 
-    this.io = await connect(...urls)
+    this.io = await method(...urls)
     this.connected = true
 
     for (const event of EVENTS) this.io.diagnose(event, () => (this.events[event] = true))

package/lerna.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comq",
-  "version": "0.7.0",
+  "version": "0.8.0-dev.0",
   "description": "ComQ",
   "author": {
     "name": "Artem Gurtovoi",
@@ -27,22 +27,22 @@
   "main": "source/index.js",
   "types": "types/index.d.ts",
   "devDependencies": {
-    "@cucumber/cucumber": "9.1.0",
-    "@toa.io/command": "0.4.0",
-    "@toa.io/tomato": "0.4.0",
-    "@toa.io/yaml": "0.4.0",
-    "@types/amqplib": "0.10.1",
-    "@types/jest": "29.5.0",
-    "husky": "8.0.3",
-    "jest": "29.5.0",
-    "randomstring": "1.2.3",
-    "snazzy": "9.0.0",
-    "standard": "17.0.0"
+    "@cucumber/cucumber": "^9.1.2",
+    "@toa.io/command": "^0.4.0",
+    "@toa.io/tomato": "^0.4.0",
+    "@toa.io/yaml": "^0.4.0",
+    "@types/amqplib": "^0.10.1",
+    "@types/jest": "^29.5.2",
+    "husky": "^8.0.3",
+    "jest": "^29.5.0",
+    "randomstring": "^1.3.0",
+    "snazzy": "^9.0.0",
+    "standard": "^17.1.0"
   },
   "dependencies": {
-    "@toa.io/generic": "0.4.0",
-    "amqplib": "0.10.3",
-    "msgpackr": "1.8.5"
+    "@toa.io/generic": "^0.4.0",
+    "amqplib": "^0.10.3",
+    "msgpackr": "^1.9.5"
   },
   "scripts": {
     "prepare": "husky install",

package/readme.md

@@ -173,24 +173,22 @@ The following encoding formats are supported:
 - `application/octet-stream`
 - `text/plain`
 
-## Flow Control
+## Flow control
 
 When [back pressure](https://www.rabbitmq.com/flow-control.html) is applied to a channel or the
 underlying broker connection is lost, any current and future outgoing messages will be paused.
 Corresponding returned promises will remain in a `pending` state until the pressure is removed or
 the connection is restored.
 
-## Connection Tolerance
+## Connection tolerance
 
-When initially connecting to the broker or if the established connection is lost, connection
-attempts will be repeated indefinitely with intervals increasing up to 30 seconds. Once reconnected,
-the topology will be recovered, and unanswered Requests and unconfirmed Events will be
+When the established connection is lost, it will be automatically restored.
+Reconnection attempts will be made indefinitely, with intervals increasing up to 30 seconds.
+If the broker rejects the connection, for example, due to access being denied, an exception will be thrown.
+Once reconnected, the topology will be recovered, and any unanswered requests and unconfirmed events will be
 retransmitted.
 
-If the broker rejects the connection (for example, due to access being denied), an exception will be
-thrown.
-
-## Sharded Connection
+## Sharded connection
 
 *Send to one, receive from all.*
 
@@ -198,11 +196,11 @@ A sharded connection is a mechanism that uses multiple connections simultaneousl
 balancing and mitigate failover scenarios, utilizing a set of broker instances that are **not**
 combined into a cluster.
 
-Outgoing messages are sent to a single connection chosen at random from the shard pool. Shards that
-lose their underlying connection or experience channel [back pressure](#flow-control) on
-corresponding channel are removed from the pool until the issue is resolved. Pending messages
-meeting these conditions are immediately routed among the remaining shards in the pool. If no shards
-are available, messages will wait until any shard's connection is re-established.
+Outgoing messages are sent to a single connection chosen at random from the shard pool. Shards that lose their
+underlying connection or experience channel [back pressure](#flow-control) on a corresponding channel are removed from
+the pool until the issue is resolved. Pending messages meeting these conditions are immediately routed among the
+remaining shards in the pool. If no shards are available, messages will wait until a shard's connection is
+re-established.
 
 Incoming messages are consumed from all shards.
 
@@ -213,7 +211,6 @@ Returns an instance of `IO` once a successful connection to one of the shards is
 ### Example
 
 ```javascript
-
 const shard0 = 'amqp://developer:secret@localhost:5673'
 const shard1 = 'amqp://developer:secret@localhost:5674'
 
@@ -222,9 +219,21 @@ const io = await connect(shard0, shard1)
 // ...
 
 await io.close()
-
 ```
 
+## Singleton connection
+
+`async join(url: string): IO`
+
+Similar to [`connect`](#connect), but it utilizes shared underlying connections.
+
+The connection is established once per unique `url` among instances of `IO` created with `join`,
+and it will be closed when the last instance of `IO` using that connection is [disconnected](#disconnection).
+
+[Sharded connections](#sharded-connection) are also supported.
+
+`async join(...shards: string[]): IO`
+
 ## Topology
 
 Topology is designed to deliver maximum performance while ensuring that the **at least once**
@@ -258,7 +267,7 @@ when using a single channel or channel pool.
 [^1]: The maximum number of messages has been consumed while handlers of those messages have sent
 requests and are expecting replies.
 
-### Exchanges and Queues
+### Exchanges and queues
 
 - Exchanges and queues for Events, and queues for Requests
   are [durable](https://amqp-node.github.io/amqplib/channel_api.html#channel_assertQueue).
@@ -294,7 +303,7 @@ See:
 | Reply   | unlimited | no       | exclusive | automatic      | no         |
 | Event   | limited   | yes      | durable   | manual         | yes        |
 
-## Graceful Shutdown
+## Graceful shutdown
 
 ### Sealing
 

package/source/connect.js

@@ -2,40 +2,52 @@
 
 const { IO } = require('./io')
 const { Connection } = require('./connection')
+const { SingletonConnection } = require('./singleton')
 const shards = require('./shards')
 
 /** @type {comq.connect} */
 const connect = async (...urls) => {
-  const connection = create(urls)
-
-  await connection.open()
+  return create(urls, connectionConstructor(Connection))
+}
 
-  return new IO(connection)
+/** @type {comq.connect} */
+const join = async (...urls) => {
+  return create(urls, connectionConstructor(SingletonConnection))
 }
 
 /**
  * @param {string[]} urls
- * @return {comq.Connection}
+ * @param {(urls: string[]) => comq.Connection} constructor
+ * @return {Promise<IO>}
  */
-const create = (urls) => {
-  if (urls.length === 1) return single(urls[0])
-  else return sharded(urls)
+const create = async (urls, constructor) => {
+  const connection = constructor(urls)
+
+  await connection.open()
+
+  return new IO(connection)
 }
 
-/**
- * @param {string} url
- * @return {comq.Connection}
- */
-const single = (url) => new Connection(url)
+const connectionConstructor = (ConnectionClass) =>
+  /**
+   * @param {string[]} urls
+   * @return {comq.Connection}
+   */
+  (urls) => {
+    if (urls.length === 1) return new ConnectionClass(urls[0])
+    else return shardedConnection(urls, ConnectionClass)
+  }
 
 /**
  * @param {string[]} urls
+ * @param {function} ConnectionClass
  * @return {comq.Connection}
  */
-const sharded = (urls) => {
-  const connections = urls.map(single)
+const shardedConnection = (urls, ConnectionClass) => {
+  const connections = urls.map((url) => new ConnectionClass(url))
 
   return new shards.Connection(connections)
 }
 
 exports.connect = connect
+exports.join = join

package/source/connection.js

@@ -79,7 +79,7 @@ class Connection {
       else throw exception
     }
 
-    // prevents the process crash, 'close' will be emitted next
+    // This prevents the process from crashing; 'close' will be emitted next.
     // https://amqp-node.github.io/amqplib/channel_api.html#model_events
     this.#connection.on('error', noop)
 

package/source/index.js

@@ -1,5 +1,6 @@
 'use strict'
 
-const { connect } = require('./connect')
+const { connect, join } = require('./connect')
 
 exports.connect = connect
+exports.join = join

package/source/singleton.js

@@ -0,0 +1,68 @@
+'use strict'
+
+const { Connection } = require('./connection')
+
+class SingletonConnection extends Connection {
+  /** @type {string} */
+  #url
+
+  /** @type {Promise<void>} */
+  #opened = null
+
+  constructor (url) {
+    if (instances.has(url)) return instances.get(url)
+
+    super(url)
+
+    this.#url = url
+
+    instances.set(url, this)
+  }
+
+  async open () {
+    increment(this.#url)
+
+    if (this.#opened === null) this.#opened = super.open()
+
+    await this.#opened
+  }
+
+  async close () {
+    const remainder = decrement(this.#url)
+
+    if (remainder === 0) await this.#close()
+  }
+
+  async #close () {
+    this.#opened = null
+    await super.close()
+  }
+
+  // Singletons are evil.
+  static __lets_pretend_this_method_doesnt_exist () {
+    instances.clear()
+    counters.clear()
+  }
+}
+
+function increment (url) {
+  const value = (counters.get(url) ?? 0) + 1
+
+  counters.set(url, value)
+}
+
+function decrement (url) {
+  const value = counters.get(url) - 1
+
+  counters.set(url, value)
+
+  return value
+}
+
+/** @type {Map<string, SingletonConnection>} */
+const instances = new Map()
+
+/** @type {Map<string, number>} */
+const counters = new Map()
+
+exports.SingletonConnection = SingletonConnection

package/test/connect.test.js

@@ -2,12 +2,11 @@
 
 const { generate } = require('randomstring')
 
-const { connect } = require('../')
-
 jest.mock('../source/io')
 jest.mock('../source/connection')
 jest.mock('../source/shards/connection')
 
+const { connect } = require('../')
 const { IO } = require('../source/io')
 
 const {

package/test/join.test.js

@@ -0,0 +1,58 @@
+'use strict'
+
+const { generate } = require('randomstring')
+
+jest.mock('../source/io')
+jest.mock('../source/singleton')
+jest.mock('../source/shards/connection')
+
+const { /** @type {jest.MockedClass<comq.IO>} */ IO } = require('../source/io')
+
+const {
+  /** @type {jest.MockedClass<comq.Connection>} */
+  SingletonConnection
+} = require('../source/singleton')
+
+const shards = /** @type {{ Connection: jest.MockedClass<comq.Connection>}} */
+  require('../source/shards')
+
+const { join } = require('../')
+
+const url = generate()
+
+/** @type {comq.IO} */
+let io
+
+beforeEach(async () => {
+  jest.clearAllMocks()
+
+  io = await join(url)
+})
+
+it('should be', async () => {
+  expect(join).toBeInstanceOf(Function)
+})
+
+it('should return instance of IO', async () => {
+  expect(io).toStrictEqual(IO.mock.instances[0])
+})
+
+it('should create singleton connection', async () => {
+  expect(SingletonConnection).toHaveBeenCalled()
+  expect(SingletonConnection).toHaveBeenCalledWith(url)
+  expect(IO).toHaveBeenCalledWith(SingletonConnection.mock.instances[0])
+})
+
+it('should create sharded connection', async () => {
+  jest.clearAllMocks()
+
+  const urls = [generate(), generate()]
+
+  io = await join(...urls)
+
+  for (const url of urls) expect(SingletonConnection).toHaveBeenCalledWith(url)
+
+  expect(shards.Connection).toHaveBeenCalledWith(SingletonConnection.mock.instances)
+  expect(IO).toHaveBeenCalledWith(shards.Connection.mock.instances[0])
+  expect(io).toStrictEqual(IO.mock.instances[0])
+})

package/test/singleton.fixtures.js

@@ -0,0 +1,21 @@
+'use strict'
+
+class Connection {
+  static ctor = jest.fn(async () => undefined)
+  static open = jest.fn(async () => undefined)
+  static close = jest.fn(async () => undefined)
+
+  constructor (...args) {
+    Connection.ctor(...args)
+  }
+
+  async open () {
+    await Connection.open()
+  }
+
+  async close () {
+    await Connection.close()
+  }
+}
+
+exports.mock = { Connection }

package/test/singleton.test.js

@@ -0,0 +1,113 @@
+'use strict'
+
+const { generate } = require('randomstring')
+
+const { mock } = require('./singleton.fixtures')
+
+jest.mock('../source/connection', () => ({ Connection: mock.Connection }))
+
+const { SingletonConnection } = require('../source/singleton')
+
+it('should be', async () => {
+  expect(SingletonConnection).toBeInstanceOf(Function)
+})
+
+/** @type {SingletonConnection} */
+let connection
+
+const url = generate()
+
+beforeEach(() => {
+  jest.clearAllMocks()
+
+  SingletonConnection.__lets_pretend_this_method_doesnt_exist()
+
+  connection = new SingletonConnection(url)
+})
+
+it('should extend Connection', async () => {
+  expect(connection).toBeInstanceOf(mock.Connection)
+  expect(mock.Connection.ctor).toHaveBeenCalledWith(url)
+})
+
+describe('connection', () => {
+  beforeEach(async () => {
+    await connection.open()
+  })
+
+  afterEach(async () => {
+    await connection.close()
+  })
+
+  it('should open connection', async () => {
+    expect(mock.Connection.open).toHaveBeenCalled()
+  })
+
+  it('should open connection once per url across instances', async () => {
+    jest.clearAllMocks()
+
+    const url = generate()
+    const second = new SingletonConnection(url)
+    const third = new SingletonConnection(url)
+
+    await Promise.all([second.open(), third.open()])
+
+    expect(mock.Connection.open).toHaveBeenCalledTimes(1)
+
+    const fourth = new SingletonConnection(generate())
+
+    await fourth.open()
+
+    expect(mock.Connection.open).toHaveBeenCalledTimes(2)
+
+    await second.close()
+    await third.close()
+    await fourth.close()
+  })
+
+  it('should close connection', async () => {
+    await connection.close()
+
+    expect(mock.Connection.close).toHaveBeenCalled()
+  })
+
+  it('should close connection once', async () => {
+    const url = generate()
+    const one = new SingletonConnection(url)
+    const two = new SingletonConnection(url)
+
+    await Promise.all([one.open(), two.open()])
+    await Promise.all([one.close(), two.close()])
+
+    expect(mock.Connection.close).toHaveBeenCalledTimes(1)
+  })
+
+  it('should not close connection if other instances connected', async () => {
+    jest.clearAllMocks()
+    const second = new SingletonConnection(url)
+
+    await second.open()
+    await second.close()
+
+    expect(mock.Connection.close).not.toHaveBeenCalled()
+  })
+
+  it('should close connection when all instances are disconnected', async () => {
+    const second = new SingletonConnection(url)
+
+    await second.open()
+    await second.close()
+    await connection.close()
+
+    expect(mock.Connection.close).toHaveBeenCalled()
+  })
+
+  it('should reopen connection', async () => {
+    const one = new SingletonConnection(url)
+
+    await connection.close()
+    await one.open()
+
+    expect(mock.Connection.open).toHaveBeenCalledTimes(2)
+  })
+})

package/types/index.d.ts

@@ -3,3 +3,4 @@ import { connect } from './connection'
 export type { IO, consumer, producer } from './io'
 
 export const connect: connect
+export const join: connect