comq 0.16.0 → 0.16.2

package/test/ReplyStream.test.js

@@ -1,9 +1,9 @@
 'use strict'
 
-const { EventEmitter } = require('node:events')
 const { once } = require('node:events')
 const { ReplyStream, UNCONFIRMED } = require('../source/.io/ReplyStream')
-const { control } = require('../source/.io/const')
+const { createReplyEmitter } = require('../source/.io/createReplyEmitter')
+const { control, FLOW_HEADER } = require('../source/.io/const')
 
 /** @type {jest.Mock} */
 let reply
@@ -18,7 +18,7 @@ beforeEach(() => {
   reply = jest.fn().mockResolvedValue(true)
 
   const request = {
-    emitter: new EventEmitter(),
+    emitter: createReplyEmitter('test'),
     properties: { correlationId: 'test-correlation' }
   }
 
@@ -63,7 +63,7 @@ it('should reject confirmation when nothing arrives within the idle interval', a
   global.COMQ_TESTING_IDLE_INTERVAL = 10
 
   const request = {
-    emitter: new EventEmitter(),
+    emitter: createReplyEmitter('test'),
     properties: { correlationId: 'idle-correlation' }
   }
 
@@ -81,3 +81,81 @@ it('should keep confirmation resolved after control.ok', async () => {
 
   await expect(stream.confirmation).resolves.toBeUndefined()
 })
+
+describe('flow', () => {
+  const TOTAL = 40 // well beyond the 16 values a Readable holds in object mode
+
+  /**
+   * @param {boolean} flow whether the producer honours pause and resume
+   */
+  const ok = (flow) => ({ headers: { index: 0, [FLOW_HEADER]: flow }, type: 'control' })
+
+  const send = () => {
+    for (let index = 1; index <= TOTAL; index++) stream.arrange(index, { headers: { index } })
+
+    stream.arrange(control.end, { headers: { index: TOTAL + 1 }, type: 'control' })
+  }
+
+  // dropping the listener once behind would leave the stream waiting for values that have passed
+  it('should keep receiving while the consumer is behind', async () => {
+    stream.arrange(control.ok, ok(false))
+    send()
+
+    const received = []
+
+    for await (const value of stream) received.push(value)
+
+    expect(received).toHaveLength(TOTAL)
+    expect(received[TOTAL - 1]).toStrictEqual(TOTAL)
+  })
+
+  it('should not ask a producer that knows nothing of pause', async () => {
+    stream.arrange(control.ok, ok(false))
+    send()
+
+    expect(reply).not.toHaveBeenCalled()
+  })
+
+  it('should ask the producer to pause once behind, and to resume once caught up', async () => {
+    stream.arrange(control.ok, ok(true))
+
+    for (let index = 1; index <= TOTAL; index++) stream.arrange(index, { headers: { index } })
+
+    expect(reply).toHaveBeenCalledTimes(1)
+    expect(reply).toHaveBeenCalledWith({ properties: ok(true) }, control.pause)
+
+    const drained = new Promise((resolve) => stream.on('data', (value) => { if (value === TOTAL) resolve() }))
+
+    await drained
+
+    expect(reply).toHaveBeenCalledTimes(2)
+    expect(reply).toHaveBeenLastCalledWith({ properties: ok(true) }, control.resume)
+  })
+
+  it('should bound the values held out of order by their size', async () => {
+    global.COMQ_TESTING_MAX_BUFFER_SIZE = 1000
+    global.COMQ_TESTING_MAX_BUFFER_BYTES = 100
+
+    try {
+      const request = {
+        emitter: createReplyEmitter('test'),
+        properties: { correlationId: 'bytes-correlation' }
+      }
+
+      const held = new ReplyStream(request, reply)
+      const closed = once(held, 'close')
+
+      held.arrange(1, { headers: { index: 1 } }, 60)
+
+      expect(held.destroyed).toBe(false)
+
+      held.arrange(2, { headers: { index: 2 } }, 60)
+
+      await closed
+
+      expect(held.destroyed).toBe(true)
+    } finally {
+      delete global.COMQ_TESTING_MAX_BUFFER_BYTES
+    }
+  })
+})

package/test/channel.test.js

@@ -971,3 +971,61 @@ const getCreatedChannel = (conn) => {
 
   return (conn ?? connection)[method].mock.results[0].value
 }
+
+describe('consumer tags', () => {
+  const queue = generate()
+  const consumer = jest.fn()
+
+  beforeEach(async () => {
+    channel = await create(connection, topology)
+    chan = await getCreatedChannel()
+  })
+
+  // the consumers of a lost channel went down with it, and their tags would pile
+  // up with every reconnection to be cancelled on a channel that never had them
+  it('should cancel the consumers of the current channel only', async () => {
+    await channel.consume(queue, consumer)
+
+    const replacement = await amqplib.connect()
+
+    await channel.recover(replacement)
+
+    const repl = await getCreatedChannel(replacement)
+
+    expect(repl.consume).toHaveBeenCalledTimes(1)
+
+    const { consumerTag } = await repl.consume.mock.results[0].value
+
+    await channel.seal()
+
+    expect(repl.cancel).toHaveBeenCalledTimes(1)
+    expect(repl.cancel).toHaveBeenCalledWith(consumerTag)
+  })
+
+  it('should let go of the recorded subscriptions once sealed', async () => {
+    await channel.consume(queue, consumer)
+    await channel.seal()
+
+    const replacement = await amqplib.connect()
+
+    await channel.recover(replacement)
+
+    const repl = await getCreatedChannel(replacement)
+
+    expect(repl.consume).not.toHaveBeenCalled()
+  })
+})
+
+describe('release', () => {
+  it('should be called once the channel is closed', async () => {
+    const release = jest.fn()
+
+    channel = await create(connection, topology, undefined, release)
+
+    expect(release).not.toHaveBeenCalled()
+
+    await channel.close()
+
+    expect(release).toHaveBeenCalledWith(channel)
+  })
+})

package/test/connection.mock.js

@@ -11,6 +11,7 @@ const channel = /** @type {jest.MockedFunction<(sharded?: boolean, index?: numbe
     subscribe: jest.fn(async () => undefined),
     publish: jest.fn(async () => undefined),
     diagnose: jest.fn(async () => undefined),
+    forget: jest.fn(() => undefined),
     seal: jest.fn(async () => undefined),
     close: jest.fn(async () => undefined),
     closed: false,
@@ -26,7 +27,8 @@ const connection = (sharded = false) => (/** @type {jest.MockedObject<comq.Conne
   createChannel: jest.fn(async (type, index) => channel(sharded, index)),
   open: jest.fn(async () => undefined),
   close: jest.fn(async () => undefined),
-  diagnose: jest.fn(() => undefined)
+  diagnose: jest.fn(() => undefined),
+  forget: jest.fn(() => undefined)
 })
 
 exports.connection = connection

package/test/connection.test.js

@@ -184,7 +184,7 @@ describe('reconnection', () => {
 
     const boom = new Error('reconnect failed')
 
-    connection.open = jest.fn(async () => { throw boom })
+    amqplib.connect.mockRejectedValueOnce(boom)
 
     conn.emit('close', new Error('broker down'))
 
@@ -194,8 +194,38 @@ describe('reconnection', () => {
 
     expect(errors).toContain(boom)
     expect(unhandled).not.toHaveBeenCalled()
+
+    // the attempt is retried in the background, and would connect in a later case
+    await connection.close()
   })
 
+  // the singleton answers `open()` with the first opening, made once and remembered
+  it('should reconnect a connection whose open() is remembered', async () => {
+    class Remembered extends Connection {
+      #opened = null
+
+      async open () {
+        this.#opened ??= super.open()
+
+        await this.#opened
+      }
+    }
+
+    const remembered = new Remembered(generate())
+
+    await remembered.open()
+
+    const first = await amqplib.connect.mock.results.at(-1).value
+
+    first.emit('close', new Error('lost'))
+
+    await expect(remembered.createChannel('event')).resolves.toBeDefined()
+
+    expect(amqplib.connect).toHaveBeenCalledTimes(3)
+
+    await remembered.close()
+  }, 10000)
+
   it('should reconnect when connection is lost while channels recover', async () => {
     const channel = await connection.createChannel('request')
 
@@ -326,7 +356,7 @@ describe('create channel', () => {
       const preset = presets[type]
       const channel = await connection.createChannel(type)
 
-      expect(create).toHaveBeenCalledWith(conn, preset, undefined)
+      expect(create).toHaveBeenCalledWith(conn, preset, undefined, expect.any(Function))
       expect(channel).toStrictEqual(await create.mock.results[0].value)
     })
 
@@ -336,7 +366,7 @@ describe('create channel', () => {
 
     await connection.createChannel(type, index)
 
-    expect(create).toHaveBeenCalledWith(expect.anything(), expect.anything(), index)
+    expect(create).toHaveBeenCalledWith(expect.anything(), expect.anything(), index, expect.any(Function))
   })
 
   it('should create channel after exception', async () => {
@@ -437,6 +467,21 @@ describe('closed channels', () => {
 
     expect(channel.recover).toHaveBeenCalled()
   })
+
+  // a closed channel held by a shared connection would hold its IO until the
+  // connection happens to make another channel
+  it('should let go of one that has been given back', async () => {
+    const channel = await connection.createChannel('event')
+    const release = create.mock.calls[0][3]
+
+    release(channel)
+
+    conn.emit('close', new Error())
+
+    await timeout(50)
+
+    expect(channel.recover).not.toHaveBeenCalled()
+  })
 })
 
 describe('channel exhaustion', () => {
@@ -765,3 +810,20 @@ describe('diagnostics', () => {
     }
   })
 })
+
+describe('forget', () => {
+  afterEach(async () => {
+    await connection.close()
+  })
+
+  it('should stop reporting to the listener', async () => {
+    const listener = /** @type {Function} */ jest.fn()
+
+    await connection.diagnose('open', listener)
+    connection.forget('open', listener)
+
+    await connection.open()
+
+    expect(listener).not.toHaveBeenCalled()
+  })
+})

