comq 0.13.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

@@ -1,73 +1,43 @@
 name: Release
 
 on:
-  pull_request:
-    types: [closed]
+  push:
     branches:
       - release
-      - alpha
-    paths:
-      - 'source/**'
-      - 'types/**'
-      - 'package-lock.json'
 
-env:
-  CI: 1
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+  id-token: write
 
 jobs:
-  publish:
-    if: github.event.pull_request.merged == true
+  release:
     runs-on: ubuntu-latest
+    env:
+      HUSKY: 0
 
     steps:
-      - name: Setup Node
-        uses: actions/setup-node@v6
-        with:
-          node-version: 20
-          registry-url: 'https://registry.npmjs.org'
-
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
+          persist-credentials: false
 
-      - name: Run tests
-        run: npm i && npm test
-
-      - name: Import GPG key
-        id: gpg
-        uses: crazy-max/ghaction-import-gpg@v6
+      - name: Setup Node
+        uses: actions/setup-node@v7
         with:
-          gpg_private_key: ${{ secrets.TOABOT_GPG_PRIVATE_KEY }}
-          passphrase: ${{ secrets.TOABOT_GPG_PASSPHRASE }}
-          git_user_signingkey: true
-          git_commit_gpgsign: true
+          node-version: "24"
+          registry-url: https://registry.npmjs.org
+          package-manager-cache: false
 
-      - name: Bump version
-        run: |
-          if [ ${{ github.base_ref }} = release ]; then
-            npx lerna@7.3.0 version --conventional-graduate --no-commit-hooks --no-changelog --yes --message "ci: %s" --sign-git-commit --sign-git-tag
-          else
-            npx lerna@7.3.0 version --conventional-prerelease --preid alpha --dist-tag alpha --no-commit-hooks --no-changelog --yes --message "ci: %s" --git-tag-command "echo %s" --sign-git-commit
-          fi
-          
-          git fetch
-          git checkout dev
-          git merge ${{ github.base_ref }}
-          git push --all origin --no-verify
-        env:
-          GITHUB_TOKEN: ${{ secrets.TOABOT_GITHUB_TOKEN }}
-          GIT_AUTHOR_NAME: ${{ steps.gpg.outputs.name }}
-          GIT_AUTHOR_EMAIL: ${{ steps.gpg.outputs.email }}
-          GIT_COMMITTER_NAME: ${{ steps.gpg.outputs.name }}
-          GIT_COMMITTER_EMAIL: ${{ steps.gpg.outputs.email }}
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
 
-      - name: Publish packages
+      - name: Semantic release
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: |
-          if [ ${{ github.base_ref }} = release ]; then
-            npm publish
-          else
-            npm publish --tag alpha
-          fi
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: npx semantic-release

package/.husky/pre-push

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

package/.releaserc

@@ -0,0 +1,35 @@
+{
+  "branches": [
+    "release"
+  ],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    [
+      "@semantic-release/changelog",
+      {
+        "changelogFile": "CHANGELOG.md"
+      }
+    ],
+    [
+      "@semantic-release/npm"
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": [
+          "package.json",
+          "package-lock.json",
+          "CHANGELOG.md"
+        ],
+        "message": "chore(release): ${nextRelease.version}\n\n${nextRelease.notes}"
+      }
+    ],
+    [
+      "@semantic-release/github",
+      {
+        "owner": "toa-io"
+      }
+    ]
+  ]
+}

package/AGENTS.md

