comq 0.20.1 → 0.21.0

package/.husky/pre-commit

@@ -1,5 +1,3 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
 [ -n "$CI" ] && exit 0
+
 npm test

package/benchmarks/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/benchmarks/readme.md

@@ -0,0 +1,65 @@
+# Benchmarks
+
+What one request costs the peer that answers it: the CPU it spends, the socket writes it makes,
+and what the caller waits.
+
+```shell
+$ docker compose up -d
+$ npm run benchmark
+```
+
+The peer runs in a process of its own — that is where its CPU is read from — and answers an echo
+of a small object over `request`/`reply` on the broker `docker-compose.yaml` starts.
+
+## What it reports
+
+Two tables, because the two say different things.
+
+**At a fixed rate** sends what a rate calls for and does not wait for the answers, which is how
+traffic arrives. A rate below what the peer can serve is the honest place to read latency.
+
+**With requests in flight** keeps a fixed number of them outstanding, which is how a queue of
+callers behaves, and at a high enough number it is where the peer saturates: the rate column is
+then what the peer can serve, and the CPU column is what one message costs it there.
+
+Each row carries:
+
+| column | what it is |
+| --- | --- |
+| `messages/s` | answered in the window, over its length |
+| `CPU µs` | user and system time of the answering process, per message |
+| `writes`, `writev` | socket write calls of the answering process, per message |
+| `p50`, `p99` | what the caller waited, milliseconds |
+
+`writes` and `writev` are the mechanism, not the outcome: a message the library writes as its own
+syscall costs more than one written together with its neighbours.
+
+## Reading a result
+
+A number here means something only beside another number from the same machine. Run it on the
+revision you are changing, then on your change, and compare the columns; a difference under about
+5% between two rounds of the same revision is what this machine's noise looks like.
+
+Both rounds are printed rather than averaged, so a run that drifted is visible as a run that
+drifted.
+
+## Options
+
+| option | default | what it does |
+| --- | --- | --- |
+| `--rates` | `1000,5000,20000,40000` | messages a second for the fixed-rate table |
+| `--concurrency` | `1,8,64,256` | requests in flight for the second table |
+| `--messages` | `20000` | messages per window, in flight mode |
+| `--seconds` | `6` | length of a window, fixed-rate mode |
+| `--rounds` | `2` | how many times the whole matrix is measured |
+
+`COMQ_BENCHMARK_URL` points the run at another broker.
+
+```shell
+$ npm run benchmark -- --rates 5000 --concurrency 64 --rounds 3
+```
+
+## What it does not measure
+
+Streams, confirms, sharded or singleton connections, and recovery. It measures the path a request
+and its reply take, which is the one every other path is built on.

package/benchmarks/run.js

