comq 0.13.0 → 0.14.0

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'
+      - dev
 
-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
         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@v6
         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/.releaserc

@@ -0,0 +1,35 @@
+{
+  "branches": [
+    "dev"
+  ],
+  "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,11 @@
+# [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/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/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/shards.feature

@@ -41,7 +41,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,27 @@ 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 PAYLOAD = quantity('500k')
+const 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 = []
+  async function (queue) {
+    const buffer = randomBytes(PAYLOAD)
+    const deadline = Date.now() + DEADLINE
+    const pending = []
 
-    for (let i = 0; i < times; i++) {
-      const promise = this.io.request(queue, buffer)
+    while (!this.events.flow && Date.now() < deadline) {
+      for (let i = 0; i < BATCH; i++) { pending.push(this.io.request(queue, buffer).catch(() => {})) }
 
-      promises.push(promise)
-
-      if ((i + 1) % each === 0) await timeout(interval)
+      await timeout(0)
     }
 
-    await Promise.all(promises)
-  })
-
-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:3.10.0-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/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/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()
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comq",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "ComQ",
   "author": {
     "name": "Artem Gurtovoi",
@@ -24,17 +24,24 @@
   "main": "source/index.js",
   "types": "types/index.d.ts",
   "devDependencies": {
-    "@cucumber/cucumber": "^10.0.1",
-    "@toa.io/command": "^0.4.0",
-    "@toa.io/generic": "^1.0.0-alpha.0",
-    "@types/amqplib": "^0.10.3",
-    "@types/jest": "^29.5.8",
-    "husky": "^9.0.11",
-    "jest": "^29.5.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@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",
+    "@toa.io/generic": "^1.0.0-alpha.208",
+    "@types/amqplib": "^0.10.8",
+    "@types/jest": "^30.0.0",
+    "husky": "^9.1.7",
+    "jest": "^30.4.2",
     "js-yaml": "^4.1.1",
-    "randomstring": "^1.3.0",
+    "randomstring": "^1.3.1",
     "snazzy": "^9.0.0",
-    "standard": "^17.1.0"
+    "standard": "^17.1.2",
+    "testcontainers": "^12.0.0"
   },
   "dependencies": {
     "amqplib": "^2.0.1",
@@ -43,7 +50,7 @@
     "reretry": "^0.1.0"
   },
   "scripts": {
-    "prepare": "echo run: husky install",
+    "prepare": "husky",
     "test": "standard && jest",
     "features": "cucumber-js --fail-fast -t 'not @manual'",
     "lint": "standard --fix --verbose | snazzy"
@@ -52,8 +59,5 @@
     "env": [
       "jest"
     ]
-  },
-  "workspaces": [
-    "."
-  ]
+  }
 }

package/lerna.json

@@ -1,4 +0,0 @@
-{
-  "version": "0.12.0",
-  "conventionalCommits": true
-}