package/test/io.diagnostics.test.js

@@ -93,3 +93,14 @@ const findChannel = (type) => {
 
   return connection.createChannel.mock.results[index].value
 }
+
+// a connection is shared and outlives its IOs, so a listener left on it would hold the IO
+it('should forget the connection listeners on close', async () => {
+  await io.close()
+
+  for (const [event, listener] of connection.diagnose.mock.calls) {
+    expect(connection.forget).toHaveBeenCalledWith(event, listener)
+  }
+
+  expect(connection.forget).toHaveBeenCalledTimes(connection.diagnose.mock.calls.length)
+})

package/test/memory.test.js

@@ -0,0 +1,273 @@
+'use strict'
+
+// Watches what a closed IO leaves behind. Every scenario keeps weak references to
+// what it has opened and closed, and expects the garbage collector to have taken
+// all of it; the heap growth per iteration is reported alongside.
+
+const v8 = require('node:v8')
+const vm = require('node:vm')
+const stream = require('node:stream')
+const { generate } = require('randomstring')
+const { timeout } = require('./helpers')
+const mock = require('./amqplib.mock')
+const { amqplib, connect } = mock
+
+jest.mock('amqplib', () => mock.amqplib)
+
+const { connect: open, assert } = require('../source')
+const { SingletonConnection } = require('../source/singleton')
+
+v8.setFlagsFromString('--expose-gc')
+
+const gc = vm.runInNewContext('gc')
+
+/** @type {{ scenario: string, iterations: number, watched: number, retained: number, growth: string }[]} */
+const report = []
+
+beforeEach(() => {
+  jest.clearAllMocks()
+  amqplib.connect.mockImplementation(async (url) => wired(await connect(url)))
+
+  global.COMQ_TESTING_SHUTDOWN_TIMEOUT = 1
+  global.COMQ_TESTING_WATCHDOG_INTERVAL = 60_000
+})
+
+afterEach(() => {
+  SingletonConnection.__lets_pretend_this_method_doesnt_exist()
+
+  delete global.COMQ_TESTING_SHUTDOWN_TIMEOUT
+  delete global.COMQ_TESTING_WATCHDOG_INTERVAL
+})
+
+afterAll(() => {
+  console.info('Memory report (heap growth is per iteration, after garbage collection)\n' +
+    formatted(report))
+})
+
+it('should let go of an IO and its channels once closed', async () => {
+  const retained = await measure('connect, reply, consume, emit, close', 100, async () => {
+    const io = await open(generate())
+
+    await io.reply(generate(), () => generate())
+    await io.consume(generate(), generate(), () => undefined)
+    await io.emit(generate(), { value: generate() })
+    await io.enqueue(generate(), { value: generate() })
+
+    const channels = await amqpChannels()
+
+    await io.close()
+
+    return [io, ...channels]
+  })
+
+  expect(retained).toStrictEqual(0)
+})
+
+// a singleton connection outlives every IO opened on it
+it('should let go of the IOs of a singleton connection', async () => {
+  const url = generate()
+
+  const retained = await measure('assert, reply, close (singleton)', 100, async () => {
+    const io = await assert(url)
+
+    await io.reply(generate(), () => generate())
+
+    const channels = await amqpChannels()
+
+    await io.close()
+
+    return [io, ...channels]
+  })
+
+  expect(retained).toStrictEqual(0)
+})
+
+it('should let go of the streams passed to request and emit', async () => {
+  const io = await open(generate())
+  const queue = generate()
+  const exchange = generate()
+
+  await io.reply(queue, (request) => request)
+
+  const retained = await measure('request and emit with a stream', 100, async () => {
+    const requests = stream.Readable.from([{ a: generate() }, { b: generate() }])
+    const events = stream.Readable.from([{ a: generate() }, { b: generate() }])
+
+    const replies = await io.request(queue, requests)
+
+    // eslint-disable-next-line no-void, no-unused-vars
+    for await (const _ of replies) void 0
+
+    await io.emit(exchange, events)
+
+    return [requests, events]
+  })
+
+  await io.close()
+
+  expect(retained).toStrictEqual(0)
+})
+
+it('should let go of the channels lost with a connection', async () => {
+  const io = await open(generate())
+
+  await io.reply(generate(), () => generate())
+  await io.consume(generate(), generate(), () => undefined)
+
+  const retained = await measure('reconnection', 50, async () => {
+    const before = await amqpChannels()
+    const conn = await amqplib.connect.mock.results.at(-1).value
+
+    let recovered = 0
+
+    const recovery = new Promise((resolve) => io.diagnose('recover', () => { if (++recovered === 3) resolve() }))
+
+    conn.emit('close', new Error(generate()))
+
+    await recovery
+
+    return before
+  })
+
+  await io.close()
+
+  expect(retained).toStrictEqual(0)
+})
+
+/**
+ * @param {string} scenario
+ * @param {number} iterations
+ * @param {(index: number) => Promise<object[]>} iteration returning what must be collected afterwards
+ * @return {Promise<number>} how many of the watched objects are still alive
+ */
+async function measure (scenario, iterations, iteration) {
+  /** @type {WeakRef<object>[]} */
+  const refs = []
+
+  await collect()
+
+  const before = process.memoryUsage().heapUsed
+
+  // in a frame of its own, so that nothing of the last iteration is left on the stack
+  await watch(refs, iterations, iteration)
+
+  // mocks remember what they returned, and spies are registered until restored,
+  // either of which would keep what they were made on alive
+  jest.clearAllMocks()
+  jest.restoreAllMocks()
+
+  await collect()
+
+  const after = process.memoryUsage().heapUsed
+  const retained = refs.filter((ref) => ref.deref() !== undefined).length
+  const growth = ((after - before) / iterations / 1024).toFixed(1) + ' KB'
+
+  report.push({ scenario, iterations, watched: refs.length, retained, growth })
+
+  return retained
+}
+
+/**
+ * @param {WeakRef<object>[]} refs
+ * @param {number} iterations
+ * @param {(index: number) => Promise<object[]>} iteration
+ */
+async function watch (refs, iterations, iteration) {
+  for (let i = 0; i < iterations; i++) {
+    const objects = await iteration(i)
+
+    for (const object of objects) refs.push(new WeakRef(object))
+  }
+}
+
+/**
+ * The channels amqplib has been asked for since the last call.
+ *
+ * @return {Promise<object[]>}
+ */
+async function amqpChannels () {
+  const channels = []
+
+  for (const { value } of amqplib.connect.mock.results) {
+    const conn = await value
+
+    for (const method of ['createChannel', 'createConfirmChannel']) {
+      for (const result of conn[method].mock.results) channels.push(await result.value)
+
+      conn[method].mockClear()
+    }
+  }
+
+  return channels
+}
+
+/**
+ * A broker of sorts: what is published to a queue is delivered to its consumer,
+ * so that requests are answered and streams of them come to an end.
+ *
+ * @param {jest.MockedObject<comq.amqp.Connection>} conn
+ * @return {jest.MockedObject<comq.amqp.Connection>}
+ */
+function wired (conn) {
+  const consumers = new Map()
+  const tags = new Map()
+
+  // a broker forgets the consumers of a connection that is gone
+  conn.on('close', () => consumers.clear())
+
+  for (const method of ['createChannel', 'createConfirmChannel']) {
+    const create = conn[method].getMockImplementation()
+
+    conn[method].mockImplementation(async () => {
+      const chan = await create()
+
+      chan.consume.mockImplementation(async (queue, callback) => {
+        const consumerTag = generate()
+
+        consumers.set(queue, callback)
+        tags.set(consumerTag, queue)
+
+        return { consumerTag }
+      })
+
+      chan.cancel.mockImplementation(async (consumerTag) => {
+        consumers.delete(tags.get(consumerTag))
+        tags.delete(consumerTag)
+      })
+
+      chan.publish.mockImplementation((exchange, routingKey, content, properties, resolve) => {
+        resolve?.(null)
+
+        const callback = consumers.get(routingKey)
+
+        if (callback !== undefined) setImmediate(callback, { content, properties, fields: { exchange, routingKey } })
+
+        return true
+      })
+
+      return chan
+    })
+  }
+
+  return conn
+}
+
+async function collect () {
+  // an object a WeakRef was made for in the current task is kept until the task ends
+  await timeout(0)
+
+  gc()
+  gc()
+
+  await timeout(0)
+
+  gc()
+}
+
+function formatted (rows) {
+  const columns = ['scenario', 'iterations', 'watched', 'retained', 'growth']
+  const width = (column) => Math.max(column.length, ...rows.map((row) => String(row[column]).length))
+  const line = (cells) => cells.map((cell, i) => String(cell).padEnd(width(columns[i]))).join('  ')
+
+  return [line(columns), ...rows.map((row) => line(columns.map((column) => row[column])))].join('\n')
+}