@@ -0,0 +1,196 @@
+// What one request costs the process that answers it. See readme.md.
+//
+// node benchmarks/run.js [--rates 1000,5000] [--concurrency 1,8] [--messages 20000]
+// [--seconds 6] [--rounds 2]
+
+import { fork } from 'node:child_process'
+import { parseArgs } from 'node:util'
+import { createRequire } from 'node:module'
+import { setTimeout as sleep } from 'node:timers/promises'
+
+const require = createRequire(import.meta.url)
+const { connect } = require('../source/index.js')
+
+const { values } = parseArgs({
+  options: {
+    rates: { type: 'string', default: '1000,5000,20000,40000' },
+    concurrency: { type: 'string', default: '1,8,64,256' },
+    messages: { type: 'string', default: '20000' },
+    seconds: { type: 'string', default: '6' },
+    rounds: { type: 'string', default: '2' }
+  }
+})
+
+const url = process.env.COMQ_BENCHMARK_URL ?? 'amqp://developer:secret@localhost:5673'
+const rates = numbers(values.rates)
+const concurrencies = numbers(values.concurrency)
+const messages = Number(values.messages)
+const seconds = Number(values.seconds)
+const rounds = Number(values.rounds)
+
+const durations = []
+
+/** What a request carries, which is small, as a call between components is. */
+const payload = {
+  id: '4c4759e6f9c74da989d64511df42d6f4',
+  title: 'First pot',
+  rank: 7,
+  public: true,
+  tags: ['one', 'two', 'three']
+}
+
+const server = await start()
+const io = await connect(url)
+
+try {
+  const open = []
+  const closed = []
+
+  for (let round = 1; round <= rounds; round++) {
+    for (const rate of rates) open.push(await atRate(rate, round))
+    for (const concurrency of concurrencies) closed.push(await inFlight(concurrency, round))
+  }
+
+  report('At a fixed rate', ['rate'], open)
+  report('With requests in flight', ['in flight'], closed)
+} finally {
+  await io.close()
+
+  server.kill()
+}
+
+/**
+ * Requests sent at a rate, as traffic arrives: a millisecond's worth at a time, none of them
+ * waited for. What a peer costs per message is read from the peer itself.
+ */
+async function atRate (rate, round) {
+  await load(() => send(rate, 2, false))
+
+  const measured = await load(() => send(rate, seconds, true))
+
+  return { round, of: rate, ...measured }
+}
+
+/** Requests kept in flight, as a queue of callers is: the peer is never idle between them. */
+async function inFlight (concurrency, round) {
+  await load(() => saturate(concurrency, Math.min(5000, messages), false))
+
+  const measured = await load(() => saturate(concurrency, messages, true))
+
+  return { round, of: concurrency, ...measured }
+}
+
+/** A window: what the peer spent, and what the caller waited, between two readings. */
+async function load (work) {
+  durations.length = 0
+
+  const before = await io.request('comq.benchmark.meter', null)
+  const started = process.hrtime.bigint()
+
+  await work()
+
+  const elapsed = Number(process.hrtime.bigint() - started) / 1e9
+  const after = await io.request('comq.benchmark.meter', null)
+  const answered = after.answered - before.answered
+  const cpu = after.cpu.user + after.cpu.system - before.cpu.user - before.cpu.system
+
+  return {
+    answered,
+    rate: Math.round(answered / elapsed),
+    cpu: round2(cpu / answered),
+    writes: round3((after.write - before.write) / answered),
+    writevs: round3((after.writev - before.writev) / answered),
+    p50: percentile(0.5),
+    p99: percentile(0.99)
+  }
+}
+
+async function send (rate, duration, record) {
+  const started = process.hrtime.bigint()
+  const pending = []
+
+  let sent = 0
+
+  while (elapsed(started) < duration) {
+    const due = Math.round(elapsed(started) * rate)
+
+    while (sent < due) {
+      sent++
+      pending.push(request(record))
+    }
+
+    await sleep(1)
+  }
+
+  await Promise.all(pending)
+}
+
+async function saturate (concurrency, count, record) {
+  let sent = 0
+
+  const caller = async () => {
+    while (sent < count) {
+      sent++
+
+      await request(record)
+    }
+  }
+
+  await Promise.all(Array.from({ length: concurrency }, caller))
+}
+
+async function request (record) {
+  const at = process.hrtime.bigint()
+
+  await io.request('comq.benchmark.echo', payload)
+
+  if (record) durations.push(Number(process.hrtime.bigint() - at) / 1e6)
+}
+
+function report (title, columns, rows) {
+  console.log(`\n## ${title}\n`)
+  console.log(`| ${columns[0]} | round | messages/s | CPU µs | writes | writev | p50 ms | p99 ms |`)
+  console.log('| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |')
+
+  for (const row of rows) {
+    console.log(`| ${row.of} | ${row.round} | ${row.rate} | ${row.cpu} | ${row.writes} | ` +
+      `${row.writevs} | ${row.p50} | ${row.p99} |`)
+  }
+}
+
+/** The peer in a process of its own, which is where its CPU is measured. */
+async function start () {
+  const child = fork(new URL('server.js', import.meta.url), { stdio: 'inherit' })
+
+  await new Promise((resolve, reject) => {
+    child.once('message', resolve)
+    child.once('exit', (code) => reject(new Error(`The peer exited with ${code}`)))
+  })
+
+  return child
+}
+
+function percentile (share) {
+  // a warm-up window records nothing, and its result is discarded
+  if (durations.length === 0) return 0
+
+  const sorted = durations.slice().sort((a, b) => a - b)
+
+  return round3(sorted[Math.floor(sorted.length * share)])
+}
+
+function elapsed (since) {
+  return Number(process.hrtime.bigint() - since) / 1e9
+}
+
+function numbers (list) {
+  return list.split(',').map(Number)
+}
+
+function round2 (value) {
+  return Number(value.toFixed(2))
+}
+
+function round3 (value) {
+  return Number(value.toFixed(3))
+}

