comq 0.22.0 → 0.24.0

package/source/index.js

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

package/source/io.js

@@ -6,7 +6,6 @@ const { Promex } = require('promex')
 const { memo, failsafe, lazy, track } = require('./attributes')
 const { verdictOf, PARK } = require('./verdicts')
 const { Unroutable } = require('./unroutable')
-const { Abandoned } = require('./abandoned')
 
 const { decode } = require('./decode')
 const { encode } = require('./encode')
@@ -31,8 +30,15 @@ class IO {
   /** @type {comq.Channel} */
   #events
 
-  /** @type {Map<string, comq.ReplyEmitter>} */
-  #emitters = new Map()
+  /**
+   * Where this IO's replies arrive. One queue answers every request it makes: a reply is
+   * found by its correlation identifier, which is unique across processes, so a queue per
+   * target would name what the identifier already tells apart — and the broker would hold
+   * one for every distinct queue the caller has ever requested.
+   *
+   * @type {comq.ReplyEmitter}
+   */
+  #emitter
 
   /** @type {comq.ReplyEmitter | null} */
   #control = null
@@ -40,9 +46,6 @@ class IO {
   /** @type {Map<Promex, comq.Request>} */
   #pendingReplies = new Map()
 
-  /** Whether this has stopped waiting for Replies, see `abandon`. */
-  #abandoning = false
-
   /** @type {[comq.diagnostics.Event, Function][]} */
   #forwarders = []
 
@@ -81,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 })
   }
 
   /**
@@ -100,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)
   }
 
@@ -126,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,
       /**
@@ -149,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,
       /**
@@ -254,30 +263,6 @@ class IO {
     await this.#destroyStreams(this.#replyStreams)
   })
 
-  /**
-   * Stops waiting for Replies: every one still outstanding is rejected with `Abandoned`, and a
-   * Request made from now on is refused with it.
-   *
-   * A close waits for every consumer callback to return, and such a callback may be waiting on
-   * a Request of its own. Where the answer to that Request is the very thing going away — the
-   * process it would come from is shutting down alongside this one — the close waits for as
-   * long as the answer takes. This is how that wait is ended. What the Requests themselves do
-   * is not affected: they were sent and may well be processed; what is given up is this side's
-   * interest in the answers.
-   *
-   * Callable at any time, including while a close is already under way.
-   */
-  abandon = memo(async () => {
-    this.#abandoning = true
-
-    // the same three steps `#abandon` takes for one Reply whose caller stopped waiting
-    for (const [reply, request] of this.#pendingReplies) {
-      request.emitter.off(request.properties.correlationId)
-      this.#pendingReplies.delete(reply)
-      reply.reject(new Abandoned())
-    }
-  })
-
   close = memo(async () => {
     await this.seal()
     await this.#destroyStreams(this.#replyPipes)
@@ -340,13 +325,20 @@ class IO {
     return [buffer, properties]
   }
 
-  async #consumeReplies (queue) {
-    const emitter = io.createReplyEmitter(queue)
-    const consumer = this.#getReplyConsumer(queue, emitter)
+  async #consumeReplies () {
+    this.#emitter = await this.#consumeRepliesOf(REPLY)
+  }
+
+  /**
+   * @param {string} label
+   * @returns {Promise<comq.ReplyEmitter>}
+   */
+  async #consumeRepliesOf (label) {
+    const emitter = io.createReplyEmitter(label)
 
-    this.#emitters.set(queue, emitter)
+    await this.#replies.consume(emitter.queue, this.#getReplyConsumer(emitter))
 
-    await this.#replies.consume(emitter.queue, consumer)
+    return emitter
   }
 
   // endregion
@@ -417,11 +409,10 @@ class IO {
       })
 
   /**
-   * @param {string} queue
    * @param {comq.ReplyEmitter} emitter
    * @returns {comq.channels.Consumer}
    */