@@ -0,0 +1,35 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+### Project Overview
+
+ComQ is a Node.js communication library over AMQP (RabbitMQ). It provides RPC, pub/sub, task queues, pipelines, and sharded connections.
+
+### Services
+
+Feature tests start two RabbitMQ instances automatically via Testcontainers (`features/steps/brokers.js`). Credentials: `developer` / `secret`. AMQP ports are assigned dynamically on the host.
+
+### Docker
+
+Feature tests require a running Docker daemon. In nested container environments, start Docker with:
+
+```bash
+sudo dockerd --exec-opt native.cgroupdriver=cgroupfs &
+sudo chmod 666 /var/run/docker.sock
+```
+
+Do not use `docker compose up` for feature tests — Testcontainers manages broker lifecycle. `docker compose` may fail here because `deploy.resources.limits.memory` requires cgroupv2 memory limits that are unavailable in nested setups.
+
+### Commands
+
+- `npm test` — runs `standard` (lint) + `jest` (300 unit tests, no RabbitMQ required)
+- `npm run features` — runs all Cucumber feature tests (starts RabbitMQ via Testcontainers)
+- `npm run lint` — runs `standard --fix --verbose | snazzy`
+
+### Testing Notes
+
+- Unit tests (`jest`) use mocks and do NOT require running RabbitMQ.
+- Feature tests (`cucumber-js`) start brokers in `BeforeAll` and stop them in `AfterAll`.
+- Recovery/connection tests (in `features/connection.feature`, `features/recovery.feature`, `features/shards.feature`) stop/kill broker containers and take 5-15 minutes to complete.
+- To run only fast feature tests (no broker stop/start): `npx cucumber-js --fail-fast -t 'not @manual' features/events.feature features/rpc.feature features/tasks.feature features/singleton.feature features/properties.feature features/tasks.shards.feature`

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# [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)
+
+
+### Features
+
+* **features:** manage RabbitMQ brokers with Testcontainers ([1d9ca59](https://github.com/toa-io/comq/commit/1d9ca591ff458c75caf87ab63224b15942ba7d07))
+* **features:** use Testcontainers for RabbitMQ in Gherkin tests ([#219](https://github.com/toa-io/comq/issues/219)) ([a33e66b](https://github.com/toa-io/comq/commit/a33e66bfc357f0f089c728bc60c08f6f24b2c8d1))
+
+# Changelog
+
+All notable changes to this project are documented in this file by [semantic-release](https://github.com/semantic-release/semantic-release).

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/backpressure.feature

@@ -8,5 +8,4 @@ Feature: Back pressure handling
     """
     () => { return Buffer.from('ok') }
     """
-    When I'm sending 500kB requests to the `flood` queue at 5kHz for 0.5 seconds
-    Then back pressure was applied
+    When I'm flooding the `flood` queue until back pressure is applied

package/features/connection.feature

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

package/features/readme.md

@@ -1,4 +1,11 @@
 # Features
 
-To run features, start the RabbitMQ server by running `docker compose up -d` in the package root,
-then execute `npm run features`.
+Feature tests start two RabbitMQ instances automatically via [Testcontainers](https://node.testcontainers.org/modules/rabbitmq/).
+
+Run them with:
+
+```bash
+npm run features
+```
+
+Docker must be available on the host. No manual `docker compose` setup is required.

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"
@@ -41,7 +43,7 @@ Feature: Sharded Connection
   Scenario: Shard crashes while publishing events
     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
+    And I'm publishing 1kB events to the `flood` exchange at 10Hz
     When one of the brokers has crashed
     Then no exceptions are thrown
     And all events have been received

package/features/steps/backpressure.js

@@ -4,43 +4,45 @@ const assert = require('node:assert')
 const { randomBytes } = require('node:crypto')
 const { quantity, timeout } = require('@toa.io/generic')
 
-const { When, Then } = require('@cucumber/cucumber')
+const { When } = require('@cucumber/cucumber')
 
-When('I\'m sending {quantity}B requests to the {token} queue at {quantity}Hz for {number} second(s)',
+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',
   /**
-   * @param {string} bytesQ
    * @param {string} queue
-   * @param {string} frequencyQ
-   * @param {number} seconds
    * @this {comq.features.Context}
    */
-  async function (bytesQ, queue, frequencyQ, seconds) {
-    const bytes = quantity(bytesQ)
-    const frequency = quantity(frequencyQ)
-    const buffer = randomBytes(bytes)
-    const times = seconds * frequency
-
-    // intervals less than 1ms are not accurate
-    const interval = Math.max((1000 / frequency), 1)
-    const each = Math.max(1 / (1000 / frequency), 1)
-
-    const promises = []
-
-    for (let i = 0; i < times; i++) {
-      const promise = this.io.request(queue, buffer)
-
-      promises.push(promise)
-
-      if ((i + 1) % each === 0) await timeout(interval)
+  async function (queue) {
+    const deadline = Date.now() + DEADLINE
+    const pending = []
+    const errors = []
+    let iteration = 0
+
+    while (!this.events.flow && Date.now() < deadline) {
+      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]
     }
 
-    await Promise.all(promises)
-  })
+    if (errors.length > 0) throw errors[0]
 
-Then('back pressure was applied',
-  /**
-   * @this {comq.features.Context}
-   */
-  function () {
     assert.equal(this.events.flow, true, 'Back pressure hasn\'t been applied')
   })

package/features/steps/broker.js

@@ -1,13 +1,13 @@
 'use strict'
 
-const { timeout, random } = require('@toa.io/generic')
-const { execute } = require('@toa.io/command')
+const { random } = require('@toa.io/generic')
 
 const { Given } = require('@cucumber/cucumber')
+const { BROKERS_AMOUNT, actions } = require('./brokers')
 
 Given('the broker is/has {status}',
   /**
-   * @param {'up' | 'down'} status
+   * @param {'up' | 'down' | 'crashed'} status
    * @this {comq.features.Context}
    */
   async function (status) {
@@ -18,7 +18,7 @@ Given('the broker is/has {status}',
 
 Given('one of the brokers is/has {status}',
   /**
-   * @param {'up' | 'down'} status
+   * @param {'up' | 'down' | 'crashed'} status
    * @this {comq.features.Context}
    */
   async function (status) {
@@ -28,29 +28,3 @@ Given('one of the brokers is/has {status}',
 
     await actions[status](shard)
   })
-
-const actions = {
-  up: async (n = 0) => {
-    await execute('docker start comq-rmq-' + n)
-    await healthy(n)
-  },
-  down: async (n = 0) => {
-    await execute('docker stop comq-rmq-' + n)
-  },
-  crashed: async (n = 0) => {
-    await execute('docker kill comq-rmq-' + n)
-  }
-}
-
-async function healthy (n) {
-  let process
-
-  do {
-    await timeout(HEALTHCHECK_INTERVAL)
-
-    process = await execute('docker inspect -f {{.State.Health.Status}} comq-rmq-' + n)
-  } while (process.output !== 'healthy')
-}
-
-const BROKERS_AMOUNT = 2
-const HEALTHCHECK_INTERVAL = global.COMQ_TESTING_HEALTHCHECK_INTERVAL ?? 1000

package/features/steps/brokers.js

@@ -0,0 +1,125 @@
+'use strict'
+
+const { execFile } = require('node:child_process')
+const { promisify } = require('node:util')
+const { timeout } = require('@toa.io/generic')
+const { RabbitMQContainer } = require('@testcontainers/rabbitmq')
+const { getContainerRuntimeClient } = require('testcontainers')
+
+const docker = promisify(execFile)
+
+const IMAGE = 'rabbitmq:4.3-management'
+const USER = 'developer'
+const PASSWORD = 'secret'
+const AMQP_PORT = 5672
+const BROKERS_AMOUNT = 2
+const HOST_PORTS = [5673, 5674]
+const HEALTHCHECK_INTERVAL = global.COMQ_TESTING_HEALTHCHECK_INTERVAL ?? 1000
+
+/** @type {import('@testcontainers/rabbitmq').StartedRabbitMQContainer[]} */
+const brokers = []
+
+async function startBrokers () {
+  if (brokers.length > 0) return
+
+  for (let n = 0; n < BROKERS_AMOUNT; n++) await removeStale(`comq-rmq-${n}`)
+
+  const started = await Promise.all(
+    HOST_PORTS.map((hostPort, n) =>
+      new RabbitMQContainer(IMAGE)
+        .withEnvironment({
+          RABBITMQ_DEFAULT_USER: USER,
+          RABBITMQ_DEFAULT_PASS: PASSWORD
+        })
+        .withAutoRemove(false)
+        .withName(`comq-rmq-${n}`)
+        .withExposedPorts({ container: AMQP_PORT, host: hostPort })
+        .withHealthCheck({
+          test: ['CMD', 'rabbitmq-diagnostics', '-q', 'ping'],
+          interval: 5000,
+          timeout: 1000,
+          retries: 5
+        })
+        .start()
+    )
+  )
+
+  brokers.push(...started)
+
+  await Promise.all(
+    Array.from({ length: BROKERS_AMOUNT }, (_, n) => healthy(n))
+  )
+}
+
+async function stopBrokers () {
+  await Promise.all(brokers.map((broker) => broker.stop({ remove: true })))
+  brokers.length = 0
+}
+
+/**
+ * @param {string} name
+ */
+async function removeStale (name) {
+  const client = await getContainerRuntimeClient()
+  const listed = await client.container.list()
+
+  for (const info of listed) {
+    if (!info.Names.some((entry) => entry === `/${name}`)) continue
+
+    const container = client.container.getById(info.Id)
+
+    try {
+      await client.container.stop(container, { timeout: 0 })
+    } catch {
+      // already stopped
+    }
+
+    await container.remove({ force: true })
+  }
+}
+
+/**
+ * @param {number} [n]
+ * @returns {string}
+ */
+function getAddress (n = 0) {
+  if (brokers[n] === undefined) throw new Error(`Broker ${n} is not started`)
+
+  return `localhost:${HOST_PORTS[n]}`
+}
+
+/**
+ * @param {number} [n]
+ */
+async function healthy (n = 0) {
+  do {
+    await timeout(HEALTHCHECK_INTERVAL)
+
+    const { stdout } = await docker('docker', ['inspect', '-f', '{{.State.Health.Status}}', `comq-rmq-${n}`])
+
+    if (stdout.trim() === 'healthy') return
+  } while (true)
+}
+
+const actions = {
+  up: async (n = 0) => {
+    await docker('docker', ['start', `comq-rmq-${n}`])
+    await healthy(n)
+  },
+  down: async (n = 0) => {
+    await docker('docker', ['stop', `comq-rmq-${n}`])
+  },
+  crashed: async (n = 0) => {
+    await docker('docker', ['kill', `comq-rmq-${n}`])
+  }
+}
+
+module.exports = {
+  BROKERS_AMOUNT,
+  USER,
+  PASSWORD,
+  startBrokers,
+  stopBrokers,
+  getAddress,
+  actions
+}

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/context.js

@@ -2,6 +2,7 @@
 
 const { World } = require('@cucumber/cucumber')
 const { connect, assert } = require('../../')
+const { getAddress, USER, PASSWORD } = require('./brokers')
 
 /**
  * @implements {comq.features.Context}
@@ -88,14 +89,11 @@ class Context extends World {
   }
 
   #url (i, user, password) {
-    return PROTOCOL + user + ':' + password + '@' + SHARDS[i]
+    return PROTOCOL + user + ':' + password + '@' + getAddress(i)
   }
 }
 
 const PROTOCOL = 'amqp://'
-const SHARDS = ['localhost:5673', 'localhost:5674']
-const USER = 'developer'
-const PASSWORD = 'secret'
 
 /** @type {comq.diagnostics.Event[]} */
 const EVENTS = ['open', 'close', 'flow', 'discard']

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/hooks.js

@@ -1,11 +1,24 @@
 'use strict'
 
-const { After } = require('@cucumber/cucumber')
+const { BeforeAll, After, AfterAll } = require('@cucumber/cucumber')
+const { startBrokers, stopBrokers, actions, BROKERS_AMOUNT } = require('./brokers')
+
+BeforeAll({ timeout: 120_000 }, async function () {
+  await startBrokers()
+})
 
 After(
   /**
    * @this {comq.features.Context}
    */
   async function () {
+    await Promise.all(
+      Array.from({ length: BROKERS_AMOUNT }, (_, n) => actions.up(n))
+    )
+
     await this.disconnect()
   })
+
+AfterAll(async function () {
+  await stopBrokers()
+})