comq 0.6.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/connection.feature

@@ -3,14 +3,6 @@ Feature: Connection Tolerance
   Scenario: Connect
     Given an active connection to the broker
 
-  Scenario: Connecting to a broker before it was started
-    Given the broker is down
-    When I attempt to connect to the broker for 0.2 seconds
-    Then the connection is not established
-    And no exceptions are thrown
-    When the broker is up
-    Then the connection is established
-
   Scenario: Restoring connection after broker restart
     Given an active connection to the broker
     When the broker is down

package/features/shards.feature

@@ -3,25 +3,26 @@ Feature: Sharded Connection
   Scenario: Establishing sharded connection
     Given an active sharded connection
 
-  Scenario: Connecting and waiting for 'open' event
-    Given the connection to both shards is established
-
   Scenario: Connecting while a shard is down
     Given one of the brokers has crashed
     When I attempt to establish sharded connection
-    Then the connection is established
+    Then an exception is thrown: "ECONNREFUSED"
     Then the broker is up
 
+  Scenario: Connecting with wrong credentials
+    When I attempt to establish a sharded connection as "someone" with password "whatever"
+    Then an exception is thrown: "Handshake terminated by server: 403 (ACCESS-REFUSED)"
+
   Scenario: Sending a request to a sharded connection while one broker is down
-    Given one of the brokers has crashed
-    And an active sharded connection
+    Given an active sharded connection
+    And one of the brokers has crashed
     And a producer replying `add_numbers` queue
     When the consumer sends a request to the `add_numbers` queue
     Then the consumer receives the reply
     Then the broker is up
 
   Scenario: Publishing an event to a sharded connection missing one broker
-    Given the connection to both shards is established
+    Given an active sharded connection
     And events are exclusively consumed from the `numbers_added` exchange
     And one of the brokers has crashed
     When an event is emitted to the `numbers_added` exchange
@@ -29,7 +30,7 @@ Feature: Sharded Connection
     Then the broker is up
 
   Scenario: Shard crashes while sending requests
-    Given the connection to both shards is established
+    Given an active sharded connection
     And a producer replying `flood` queue
     And I'm sending 1kB requests to the `flood` queue at 1kHz
     When one of the brokers has crashed
@@ -38,7 +39,7 @@ Feature: Sharded Connection
     Then the broker is up
 
   Scenario: Shard crashes while publishing events
-    Given the connection to both shards is established
+    Given an active sharded connection
     And events are exclusively consumed from the `flood` exchange
     And I'm publishing 1kB events to the `flood` exchange at 100Hz
     When one of the brokers has crashed
@@ -47,7 +48,7 @@ Feature: Sharded Connection
     Then the broker is up
 
   Scenario: Sealing sharded connection while one broker is down
-    Given the connection to both shards is established
+    Given an active sharded connection
     And a producer replying `echo` queue
     And one of the brokers has crashed
     And the connection has started sealing
@@ -55,7 +56,3 @@ Feature: Sharded Connection
     And the broker is up
     Then the connection is sealed
     And the consumer does not receive the reply
-
-  Scenario: Connecting with wrong credentials
-    When I attempt to establish a sharded connection as "someone" with password "whatever"
-    Then an exception is thrown: "Handshake terminated by server: 403 (ACCESS-REFUSED)"

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/.test/connection.test.js

@@ -62,12 +62,6 @@ describe('Given an active sharded connection', () => {
   })
 })
 
