comq 0.4.1-dev.3 → 0.5.0-dev.0

package/readme.md

@@ -5,16 +5,18 @@ Node.js.
 
 ## Features
 
-1. Dynamic topology
-2. Request-reply (RPC)
-3. Events (pub/sub)
-4. Content encoding
-5. Flow control and back pressure handling
-6. Consumer acknowledgments and publisher confirms
-7. Poison message handling
-8. Connection tolerance
-9. Broker restart resilience
-10. Graceful shutdown
+1. [Dynamic topology](#topology)
+2. [Request](#request)-[reply](#reply) (RPC)
+3. Events ([pub](#emission)/[sub](#consumption))
+4. [Content encoding](#encoding)
+5. [Flow control](#flow-control) and back pressure handling
+6. [Consumer acknowledgments](#messages) and [publisher confirms](#channels)
+7. [Poison message handling](#messages)
+8. [Connection tolerance](#connection-tolerance) and broker restart resilience
+9. [Sharded connection](#sharded-connection)
+10. [Graceful shutdown](#graceful-shutdown)
+
+> CommonJS, ECMAScript and TypeScript compatible (types included).
 
 ## TL;DR
 
@@ -37,7 +39,7 @@ to [`amqplib.connect`](https://amqp-node.github.io/amqplib/channel_api.html#conn
 ### Example
 
 ```javascript
-const { connect } = require('comq')
+import { connect } from 'comq'
 
 const url = 'amqp://developer:secret@localhost'
 const io = await connect(url)
@@ -66,7 +68,7 @@ value as in the Request.
 
 ## Reply
 
-`async IO.reply(queue: string, producer)`
+`async IO.reply(queue: string, producer): void`
 
 `producer` function's signature is `async? (message: any): any`
 
@@ -94,7 +96,7 @@ await io.reply('add_numbers', ({ a, b }) => (a + b))
 
 ## Request
 
-`async IO.request(queue: string, payload: any, [encoding: string])`
+`async IO.request(queue: string, payload: any, [encoding: string]): any`
 
 Send encoded Request message with `replyTo` and `correlationId` properties set and
 return decoded Reply content.
@@ -109,7 +111,7 @@ const sum = await io.request('add_numbers', { a: 1, b: 2 })
 
 ## Consumption
 
-`async IO.consume(exchange: string, [group: string], consumer)`
+`async IO.consume(exchange: string, [group: string], consumer): void`
 
 `consumer` function's signature is `async? (payload: any): void`
 
@@ -135,7 +137,7 @@ await io.consume('numbers_added', 'logger', ({ a, b }) => {
 
 ## Emission
 
-`async IO.emit(exchange: string, payload: any, [encoding: string])`
+`async IO.emit(exchange: string, payload: any, [encoding: string]): void`
 
 Publish encoded Event to the `exchange`.
 
@@ -175,18 +177,61 @@ The following encoding formats are supported:
 
 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 resent.
+the topology will be recovered, and 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
+
+*Send to one, receive from all.*
+
+A sharded connection is a mechanism that uses multiple connections simultaneously to achieve load
+balancing and mitigate failover scenarios, utilizing a set of broker instances that are **not**
+combined into a cluster.
+
+`async connect(...shards: string[]): IO`
+
+Returns an instance of `IO` once a successful connection to one of the shards is 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
+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.
+
+Incoming messages are consumed from all shards.
+
+### Example
+
+```javascript
+
+const shard0 = 'amqp://developer:secret@localhost:5673'
+const shard1 = 'amqp://developer:secret@localhost:5674'
+
+const io = await connect(shard0, shard1)
+
+// ...
+
+await io.close()
+
+```
+
+## 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.
+
 ## Topology
 
 Topology is designed to deliver maximum performance while ensuring that the **at least once**
 guarantee provided by RabbitMQ is maintained.
 
-> Topology design assumes that unanswered Requests and unconfirmed Events will be resent upon
-> reconnection.
+> Topology design assumes that unanswered Requests and unconfirmed Events will be retransmitted
+> upon reconnection.
 
 ### Dynamic
 
@@ -244,23 +289,23 @@ See:
 ### Cheatsheet
 
 | Message | Prefetch  | Confirms | Queue     | Acknowledgment | Persistent |
-|---------|-----------|----------|-----------|-----------------|------------|
-| Request | limited   | no       | durable   | manual          | no         |
-| Reply   | unlimited | no       | exclusive | automatic       | no         |
-| Event   | limited   | yes      | durable   | manual          | yes        |
+|---------|-----------|----------|-----------|----------------|------------|
+| Request | limited   | no       | durable   | manual         | no         |
+| Reply   | unlimited | no       | exclusive | automatic      | no         |
+| Event   | limited   | yes      | durable   | manual         | yes        |
 
 ## Graceful Shutdown
 
 ### Sealing
 
-`async IO.seal()`
+`async IO.seal(): void`
 
 [Stop receiving](https://amqp-node.github.io/amqplib/channel_api.html#channel_cancel) new Events and
 Requests.
 
 ### Disconnection
 
-`async IO.close()`
+`async IO.close(): void`
 
 1. Call `IO.seal()`.
 2. Wait for any outstanding messages to be processed[^2] and acknowledged. Sending Requests,
@@ -295,19 +340,24 @@ calling `IO.close()`.
 
 Subscribe to one of the diagnostic events:
 
-- `open`: connection is restored[^3].
+- `open`: connection is opened[^3].
 - `close`: connection is closed.
   Optional [`error`](https://amqp-node.github.io/amqplib/channel_api.html#model_events) is passed
   as an argument.
 - `flow`: back pressure is applied to a channel. [Channel type](./types/topology.d.ts) is passed as
   an argument.
 - `drain`: back pressure is removed from a channel. Channel type is passed.
+- `remove`: channel is removed from the [pool](#sharded-connection).
 - `recover`: channel's topology is recovered. Channel type is passed.
 - `discard`: message is [discarded](#messages) as it repeatedly caused
   exceptions. Channel type,
   raw [amqp message object](https://amqp-node.github.io/amqplib/channel_api.html#channel_consume)
   and the exception are passed as arguments.
 
+In the case of a [sharded connection](#sharded-connection), an additional argument specifying the
+shard number will be passed to listeners. The shard number corresponds to the number of the argument
+used in the `connect` function call.
+
 [^3]: As [`connect`](#connect) function returns an instance of `IO` *after* the connection has been
 established, there is no way to capture the initial `open` event.
 

package/source/channel.js

@@ -7,18 +7,29 @@ const { lazy, recall, promex, failsafe, immediate } = require('@toa.io/generic')
  * @implements {comq.Channel}
  */
 class Channel {
+  index
+
+  /** @type {comq.amqp.Connection} */
+  #connection
+
   /** @type {comq.Topology} */
   #topology
 
   /** @type {comq.amqp.Channel} */
   #channel
 
+  /** @type {boolean} */
+  #failfast
+
   /** @type {string[]} */
   #tags = []
 
   /** @type {toa.generic.Promex} */
   #paused
 
+  /** @type {boolean} */
+  #sealed = false
+
   /** @type {toa.generic.Promex} */
   #recovery = promex()
 
@@ -28,16 +39,23 @@ class Channel {
   #diagnostics = new EventEmitter()
 
   /**
+   * @param {comq.amqp.Connection} connection
    * @param {comq.Topology} topology
+   * @param {number} index
    */
-  constructor (topology) {
+  constructor (connection, topology, index) {
+    this.index = index
+
+    this.#connection = connection
     this.#topology = topology
-  }
+    this.#failfast = index !== undefined
 
-  async create (connection) {
-    const method = `create${this.#topology.confirms ? 'Confirm' : ''}Channel`
+    if (this.#failfast) failsafe.disable(this.send, this.publish)
+  }
 
-    this.#channel = await connection[method]()
+  async create () {
+    if (this.#topology.confirms) this.#channel = await this.#connection.createConfirmChannel()
+    else this.#channel = await this.#connection.createChannel()
   }
 
   consume = recall(this,
@@ -48,7 +66,7 @@ class Channel {
          * @param {comq.channels.consumer} callback
          */
         async (queue, callback) => {
-          await this.#consume(queue, callback)
+          if (!this.#sealed) await this.#consume(queue, callback)
         })))
 
   subscribe = recall(this,
@@ -61,7 +79,7 @@ class Channel {
          * @returns {Promise<void>}
          */
         async (exchange, queue, callback) => {
-          await this.#consume(queue, callback)
+          if (!this.#sealed) await this.#consume(queue, callback)
         })))
 
   send = failsafe(this, this.#recover,
@@ -80,7 +98,7 @@ class Channel {
       /**
        * @param {string} exchange
        * @param {Buffer} buffer
-       * @param {import('amqplib').Options.Publish} [options]
+       * @param {comq.amqp.options.Publish} [options]
        */
       async (exchange, buffer, options) => {
         await this.#publish(exchange, DEFAULT, buffer, options)
@@ -89,15 +107,18 @@ class Channel {
   async throw (queue, buffer, options) {
     try {
       await this.#publish(DEFAULT, queue, buffer, options)
-    } catch {
-      // whatever
+    } catch (exception) {
+      if (this.#failfast) throw exception
+      // ignore otherwise
     }
   }
 
   async seal () {
+    this.#sealed = true
+
     const cancellations = this.#tags.map((tag) => this.#channel.cancel(tag))
 
-    await Promise.all(cancellations)
+    await Promise.all(cancellations).catch(noop) // won't recover anyway
   }
 
   diagnose (event, listener) {
@@ -105,16 +126,18 @@ class Channel {
   }
 
   async recover (connection) {
-    await this.create(connection)
+    this.#connection = connection
+
+    await this.create()
 
     lazy.reset(this)
     await recall(this)
 
-    this.#unpause(REJECTION)
+    this.#unpause(INTERRUPTION)
 
-    for (const confirmation of this.#confirmations) confirmation.reject(REJECTION)
+    for (const confirmation of this.#confirmations) confirmation.reject(INTERRUPTION)
 
-    // let unpause and confirmation rejections be handled
+    // let unpause and confirmation interruptions be handled
     await immediate()
 
     this.#recovery.resolve()
@@ -142,7 +165,7 @@ class Channel {
    * @returns {Promise<void>}
    */
   async #assertExchange (exchange) {
-    /** @type {import('amqplib').Options.AssertExchange} */
+    /** @type {comq.amqp.options.Exchange} */
     const options = { durable: this.#topology.durable }
 
     await this.#channel.assertExchange(exchange, 'fanout', options)
@@ -208,7 +231,7 @@ class Channel {
    * @returns {Promise<void>}
    */
   async #consume (queue, consumer) {
-    /** @type {import('amqplib').Options.Consume} */
+    /** @type {comq.amqp.options.Consume} */
     const options = {}
 
     if (this.#topology.acknowledgments) consumer = this.#getAcknowledgingConsumer(consumer)
@@ -230,7 +253,7 @@ class Channel {
 
         this.#channel.ack(message)
       } catch (exception) {
-        if (exception.message === 'Channel closed') return // message will be requeued by the broker
+        if (exception.message === 'Channel closed') return // the message will be requeued by the broker
 
         if (message.fields.redelivered) this.#discard(message, exception)
         else this.#requeue(message)
@@ -238,14 +261,14 @@ class Channel {
     }
 
   /**
-   * @param {import('amqplib').ConsumeMessage} message
+   * @param {comq.amqp.Message} message
    */
   #requeue (message) {
     this.#channel.nack(message, false, true)
   }
 
   /**
-   * @param {import('amqplib').ConsumeMessage} message
+   * @param {comq.amqp.Message} message
    * @param {Error} [exception]
    */
   #discard (message, exception) {
@@ -259,6 +282,8 @@ class Channel {
     this.#paused = promex()
     this.#channel.once('drain', this.#unpause)
     this.#diagnostics.emit('flow')
+
+    if (this.#failfast) throw INTERRUPTION
   }
 
   /**
@@ -276,20 +301,20 @@ class Channel {
 
   async #recover (exception) {
     if (permanent(exception)) return false
-
-    await this.#recovery
+    else await this.#recovery
   }
 }
 
 /**
  * @param {comq.amqp.Connection} connection
  * @param {comq.Topology} topology
+ * @param {number} [index]
  * @return {Promise<comq.Channel>}
  */
-const create = async (connection, topology) => {
-  const channel = new Channel(topology)
+async function create (connection, topology, index) {
+  const channel = new Channel(connection, topology, index)
 
-  await channel.create(connection)
+  await channel.create()
 
   return channel
 }
@@ -297,24 +322,23 @@ const create = async (connection, topology) => {
 /**
  * @return {boolean}
  */
-const permanent = (exception) => {
+function permanent (exception) {
   const closed = exception.message === 'Channel closed'
   const ended = exception.message === 'Channel ended, no reply will be forthcoming'
-  const internal = exception === REJECTION
-  const unpause = exception.pause === 1
+  const internal = exception === INTERRUPTION
 
-  return !closed && !ended && !internal && !unpause
+  return !closed && !ended && !internal
 }
 
 const DEFAULT = ''
 
-/** @type {import('amqplib').Options.AssertQueue} */
+/** @type {comq.amqp.options.Queue} */
 const DURABLE = { durable: true }
 
-/** @type {import('amqplib').Options.AssertQueue} */
+/** @type {comq.amqp.options.Queue} */
 const EXCLUSIVE = { exclusive: true }
 
-const REJECTION = /** @type {Error} */ Symbol('rejection')
+const INTERRUPTION = /** @type {Error} */ Symbol('internal interruption')
 
 function noop () {}
 

package/source/connect.js

@@ -2,14 +2,40 @@
 
 const { IO } = require('./io')
 const { Connection } = require('./connection')
+const shards = require('./shards')
 
 /** @type {comq.connect} */
-const connect = async (url) => {
-  const connection = new Connection(url)
+const connect = async (...urls) => {
+  const connection = create(urls)
 
   await connection.open()
 
   return new IO(connection)
 }
 
+/**
+ * @param {string[]} urls
+ * @return {comq.Connection}
+ */
+const create = (urls) => {
+  if (urls.length === 1) return single(urls[0])
+  else return sharded(urls)
+}
+
+/**
+ * @param {string} url
+ * @return {comq.Connection}
+ */
+const single = (url) => new Connection(url)
+
+/**
+ * @param {string[]} urls
+ * @return {comq.Connection}
+ */
+const sharded = (urls) => {
+  const connections = urls.map(single)
+
+  return new shards.Connection(connections)
+}
+
 exports.connect = connect

package/source/connection.js

@@ -4,7 +4,7 @@ const { EventEmitter } = require('node:events')
 const amqp = require('amqplib')
 const { retry, promex, failsafe } = require('@toa.io/generic')
 
-const presets = require('./presets')
+const presets = require('./topology')
 const channels = require('./channel')
 
 /**
@@ -14,7 +14,7 @@ class Connection {
   /** @type {string} */
   #url
 
-  /** @type {import('amqplib').Connection} */
+  /** @type {comq.amqp.Connection} */
   #connection
 
   /** @type {comq.Channel[]} */
@@ -33,21 +33,26 @@ class Connection {
   }
 
   async open () {
-    await retry((retry) => this.#open(retry), RETRY)
+    await retry(this.#open, RETRY)
   }
 
   async close () {
-    try {
-      await this.#connection.close()
-    } catch (e) {
-      // connection already closed
-    }
+    if (this.#connection === undefined) await this.#recovery
+
+    await this.#connection.close()
   }
 
   createChannel = failsafe(this, this.#recover,
-    async (type) => {
-      const preset = presets[type]
-      const channel = await channels.create(this.#connection, preset)
+    /**
+     * @param {comq.topology.type} type
+     * @param {number} [index]
+     * @return {Promise<comq.Channel>}
+     */
+    async (type, index) => {
+      if (this.#connection === undefined) await this.#recovery
+
+      const topology = presets[type]
+      const channel = await channels.create(this.#connection, topology, index)
 
       this.#channels.push(channel)
 
@@ -59,9 +64,9 @@ class Connection {
   }
 
   /**
-   * @param {Function} retry
+   * @type {toa.generic.retry.Task}
    */
-  async #open (retry) {
+  #open = async (retry) => {
     try {
       this.#connection = await amqp.connect(this.#url)
     } catch (exception) {
@@ -69,11 +74,11 @@ class Connection {
       else throw exception
     }
 
-    this.#connection.on('close', this.#close)
-
     // prevents process crash, 'close' will be emitted next
     // https://amqp-node.github.io/amqplib/channel_api.html#model_events
-    this.#connection.on('error', () => undefined)
+    this.#connection.on('error', noop)
+
+    this.#connection.on('close', this.#close)
     this.#diagnostics.emit('open')
 
     for (const channel of this.#channels) await channel.recover(this.#connection)
@@ -87,8 +92,8 @@ class Connection {
    */
   #close = async (error) => {
     this.#diagnostics.emit('close', error)
-
     this.#connection.removeAllListeners()
+    this.#connection = undefined
 
     if (error !== undefined) await this.open()
   }
@@ -114,4 +119,6 @@ const transient = (exception) => {
   return refused || handshake
 }
 
+function noop () {}
+
 exports.Connection = Connection

package/source/decode.js

@@ -3,7 +3,7 @@
 const decoders = require('./encoders')
 
 /**
- * @param {import('amqplib').ConsumeMessage} message
+ * @param {comq.amqp.Message} message
  * @returns {any}
  */
 const decode = (message) => {

package/source/events.js

@@ -0,0 +1,7 @@
+'use strict'
+
+/** @type {comq.diagnostics.event[]} */
+exports.connection = ['open', 'close']
+
+/** @type {comq.diagnostics.event[]} */
+exports.channel = ['flow', 'drain', 'recover', 'discard']

package/source/io.js

@@ -6,6 +6,7 @@ const { lazy, track, failsafe, promex } = require('@toa.io/generic')
 
 const { decode } = require('./decode')
 const { encode } = require('./encode')
+const events = require('./events')
 const io = require('./.io')
 
 /**
@@ -38,7 +39,7 @@ class IO {
   constructor (connection) {
     this.#connection = connection
 
-    for (const event of CONNECTION_EVENTS) {
+    for (const event of events.connection) {
       this.#connection.diagnose(event, (...args) => this.#diagnostics.emit(event, ...args))
     }
   }
@@ -55,13 +56,14 @@ class IO {
       await this.#requests.consume(queue, consumer)
     })
 
+  // failsafe is aimed to retransmit unanswered messages
   request = lazy(this, [this.#createRequestReplyChannels, this.#consumeReplies],
     failsafe(this, this.#recover,
       /**
        * @param {string} queue
        * @param {any} payload
        * @param {comq.encoding} [encoding]
-       * @param {comq.ReplyToPropertyFormatter} replyToFormatter
+       * @param {comq.ReplyToPropertyFormatter} [replyToFormatter]
        * @returns {Promise<void>}
        */
       async (queue, payload, encoding, replyToFormatter) => {
@@ -123,7 +125,7 @@ class IO {
     this.#requests = await this.#createChannel('request')
     this.#replies = await this.#createChannel('reply')
 
-    this.#requests.diagnose('recover', this.#resend)
+    this.#setupRetransmission()
   }
 
   async #createEventChannel () {
@@ -148,13 +150,19 @@ class IO {
   async #createChannel (type) {
     const channel = await this.#connection.createChannel(type)
 
-    for (const event of CHANNEL_EVENTS) {
+    for (const event of events.channel) {
       channel.diagnose(event, (...args) => this.#diagnostics.emit(event, type, ...args))
     }
 
     return channel
   }
 
+  #setupRetransmission () {
+    const event = (this.#requests.sharded === true) ? 'remove' : 'recover'
+
+    this.#requests.diagnose(event, this.#retransmit)
+  }
+
   /**
    * @param {comq.producer} producer
    * @returns {comq.channels.consumer}
@@ -185,6 +193,9 @@ class IO {
    * @returns {comq.channels.consumer}
    */
   #getReplyConsumer = (queue, emitter) =>
+    /**
+     * @param {comq.amqp.Message} message
+     */
     (message) => {
       const payload = decode(message)
 
@@ -216,12 +227,14 @@ class IO {
   }
 
   #recover (exception) {
-    if (exception !== REJECTION) return false
+    if (exception !== RETRANSMISSION) return false
   }
 
-  #resend = () => {
+  #retransmit = () => {
     for (const emitter of Object.values(this.#emitters)) emitter.clear()
-    for (const reply of this.#pendingReplies) reply.reject(REJECTION)
+
+    // trigger failsafe attribute
+    for (const reply of this.#pendingReplies) reply.reject(RETRANSMISSION)
   }
 
   /**
@@ -246,13 +259,7 @@ const OCTETS = 'application/octet-stream'
 /** @type {comq.encoding} */
 const DEFAULT = 'application/msgpack'
 
-/** @type {comq.diagnostics.event[]} */
-const CONNECTION_EVENTS = ['open', 'close']
-
-/** @type {comq.diagnostics.event[]} */
-const CHANNEL_EVENTS = ['flow', 'drain', 'recover', 'discard']
-
-const REJECTION = /** @type {Error} */ Symbol('resend')
+const RETRANSMISSION = /** @type {Error} */ Symbol('retransmission')
 
 function noop () {}