package/test/pipeline.test.js

@@ -78,4 +78,25 @@ class Channel extends EventEmitter {
   diagnose (event, callback) {
     this.on(event, callback)
   }
+
+  forget (event, callback) {
+    this.off(event, callback)
+  }
 }
+
+// the source must not stay a listener of the channel once the pipeline is done
+it('should let go of the source once done', async () => {
+  const input = stream.Readable.from([1, 2, 3])
+  const pipe = pipeline(input, (x) => x, channel)
+
+  expect(channel.listenerCount('pause')).toBe(1)
+  expect(channel.listenerCount('resume')).toBe(1)
+
+  // eslint-disable-next-line no-void, no-unused-vars
+  for await (const _ of pipe) void 0
+
+  await timeout(0)
+
+  expect(channel.listenerCount('pause')).toBe(0)
+  expect(channel.listenerCount('resume')).toBe(0)
+})

package/test/shards/connection.test.js

@@ -132,3 +132,18 @@ describe.each(/** @type {comq.diagnostics.Event[]} */ ['open', 'close'])('diagno
       expect(listener).toHaveBeenCalledWith(event, ...args, index)
     })
   })
+
+describe('forget', () => {
+  it('should stop re-emitting to the listener', async () => {
+    const listener = /** @type {Function} */ jest.fn()
+
+    connection.diagnose('open', listener)
+    connection.forget('open', listener)
+
+    const call = connections[0].diagnose.mock.calls.find((call) => call[0] === 'open')
+
+    call[1]()
+
+    expect(listener).not.toHaveBeenCalled()
+  })
+})