-describe('Given the connection to both shards is established', () => {
-  tomato.steps.Gi('the connection to both shards is established')
-
-  it('should be', async () => undefined)
-})
-
 describe('When I attempt to connect to the broker for {number} second(s)', () => {
   const step = tomato.steps.Wh('I attempt to connect to the broker for {number} second(s)')
 

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

@@ -1,7 +1,7 @@
 'use strict'
 
 const assert = require('node:assert')
-const { timeout, promex } = require('@toa.io/generic')
+const { timeout } = require('@toa.io/generic')
 
 const { Given, When, Then } = require('@cucumber/cucumber')
 
@@ -26,22 +26,25 @@ Given('an active sharded connection',
     await this.connecting
   })
 
-Given('the connection to both shards is established',
+Given('an active singleton connection',
   /**
    * @this {comq.features.Context}
    */
   async function () {
-    const promise = promex()
-
-    this.sharded = true
-    this.connecting = this.connect()
+    this.connecting = this.join()
 
     await this.connecting
+  })
 
-    // second shard is connected
-    this.io.diagnose('open', () => promise.resolve())
+Given('an active sharded singleton connection',
+  /**
+   * @this {comq.features.Context}
+   */
+  async function () {
+    this.sharded = true
+    this.connecting = this.join()
 
-    return promise
+    await this.connecting
   })
 
 When('I attempt to connect to the broker for {number} second(s)',
@@ -185,6 +188,6 @@ const CONNECTION_EVENTS = {
 }
 
 const CONNECTION_GAPS = {
-  lost: global.COMQ_TESTING_CONNECTION_GAP_LOST ?? 10,
-  restored: global.COMQ_TESTING_CONNECTION_GAP_RESTORED ?? 5000
+  lost: 10,
+  restored: 5000
 }

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.6.0",
+  "version": "0.8.0-dev.0",
   "conventionalCommits": true
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comq",
-  "version": "0.6.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/channel.js

@@ -1,7 +1,7 @@
 'use strict'
 
 const { EventEmitter } = require('node:events')
-const { lazy, recall, promex, failsafe, immediate } = require('@toa.io/generic')
+const { lazy, recall, promex, failsafe, timeout } = require('@toa.io/generic')
 
 /**
  * @implements {comq.Channel}
@@ -137,8 +137,7 @@ class Channel {
 
     for (const confirmation of this.#confirmations) confirmation.reject(INTERRUPTION)
 
-    // let unpause and confirmation interruptions be handled
-    await immediate()
+    await timeout(0) // let unpause and confirmation interruptions be handled
 
     this.#recovery.resolve()
     this.#recovery = promex()

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

@@ -23,6 +23,9 @@ class Connection {
   /** @type {toa.generic.Promex} */
   #recovery = promex()
 
+  /** @type {boolean} */
+  #running = false
+
   #diagnostics = new EventEmitter()
 
   /**
@@ -34,6 +37,8 @@ class Connection {
 
   async open () {
     await retry(this.#open, RETRY)
+
+    this.#running = true
   }
 
   async close () {
@@ -70,11 +75,11 @@ class Connection {
     try {
       this.#connection = await amqp.connect(this.#url)
     } catch (exception) {
-      if (transient(exception)) return retry()
+      if (this.#transient(exception)) return retry()
       else throw exception
     }
 
-    // prevents 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)
 
@@ -101,6 +106,12 @@ class Connection {
   #recover () {
     return this.#recovery
   }
+
+  #transient (exception) {
+    const abruptly = exception.message === 'Socket closed abruptly during opening handshake'
+
+    return this.#running || abruptly
+  }
 }
 
 /** @type {toa.generic.retry.Options} */
@@ -108,17 +119,6 @@ const RETRY = {
   retries: Infinity
 }
 
-/**
- * @param {Error} exception
- * @returns {boolean}
- */
-const transient = (exception) => {
-  const refused = exception.code === 'ECONNREFUSED'
-  const handshake = exception.message === 'Socket closed abruptly during opening handshake'
-
-  return refused || handshake
-}
-
 function noop () {}
 
 exports.Connection = Connection

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/shards/connection.js

@@ -23,9 +23,13 @@ class Connection {
   }
 
   async open () {
-    const opening = this.#connections.map((connection) => connection.open())
+    const openings = this.#connections.map((connection) => connection.open())
 
-    await Promise.any(opening)
+    try {
+      await Promise.all(openings)
+    } catch (exception) {
+      await this.#cancel(openings, exception)
+    }
   }
 
   async close () {
@@ -51,6 +55,21 @@ class Connection {
       connection.diagnose(event, (...args) => this.#diagnostics.emit(event, ...args, index))
     }
   }
+
+  /**
+   * @param {Promise<any>[]} openings
+   * @param {Error} exception
+   */
+  async #cancel (openings, exception) {
+    const settled = await Promise.allSettled(openings)
+    const indexes = settled.map((result, index) => result.status === 'fulfilled' ? index : -1)
+    const opened = indexes.filter((index) => index !== -1)
+    const closings = opened.map((index) => this.#connections[index].close())
+
+    await Promise.all(closings)
+
+    throw exception
+  }
 }
 
 exports.Connection = Connection

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/channel.test.js

@@ -577,7 +577,7 @@ describe('recovery', () => {
       if (sealed) await channel.seal()
     })
 
-    it('should re-assert queue after recovery', async () => {
+    it('should re-assert queue', async () => {
       chan.assertQueue.mockImplementation(async () => { throw new Error('Channel closed') })
 
       /** @type {comq.amqp.Connection} */
@@ -598,7 +598,7 @@ describe('recovery', () => {
       expect(repl.assertQueue).toHaveBeenCalled()
     })
 
-    it('should re-assert exchange after exception', async () => {
+    it('should re-assert exchange', async () => {
       chan.assertExchange.mockImplementation(async () => { throw new Error('Channel ended, no reply will be forthcoming') })
 
       /** @type {comq.amqp.Connection} */
@@ -619,7 +619,7 @@ describe('recovery', () => {
       expect(repl.assertExchange).toHaveBeenCalled()
     })
 
-    it('should re-bind queue after exception', async () => {
+    it('should re-bind queue', async () => {
       chan.bindQueue.mockImplementation(async () => { throw new Error('Channel ended, no reply will be forthcoming') })
 
       /** @type {comq.amqp.Connection} */
@@ -642,7 +642,7 @@ describe('recovery', () => {
       expect(repl.bindQueue).toHaveBeenCalled()
     })
 
-    it(`should${not} re-consume after recovery`, async () => {
+    it(`should${not} re-consume`, async () => {
       await channel.consume(queue, consumer)
 
       const replacement = await amqplib.connect()
@@ -655,7 +655,7 @@ describe('recovery', () => {
       else expect(chan.consume).toHaveBeenCalledWith(queue, expect.any(Function), expect.anything())
     })
 
-    it(`should${not} re-consume after exception `, async () => {
+    it(`should${not} re-consume`, async () => {
       chan.consume.mockImplementation(async () => { throw new Error('Channel ended, no reply will be forthcoming') })
 
       /** @type {comq.amqp.Connection} */
@@ -677,7 +677,7 @@ describe('recovery', () => {
       else expect(repl.consume).toHaveBeenCalled()
     })
 
-    it(`should${not} re-subscribe after recovery`, async () => {
+    it(`should${not} re-subscribe`, async () => {
       await channel.subscribe(exchange, queue, consumer)
 
       const replacement = await amqplib.connect()
@@ -690,7 +690,7 @@ describe('recovery', () => {
       else expect(repl.consume).toHaveBeenCalledWith(queue, expect.any(Function), expect.anything())
     })
 
-    it('should re-send after exception', async () => {
+    it('should re-send', async () => {
       const queue = generate()
       const buffer = Buffer.from(generate())
 
@@ -702,7 +702,6 @@ describe('recovery', () => {
       setImmediate(async () => {
         expect(chan.publish).toHaveBeenCalled()
 
-        chan.publish.mockImplementation(async () => {})
         replacement = await amqplib.connect()
 
         await channel.recover(replacement)
@@ -712,9 +711,6 @@ describe('recovery', () => {
 
       const repl = await getCreatedChannel(replacement)
 
-      // await recovery effect
-      await timeout(5)
-
       expect(repl.publish).toHaveBeenCalled()
     })
 
@@ -757,7 +753,7 @@ describe('recovery', () => {
       )
     })
 
-    it('should unpause on recovery', async () => {
+    it('should unpause', async () => {
       jest.clearAllMocks()
 
       topology.confirms = false

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/connection.test.js

@@ -30,12 +30,6 @@ beforeEach(() => {
   connection = new Connection(url)
 })
 
-/** @type {[string, Partial<Error>][]} */
-const TRANSIENT_ERRORS = [
-  ['ECONNREFUSED', { code: 'ECONNREFUSED' }],
-  ['Socket closed', { message: 'Socket closed abruptly during opening handshake' }]
-]
-
 // endregion
 
 describe('initial connection', () => {
@@ -45,7 +39,9 @@ describe('initial connection', () => {
     expect(amqplib.connect).toHaveBeenCalledWith(url)
   })
 
-  it.each(TRANSIENT_ERRORS)('should reconnect on %s',
+  it.each(/** @type {[string, Partial<Error>][]} */[
+    ['Socket closed', { message: 'Socket closed abruptly during opening handshake' }]
+  ])('should reconnect on %s',
     async (_, error) => {
       amqplib.connect.mockImplementationOnce(async () => { throw error })
 
@@ -54,12 +50,13 @@ describe('initial connection', () => {
       expect(amqplib.connect).toHaveBeenCalledTimes(2)
     })
 
-  it('should throw if error is permanent', async () => {
-    const error = new Error()
-
-    amqplib.connect.mockImplementationOnce(async () => { throw error })
+  it.each(/** @type {[string, Partial<Error>][]} */[
+    ['ECONNREFUSED', { code: 'ECONNREFUSED' }],
+    ['any exception', new Error(generate())]
+  ])('should throw if error is %s', async (_, exception) => {
+    amqplib.connect.mockImplementationOnce(async () => { throw exception })
 
-    await expect(connection.open()).rejects.toThrow(error)
+    await expect(connection.open()).rejects.toStrictEqual(exception)
   })
 })
 
@@ -77,7 +74,7 @@ describe('reconnection', () => {
     expect(amqplib.connect).toHaveBeenCalledTimes(1)
 
     // const clear = jest.spyOn(conn, 'removeAllListeners')
-    const error = { message: generate() }
+    const error = { code: 'ECONNREFUSED' }
 
     conn.emit('close', error)
 

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/shards/channel.test.js

@@ -374,20 +374,21 @@ it('should remove channel with back pressure from the pool', async () => {
   }
 
   await send()
+
   expect(chan.send).toHaveBeenCalled()
+
   chan.send.mockClear()
 
-  // emit 'flow'
-  for (const listener of flowListeners) listener()
+  for (const flow of flowListeners) flow()
 
   await send()
+
   expect(chan.send).not.toHaveBeenCalled()
-  chan.send.mockClear()
 
-  // emit 'drain'
-  for (const listener of drainListeners) listener()
+  for (const drain of drainListeners) drain()
 
   await send()
+
   expect(chan.send).toHaveBeenCalled()
 })
 

package/test/shards/connection.test.js

@@ -1,7 +1,7 @@
 'use strict'
 
 const { generate } = require('randomstring')
-const { random, promex, sample } = require('@toa.io/generic')
+const { random, promex, immediate } = require('@toa.io/generic')
 
 const { Connection } = require('../../source/shards')
 
@@ -16,7 +16,7 @@ it('should be', async () => {
 })
 
 /** @type {jest.MockedObject<comq.Connection>[]} */
-const connections = [mock.connection(), mock.connection()]
+let connections
 
 /** @type {comq.Connection} */
 let connection
@@ -24,12 +24,13 @@ let connection
 beforeEach(() => {
   jest.clearAllMocks()
 
+  connections = [mock.connection(), mock.connection()]
   connection = new Connection(connections)
 })
 
 describe('open', () => {
-  it('should resolve when one of connections is established', async () => {
-    expect.assertions(1)
+  it('should resolve when all of the connections are established', async () => {
+    expect.assertions(2)
 
     /** @type {toa.generic.Promex[]} */
     const promises = []
@@ -41,19 +42,45 @@ describe('open', () => {
       promises.push(promise)
     }
 
-    let connected = false
+    let resolved = false
 
-    setImmediate(() => {
-      expect(connected).toStrictEqual(false)
+    setImmediate(async () => {
+      expect(resolved).toStrictEqual(false)
 
-      const any = sample(promises)
+      const first = promises.shift()
 
-      any.resolve()
+      first.resolve()
+
+      await immediate()
+
+      promises.forEach((promise) => promise.resolve())
+
+      resolved = true
     })
 
     await connection.open()
 
-    connected = true
+    expect(resolved).toStrictEqual(true)
+  })
+
+  it('should close opened connection if one fails', async () => {
+    connections.push(mock.connection())
+
+    const [one, bad, two] = connections
+    const exception = new Error(generate())
+
+    one.open.mockImplementation(() => Promise.resolve())
+    two.open.mockImplementation(() => Promise.resolve())
+
+    bad.open.mockImplementation(async () => {
+      await immediate()
+      throw exception
+    })
+
+    await expect(connection.open()).rejects.toThrow(exception)
+
+    expect(one.close).toHaveBeenCalled()
+    expect(two.close).toHaveBeenCalled()
   })
 })
 
@@ -81,9 +108,9 @@ describe('createChannel', () => {
 
 describe.each(/** @type {comq.diagnostics.event[]} */ ['open', 'close'])('diagnose %s event',
   (event) => {
-    const index = random(connections.length)
-
     it('should re-emit event', async () => {
+      const index = random(connections.length)
+
       for (const conn of connections) {
         expect(conn.diagnose).toHaveBeenCalledWith(event, expect.any(Function))
       }

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