comq 0.15.5 → 0.15.7

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [0.15.7](https://github.com/toa-io/comq/compare/v0.15.6...v0.15.7) (2026-08-26)
+
+
+### Bug Fixes
+
+* wait instead of publishing when every shard is down ([41cd715](https://github.com/toa-io/comq/commit/41cd715ad07c1b141f0eabd23b2d444c60855b65))
+* wait instead of publishing when every shard is down ([#250](https://github.com/toa-io/comq/issues/250)) ([968882c](https://github.com/toa-io/comq/commit/968882c342c51b129133ad27d761cfcbfb622fce))
+* wait instead of publishing when every shard is down ([#251](https://github.com/toa-io/comq/issues/251)) ([a6cfe8a](https://github.com/toa-io/comq/commit/a6cfe8a75128cb63ad1bbbbf0e1c57cb2fbfdc37)), closes [#250](https://github.com/toa-io/comq/issues/250) [#250](https://github.com/toa-io/comq/issues/250)
+
+## [0.15.6](https://github.com/toa-io/comq/compare/v0.15.5...v0.15.6) (2026-08-26)
+
+
+### Bug Fixes
+
+* do not report shards as lost on shutdown ([abbe0e8](https://github.com/toa-io/comq/commit/abbe0e8e1048509ff2c981b7aa33659c0829e821))
+* do not report shards as lost on shutdown ([#248](https://github.com/toa-io/comq/issues/248)) ([b269a5c](https://github.com/toa-io/comq/commit/b269a5cc78d8ca74036290abec234a1e87056e9c))
+
 ## [0.15.5](https://github.com/toa-io/comq/compare/v0.15.4...v0.15.5) (2026-08-25)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comq",
-  "version": "0.15.5",
+  "version": "0.15.7",
   "description": "ComQ",
   "author": {
     "name": "Artem Gurtovoi",

package/readme.md

@@ -491,7 +491,8 @@ Subscribe to one of the diagnostic events:
   Optional [`error`](https://amqp-node.github.io/amqplib/channel_api.html#model_events) is passed
   as an argument.
 - `error`: an attempt to restore the connection has failed. The exception is passed as an argument.
-  Attempts continue, so this event is the only way to observe an ongoing outage.
+  Attempts continue until one succeeds.
+- `reconnect`: an attempt to restore the connection has started. Followed by `open` or `error`.
 - `flow`: back pressure is applied to a channel. [Channel type](./types/topology.d.ts) is passed as
   an argument.
 - `drain`: back pressure is removed from a channel. Channel type is passed.
@@ -520,9 +521,12 @@ established, there is no way to capture the initial `open` event.
 ```javascript
 io.diagnose('flow', (type) => console.log(`Back pressure was applied to the ${type} channel`))
 
-io.diagnose('open', () => console.log('AMQP connection established'))
-io.diagnose('close', (error) => console.log('AMQP connection closed', error?.message))
-io.diagnose('error', (error) => console.log('AMQP connection failed', error.message))
+io.diagnose('reconnect', (shard) => console.log('AMQP reconnecting', { shard }))
+io.diagnose('open', (shard) => console.log('AMQP connection established', { shard }))
+io.diagnose('close', (error, shard) => console.log('AMQP connection closed', { message: error?.message, shard }))
+io.diagnose('error', (error, shard) => console.log('AMQP connection failed', { message: error.message, shard }))
+io.diagnose('lost', (type, shard) => console.log('AMQP shard lost', { type, shard }))
+io.diagnose('recover', (type, shard) => console.log('AMQP channel recovered', { type, shard }))
 ```
 
 # Gratitude

package/source/connection.js

@@ -60,6 +60,10 @@ class Connection {
     return this.#connection !== undefined
   }
 
+  get closed () {
+    return this.#closed
+  }
+
   async open () {
     this.#closed = false
 
@@ -69,6 +73,11 @@ class Connection {
 
     await this.#opening
 
+    if (this.#closed) return
+
+    // close may have landed after this attempt succeeded but before `#opening` was cleared
+    if (this.#connection === undefined) return this.open()
+
     this.#running = true
   }
 
@@ -105,16 +114,18 @@ class Connection {
   #open = async (retry) => {
     if (this.#closed) return
 
+    // the initial connect finishes before the caller can subscribe
+    if (this.#running) this.#diagnostics.emit('reconnect')
+
     /** @type {comq.amqp.Connection} */
     let connection
 
     try {
-      connection = await amqp.connect(this.#url, { timeout: CONNECT_MS })
+      connection = await this.#connect()
     } catch (exception) {
       if (this.#closed) return
       if (!this.#transient(exception)) throw exception
 
-      // attempts are made until one succeeds, so an outage is observable only here
       this.#diagnostics.emit('error', exception)
 
       return retry
@@ -196,6 +207,43 @@ class Connection {
     return this.#recovery
   }
 
+  /**
+   * amqplib's `timeout` is a socket idle timer and starts only after DNS.
+   * After a machine wakes, `getaddrinfo` itself can hang, so the attempt is
+   * also bounded here.
+   *
+   * @return {Promise<comq.amqp.Connection>}
+   */
+  async #connect () {
+    const connecting = amqp.connect(this.#url, { timeout: CONNECT_MS })
+
+    let timer
+
+    const expired = new Promise((_resolve, reject) => {
+      timer = setTimeout(() => {
+        const exception = new Error('connect ETIMEDOUT')
+
+        exception.code = 'ETIMEDOUT'
+
+        reject(exception)
+      }, CONNECT_MS)
+
+      timer.unref()
+    })
+
+    expired.catch(noop)
+
+    try {
+      return await Promise.race([connecting, expired])
+    } catch (exception) {
+      connecting.then((connection) => this.#shutdown(connection), noop)
+
+      throw exception
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
   /**
    * @param {comq.amqp.Connection} connection
    * @param {number} [timeoutMs]

package/source/events.js

@@ -1,7 +1,7 @@
 'use strict'
 
 /** @type {comq.diagnostics.Event[]} */
-exports.connection = ['open', 'close', 'error']
+exports.connection = ['open', 'close', 'error', 'reconnect']
 
 /** @type {comq.diagnostics.Event[]} */
 exports.channel = ['flow', 'drain', 'recover', 'discard', 'pause', 'resume', 'return', 'lost']

package/source/shards/channel.js

@@ -111,6 +111,7 @@ class Channel {
    * when it actually fails to publish, otherwise a lost connection would
    * interrupt the streams it is carrying. Losing a shard is reported instead,
    * since a request awaiting its reply on it will never be answered.
+   * A connection closed on purpose is not a loss.
    *
    * @param {comq.Connection} connection
    * @param {number} index
@@ -121,10 +122,13 @@ class Channel {
 
     if (connection.connected === false) this.#down[index].resolve()
 
-    connection.diagnose('close', () => {
+    connection.diagnose('close', (error) => {
       this.#alive[index] = false
       this.#down[index].resolve()
-      this.#diagnostics.emit(LOST, index)
+
+      if (error !== undefined && connection.closed !== true) {
+        this.#diagnostics.emit(LOST, index)
+      }
     })
 
     connection.diagnose('open', () => {
@@ -314,26 +318,30 @@ class Channel {
   }
 
   /**
-   * The channels of the shards that are known to be connected, falling back to the
-   * whole pool while none is, so that a publish is attempted rather than dropped.
+   * The channels of the shards that are known to be connected.
+   * An empty result means every shard is down or benched — wait rather than
+   * publish: a destroyed socket accepts a write without complaining.
    *
    * @return {comq.Channel[]}
    */
   #reachable () {
-    const reachable = this.#pool.filter((channel) => this.#alive[channel.index] !== false)
-
-    return reachable.length === 0 ? this.#pool : reachable
+    return this.#pool.filter((channel) => this.#alive[channel.index] !== false)
   }
 
   /**
    * @param {(channel: comq.Channel) => void} fn
    */
   async #one (fn) {
-    if (this.#pool.length === 0) await this.#recovery
-
-    // publishing to a lost shard is silently accepted by the destroyed socket, so
-    // it must be avoided rather than retried: nothing would report the loss twice
+    // capture before the check: recover may replace `#recovery` in between
+    const waiting = this.#recovery
     const pool = this.#reachable()
+
+    if (pool.length === 0) {
+      await waiting
+
+      return this.#one(fn)
+    }
+
     const channel = pool[Math.floor(Math.random() * pool.length)]
 
     try {
@@ -341,7 +349,7 @@ class Channel {
     } catch {
       this.#remove(channel)
 
-      return await this.#one(fn)
+      return this.#one(fn)
     }
   }
 }

package/test/connection.mock.js

@@ -20,6 +20,7 @@ const channel = /** @type {jest.MockedFunction<(sharded?: boolean, index?: numbe
  */
 const connection = (sharded = false) => (/** @type {jest.MockedObject<comq.Connection>} */ {
   connected: true,
+  closed: false,
   createChannel: jest.fn(async (type, index) => channel(sharded, index)),
   open: jest.fn(async () => undefined),
   close: jest.fn(async () => undefined),

package/test/connection.test.js

@@ -211,6 +211,41 @@ describe('reconnection', () => {
     expect(errors).toContain(exception)
   }, 10000)
 
+  it('should emit reconnect when restoring a lost connection', async () => {
+    const reconnect = jest.fn()
+
+    connection.diagnose('reconnect', reconnect)
+    conn.emit('close', new Error('lost'))
+
+    await connection.createChannel('event')
+
+    expect(reconnect).toHaveBeenCalled()
+  }, 10000)
+
+  it('should bound a connect that never settles', async () => {
+    jest.useFakeTimers()
+
+    try {
+      const errors = []
+
+      connection.diagnose('error', (exception) => errors.push(exception))
+      amqplib.connect.mockImplementation(() => new Promise(() => undefined))
+
+      conn.emit('close', new Error('lost'))
+
+      await jest.advanceTimersByTimeAsync(0)
+      await jest.advanceTimersByTimeAsync(30_000)
+
+      expect(errors).toEqual([expect.objectContaining({ code: 'ETIMEDOUT' })])
+
+      await jest.advanceTimersByTimeAsync(2_000)
+
+      expect(amqplib.connect.mock.calls.length).toBeGreaterThan(2)
+    } finally {
+      jest.useRealTimers()
+    }
+  })
+
   it('should ignore close from a stale connection', async () => {
     const stale = conn
     const closeHandler = stale.on.mock.calls.find(([event]) => event === 'close')[1]
@@ -402,6 +437,7 @@ describe('close', () => {
     const amqp = await amqplib.connect.mock.results[0].value
 
     expect(amqp.close).toHaveBeenCalled()
+    expect(connection.closed).toStrictEqual(true)
   })
 
   it('should close after connection is (re)established', async () => {
@@ -475,6 +511,21 @@ describe('diagnostics', () => {
     expect(captured).toStrictEqual(true)
   })
 
+  it('should not emit reconnect on the initial open', async () => {
+    const reconnect = jest.fn()
+
+    connection.diagnose('reconnect', reconnect)
+
+    jest.clearAllMocks()
+
+    connection = new Connection(url)
+    connection.diagnose('reconnect', reconnect)
+
+    await connection.open()
+
+    expect(reconnect).not.toHaveBeenCalled()
+  })
+
   it('should re-emit `close` event', async () => {
     let captured
 

package/test/io.diagnostics.test.js

@@ -61,7 +61,7 @@ it('should not throw on error without listeners', async () => {
   expect(() => emit(new Error(generate()))).not.toThrow()
 })
 
-it.each(['open', 'close'])('should re-emit %s from connection',
+it.each(['open', 'close', 'error', 'reconnect'])('should re-emit %s from connection',
   /**
    * @param {comq.diagnostics.Event} event
    */

package/test/shards/channel.test.js

@@ -40,11 +40,45 @@ it('should report a lost shard', async () => {
 
   expect(calls.length).toBeGreaterThan(0)
 
-  for (const call of calls) call[1]()
+  for (const call of calls) call[1](new Error('gone'))
 
   expect(lost).toHaveBeenCalledWith(1)
 })
 
+it('should not report a lost shard when the connection is closed', async () => {
+  channel = await create(connections, type)
+
+  const lost = /** @type {jest.MockedFunction} */ jest.fn()
+
+  channel.diagnose('lost', lost)
+
+  connections[1].closed = true
+
+  const calls = connections[1].diagnose.mock.calls.filter((call) => call[0] === 'close')
+
+  expect(calls.length).toBeGreaterThan(0)
+
+  for (const call of calls) call[1](new Error('gone'))
+
+  expect(lost).not.toHaveBeenCalled()
+})
+
+it('should not report a lost shard when the connection is closed cleanly', async () => {
+  channel = await create(connections, type)
+
+  const lost = /** @type {jest.MockedFunction} */ jest.fn()
+
+  channel.diagnose('lost', lost)
+
+  const calls = connections[1].diagnose.mock.calls.filter((call) => call[0] === 'close')
+
+  expect(calls.length).toBeGreaterThan(0)
+
+  for (const call of calls) call[1]()
+
+  expect(lost).not.toHaveBeenCalled()
+})
+
 it('should not publish to a lost shard', async () => {
   channel = await create(connections, type)
 
@@ -62,6 +96,40 @@ it('should not publish to a lost shard', async () => {
   expect(channels[1].send).not.toHaveBeenCalled()
 })
 
+it('should wait for a shard to recover when all are lost', async () => {
+  channel = await create(connections, type)
+
+  const channels = await getCreatedChannels()
+  const buffer = randomBytes(8)
+  const label = generate()
+  let sent = false
+
+  for (const connection of connections) {
+    const calls = connection.diagnose.mock.calls.filter((call) => call[0] === 'close')
+
+    for (const call of calls) call[1](new Error('gone'))
+  }
+
+  const sending = channel.send(label, buffer).then(() => { sent = true })
+
+  await immediate()
+
+  expect(sent).toStrictEqual(false)
+
+  for (const chan of channels) expect(chan.send).not.toHaveBeenCalled()
+
+  const open = connections[0].diagnose.mock.calls.filter((call) => call[0] === 'open')
+  const recover = channels[0].diagnose.mock.calls.filter((call) => call[0] === 'recover')
+
+  for (const call of open) call[1]()
+  for (const call of recover) call[1]()
+
+  await sending
+
+  expect(channels[0].send).toHaveBeenCalled()
+  expect(channels[1].send).not.toHaveBeenCalled()
+})
+
 // a lost shard is not benched, so it is used again as soon as it reconnects
 it('should publish to a recovered shard', async () => {
   channel = await create(connections, type)

package/types/connection.d.ts

@@ -7,6 +7,7 @@ declare namespace comq {
 
   interface Connection {
     readonly connected?: boolean
+    readonly closed?: boolean
 
     open(): Promise<void>
 

package/types/diagnostic.d.ts

@@ -1,7 +1,7 @@
 declare namespace comq.diagnostics {
 
-  type Event = 'open' | 'close' | 'error' | 'flow' | 'drain' | 'remove' | 'recover' | 'discard' |
-    'pause' | 'resume' | 'return'
+  type Event = 'open' | 'close' | 'error' | 'reconnect' | 'flow' | 'drain' | 'remove' | 'lost' |
+    'recover' | 'discard' | 'pause' | 'resume' | 'return'
 
   interface Diagnosable {
     diagnose(event: Event, listener: Function): void

package/types/io.d.ts

@@ -63,6 +63,8 @@ declare namespace comq {
 
     diagnose(event: 'error', listener: (error: Error, index?: number) => void): void
 
+    diagnose(event: 'reconnect', listener: (index?: number) => void): void
+
     diagnose(event: 'flow', listener: (channel: _topology.type, index?: number) => void): void
 
     diagnose(event: 'drain', listener: (channel: _topology.type, index?: number) => void): void