package/benchmarks/server.js

@@ -0,0 +1,47 @@
+// The peer under measurement: it answers an echo, and reports what answering cost it.
+//
+// The socket's write methods are counted here rather than in the library, because what a message
+// costs a process is mostly the syscalls it makes: a reply and the acknowledgement of the request
+// it answers are two writes unless something puts them together.
+
+import net from 'node:net'
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+const { connect } = require('../source/index.js')
+
+const counters = { write: 0, writev: 0, chunks: 0 }
+const write = net.Socket.prototype._write
+const writev = net.Socket.prototype._writev
+
+net.Socket.prototype._write = function (...args) {
+  counters.write++
+  counters.chunks++
+
+  return write.apply(this, args)
+}
+
+net.Socket.prototype._writev = function (chunks, ...rest) {
+  counters.writev++
+  counters.chunks += chunks.length
+
+  return writev.apply(this, [chunks, ...rest])
+}
+
+const url = process.env.COMQ_BENCHMARK_URL ?? 'amqp://developer:secret@localhost:5673'
+
+let answered = 0
+
+const io = await connect(url)
+
+await io.reply('comq.benchmark.echo', (payload) => {
+  answered++
+
+  return payload
+})
+
+// read before and after a window, so what is reported is what that window cost
+await io.reply('comq.benchmark.meter', () => ({ answered, cpu: process.cpuUsage(), ...counters }))
+
+process.send?.('ready')
+console.log('ready')

package/features/rpc.streams.feature

@@ -49,12 +49,13 @@ Feature: Reply streams
     Given heartbeat interval is set to 300ms
     And a number generator with 100ms increasing delay replying `get_numbers` queue
     When the consumer requests a stream with request to the `get_numbers` queue
-    Then the consumer receives the stream:
-      """yaml
-      [0, 1, 3]
-      """
-    And after 500ms
-    Then the generator is destroyed
+    And the consumer receives the stream
+    # a stream that stopped arriving is not a stream that ended
+    Then the consumer's stream terminates
+    And a stream that lost values has raised
+    And the consumer has received a prefix of the stream
+    And after 200ms
+    And the generator is destroyed
 
   Scenario: Reply stream heartbeat
     # delay will exceed the idle timeout on the 3rd reply
@@ -71,12 +72,9 @@ Feature: Reply streams
     Then the consumer receives the stream
     And after 300ms
     Then the broker has crashed
-    # idle timeout
-    Then after 150ms
-    Then the consumer has received the stream:
-      """yaml
-      [0, 1, 2]
-      """
+    Then the consumer's stream terminates
+    And a stream that lost values has raised
+    And the consumer has received a prefix of the stream
     Then after 200ms
     Then the broker is up
     And the generator is destroyed

package/features/rpc.streams.shards.feature

@@ -29,10 +29,10 @@ Feature: Reply streams over shards
     And after 300ms
     And the broker has crashed
     And the broker is up
-    Then the consumer interrupts the stream
-    And the consumer has received the stream containing:
-      """yaml
-      [0, 1, 2, 3, 4, 5, 6]
-      """
+    # a stream whose shard carried a value away with it is cut short; one over a shard that
+    # survived is not, and neither of them ends as though it had been answered whole
+    Then the consumer's stream terminates
+    And a stream that lost values has raised
+    And the consumer has received a prefix of the stream
     And after 1000ms
     And the generator is destroyed