package/types/connection.d.ts

@@ -18,6 +18,8 @@ declare namespace comq {
     createChannel(type: _topology.type, index: number): Promise<_channel.Channel>
 
     diagnose(event: _diagnostics.Event, listener: Function): void
+
+    forget(event: _diagnostics.Event, listener: Function): void
   }
 
   type Connect = (...urls: string[]) => Promise<_io.IO>

package/types/io.d.ts

@@ -10,8 +10,21 @@ declare namespace comq {
   type Producer<Input = any, Output = any> = (message: Input) => Output | Promise<Output>
   type Consumer<T = any> = (message: T, headers?: _amqp.Properties) => void | Promise<void>
 
-  interface ReplyEmitter extends EventEmitter {
+  type ReplyHandler = (payload: any, properties: _amqp.Properties, size?: number) => void
+
+  interface ReplyEmitter {
     readonly queue: string
+
+    /** A correlation identifier unique across every consumer of a producer. */
+    next(): string
+
+    on(correlationId: string, handler: ReplyHandler): void
+
+    off(correlationId: string, handler?: ReplyHandler): void
+
+    emit(correlationId: string, payload: any, properties: _amqp.Properties, size?: number): boolean
+
+    readonly pending: number
   }
 
   interface Destroyable extends EventEmitter {
@@ -19,7 +32,6 @@ declare namespace comq {
   }
 
   interface Request {
-    buffer: Buffer
     emitter: ReplyEmitter
     properties: _amqp.Properties
   }