comq 0.23.0 → 0.24.0

package/discussions/amqp-1.0.md

@@ -0,0 +1,127 @@
+# AMQP 1.0
+
+**comq stays on AMQP 0-9-1 over [amqplib](https://github.com/amqp-node/amqplib).**
+
+RabbitMQ 4 speaks AMQP 1.0 natively and keeps 0-9-1 as a first-class protocol; both are
+supported out of the box and neither is on its way out. The choice is therefore comq's to make on
+what each protocol and each client gives it, and the answer today is that 1.0 costs a rewrite of
+the transport layer, changes comq's public API, breaks the wire between comq versions, and
+returns nothing comq uses.
+
+Two separate questions hide in "switch to the official client", and they have different answers.
+The client is unusable for comq today. The protocol is usable and in places cleaner, and still
+does not pay for itself.
+
+Measured on 2026-09-20 against RabbitMQ 4.3.6, with `rabbitmq-amqp-js-client` 1.0.0, `rhea` 3.0.5
+and `amqplib` 2.0.1.
+
+## The client
+
+[`rabbitmq-amqp-js-client`](https://github.com/coders51/rabbitmq-amqp-js-client) is listed among
+RabbitMQ's AMQP 1.0 client libraries and is maintained by coders51 rather than by the RabbitMQ
+team, unlike the Java, .NET, Go and Python clients. It is a thin wrapper over
+[rhea](https://github.com/amqp/rhea), which does the protocol.
+
+What it offers an application is a connection, a publisher, a consumer and a management link.
+What comq needs from a client, it does not reach:
+
+| comq | the client |
+|---|---|
+| 16 [diagnostic events](../readme.md#diagnostics) | connection, publisher and consumer state changes are unobservable ([#40](https://github.com/coders51/rabbitmq-amqp-js-client/issues/40)) |
+| [`seal`](../readme.md#sealing) stops consuming and waits | `Consumer.close` is synchronous and returns nothing ([#34](https://github.com/coders51/rabbitmq-amqp-js-client/issues/34)) |
+| topology recovered after a reconnect | the links come back, the topology does not ([#42](https://github.com/coders51/rabbitmq-amqp-js-client/issues/42)) |
+| prefetch 300, per channel | rhea's default credit window of 1000, fixed |
+| Requests and Replies are published unconfirmed | `publish` always awaits settlement |
+| `amqp://user:pass@host/vhost`, heartbeat 15s | host, port, username, password |
+
+Three defects it has today would each stop comq on its own:
+
+- **A publish to a queue that does not exist never settles.** The broker refuses the attach with
+  `amqp:not-found`; `createPublisher` resolves regardless, and the `publish` promise stays
+  pending forever.
+- **Attaching to another connection's exclusive queue kills the process.** `createConsumer`
+  resolves, the broker ends the session, and rhea emits an unhandled `error` on a container the
+  client keeps private. That is exactly what [`back`](../readme.md#addressed-requests) does on
+  every key already held.
+- **Every body goes out as an `amqp-value` section**, Buffers included, so a 0-9-1 consumer
+  receives the section bytes in front of the payload and `type: 'amqp-1.0'` among the properties.
+  A process on 0-9-1 and a process on the client cannot exchange a message, which rules out a
+  rolling migration. rhea with an explicit `data_section` interoperates cleanly, so this is the
+  client's message model rather than the protocol.
+
+Queue `arguments` are typed `Record<string, string>` while the broker requires integers for
+`x-message-ttl` (`expected integer, got longstr`) and accepts the numbers the typing forbids. The
+dependency on rhea is `github:amqp/rhea` — a git reference that resolves to `git+ssh` in a
+lockfile and builds on install, which would land in comq's dependency tree and in every CI that
+installs comq.
+
+Adopted with those gaps filled locally, "the official client" becomes "rhea, plus a management
+link we wrote" — which is the layer comq already is, over a client with fifteen years behind it.
+
+## The protocol
+
+Everything comq does is expressible over AMQP 1.0, and three mechanisms fit it better than 0-9-1
+does:
+
+- **An unroutable publish comes back as a `RELEASED` outcome on the send itself**, where 0-9-1
+  reports it asynchronously through `mandatory` and `basic.return` and comq has to correlate it.
+- **The `ttl` header is honoured per message**, so a [`call`](../readme.md#timeout)'s expiration
+  carries unchanged.
+- **Credit is granted per link**, which is what comq's [channel segregation](../readme.md#channels)
+  approximates with a prefetch count per channel.
+
+The rest holds: an exclusive queue declared over the management link is refused to a second
+connection (`400 cannot obtain exclusive access`), so `back` still holds a Key; numeric queue
+arguments are accepted, so the [retry ladder](../readme.md#retries) and `comq.parked` are
+unchanged. Streams with offsets and server-side filters are the one capability 0-9-1 cannot match,
+and comq consumes no streams.
+
+### What it costs
+
+**comq's public API is shaped by 0-9-1.** `Properties` is in the consumer signature, `emit`,
+`enqueue` and `route` take publish options, and `discard`, `retry` and `return` hand listeners a
+raw amqplib message. Every one of those changes, and so does what reads them — `@toa.io/bindings.amqp`
+reads `message.properties.correlationId` and `properties.headers`.
+
+**Message properties land elsewhere.** A 0-9-1 header prefixed `x-` arrives over 1.0 as a message
+annotation rather than an application property, beside the broker's own `x-exchange` and
+`x-routing-key`; `replyTo: 'rq'` arrives as `/queues/rq`. comq's [`x-comq-*` headers](../docs/headers.md)
+move with them.
+
+**The management UI and API stop reporting message rates** for AMQP 1.0 connections; queue depth
+survives, `message_stats` is null. Frame-intercepting plugins and transactions are 0-9-1 only,
+and comq uses neither.
+
+**The work is the transport layer and the unit suite.** `source/connection.js` and
+`source/channel.js` are 1,256 lines written against amqplib's channel API, `source/io.js` another
+797 that speak its vocabulary, and `test/` is built on `test/amqplib.mock.js` — some 6,400 lines
+that go with the thing they mock. The 88 scenarios in `features/` are behaviour-level and would
+carry over, which makes them the whole safety net for the change.
+
+### What it does not buy
+
+Throughput is level and the latency comq optimises for is worse. Same broker over loopback,
+20,000 messages of ~180 bytes, three runs, `TCP_NODELAY` on both:
+
+| | amqplib | rhea |
+|---|---|---|
+| publish, awaiting confirmation or settlement | 77–88k msg/s | 79–103k msg/s |
+| consume and acknowledge | 121–143k msg/s | 110–128k msg/s |
+
+Sequential request and reply, 2,000 round trips, one in flight:
+
+| | p50 | p99 |
+|---|---|---|
+| amqplib | 0.20 ms | 0.36–0.41 ms |
+| rhea | 0.26–0.29 ms | 0.51–0.57 ms |
+
+rhea enables `TCP_NODELAY` when a receiver is attached and leaves it to the `tcp_no_delay` option
+otherwise, so a connection that only publishes is left to Nagle — the same delay comq took out of
+amqplib in 0.20.1, and worth 22 ms per round trip when it is missed.
+
+## What would reverse this
+
+- comq needs RabbitMQ streams with server-side filtering.
+- The client exposes connection and link state, a consumer close that waits, a credit setting and
+  a vhost — the four things its own issues already name.
+- RabbitMQ announces an end for AMQP 0-9-1.

package/features/rpc.call.feature

@@ -65,7 +65,29 @@ Feature: Calls under a key
   Scenario: A caller stops waiting for a holder that crashed
     Given a holder never answering `void` under the `a` key
     When the consumer calls `void` under the `a` key with a 1000ms timeout
-    And after 100ms
+    And the silent holder has taken the call
     And the silent holder crashes
     Then the consumer stops waiting
     And a call to `void` under the `a` key is refused within 10 seconds
+
+  Scenario: A caller stops waiting at its timeout
+    Given a holder on another connection answering `slow` under the `a` key in 1000ms
+    When the consumer calls `slow` under the `a` key with a 200ms timeout
+    Then the consumer stops waiting
+
+  Scenario: A call its holder has not taken in time is never processed
+    Given a holder not taking `later` under the `a` key
+    When the consumer calls `later` under the `a` key with a 200ms timeout
+    Then the consumer stops waiting
+    When after 300ms
+    And the idle holder starts taking
+    Then the idle holder takes nothing
+
+  Scenario: A call abandoned by its signal stays in its queue
+    Given a holder not taking `stray` under the `a` key
+    When the consumer calls `stray` under the `a` key with a signal
+    And after 100ms
+    And the signal aborts
+    Then the consumer stops waiting for the aborted call
+    When the idle holder starts taking
+    Then the idle holder takes the call

package/features/rpc.call.recovery.feature

@@ -39,13 +39,6 @@ Feature: Calls under a key across failures
     And the broker is up
     Then the call ends
 
-  Scenario: A caller stops waiting for a request at its timeout while the broker is down
-    Given an active connection to the broker
-    And a producer replying `echo` queue
-    When the broker has crashed
-    And the consumer sends a request to the `echo` queue with a 1000ms timeout
-    Then the consumer stops waiting within 5 seconds
-
   Scenario: A caller stops waiting for a call at its timeout while the broker is down
     Given an active connection to the broker
     And a holder on another connection answering `echo` under the `a` key
@@ -53,20 +46,6 @@ Feature: Calls under a key across failures
     And the consumer calls `echo` under the `a` key with a 1000ms timeout
     Then the consumer stops waiting within 5 seconds
 
-  Scenario: A request re-sent after the broker restarts expires at its caller's deadline
-
-    The request is lost with the broker and sent again once the connection is restored, carrying
-    the time its caller has left.
-
-    Given an active connection to the broker
-    When the consumer sends a request to the `resent` queue with a 30000ms timeout
-    And after 200ms
-    And the broker has crashed
-    And the broker is up
-    Then the consumer stops waiting within 40 seconds
-    When a producer counting requests to the `resent` queue
-    Then the producer receives nothing
-
   Scenario: A call reaches its holder while one of the brokers is down
     Given an active sharded connection
     And a holder on another connection answering `echo` under the `a` key

package/features/rpc.parked.feature

@@ -5,13 +5,13 @@ Feature: Parked requests
 
   Scenario: A parked request can still be answered
 
-    A caller that sets no timeout is certain of an eventual answer for as long as it is
-    alive, and parking is what keeps that true when no consumer can produce one: the
-    request is kept, along with who was asking. Somebody else can answer it, and the
-    caller — still waiting, still holding an exclusive reply queue — receives it.
+    A caller is certain of an eventual answer for as long as it is alive, and parking
+    is what keeps that true when no consumer can produce one: the request is kept, along
+    with who was asking. Somebody else can answer it, and the caller — still waiting,
+    still holding an exclusive reply queue — receives it.
 
-    A caller that sets a timeout trades that for an end to the wait: once it stops
-    waiting, a parked request is addressed to a caller that has gone.
+    This is why a request has no timeout and cannot be withdrawn: either would leave the
+    parked message addressed to a caller that is no longer listening.
 
     Given a producer failing every request to the `unanswerable` queue
     When a request is sent to the `unanswerable` queue

package/features/steps/call.js

@@ -1,7 +1,7 @@
 'use strict'
 
 const assert = require('node:assert')
-const amqplib = require('amqplib')
+const amqplib = require('@toa.io/amqplib')
 const { Given, When, Then, After } = require('@cucumber/cucumber')
 
 const { connect, Unroutable } = require('../../')
@@ -84,11 +84,76 @@ Given('a holder never answering {token} under the {token} key',
     await channel.assertExchange(exchange, 'direct', { durable: true })
     await channel.assertQueue(queue, { exclusive: true })
     await channel.bindQueue(queue, exchange, key)
-    await channel.consume(queue, () => undefined)
+    await channel.consume(queue, () => (this.handed = true))
 
     this.silent = connection
   })
 
+Then('the silent holder has taken the call',
+  /**
+   * The publication is awaited nowhere, and what the crash has to find already queued is what
+   * the holder has been handed.
+   *
+   * @this {comq.features.Context}
+   */
+  async function () {
+    assert.equal(await until(() => this.handed === true, 10_000), true,
+      'The silent holder was handed nothing')
+  })
+
+Given('a holder not taking {token} under the {token} key',
+  /**
+   * Holds the key as comq does, and takes nothing until told to, so that a call waits in its
+   * queue. Each scenario holds a key of its own: the broker releases an exclusive queue once it
+   * has noticed the connection close, and a scenario that declared it again before then would be
+   * refused it.
+   *
+   * @param {string} exchange
+   * @param {string} key
+   * @this {comq.features.Context}
+   */
+  async function (exchange, key) {
+    const connection = await amqplib.connect(url(0))
+    const channel = await connection.createChannel()
+    const queue = exchange + '.' + key
+
+    await channel.assertExchange(exchange, 'direct', { durable: true })
+    await channel.assertQueue(queue, { exclusive: true })
+    await channel.bindQueue(queue, exchange, key)
+
+    this.idle = { connection, channel, queue, taken: 0 }
+  })
+
+When('the idle holder starts taking',
+  /**
+   * @this {comq.features.Context}
+   */
+  async function () {
+    const idle = this.idle
+
+    await idle.channel.consume(idle.queue, () => idle.taken++, { noAck: true })
+  })
+
+When('the consumer calls {token} under the {token} key with a signal',
+  /**
+   * @param {string} exchange
+   * @param {string} key
+   * @this {comq.features.Context}
+   */
+  async function (exchange, key) {
+    this.controller = new AbortController()
+
+    call(this, this.io.call(exchange, key, { key }, { signal: this.controller.signal }))
+  })
+
+When('the signal aborts',
+  /**
+   * @this {comq.features.Context}
+   */
+  function () {
+    this.controller.abort()
+  })
+
 When('the silent holder crashes',
   /**
    * Its socket is destroyed without a word, as a process that dies leaves it.
@@ -149,16 +214,6 @@ When('the consumer calls {token} under the {token} key {number} times',
     this.replies = await Promise.all(calls)
   })
 
-When('the consumer sends a request to the {token} queue with a {number}ms timeout',
-  /**
-   * @param {string} queue
-   * @param {number} ms
-   * @this {comq.features.Context}
-   */
-  async function (queue, ms) {
-    call(this, this.io.request(queue, { queue }, { timeout: ms }))
-  })
-
 When('the holder is sealed',
   /**
    * @this {comq.features.Context}
@@ -192,19 +247,32 @@ When('the first holder disconnects',
     await this.holder.close()
   })
 
-When('a producer counting requests to the {token} queue',
+Then('the idle holder takes nothing',
   /**
-   * @param {string} queue
    * @this {comq.features.Context}
    */
-  async function (queue) {
-    this.produced = 0
+  async function () {
+    await timeout(500)
 
-    await this.io.reply(queue, () => {
-      this.produced++
+    assert.equal(this.idle.taken, 0, 'An expired call was taken')
+  })
 
-      return null
-    })
+Then('the idle holder takes the call',
+  /**
+   * @this {comq.features.Context}
+   */
+  async function () {
+    await until(() => this.idle.taken > 0, 5000)
+
+    assert.equal(this.idle.taken, 1)
+  })
+
+Then('the consumer stops waiting for the aborted call',
+  /**
+   * @this {comq.features.Context}
+   */
+  async function () {
+    await assert.rejects(this.reply, (error) => error.name === 'AbortError')
   })
 
 Then('the call is refused as unroutable',
@@ -373,16 +441,6 @@ Then('every call is answered',
     assert.deepEqual(this.replies, this.replies.map((_, n) => n))
   })
 
-Then('the producer receives nothing',
-  /**
-   * @this {comq.features.Context}
-   */
-  async function () {
-    await timeout(500)
-
-    assert.equal(this.produced, 0, 'An expired request was processed')
-  })
-
 After(
   /**
    * @this {comq.features.Context}
@@ -390,9 +448,11 @@ After(
   async function () {
     await Promise.all((this.holders ?? []).map((io) => io.close()))
     await this.silent?.close().catch(() => undefined)
+    await this.idle?.connection.close().catch(() => undefined)
 
     this.holders = []
     this.silent = undefined
+    this.idle = undefined
   })
 
 /**

package/features/steps/events.js

@@ -225,7 +225,7 @@ async function consumed (group) {
 /**
  * @param {string} exchange
  * @param {any} message
- * @param {import('amqplib').Options.Publish} [properties]
+ * @param {import('@toa.io/amqplib').Options.Publish} [properties]
  * @return {Promise<void>}
  * @this {comq.features.Context}
  */

package/features/steps/parking.js

@@ -1,7 +1,7 @@
 'use strict'
 
 const assert = require('node:assert')
-const amqplib = require('amqplib')
+const amqplib = require('@toa.io/amqplib')
 const { Given, When, Then } = require('@cucumber/cucumber')
 
 const { getAddress, USER, PASSWORD } = require('./brokers')
@@ -58,7 +58,7 @@ Then('a message parked from the {token} exchange is in the parking queue',
  * Runs `read` against a connection of its own, so that what it does to the parking
  * queue is not what comq is doing to it.
  *
- * @param {(channel: import('amqplib').Channel) => Promise<void>} read
+ * @param {(channel: import('@toa.io/amqplib').Channel) => Promise<void>} read
  */
 async function reading (read) {
   const connection = await amqplib.connect(`amqp://${USER}:${PASSWORD}@${getAddress(0)}`)
@@ -77,9 +77,9 @@ async function reading (read) {
  * every scenario before this one left in it, so everything that does not match is given
  * back; the match is left unacknowledged, for the caller to take or to return.
  *
- * @param {import('amqplib').Channel} channel
- * @param {(message: import('amqplib').GetMessage) => boolean} matches
- * @returns {Promise<import('amqplib').GetMessage | undefined>}
+ * @param {import('@toa.io/amqplib').Channel} channel
+ * @param {(message: import('@toa.io/amqplib').GetMessage) => boolean} matches
+ * @returns {Promise<import('@toa.io/amqplib').GetMessage | undefined>}
  */
 async function pick (channel, matches) {
   const deadline = Date.now() + DEADLINE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comq",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "ComQ",
   "author": {
     "name": "Artem Gurtovoi",
@@ -34,7 +34,6 @@
     "@semantic-release/npm": "^13.1.2",
     "@semantic-release/release-notes-generator": "^14.1.0",
     "@testcontainers/rabbitmq": "^12.1.0",
-    "@types/amqplib": "^0.10.8",
     "@types/jest": "^30.0.0",
     "conventional-changelog-conventionalcommits": "^8.0.0",
     "fast-glob": "^3.3.3",
@@ -49,13 +48,16 @@
     "testcontainers": "^12.0.4"
   },
   "dependencies": {
-    "amqplib": "^2.0.1",
+    "@toa.io/amqplib": "^0.1.0",
     "promex": "^0.1.1",
     "reretry": "^0.1.0"
   },
+  "engines": {
+    "node": ">=24.0.0"
+  },
   "scripts": {
     "prepare": "husky",
-    "test": "standard && jest",
+    "test": "standard && NODE_OPTIONS=--experimental-vm-modules jest",
     "features": "cucumber-js --fail-fast -t 'not @manual'",
     "features:fast": "cucumber-js --fail-fast -t 'not @manual and not @heavy'",
     "benchmark": "node benchmarks/run.js",

package/readme.md

@@ -6,8 +6,8 @@ for distributed, eventually consistent systems running on Node.js.
 ## Features
 
 - [Dynamic topology](#topology)
-- [Request](#request)-[reply](#reply) (RPC), with a [timeout](#timeout)
-- [Addressed requests](#addressed-requests) to the one connection holding a Key
+- [Request](#request)-[reply](#reply) (RPC)
+- [Addressed requests](#addressed-requests) to the one connection holding a Key, with a [timeout](#timeout)
 - Events ([pub](#emission)/[sub](#consumption)), fanned out or [routed](#routing)
 - [Tasks](#tasks)
 - [Pipelines](#pipelines)
@@ -107,51 +107,22 @@ await io.reply('add_numbers', ({ a, b }) => (a + b))
 
 ## Request
 
-`async IO.request(queue: string, payload: any, options?: string | RequestOptions): any`
+`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. The promise stays pending until the Reply arrives, or until the
-[timeout](#timeout) passes.
+return decoded Reply content. The promise stays pending until the Reply arrives, however long
+that takes: a Request has no timeout and cannot be withdrawn. One no Producer can answer is
+[parked](#parked-messages), and can still be answered while its caller waits.
 
 On the initial call, the queue for Requests is asserted, and so is the one this `IO` receives
 every Reply on.
 
-`options` is the encoding, or an object:
-
-| Option     | Type          | Default            |
-|------------|---------------|--------------------|
-| `encoding` | `string`      | `application/json` |
-| `timeout`  | `number`, ms  | none               |
-| `signal`   | `AbortSignal` | none               |
-
 ### Example
 
 ```javascript
 const sum = await io.request('add_numbers', { a: 1, b: 2 })
 ```
 
-### Timeout
-
-A Request with a `timeout` rejects once it passes, with the `TimeoutError` of
-[`AbortSignal.timeout`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static).
-It is published with that much
-[expiration](https://www.rabbitmq.com/docs/ttl#per-message-ttl-in-publishers), so a Request no
-Producer has taken by then is dropped by the broker and never processed. A Request a Producer has
-already taken is processed to the end, and its Reply is discarded. A Request re-sent after a lost
-connection carries the time it has left.
-
-A `signal` rejects the Request with its reason once aborted, within the `timeout` where both are
-given. It ends the wait and leaves the Request where it is: in its queue until the `timeout`
-passes, or, without a `timeout`, until a Producer takes it. A Request abandoned by its `signal` may
-therefore still be processed.
-
-A Request that failed and waits for its [next attempt](#retries) loses its expiration on the way
-back to its queue, so it may be processed after its caller has stopped waiting.
-
-```javascript
-const sum = await io.request('add_numbers', { a: 1, b: 2 }, { timeout: 5000 })
-```
-
 ## Consumption
 
 `async IO.consume(exchange: string, group?: string, consumer): void`
@@ -231,7 +202,7 @@ await io.route('records', 'store.customers', { id: 2 }) // not delivered to the
 
 `async IO.back(exchange: string, key: string, producer): void`
 
-`async IO.call(exchange: string, key: string, payload: any, options?: string | RequestOptions): any`
+`async IO.call(exchange: string, key: string, payload: any, options?: string | CallOptions): any`
 
 A Request to the one connection holding a Key, where a [Request](#request) goes to whichever
 Producer takes it first.
@@ -245,8 +216,15 @@ is let go when its connection closes, however it closes — once the broker has
 connection that went without a word. `back` returns once a broker holds the Key. The rest of the
 connection works throughout, and a connection that is restored claims its Keys again the same way.
 
-`call` publishes the encoded Request to the exchange under the `key` and returns the decoded Reply,
-taking the same options as [`request`](#request).
+`call` publishes the encoded Request to the exchange under the `key` and returns the decoded Reply.
+
+`options` is the encoding, or an object:
+
+| Option     | Type          | Default            |
+|------------|---------------|--------------------|
+| `encoding` | `string`      | `application/json` |
+| `timeout`  | `number`, ms  | none               |
+| `signal`   | `AbortSignal` | none               |
 
 A call ends in one of three ways:
 
@@ -272,6 +250,24 @@ same Key can therefore hold it on different shards and both answer calls, and `t
 so. A call returned by one shard is published on the next, and refused once every shard has
 returned it.
 
+### Timeout
+
+A call with a `timeout` rejects once it passes, with the `TimeoutError` of
+[`AbortSignal.timeout`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static).
+It is published with that much
+[expiration](https://www.rabbitmq.com/docs/ttl#per-message-ttl-in-publishers), so a call its holder
+has not taken by then is dropped by the broker and never processed. A call the holder has already
+taken is processed to the end, and its Reply is discarded. A call re-sent after a lost connection
+carries the time it has left.
+
+A `signal` rejects the call with its reason once aborted, within the `timeout` where both are
+given. It ends the wait and leaves the call where it is: in its queue until the `timeout` passes,
+or, without a `timeout`, until its holder takes it. A call abandoned by its `signal` may therefore
+still be processed.
+
+A call that failed and waits for its [next attempt](#retries) loses its expiration on the way back
+to its queue, so it may be processed after its caller has stopped waiting.
+
 ### Example
 
 ```javascript
@@ -661,10 +657,9 @@ The queue grows until somebody drains it, which is deliberate — the alternativ
 evidence. Nothing comq does removes it or what it holds. Alert on [`discard`](#diagnostics), and
 do not delete `comq.retry.*` or `comq.parked` on a running system.
 
-> **A parked Request is never answered.** A Consumer awaiting its Reply waits until its
-> [timeout](#timeout), or indefinitely without one, and with a limited prefetch that can deadlock
-> it. Parking keeps the Request rather than deleting
-> it — and it keeps `replyTo` and `correlationId`, so a Reply can still be produced from it by
+> **A parked Request is never answered.** A Consumer awaiting its Reply waits indefinitely — a
+> call until its [timeout](#timeout) — and with a limited prefetch that can deadlock it. Parking
+> keeps the Request rather than deleting it — and it keeps `replyTo` and `correlationId`, so a Reply can still be produced from it by
 > hand while the caller is alive — but comq itself sends no Reply and reports no error to the
 > caller.
 

package/source/connection.js

@@ -1,12 +1,11 @@
 'use strict'
 
 const { setTimeout: delay } = require('node:timers/promises')
-const amqp = require('amqplib')
+const amqp = require('@toa.io/amqplib')
 const { Promex } = require('promex')
 const { retry } = require('reretry')
 
 const { failsafe } = require('./attributes')
-const { batch } = require('./batch')
 const presets = require('./topology')
 const channels = require('./channel')
 const emitter = require('./emitter')
@@ -148,8 +147,6 @@ class Connection {
     connection.on('close', (error) => this.#close(connection, error))
     this.#connection = connection
 
-    batch(connection.connection?.stream)
-
     this.#armWatchdog(connection)
     this.#diagnostics.emit('open')
 

package/source/io.js

@@ -84,16 +84,21 @@ class IO {
     })
 
   /**
+   * Waits for the Reply for as long as it takes: a Request is answered eventually, and one no
+   * Producer can answer is parked rather than abandoned.
+   *
    * @param {string} queue
    * @param {any | Readable} payload
-   * @param {comq.Encoding | comq.RequestOptions} [options]
+   * @param {comq.Encoding} [encoding]
    * @returns {Promise<any | Readable>}
    */
-  request (queue, payload, options) {
-    const settled = terms(options)
+  async request (queue, payload, encoding) {
+    // a caller of the version that took a timeout here would otherwise wait on in silence
+    if (typeof encoding === 'object' && encoding !== null) {
+      throw new TypeError('A Request takes an encoding and waits for its Reply')
+    }
 
-    // the channels and the queue a first Request declares are waited for within the terms too
-    return abortable(this.#request(queue, payload, settled), settled.signal)
+    return await this.#request(queue, payload, { encoding })
   }
 
   /**
@@ -103,12 +108,13 @@ class IO {
    * @param {string} exchange
    * @param {string} key
    * @param {any} payload
-   * @param {comq.Encoding | comq.RequestOptions} [options]
+   * @param {comq.Encoding | comq.CallOptions} [options]
    * @returns {Promise<any | Readable>}
    */
   call (exchange, key, payload, options) {
     const settled = terms(options)
 
+    // the channels a first call declares are waited for within the terms too
     return abortable(this.#call(exchange, key, payload, settled), settled.signal)
   }
 
@@ -129,8 +135,7 @@ class IO {
       await this.#requests.held(exchange, exchange + '.' + key, key, consumer)
     })
 
-  // failsafe is aimed to retransmit unanswered messages; the terms are taken once, so a
-  // re-sent Request keeps the deadline of the first
+  // failsafe is aimed to retransmit unanswered messages
   #request = lazy(this, [this.#createRequestReplyChannels, this.#consumeReplies],
     failsafe(this, this.#recover,
       /**
@@ -152,6 +157,7 @@ class IO {
           (buffer, properties) => this.#requests.send(queue, buffer, properties))
       }))
 
+  // the terms are taken once, so a re-sent call keeps the deadline of the first
   #call = lazy(this, [this.#createRequestReplyChannels, this.#consumeReplies],
     failsafe(this, this.#recover,
       /**
@@ -708,10 +714,10 @@ const REPLY = 'comq.reply'
 const CONTROL = 'control'
 
 /**
- * What a caller passed, settled once: a timeout becomes the moment the Request expires, so that
+ * What a caller passed, settled once: a timeout becomes the moment the call expires, so that
  * every attempt of it shares one deadline.
  *
- * @param {comq.Encoding | comq.RequestOptions} [options]
+ * @param {comq.Encoding | comq.CallOptions} [options]
  * @returns {comq.Terms}
  */
 function terms (options) {

package/test/amqplib.mock.js

@@ -58,7 +58,7 @@ class Connection extends EventEmitter {
 
 const connect = async (url) => new Connection(url)
 
-/** @type {jest.MockedObject<import('amqplib')>} */
+/** @type {jest.MockedObject<import('@toa.io/amqplib')>} */
 const amqplib = {
   connect: jest.fn(connect)
 }

package/test/connection.test.js

@@ -10,7 +10,7 @@ const { amqplib, connect } = require('./amqplib.mock')
 const { channel: create } = require('./connection.mock')
 const mock = { amqplib, channel: { create } }
 
-jest.mock('amqplib', () => mock.amqplib)
+jest.mock('@toa.io/amqplib', () => mock.amqplib)
 jest.mock('../source/channel', () => mock.channel)
 
 const presets = require('../source/topology')

package/test/{io.request.terms.test.js → io.call.terms.test.js}

@@ -21,7 +21,8 @@ let requests
 /** @type {jest.MockedObject<comq.Channel>} */
 let replies
 
-const queue = generate()
+const exchange = generate()
+const key = generate()
 const payload = { [generate()]: generate() }
 
 beforeEach(async () => {
@@ -34,12 +35,12 @@ beforeEach(async () => {
 // endregion
 
 describe('timeout', () => {
-  it('should expire the Request when the caller stops waiting', async () => {
-    io.request(queue, payload, { timeout: 10000 }).catch(noop)
+  it('should expire the call when the caller stops waiting', async () => {
+    io.call(exchange, key, payload, { timeout: 10000 }).catch(noop)
 
     await initialized()
 
-    const expiration = Number(requests.send.mock.calls[0][2].expiration)
+    const expiration = Number(requests.route.mock.calls[0][3].expiration)
 
     expect(expiration).toBeGreaterThan(9000)
     expect(expiration).toBeLessThanOrEqual(10000)
@@ -48,29 +49,29 @@ describe('timeout', () => {
   it('should keep the encoding', async () => {
     const encoding = 'application/octet-stream'
 
-    io.request(queue, randomBytes(8), { encoding, timeout: 10000 }).catch(noop)
+    io.call(exchange, key, randomBytes(8), { encoding, timeout: 10000 }).catch(noop)
 
     await initialized()
 
-    expect(requests.send.mock.calls[0][2].contentType).toStrictEqual(encoding)
+    expect(requests.route.mock.calls[0][3].contentType).toStrictEqual(encoding)
   })
 
   it('should stop waiting while the channels are being created', async () => {
     connection.createChannel.mockImplementation(() => new Promise(noop))
 
-    const promise = io.request(queue, payload, { timeout: 20 })
+    const promise = io.call(exchange, key, payload, { timeout: 20 })
 
     await expect(promise).rejects.toMatchObject({ name: 'TimeoutError' })
   })
 
   it('should reject once it has passed', async () => {
-    const promise = io.request(queue, payload, { timeout: 20 })
+    const promise = io.call(exchange, key, payload, { timeout: 20 })
 
     await expect(promise).rejects.toMatchObject({ name: 'TimeoutError' })
   })
 
   it('should resolve with a reply that arrives in time', async () => {
-    const promise = io.request(queue, payload, { timeout: 10000 })
+    const promise = io.call(exchange, key, payload, { timeout: 10000 })
     const content = randomBytes(8)
 
     await initialized()
@@ -80,7 +81,7 @@ describe('timeout', () => {
   })
 
   it('should re-send with the time that is left', async () => {
-    io.request(queue, payload, { timeout: 10000 }).catch(noop)
+    io.call(exchange, key, payload, { timeout: 10000 }).catch(noop)
 
     await initialized()
     await timeout(20)
@@ -89,10 +90,10 @@ describe('timeout', () => {
 
     await immediate()
 
-    expect(requests.send).toHaveBeenCalledTimes(2)
+    expect(requests.route).toHaveBeenCalledTimes(2)
 
-    const first = Number(requests.send.mock.calls[0][2].expiration)
-    const second = Number(requests.send.mock.calls[1][2].expiration)
+    const first = Number(requests.route.mock.calls[0][3].expiration)
+    const second = Number(requests.route.mock.calls[1][3].expiration)
 
     expect(second).toBeLessThan(first)
   })
@@ -102,7 +103,7 @@ describe('signal', () => {
   it('should reject with the reason it was aborted for', async () => {
     const controller = new AbortController()
     const reason = new Error(generate())
-    const promise = io.request(queue, payload, { signal: controller.signal })
+    const promise = io.call(exchange, key, payload, { signal: controller.signal })
 
     await initialized()
 
@@ -111,14 +112,14 @@ describe('signal', () => {
     await expect(promise).rejects.toBe(reason)
   })
 
-  it('should leave the Request in its queue', async () => {
+  it('should leave the call in its queue', async () => {
     const controller = new AbortController()
 
-    io.request(queue, payload, { signal: controller.signal }).catch(noop)
+    io.call(exchange, key, payload, { signal: controller.signal }).catch(noop)
 
     await initialized()
 
-    expect(requests.send.mock.calls[0][2].expiration).toBeUndefined()
+    expect(requests.route.mock.calls[0][3].expiration).toBeUndefined()
   })
 
   it('should reject at once when aborted before the channels exist', async () => {
@@ -129,27 +130,27 @@ describe('signal', () => {
 
     controller.abort(reason)
 
-    await expect(io.request(queue, payload, { signal: controller.signal })).rejects.toBe(reason)
+    await expect(io.call(exchange, key, payload, { signal: controller.signal })).rejects.toBe(reason)
   })
 
   it('should send nothing once aborted', async () => {
     const controller = new AbortController()
 
-    // the channels exist before the aborted Request is made
-    io.request(queue, payload).catch(noop)
+    // the channels exist before the aborted call is made
+    io.call(exchange, key, payload).catch(noop)
 
     await initialized()
 
     controller.abort()
 
-    await expect(io.request(queue, payload, { signal: controller.signal })).rejects.toBeDefined()
+    await expect(io.call(exchange, key, payload, { signal: controller.signal })).rejects.toBeDefined()
 
-    expect(requests.send).toHaveBeenCalledTimes(1)
+    expect(requests.route).toHaveBeenCalledTimes(1)
   })
 
   it('should not re-send what it abandoned', async () => {
     const controller = new AbortController()
-    const promise = io.request(queue, payload, { signal: controller.signal })
+    const promise = io.call(exchange, key, payload, { signal: controller.signal })
 
     await initialized()
 
@@ -161,19 +162,19 @@ describe('signal', () => {
 
     await immediate()
 
-    expect(requests.send).toHaveBeenCalledTimes(1)
+    expect(requests.route).toHaveBeenCalledTimes(1)
   })
 
   it('should stop waiting for a publication', async () => {
-    io.request(queue, payload).catch(noop)
+    io.call(exchange, key, payload).catch(noop)
 
     await initialized()
 
-    requests.send.mockImplementationOnce(() => new Promise(noop))
+    requests.route.mockImplementationOnce(() => new Promise(noop))
 
     const controller = new AbortController()
     const reason = new Error(generate())
-    const promise = io.request(queue, payload, { signal: controller.signal })
+    const promise = io.call(exchange, key, payload, { signal: controller.signal })
 
     await immediate()
 
@@ -184,7 +185,7 @@ describe('signal', () => {
 
   it('should discard a reply that arrives afterwards', async () => {
     const controller = new AbortController()
-    const promise = io.request(queue, payload, { signal: controller.signal })
+    const promise = io.call(exchange, key, payload, { signal: controller.signal })
 
     await initialized()
 
@@ -197,7 +198,7 @@ describe('signal', () => {
 
   it('should end the wait within the timeout', async () => {
     const controller = new AbortController()
-    const promise = io.request(queue, payload, { signal: controller.signal, timeout: 20 })
+    const promise = io.call(exchange, key, payload, { signal: controller.signal, timeout: 20 })
 
     await expect(promise).rejects.toMatchObject({ name: 'TimeoutError' })
   })
@@ -216,7 +217,7 @@ async function initialized () {
  * @param {Buffer} [content]
  */
 async function answer (index, content = randomBytes(8)) {
-  const { correlationId } = requests.send.mock.calls[index][2]
+  const { correlationId } = requests.route.mock.calls[index][3]
   const deliver = replies.consume.mock.calls[0][1]
 
   await deliver({ content, properties: { correlationId } })

package/test/io.call.test.js

@@ -98,16 +98,6 @@ describe('call', () => {
   })
 })
 
-describe('timeout', () => {
-  it('should stop waiting while the channels are being created', async () => {
-    connection.createChannel.mockImplementation(() => new Promise(() => undefined))
-
-    const promise = io.call(exchange, key, payload, { timeout: 20 })
-
-    await expect(promise).rejects.toMatchObject({ name: 'TimeoutError' })
-  })
-})
-
 describe('back', () => {
   const producer = jest.fn(() => generate())
 

package/test/io.request.test.js

@@ -115,6 +115,19 @@ describe('send', () => {
     expect(call[2]).toMatchObject({ contentType })
   })
 
+  it('should not expire', async () => {
+    expect(call[2].expiration).toBeUndefined()
+  })
+
+  it('should refuse options other than the encoding', async () => {
+    requests.send.mockClear()
+
+    await expect(io.request(queue, payload, { timeout: 1000 })).rejects.toBeInstanceOf(TypeError)
+    await expect(io.request(queue, payload, { signal: new AbortController().signal })).rejects.toBeInstanceOf(TypeError)
+
+    expect(requests.send).not.toHaveBeenCalled()
+  })
+
   it('should throw if encoding is not supported', async () => {
     const encoding = /** @type {comq.Encoding} */ 'wtf/' + generate()
 

package/test/memory.test.js

@@ -12,7 +12,7 @@ const { timeout } = require('./helpers')
 const mock = require('./amqplib.mock')
 const { amqplib, connect } = mock
 
-jest.mock('amqplib', () => mock.amqplib)
+jest.mock('@toa.io/amqplib', () => mock.amqplib)
 
 const { connect: open, assert } = require('../source')
 const { SingletonConnection } = require('../source/singleton')

package/types/amqp.d.ts

@@ -1,4 +1,4 @@
-import * as amqplib from 'amqplib'
+import * as amqplib from '@toa.io/amqplib'
 
 declare namespace comq.amqp {
 

package/types/channel.d.ts

@@ -1,4 +1,4 @@
-import { Message, Options, Connection } from 'amqplib'
+import { Message, Options, Connection } from '@toa.io/amqplib'
 import * as _diagnostics from './diagnostic'
 
 declare namespace comq {

package/types/io.d.ts

@@ -37,19 +37,19 @@ declare namespace comq {
     signal?: AbortSignal
   }
 
-  /** How long a caller waits for a Reply. */
-  interface RequestOptions {
+  /** How long a caller waits for the Reply to a call. */
+  interface CallOptions {
     encoding?: _encoding.Encoding
 
     /**
-     * Milliseconds to wait for the Reply. A Request nobody has taken by then is dropped by the
+     * Milliseconds to wait for the Reply. A call nobody has taken by then is dropped by the
      * broker; one already taken may still be processed, and its Reply is discarded.
      */
     timeout?: number
 
     /**
-     * Ends the wait when aborted, within the timeout. The Request stays in its queue until the
-     * timeout passes, or, without one, until a Producer takes it.
+     * Ends the wait when aborted, within the timeout. The call stays in its queue until the
+     * timeout passes, or, without one, until its holder takes it.
      */
     signal?: AbortSignal
   }
@@ -64,15 +64,16 @@ declare namespace comq {
   interface IO extends _diagnostics.Diagnosable {
     reply(queue: string, produce: Producer): Promise<void>
 
-    request<Reply = any, Request = any>(queue: string, payload: Request, options?: _encoding.Encoding | RequestOptions): Promise<Reply> | Promise<Readable>
+    /** Waits for the Reply for as long as it takes. */
+    request<Reply = any, Request = any>(queue: string, payload: Request, encoding?: _encoding.Encoding): Promise<Reply> | Promise<Readable>
 
-    request(queue: string, stream: Readable, options?: _encoding.Encoding | RequestOptions): Promise<Readable>
+    request(queue: string, stream: Readable, encoding?: _encoding.Encoding): Promise<Readable>
 
     /**
      * Sends a Request to whoever holds `key` on the routed `exchange`, through `back`. One that
      * nobody holds is refused with `Unroutable`.
      */
-    call<Reply = any, Request = any>(exchange: string, key: string, payload: Request, options?: _encoding.Encoding | RequestOptions): Promise<Reply> | Promise<Readable>
+    call<Reply = any, Request = any>(exchange: string, key: string, payload: Request, options?: _encoding.Encoding | CallOptions): Promise<Reply> | Promise<Readable>
 
     /**
      * Answers the Requests `call` sends under `key`, from a queue this connection alone holds.

package/features/rpc.timeout.feature

@@ -1,19 +0,0 @@
-Feature: Request timeout
-
-  A caller may say how long it waits for a reply. A request nobody took by then is dropped by the
-  broker; one already taken is still processed, and its reply is discarded.
-
-  Background:
-    Given an active connection to the broker
-
-  Scenario: A caller stops waiting at its timeout
-    Given a producer replying `slow` queue in 1000ms
-    When the consumer sends a request to the `slow` queue with a 200ms timeout
-    Then the consumer stops waiting
-
-  Scenario: A request nobody took in time is never processed
-    When the consumer sends a request to the `later` queue with a 200ms timeout
-    Then the consumer stops waiting
-    When after 300ms
-    And a producer counting requests to the `later` queue
-    Then the producer receives nothing

package/source/batch.js

@@ -1,62 +0,0 @@
-'use strict'
-
-/**
- * Writes as one what a connection sends in one turn of the event loop.
- *
- * amqplib hands its frames to the socket one write at a time, and a request served is two of
- * them: the reply, and the acknowledgement of the request it answers. With Nagle's algorithm off,
- * which is what a socket sending without delay runs under, each is a syscall and a packet of its
- * own. Corked, they are held in the socket's buffer and leave together, in one `writev`, at the
- * end of the same turn: nothing waits for a timer, and nothing waits for a write that may never
- * come.
- *
- * This belongs in amqplib, whose `Mux` writes the frames one at a time, and where corking that
- * loop is six lines and needs no wrapping of a socket the library does not own. It is done here
- * until amqplib carries it, and goes when it does.
- *
- * @param {import('node:net').Socket} socket
- */
-function batch (socket) {
-  // whatever a connection is carried over is left as it is unless it is a stream that corks
-  if (!corkable(socket) || socket[BATCHED] === true) return
-
-  socket[BATCHED] = true
-
-  const write = socket.write.bind(socket)
-
-  const flush = () => {
-    socket[CORKED] = false
-    socket.uncork()
-  }
-
-  const cork = () => {
-    if (socket[CORKED] === true) return
-
-    socket[CORKED] = true
-    socket.cork()
-
-    process.nextTick(flush)
-  }
-
-  socket.write = (...args) => {
-    cork()
-
-    return write(...args)
-  }
-}
-
-/**
- * @param {any} socket
- * @returns {boolean}
- */
-function corkable (socket) {
-  return socket !== null && socket !== undefined &&
-    typeof socket.write === 'function' &&
-    typeof socket.cork === 'function' &&
-    typeof socket.uncork === 'function'
-}
-
-const BATCHED = Symbol('comq.batched')
-const CORKED = Symbol('comq.corked')
-
-exports.batch = batch

package/test/batch.test.js

@@ -1,94 +0,0 @@
-'use strict'
-
-const { Writable } = require('node:stream')
-
-const { batch } = require('../source/batch')
-
-/** A socket, as far as writing to it goes: what it was given, and how many times. */
-function socket () {
-  const writes = []
-
-  return Object.assign(new Writable({
-    write (chunk, _encoding, callback) {
-      writes.push([chunk.toString()])
-      callback()
-    },
-    writev (chunks, callback) {
-      writes.push(chunks.map(({ chunk }) => chunk.toString()))
-      callback()
-    }
-  }), { writes })
-}
-
-const tick = () => new Promise((resolve) => process.nextTick(resolve))
-
-it('should be', async () => {
-  expect(batch).toBeDefined()
-})
-
-it('should write what a turn wrote as one', async () => {
-  const stream = socket()
-
-  batch(stream)
-
-  stream.write('a')
-  stream.write('b')
-
-  await tick()
-
-  expect(stream.writes).toStrictEqual([['a', 'b']])
-})
-
-it('should write what a later turn wrote on its own', async () => {
-  const stream = socket()
-
-  batch(stream)
-
-  stream.write('a')
-
-  await tick()
-
-  stream.write('b')
-
-  await tick()
-
-  expect(stream.writes).toStrictEqual([['a'], ['b']])
-})
-
-it('should not hold a write past its turn', async () => {
-  const stream = socket()
-
-  batch(stream)
-
-  stream.write('a')
-
-  await tick()
-
-  expect(stream.writes).toStrictEqual([['a']])
-})
-
-it('should take a socket once', async () => {
-  const stream = socket()
-
-  batch(stream)
-
-  const wrapped = stream.write
-
-  batch(stream)
-
-  expect(stream.write).toStrictEqual(wrapped)
-})
-
-it('should leave alone what does not cork', async () => {
-  for (const value of [undefined, null, {}, { write: () => undefined }]) {
-    expect(() => batch(value)).not.toThrow()
-  }
-
-  const written = []
-  const plain = { write: (chunk) => written.push(chunk) }
-
-  batch(plain)
-  plain.write('a')
-
-  expect(written).toStrictEqual(['a'])
-})