-  #getReplyConsumer = (queue, emitter) =>
+  #getReplyConsumer = (emitter) =>
     (message) => {
       const payload = decode(message)
 
@@ -453,11 +444,8 @@ class IO {
 
     signal?.throwIfAborted()
 
-    // one made now would be waited for by nobody: the Replies are abandoned already
-    if (this.#abandoning) throw new Abandoned()
-
     const [buffer, contentType] = this.#encode(payload, terms.encoding)
-    const request = this.#createRequest(target, contentType, signal)
+    const request = this.#createRequest(contentType, signal)
     const properties = { ...request.properties }
 
     if (expires !== undefined) {
@@ -524,13 +512,12 @@ class IO {
    * The request holds no copy of what was sent: a retransmission encodes the
    * payload anew, and an unanswered request would otherwise keep two of it.
    *
-   * @param {string} queue
    * @param {comq.Encoding} contentType
    * @param {AbortSignal} [signal]
    * @return {comq.Request}
    */
-  #createRequest (queue, contentType, signal) {
-    const emitter = this.#emitters.get(queue)
+  #createRequest (contentType, signal) {
+    const emitter = this.#emitter
     const correlationId = emitter.next()
 
     /** @type {comq.amqp.Properties} */
@@ -611,11 +598,7 @@ class IO {
    * @return {Promise<comq.ReplyEmitter>}
    */
   async #createControl () {
-    const queue = 'control'
-
-    await this.#consumeReplies(queue)
-
-    return this.#emitters.get(queue)
+    return await this.#consumeRepliesOf(CONTROL)
   }
 
   /**
@@ -724,11 +707,17 @@ const DEFAULT = 'application/json'
 
 const RETRANSMISSION = /** @type {Error} */ Symbol('retransmission')
 
+/** What this IO's replies arrive on, before the random suffix that makes the queue its own. */
+const REPLY = 'comq.reply'
+
+/** What a producer steers its reply streams from, likewise. */
+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/ReplyPipe.test.js

@@ -168,3 +168,43 @@ it('should heartbeat while idle', async () => {
 
   pipe.destroy()
 })
+
+// the confirmation is published before the source is read, and a blocked broker holds the publish
+// for as long as it is blocked: the source may fail in the meantime, and nobody listens to it yet
+it('should survive a source that fails before the confirmation is sent', async () => {
+  const gate = new Promex()
+
+  reply.mockImplementation(async (message, properties) => {
+    sent.push([message, properties])
+    await gate
+
+    return true
+  })
+
+  const source = new Readable({ objectMode: true, read () {} })
+  const creating = ReplyPipe.create(request, source, channel, feedback, reply)
+
+  source.destroy(new Error('nothing arrived'))
+
+  await timeout(10)
+
+  gate.resolve()
+
+  const pipe = await creating
+
+  await closing(pipe)
+
+  expect(source.destroyed).toStrictEqual(true)
+})
+
+it('should destroy the source if the confirmation cannot be sent', async () => {
+  reply.mockImplementation(async () => {
+    throw new Error('channel closed')
+  })
+
+  const source = new Readable({ objectMode: true, read () {} })
+
+  await expect(ReplyPipe.create(request, source, channel, feedback, reply)).rejects.toThrow('channel closed')
+
+  expect(source.destroyed).toStrictEqual(true)
+})

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/channel.test.js

@@ -1040,6 +1040,7 @@ describe('release', () => {
 describe('failed messages', () => {
   const DELAY = 1000
   const RETRY = 'comq.retry.' + DELAY
+  const PARKED = 'comq.parked'
 
   let queue
   let exception
@@ -1108,10 +1109,18 @@ describe('failed messages', () => {
     it('should assert the parked queue', async () => {
       await channel.consume(queue, consumer)
 
-      expect(chan.assertQueue).toHaveBeenCalledWith('comq.parked.' + queue,
+      expect(chan.assertQueue).toHaveBeenCalledWith(PARKED,
         expect.objectContaining({ durable: true }))
     })
 
+    it('should not name the parked queue after the queue it serves', async () => {
+      await channel.consume(queue, consumer)
+
+      const named = chan.assertQueue.mock.calls.filter(([name]) => name.includes(queue))
+
+      expect(named).toHaveLength(1) // the source queue itself
+    })
+
     it('should assert the source queue first', async () => {
       await channel.consume(queue, consumer)
 
@@ -1130,15 +1139,14 @@ describe('failed messages', () => {
       expect(queues).toHaveLength(1)
     })
 
-    it('should assert a parked queue per consumed queue', async () => {
-      const one = generate()
-      const another = generate()
+    it('should assert one parked queue however many queues are consumed', async () => {
+      await channel.consume(generate(), consumer)
+      await channel.consume(generate(), consumer)
+      await channel.consume(generate(), consumer)
 
-      await channel.consume(one, consumer)
-      await channel.consume(another, consumer)
+      const parked = chan.assertQueue.mock.calls.filter(([name]) => name === PARKED)
 
-      expect(chan.assertQueue).toHaveBeenCalledWith('comq.parked.' + one, expect.anything())
-      expect(chan.assertQueue).toHaveBeenCalledWith('comq.parked.' + another, expect.anything())
+      expect(parked).toHaveLength(1)
     })
 
     it('should not assert either without acknowledgments', async () => {
@@ -1156,7 +1164,9 @@ describe('failed messages', () => {
       expect(chan.assertExchange).not.toHaveBeenCalled()
     })
 
-    it('should declare the parked queue exclusive for an exclusive queue', async () => {
+    it('should declare the parked queue durable whatever the channel is', async () => {
+      // what a groupless subscriber could not process is waiting for a person, and
+      // there is nobody left to tell once its own queue has gone with its connection
       jest.clearAllMocks()
 
       topology.durable = false
@@ -1166,9 +1176,10 @@ describe('failed messages', () => {
       await channel.consume(queue, consumer)
 
       const [, options] = chan.assertQueue.mock.calls
-        .find(([name]) => name === 'comq.parked.' + queue)
+        .find(([name]) => name === PARKED)
 
-      expect(options).toMatchObject({ exclusive: true })
+      expect(options).toMatchObject({ durable: true })
+      expect(options.exclusive).toBeUndefined()
     })
 
     it('should re-assert after recovery', async () => {
@@ -1181,7 +1192,7 @@ describe('failed messages', () => {
       const repl = await getCreatedChannel(replacement)
 
       expect(repl.assertExchange).toHaveBeenCalledWith(RETRY, 'fanout', expect.anything())
-      expect(repl.assertQueue).toHaveBeenCalledWith('comq.parked.' + queue, expect.anything())
+      expect(repl.assertQueue).toHaveBeenCalledWith(PARKED, expect.anything())
     })
   })
 
@@ -1471,7 +1482,7 @@ describe('failed messages', () => {
 
       expect(asserted()).toStrictEqual(['comq.retry.1000'])
       expect(publications().map(([exchange, key]) => exchange || key))
-        .toStrictEqual(['comq.retry.1000', 'comq.parked.' + queue])
+        .toStrictEqual(['comq.retry.1000', PARKED])
     })
   })
 
@@ -1486,7 +1497,7 @@ describe('failed messages', () => {
       const [exchange, key] = publications()[0]
 
       expect(exchange).toStrictEqual('')
-      expect(key).toStrictEqual('comq.parked.' + queue)
+      expect(key).toStrictEqual(PARKED)
     })
 
     it('should not retry once the attempts are spent', async () => {
@@ -1563,7 +1574,7 @@ describe('failed messages', () => {
 
       const targets = publications().map(([, key]) => key)
 
-      expect(targets).toStrictEqual([queue, 'comq.parked.' + queue])
+      expect(targets).toStrictEqual([queue, PARKED])
     })
 
     it('should give a message one delivery more than the ladder has rungs', async () => {
@@ -1581,7 +1592,7 @@ describe('failed messages', () => {
 
       const targets = publications().map(([, key]) => key)
 
-      expect(targets).toStrictEqual([queue, queue, 'comq.parked.' + queue])
+      expect(targets).toStrictEqual([queue, queue, PARKED])
     })
   })
 
@@ -1596,7 +1607,7 @@ describe('failed messages', () => {
       const [exchange, key] = publications()[0]
 
       expect(exchange).toStrictEqual('')
-      expect(key).toStrictEqual('comq.parked.' + queue)
+      expect(key).toStrictEqual(PARKED)
       expect(publications()).toHaveLength(1)
     })
 
@@ -1684,7 +1695,7 @@ describe('failed messages', () => {
 
       await deliver(delivery({}))
 
-      expect(publications()[0][1]).toStrictEqual('comq.parked.' + queue)
+      expect(publications()[0][1]).toStrictEqual(PARKED)
     })
   })
 

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())