package/features/steps/.types/context.d.ts

@@ -31,6 +31,8 @@ declare namespace comq.features {
     stream: Readable
     streamValues: any[]
     streamEnded: boolean
+    streamError?: Error
+    streamLength?: number
     streams: Record<number, Readable>
     streamsValues: Record<number, any[]>
     streamsEnded: Record<number, boolean>

package/features/steps/rpc.js

@@ -48,8 +48,10 @@ Given('a number generator with {number}ms increasing delay replying {token} queu
   async function (delay, queue) {
     const that = this
 
+    this.streamLength = MAX
+
     class Stream extends Readable {
-      #MAX = 10
+      #MAX = MAX
       #count = 0
 
       constructor () {
@@ -305,6 +307,62 @@ Then('the consumer receives the stream',
   async function () {
     this.stream.on('data', (data) => this.streamValues.push(data))
     this.stream.on('end', () => (this.streamEnded = true))
+    this.stream.on('error', (error) => (this.streamError = error))
+  })
+
+Then('the consumer\'s stream terminates',
+  /**
+   * Either way it terminates: whole, or cut short. Bounded, so that a stream that never does
+   * fails the scenario rather than hanging it.
+   *
+   * @this {comq.features.Context}
+   */
+  async function () {
+    if (this.stream.destroyed || this.streamEnded === true) return
+
+    // both ways it terminates, and `once` would reject on the one that raises
+    const terminated = new Promise((resolve) => {
+      this.stream.once('close', resolve)
+      this.stream.once('error', resolve)
+    })
+    const expired = timeout(TERMINATION_MS).then(() => 'expired')
+
+    assert.notEqual(await Promise.race([terminated, expired]), 'expired',
+      'The stream has neither ended nor raised')
+  })
+
+Then('the consumer has received a prefix of the stream',
+  /**
+   * The order of yielded values is preserved and the tail may be lost, so what arrived is the
+   * sequence from its start, with nothing missing in between and nothing twice.
+   *
+   * @this {comq.features.Context}
+   */
+  async function () {
+    const expected = this.streamValues.map((_, index) => index)
+
+    assert.deepEqual(this.streamValues, expected,
+      `Received ${JSON.stringify(this.streamValues)}, which is not a prefix of the stream`)
+  })
+
+Then('a stream that lost values has raised',
+  /**
+   * A stream that did not deliver everything its producer yielded must not end as one that did:
+   * a caller cannot tell them apart otherwise.
+   *
+   * @this {comq.features.Context}
+   */
+  async function () {
+    const whole = this.streamValues.length === this.streamLength
+
+    if (whole) assert.equal(this.streamError, undefined, 'A whole stream has raised')
+    else {
+      assert.notEqual(this.streamError, undefined,
+        `The stream ended with ${this.streamValues.length} of ${this.streamLength} values and did not raise`)
+
+      assert.equal(this.streamError.name, 'Interrupted',
+        `The stream raised ${this.streamError.name}`)
+    }
   })
 
 Then('the consumer{number} receives the stream',
@@ -508,5 +566,10 @@ async function fetch (queue, payload, number) {
   }
 }
 
+const MAX = 10
+
+/** What a stream is given to terminate in, which is longer than this generator takes. */
+const TERMINATION_MS = 5000
+
 global.COMQ_TESTING_IDLE_INTERVAL = 150
 global.COMQ_TESTING_HEARTBEAT_INTERVAL = 100

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comq",
-  "version": "0.20.1",
+  "version": "0.21.0",
   "description": "ComQ",
   "author": {
     "name": "Artem Gurtovoi",
@@ -58,6 +58,7 @@
     "test": "standard && 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",
     "lint": "standard --fix --verbose | snazzy"
   },
   "standard": {

package/readme.md

@@ -377,7 +377,7 @@ the request will be retransmitted upon reconnection.
 
 A heartbeat message is sent to the `replyTo` queue whenever a Reply stream idles for 5 seconds.
 If the Consumer of the reply stream doesn't receive a reply or a heartbeat message for 12 seconds, the stream returned
-by `IO.request` is destroyed.
+by `IO.request` is destroyed with an `Interrupted` error.
 These intervals are not configurable.
 
 An "end stream" message is sent to the `replyTo` queue when the Reply stream is finished.
@@ -397,6 +397,17 @@ While consuming the Reply stream if the broker connection is lost,
 or if the Consumer crashes or destroys the stream returned by `IO.request`,
 some of the values yielded by the Reply stream may be lost.
 
+A stream that lost values raises `Interrupted` rather than ending, so that a stream cut short is never taken for one
+that was answered whole. What it delivered before that is the sequence from its start, in order.
+
+```javascript
+try {
+  for await (const number of stream) console.log(number)
+} catch (error) {
+  if (error instanceof Interrupted) console.log('the rest is not coming')
+}
+```
+
 To avoid inconsistency, it is strongly recommended to use the Reply stream only with _safe_ Producers, which do not
 change the application state.
 

package/source/.io/ReplyStream.js

@@ -3,6 +3,7 @@
 const { Readable } = require('node:stream')
 const { Promex } = require('promex')
 const { IDLE_INTERVAL, FLOW_HEADER, control } = require('./const')
+const { Interrupted } = require('../interrupted')
 
 class ReplyStream extends Readable {
   confirmation = new Promex()
@@ -36,6 +37,9 @@ class ReplyStream extends Readable {
   /** Whether the producer honours `pause` and `resume`. */
   #flow = false
 
+  /** Whether this stream has been handed to whoever asked for it, which is what confirms it. */
+  #confirmed = false
+
   /** Whether the producer has been asked to pause. */
   #throttled = false
 
@@ -68,13 +72,16 @@ class ReplyStream extends Readable {
     this._clear()
     this.push(null)
 
-    // a no-op once control.ok has been received
-    this.confirmation.reject(error ?? new Error(UNCONFIRMED))
+    // a no-op once control.ok has been received, and until then this is what it says: the
+    // stream never started, so the Request is re-sent rather than raised to anybody
+    this.confirmation.reject(new Error(UNCONFIRMED))
 
     if (this.#control !== undefined)
       void this.#reply(this.#control, control.end)
 
-    super._destroy(error, callback)
+    // a stream nobody has received yet cannot raise to anybody: the Request is re-sent instead,
+    // and the rejected confirmation is what says so
+    super._destroy(this.#confirmed ? error : null, callback)
   }
 
   /**
@@ -142,7 +149,7 @@ class ReplyStream extends Readable {
    */
   _buffer (payload, properties, size) {
     if (this.#buffered > this.#maxBufferSize || this.#bufferedBytes + size > this.#maxBufferBytes) {
-      this.destroy()
+      this.destroy(new Interrupted('the values held until the missing one arrives no longer fit'))
 
       return
     }
@@ -178,6 +185,7 @@ class ReplyStream extends Readable {
       case control.ok:
         this.#control = { properties }
         this.#flow = properties.headers?.[FLOW_HEADER] === true
+        this.#confirmed = true
         this.confirmation.resolve()
         break
       case control.heartbeat:
@@ -193,7 +201,10 @@ class ReplyStream extends Readable {
   _heartbeat () {
     if (this.#timeout !== null) clearTimeout(this.#timeout)
 
-    this.#timeout = setTimeout(() => this.destroy(), this.#idleInterval)
+    this.#timeout = setTimeout(
+      () => this.destroy(new Interrupted(`nothing arrived within ${this.#idleInterval}ms`)),
+      this.#idleInterval
+    )
   }
 
   _clear () {

package/source/batch.js

@@ -0,0 +1,62 @@
+'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 loop does the writing, and is proposed there:
+ * https://github.com/temich/amqplib/tree/perf/one-write-per-turn. It is done here until that
+ * lands, 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/source/connection.js

@@ -6,6 +6,7 @@ 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')
@@ -146,6 +147,9 @@ 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/index.js

@@ -3,6 +3,7 @@
 const { connect, assert } = require('./connect')
 const { Retry, Park } = require('./verdicts')
 const { Unroutable } = require('./unroutable')
+const { Interrupted } = require('./interrupted')
 
 exports.connect = connect
 exports.assert = assert
@@ -10,3 +11,4 @@ exports.assert = assert
 exports.Retry = Retry
 exports.Park = Park
 exports.Unroutable = Unroutable
+exports.Interrupted = Interrupted

package/source/interrupted.js

@@ -0,0 +1,23 @@
+'use strict'
+
+/**
+ * A Reply stream that ended before its producer did: what was received is a prefix of what was
+ * yielded, and the rest is not coming. A stream that completes ends instead, so that the two
+ * cannot be taken for one another.
+ */
+class Interrupted extends Error {
+  /** @type {string} */
+  reason
+
+  /**
+   * @param {string} reason
+   */
+  constructor (reason) {
+    super(`Reply stream has been interrupted: ${reason}`)
+
+    this.name = 'Interrupted'
+    this.reason = reason
+  }
+}
+
+exports.Interrupted = Interrupted

package/test/ReplyStream.test.js

@@ -4,6 +4,8 @@ const { once } = require('node:events')
 const { ReplyStream, UNCONFIRMED } = require('../source/.io/ReplyStream')
 const { createReplyEmitter } = require('../source/.io/createReplyEmitter')
 const { control, FLOW_HEADER } = require('../source/.io/const')
+const { Interrupted } = require('../source/interrupted')
+const { timeout } = require('./helpers')
 
 /** @type {jest.Mock} */
 let reply
@@ -72,6 +74,49 @@ it('should reject confirmation when nothing arrives within the idle interval', a
   await expect(idle.confirmation).rejects.toThrow(UNCONFIRMED)
 })
 
+it('should raise when nothing arrives within the idle interval', async () => {
+  global.COMQ_TESTING_IDLE_INTERVAL = 10
+
+  const request = {
+    emitter: createReplyEmitter('test'),
+    properties: { correlationId: 'raising-correlation' }
+  }
+
+  const idle = new ReplyStream(request, reply)
+
+  // the stream is answered, which is when it is handed to whoever asked for it
+  idle.arrange(control.ok, { headers: { index: 0 }, type: 'control' })
+
+  const [error] = await once(idle, 'error')
+
+  expect(error).toBeInstanceOf(Interrupted)
+  expect(idle.readableEnded).toStrictEqual(false)
+})
+
+it('should raise when the values held until the missing one arrives no longer fit', async () => {
+  stream.arrange(control.ok, { headers: { index: 0 }, type: 'control' })
+
+  for (let index = 2; index <= 6; index++) {
+    stream.arrange(index, { headers: { index } })
+  }
+
+  const [error] = await once(stream, 'error')
+
+  expect(error).toBeInstanceOf(Interrupted)
+})
+
+it('should end without raising when the consumer destroys it', async () => {
+  const raised = jest.fn()
+
+  stream.on('error', raised)
+  stream.arrange(control.ok, { headers: { index: 0 }, type: 'control' })
+  stream.destroy()
+
+  await timeout(10)
+
+  expect(raised).not.toHaveBeenCalled()
+})
+
 it('should keep confirmation resolved after control.ok', async () => {
   stream.arrange(control.ok, { headers: { index: 0 }, type: 'control' })
 

package/test/batch.test.js

@@ -0,0 +1,94 @@
+'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'])
+})

package/types/index.d.ts

@@ -30,3 +30,11 @@ export class Unroutable extends Error {
   readonly exchange: string
   readonly key: string
 }
+
+/**
+ * A Reply stream that ended before its producer did: what was received is a prefix of what was
+ * yielded, and the rest is not coming. A stream that completes ends instead.
+ */
+export class Interrupted extends Error {
+  readonly reason: string
+}