comq 0.14.0 → 0.15.0

package/.github/workflows/dev.yaml

@@ -0,0 +1,28 @@
+name: Dev
+
+on:
+  push:
+    branches:
+      - dev
+
+jobs:
+  features-fast:
+    runs-on: ubuntu-latest
+    env:
+      HUSKY: 0
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Setup Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: "24"
+          package-manager-cache: false
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run fast feature tests
+        run: npm run features:fast

package/.github/workflows/release.yaml

@@ -3,7 +3,7 @@ name: Release
 on:
   push:
     branches:
-      - dev
+      - release
 
 permissions:
   contents: write
@@ -19,13 +19,13 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup Node
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v7
         with:
           node-version: "24"
           registry-url: https://registry.npmjs.org

package/.husky/pre-push

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+
+[ -n "$CI" ] && exit 0
+
+npm run features:fast

package/.releaserc

@@ -1,6 +1,6 @@
 {
   "branches": [
-    "dev"
+    "release"
   ],
   "plugins": [
     "@semantic-release/commit-analyzer",

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+# [0.15.0](https://github.com/toa-io/comq/compare/v0.14.0...v0.15.0) (2026-08-01)
+
+
+### Bug Fixes
+
+* avoid channel recover deadlock after broker restart ([8eeaf2e](https://github.com/toa-io/comq/commit/8eeaf2e12321be71b57913adb6a8fb04bd24d439)), closes [#recovery](https://github.com/toa-io/comq/issues/recovery)
+* destroy half-open connections via socket idle watchdog ([9f7ed5f](https://github.com/toa-io/comq/commit/9f7ed5fe50e9ab1857547a6e908185b6b472162f))
+* ignore close events from replaced AMQP connections ([c1070ab](https://github.com/toa-io/comq/commit/c1070abeca9eb30a1c0ed07925bc06e530c1d9ce))
+* reconnect hang after broker restart ([#235](https://github.com/toa-io/comq/issues/235)) ([be07079](https://github.com/toa-io/comq/commit/be07079863194301d0279e2bdd551260196ce20a))
+* retry transient network errors on initial connect ([c436a20](https://github.com/toa-io/comq/commit/c436a2017a2b52d102afa05bc694c9f22faf2065)), closes [#transient](https://github.com/toa-io/comq/issues/transient)
+* tolerate empty YAML documents after js-yaml 5 bump ([0a05ecb](https://github.com/toa-io/comq/commit/0a05ecbf744822b3aa884382642ce51a93922dfc))
+
+
+### Features
+
+* allow request() to time out pending replies ([ac9e2bd](https://github.com/toa-io/comq/commit/ac9e2bd7eb0834d19d404c84f24548bd5475017f))
+* tag container-manipulation features [@heavy](https://github.com/heavy) and add features:fast script ([c0f52ec](https://github.com/toa-io/comq/commit/c0f52ecf72c010e387e853b3daed6884c1cef474))
+
 # [0.14.0](https://github.com/toa-io/comq/compare/v0.13.0...v0.14.0) (2026-05-24)
 
 

package/docker-compose.yaml

@@ -1,6 +1,6 @@
 services:
   rabbitmq-0:
-    image: rabbitmq:3.10.0-management
+    image: rabbitmq:4.3-management
     container_name: comq-rmq-0
     ports:
       - '5673:5672'
@@ -18,7 +18,7 @@ services:
         limits:
           memory: 512MB
   rabbitmq-1:
-    image: rabbitmq:3.10.0-management
+    image: rabbitmq:4.3-management
     container_name: comq-rmq-1
     ports:
       - '5674:5672'

package/features/connection.feature

@@ -1,3 +1,4 @@
+@heavy
 Feature: Connection Tolerance
 
   Scenario: Connect

package/features/recovery.feature

@@ -1,3 +1,4 @@
+@heavy
 Feature: Request-Reply Topology Recovery
 
   Background:

package/features/rpc.streams.feature

@@ -64,6 +64,7 @@ Feature: Reply streams
     And after 200ms
     Then the generator is destroyed
 
+  @heavy
   Scenario: Broker crashes while streaming reply
     Given a number generator with 90ms increasing delay replying `get_numbers` queue
     When the consumer requests a stream with request to the `get_numbers` queue

package/features/rpc.streams.shards.feature

@@ -21,6 +21,7 @@ Feature: Reply streams over shards
       [0, 1, 2, 3, 4]
       """
 
+  @heavy
   Scenario: Broker crashes while fetching a stream
     Given a number generator with 90ms increasing delay replying `get_numbers` queue
     When the consumer requests a stream with request to the `get_numbers` queue

package/features/shards.feature

@@ -1,3 +1,4 @@
+@heavy
 Feature: Sharded Connection
 
   Scenario: Establishing sharded connection
@@ -5,9 +6,10 @@ Feature: Sharded Connection
 
   Scenario: Connecting while a shard is down
     Given one of the brokers has crashed
-    When I attempt to establish sharded connection
-    Then an exception is thrown: "ECONNREFUSED"
-    Then the broker is up
+    When I attempt to establish sharded connection for 1 second
+    Then the connection is not established
+    When the broker is up
+    Then the connection is established
 
   Scenario: Connecting with wrong credentials
     When I attempt to establish a sharded connection as "someone" with password "whatever"

package/features/steps/backpressure.js

@@ -6,8 +6,8 @@ const { quantity, timeout } = require('@toa.io/generic')
 
 const { When } = require('@cucumber/cucumber')
 
-const PAYLOAD = quantity('500k')
-const BATCH = 20
+const BASE_PAYLOAD = quantity('500k')
+const BASE_BATCH = 20
 const DEADLINE = 25_000
 
 When('I\'m flooding the {token} queue until back pressure is applied',
@@ -16,15 +16,33 @@ When('I\'m flooding the {token} queue until back pressure is applied',
    * @this {comq.features.Context}
    */
   async function (queue) {
-    const buffer = randomBytes(PAYLOAD)
     const deadline = Date.now() + DEADLINE
     const pending = []
+    const errors = []
+    let iteration = 0
 
     while (!this.events.flow && Date.now() < deadline) {
-      for (let i = 0; i < BATCH; i++) { pending.push(this.io.request(queue, buffer).catch(() => {})) }
+      if (errors.length > 0) throw errors[0]
 
+      const payload = BASE_PAYLOAD * (iteration + 1)
+      const batch = BASE_BATCH * (iteration + 1)
+      const buffer = randomBytes(payload)
+
+      for (let i = 0; i < batch; i++) {
+        pending.push(
+          this.io.request(queue, buffer).catch((exception) => {
+            errors.push(exception)
+          })
+        )
+      }
+
+      iteration++
       await timeout(0)
+
+      if (errors.length > 0) throw errors[0]
     }
 
+    if (errors.length > 0) throw errors[0]
+
     assert.equal(this.events.flow, true, 'Back pressure hasn\'t been applied')
   })

package/features/steps/brokers.js

@@ -8,7 +8,7 @@ const { getContainerRuntimeClient } = require('testcontainers')
 
 const docker = promisify(execFile)
 
-const IMAGE = 'rabbitmq:3.10.0-management'
+const IMAGE = 'rabbitmq:4.3-management'
 const USER = 'developer'
 const PASSWORD = 'secret'
 const AMQP_PORT = 5672

package/features/steps/connection.js

@@ -88,6 +88,21 @@ When('I attempt to establish sharded connection',
     await connect(this)
   })
 
+When('I attempt to establish sharded connection for {number} second(s)',
+  /**
+   * @param {number} interval
+   * @this {comq.features.Context}
+   */
+  async function (interval) {
+    this.sharded = true
+
+    const gap = timeout(interval * 1000)
+
+    this.connecting = connect(this)
+
+    await Promise.any([this.connecting, gap])
+  })
+
 When('I attempt to establish a sharded connection as {string} with password {string}',
   /**
    * @param {string} user

package/features/steps/events.js

@@ -4,7 +4,7 @@ const stream = require('node:stream')
 const assert = require('node:assert')
 const { randomBytes } = require('node:crypto')
 const { timeout, quantity, match } = require('@toa.io/generic')
-const { load: parse } = require('js-yaml')
+const { parse } = require('./yaml')
 const { Given, When, Then } = require('@cucumber/cucumber')
 
 Given('(that ){token} is consuming events from the {token} exchange',

package/features/steps/rpc.js

@@ -3,7 +3,7 @@
 const stream = require('node:stream')
 const assert = require('node:assert')
 const { randomBytes } = require('node:crypto')
-const { load: parse } = require('js-yaml')
+const { parse } = require('./yaml')
 const { match, timeout, quantity } = require('@toa.io/generic')
 const { Given, When, Then } = require('@cucumber/cucumber')
 const { Readable } = require('node:stream')

package/features/steps/yaml.js

@@ -0,0 +1,15 @@
+'use strict'
+
+const { load } = require('js-yaml')
+
+/**
+ * @param {string} [yaml]
+ * @returns {any}
+ */
+function parse (yaml) {
+  if (yaml === undefined || yaml.trim() === '') return undefined
+
+  return load(yaml)
+}
+
+exports.parse = parse

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comq",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "ComQ",
   "author": {
     "name": "Artem Gurtovoi",
@@ -23,29 +23,34 @@
   },
   "main": "source/index.js",
   "types": "types/index.d.ts",
+  "bin": {
+    "feat": "scripts/feat.js"
+  },
   "devDependencies": {
-    "@semantic-release/changelog": "^6.0.3",
+    "@cucumber/cucumber": "^13.2.0",
+    "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.2",
     "@semantic-release/npm": "^13.1.2",
     "@semantic-release/release-notes-generator": "^14.1.0",
-    "@cucumber/cucumber": "^12.9.0",
-    "@testcontainers/rabbitmq": "^12.0.0",
+    "@testcontainers/rabbitmq": "^12.0.4",
     "@toa.io/generic": "^1.0.0-alpha.208",
     "@types/amqplib": "^0.10.8",
     "@types/jest": "^30.0.0",
+    "fast-glob": "^3.3.3",
+    "fuzzysort": "3.1.0",
     "husky": "^9.1.7",
     "jest": "^30.4.2",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^5.2.3",
     "randomstring": "^1.3.1",
     "snazzy": "^9.0.0",
     "standard": "^17.1.2",
-    "testcontainers": "^12.0.0"
+    "testcontainers": "^12.0.4"
   },
   "dependencies": {
     "amqplib": "^2.0.1",
-    "msgpackr": "^2.0.1",
+    "msgpackr": "^2.0.5",
     "promex": "^0.1.1",
     "reretry": "^0.1.0"
   },
@@ -53,6 +58,7 @@
     "prepare": "husky",
     "test": "standard && jest",
     "features": "cucumber-js --fail-fast -t 'not @manual'",
+    "features:fast": "cucumber-js --fail-fast -t 'not @manual and not @heavy'",
     "lint": "standard --fix --verbose | snazzy"
   },
   "standard": {

package/readme.md

@@ -103,10 +103,11 @@ await io.reply('add_numbers', ({ a, b }) => (a + b))
 
 ## Request
 
-`async IO.request(queue: string, payload: any, encoding?: string): any`
+`async IO.request(queue: string, payload: any, encoding?: string, timeout?: number): any`
 
 Send encoded Request message with `replyTo` and `correlationId` properties set and
-return decoded Reply content.
+return decoded Reply content. Optional `timeout` (ms) rejects with `ETIMEDOUT` if no
+Reply arrives in time; encoding may be omitted when only `timeout` is passed.
 
 On the initial call, queues for Requests and Replies are asserted.
 
@@ -114,6 +115,7 @@ On the initial call, queues for Requests and Replies are asserted.
 
 ```javascript
 const sum = await io.request('add_numbers', { a: 1, b: 2 })
+const sumOrTimeout = await io.request('add_numbers', { a: 1, b: 2 }, 5000)
 ```
 
 ## Consumption
@@ -329,14 +331,15 @@ 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 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.
+remaining shards in the pool. If no shards are available, `send` / `publish` / `request` wait until a shard's
+connection is re-established (unbounded). For RPC, pass a [`request` timeout](#request) so callers fail with
+`ETIMEDOUT` instead of hanging while the pool is empty or a Reply never arrives.
 
 Incoming messages are consumed from all shards.
 
 `async connect(...shards: string[]): IO`
 
-Returns an instance of `IO` once a successful connection to one of the shards is established.
+Returns an instance of `IO` once connections to the shards are established.
 
 ### Example
 

package/scripts/feat.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+'use strict'
+
+const { spawnSync } = require('node:child_process')
+const path = require('node:path')
+const fg = require('fast-glob')
+const fuzzysort = require('fuzzysort')
+
+const ROOT = path.resolve(__dirname, '..')
+const USAGE = 'Usage: feat <query> [name] [cucumber-args...]'
+
+function toKey (file) {
+  return path.relative(ROOT, file)
+    .replace(/^features\//, '')
+    .replace(/\.feature$/, '')
+    .replace(/\./g, '/')
+}
+
+function normalizeQuery (query) {
+  return query.replace(/\./g, '/').replace(/\\/g, '/')
+}
+
+async function main () {
+  const args = process.argv.slice(2)
+  const dashIndex = args.findIndex((arg) => arg.startsWith('-'))
+  const positional = dashIndex === -1 ? args : args.slice(0, dashIndex)
+  const query = positional[0]
+  const name = positional[1]
+
+  const cucumberArgs = [
+    ...(name ? ['--name', name] : []),
+    ...positional.slice(2),
+    ...(dashIndex === -1 ? [] : args.slice(dashIndex))
+  ]
+
+  if (!query) {
+    console.error(USAGE)
+    process.exit(1)
+  }
+
+  const files = await fg('features/**/*.feature', { cwd: ROOT, absolute: true })
+  const items = files.map((file) => ({ file, key: toKey(file) }))
+  const result = fuzzysort.go(normalizeQuery(query), items, { key: 'key', limit: 1 })
+
+  if (result.length === 0) {
+    console.error(`No feature files match "${query}"`)
+    process.exit(1)
+  }
+
+  const selected = result.map(({ obj }) => obj.file)
+
+  for (const file of selected) { console.error(path.relative(ROOT, file)) }
+
+  const cucumberBin = path.join(ROOT, 'node_modules', '.bin', 'cucumber-js')
+
+  const run = spawnSync(cucumberBin, [...selected, ...cucumberArgs], {
+    cwd: ROOT,
+    stdio: 'inherit'
+  })
+
+  process.exit(run.status ?? 1)
+}
+
+main().catch((error) => {
+  console.error(error.message)
+  process.exit(1)
+})

package/source/channel.js

@@ -34,6 +34,9 @@ class Channel {
   /** @type {Promex} */
   #recovery = new Promex()
 
+  /** @type {boolean} */
+  #recovering = false
+
   /** @type {Set<Promex>} */
   #confirmations = new Set()
 
@@ -145,7 +148,14 @@ class Channel {
     await this.create()
 
     lazy.reset(this)
-    await recall(this)
+
+    this.#recovering = true
+
+    try {
+      await recall(this)
+    } finally {
+      this.#recovering = false
+    }
 
     this.#unpause(INTERRUPTION)
 
@@ -332,6 +342,7 @@ class Channel {
 
   async #recover (exception) {
     if (permanent(exception)) return false
+    if (this.#recovering) return false
     else await this.#recovery
   }
 }

package/source/connection.js

@@ -25,9 +25,15 @@ class Connection {
   /** @type {Promex} */
   #recovery = new Promex()
 
+  /** @type {Promise<void> | null} */
+  #opening = null
+
   /** @type {boolean} */
   #running = false
 
+  /** @type {NodeJS.Timeout | null} */
+  #heartbeatTimer = null
+
   #diagnostics = emitter.create()
 
   /**
@@ -35,10 +41,17 @@ class Connection {
    */
   constructor (url) {
     this.#url = url
+
+    // EventEmitter throws on 'error' with no listeners
+    this.#diagnostics.on('error', noop)
   }
 
   async open () {
-    await retry(this.#open)
+    if (this.#opening !== null) return this.#opening
+
+    this.#opening = retry(this.#open).finally(() => { this.#opening = null })
+
+    await this.#opening
 
     this.#running = true
   }
@@ -71,8 +84,11 @@ class Connection {
   }
 
   #open = async (retry) => {
+    /** @type {comq.amqp.Connection} */
+    let connection
+
     try {
-      this.#connection = await amqp.connect(this.#url)
+      connection = await amqp.connect(this.#url)
     } catch (exception) {
       if (this.#transient(exception)) return retry
       else throw exception
@@ -80,40 +96,104 @@ class Connection {
 
     // 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)
+    connection.on('error', noop)
 
-    this.#connection.on('close', this.#close)
+    connection.on('close', (error) => this.#close(connection, error))
+    this.#connection = connection
+    this.#armWatchdog(connection)
     this.#diagnostics.emit('open')
 
-    for (const channel of this.#channels) await channel.recover(this.#connection)
+    try {
+      for (const channel of this.#channels) await channel.recover(connection)
+    } catch (exception) {
+      this.#disarmWatchdog()
+      this.#diagnostics.emit('error', exception)
+      connection.removeAllListeners()
+
+      await connection.close().catch(noop)
+
+      if (this.#connection === connection) this.#connection = undefined
+
+      return retry
+    }
 
     this.#recovery.resolve()
     this.#recovery = new Promex()
   }
 
   /**
-   * @param {Error} error
+   * @param {comq.amqp.Connection} connection
+   * @param {Error} [error]
    */
-  #close = async (error) => {
+  #close = (connection, error) => {
+    this.#disarmWatchdog()
+
+    if (this.#connection !== connection) return
+
     this.#diagnostics.emit('close', error)
-    this.#connection.removeAllListeners()
+    connection.removeAllListeners()
     this.#connection = undefined
 
-    if (error !== undefined) await this.open()
+    if (error !== undefined) {
+      this.open().catch((exception) => this.#diagnostics.emit('error', exception))
+    }
   }
 
   #recover () {
     return this.#recovery
   }
 
+  /**
+   * @param {comq.amqp.Connection} connection
+   * @param {number} [timeoutMs]
+   */
+  #armWatchdog (connection, timeoutMs = WATCHDOG_MS) {
+    const socket = connection.connection?.stream
+
+    if (socket === undefined) return
+
+    const reset = () => {
+      clearTimeout(this.#heartbeatTimer)
+      this.#heartbeatTimer = setTimeout(() => socket.destroy(), timeoutMs)
+      this.#heartbeatTimer.unref()
+    }
+
+    reset()
+    socket.on('data', reset)
+  }
+
+  #disarmWatchdog () {
+    clearTimeout(this.#heartbeatTimer)
+    this.#heartbeatTimer = null
+  }
+
   #transient (exception) {
-    const abruptly = exception.message === 'Socket closed abruptly during opening handshake'
-    const tls = exception.message === 'Client network socket disconnected before secure TLS connection was established'
+    if (this.#running) return true
+    if (TRANSIENT_CODES.has(exception.code)) return true
+    if (TRANSIENT_MESSAGES.has(exception.message)) return true
 
-    return this.#running || abruptly || tls
+    return false
   }
 }
 
+/** @type {number} */
+const WATCHDOG_MS = 60_000
+
+const TRANSIENT_CODES = new Set([
+  'ECONNREFUSED',
+  'EAI_AGAIN',
+  'ENOTFOUND',
+  'ETIMEDOUT',
+  'ECONNRESET',
+  'EHOSTUNREACH',
+  'ENETUNREACH'
+])
+
+const TRANSIENT_MESSAGES = new Set([
+  'Socket closed abruptly during opening handshake',
+  'Client network socket disconnected before secure TLS connection was established'
+])
+
 function noop () {}
 
 exports.Connection = Connection

package/source/events.js

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