comq 0.18.0 → 0.20.0

package/source/io.js

@@ -4,6 +4,8 @@ const stream = require('node:stream')
 const { setTimeout } = require('node:timers/promises')
 const { Promex } = require('promex')
 const { memo, failsafe, lazy, track } = require('./attributes')
+const { verdictOf, PARK } = require('./verdicts')
+const { Unroutable } = require('./unroutable')
 
 const { decode } = require('./decode')
 const { encode } = require('./encode')
@@ -74,31 +76,88 @@ class IO {
       await this.#requests.consume(queue, consumer)
     })
 
-  // failsafe is aimed to retransmit unanswered messages
-  request = lazy(this, [this.#createRequestReplyChannels, this.#consumeReplies],
+  /**
+   * @param {string} queue
+   * @param {any | Readable} payload
+   * @param {comq.Encoding | comq.RequestOptions} [options]
+   * @returns {Promise<any | Readable>}
+   */
+  request (queue, payload, options) {
+    const settled = terms(options)
+
+    // 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)
+  }
+
+  /**
+   * A Request to whoever holds `key` on a routed `exchange`, through `back`. One nobody holds
+   * is returned by the broker and rejects with `Unroutable`.
+   *
+   * @param {string} exchange
+   * @param {string} key
+   * @param {any} payload
+   * @param {comq.Encoding | comq.RequestOptions} [options]
+   * @returns {Promise<any | Readable>}
+   */
+  call (exchange, key, payload, options) {
+    const settled = terms(options)
+
+    return abortable(this.#call(exchange, key, payload, settled), settled.signal)
+  }
+
+  /**
+   * Answers the Requests `call` makes under `key`, from a queue that belongs to this
+   * connection alone. Sealing withdraws the key before it stops consuming.
+   */
+  back = lazy(this, this.#createRequestReplyChannels,
+    /**
+     * @param {string} exchange
+     * @param {string} key
+     * @param {comq.Producer} callback
+     * @returns {Promise<void>}
+     */
+    async (exchange, key, callback) => {
+      const consumer = this.#getRequestConsumer(callback)
+
+      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
+  #request = lazy(this, [this.#createRequestReplyChannels, this.#consumeReplies],
     failsafe(this, this.#recover,
       /**
        * @param {string} queue
        * @param {any | Readable} payload
-       * @param {comq.Encoding} [encoding]
+       * @param {comq.Terms} terms
        * @returns {Promise<any | Readable>}
        */
-      async (queue, payload, encoding) => {
+      async (queue, payload, terms) => {
         if (payload instanceof stream.Readable) {
           return pipeline(
             payload,
-            (payload) => this.request(queue, payload, encoding),
+            (payload) => this.#request(queue, payload, terms),
             this.#requests
           )
         }
 
-        const [buffer, contentType] = this.#encode(payload, encoding)
-        const request = this.#createRequest(queue, contentType)
-        const reply = this.#createReply(request)
-
-        await this.#requests.send(queue, buffer, request.properties)
+        return await this.#ask(queue, payload, terms,
+          (buffer, properties) => this.#requests.send(queue, buffer, properties))
+      }))
 
-        return reply
+  #call = lazy(this, [this.#createRequestReplyChannels, this.#consumeReplies],
+    failsafe(this, this.#recover,
+      /**
+       * @param {string} exchange
+       * @param {string} key
+       * @param {any} payload
+       * @param {comq.Terms} terms
+       * @returns {Promise<any | Readable>}
+       */
+      async (exchange, key, payload, terms) => {
+        // mandatory: a Request nobody holds the key of is returned rather than dropped
+        return await this.#ask(exchange, payload, terms,
+          (buffer, properties) => this.#requests.route(exchange, key, buffer, { ...properties, mandatory: true }))
       }))
 
   consume = lazy(this, this.#createEventChannel,
@@ -220,6 +279,9 @@ class IO {
     this.#replies = await this.#createChannel('reply')
 
     this.#setupRetransmission()
+
+    // on a sharded connection, only once every shard has returned it
+    this.#requests.diagnose('return', this.#returned)
   }
 
   async #createEventChannel () {
@@ -302,7 +364,7 @@ class IO {
        */
       async (request) => {
         const payload = decode(request)
-        const reply = await producer(payload)
+        const reply = await produce(producer, payload)
 
         if (request.properties.replyTo === undefined) return
 
@@ -349,22 +411,101 @@ class IO {
       await callback(payload, message.properties)
     })
 
+  /**
+   * Sends a Request and returns what settles with its Reply, within the terms.
+   *
+   * @param {string} target the queue or the exchange the Request is published to
+   * @param {any} payload
+   * @param {comq.Terms} terms
+   * @param {(buffer: Buffer, properties: comq.amqp.options.Publish) => Promise<void>} publish
+   * @returns {Promise<any | Readable>}
+   */
+  async #ask (target, payload, terms, publish) {
+    const { signal, expires } = terms
+
+    signal?.throwIfAborted()
+
+    const [buffer, contentType] = this.#encode(payload, terms.encoding)
+    const request = this.#createRequest(target, contentType, signal)
+    const properties = { ...request.properties }
+
+    if (expires !== undefined) {
+      const left = Math.ceil(expires - Date.now())
+
+      // a re-send past the deadline, ahead of the timer that is about to end it
+      if (left <= 0) throw new DOMException('The operation was aborted due to timeout', 'TimeoutError')
+
+      // what nobody has taken by the time its caller stops waiting, the broker drops
+      properties.expiration = String(left)
+    }
+
+    const reply = this.#createReply(request)
+
+    if (signal !== undefined) this.#abandon(request, reply, signal)
+
+    await abortable(publish(buffer, properties), signal)
+
+    return reply
+  }
+
+  /**
+   * Stops waiting for a Reply once the signal aborts. The Request is forgotten at once, so a
+   * retransmission leaves it be, and a Reply arriving later finds nobody waiting for it.
+   *
+   * @param {comq.Request} request
+   * @param {Promex} reply
+   * @param {AbortSignal} signal
+   */
+  #abandon (request, reply, signal) {
+    const abandon = () => {
+      request.emitter.off(request.properties.correlationId)
+      this.#pendingReplies.delete(reply)
+      reply.reject(signal.reason)
+    }
+
+    const settled = () => signal.removeEventListener('abort', abandon)
+
+    signal.addEventListener('abort', abandon, { once: true })
+    reply.then(settled, settled)
+  }
+
+  /**
+   * A Request the broker returned reached nobody, and nobody will answer it.
+   *
+   * @param {comq.amqp.Message} message
+   */
+  #returned = (message) => {
+    const { correlationId, replyTo } = message.properties
+
+    for (const [reply, request] of this.#pendingReplies) {
+      if (request.properties.correlationId !== correlationId) continue
+      if (request.emitter.queue !== replyTo) continue
+
+      request.emitter.off(correlationId)
+      this.#pendingReplies.delete(reply)
+      reply.reject(new Unroutable(message.fields.exchange, message.fields.routingKey))
+
+      return
+    }
+  }
+
   /**
    * 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) {
+  #createRequest (queue, contentType, signal) {
     const emitter = this.#emitters.get(queue)
     const correlationId = emitter.next()
 
     /** @type {comq.amqp.Properties} */
     const properties = { contentType, correlationId, replyTo: emitter.queue }
 
-    return { emitter, properties }
+    return { emitter, properties, signal }
   }
 
   /**
@@ -416,6 +557,9 @@ class IO {
           return reply.reject(RETRANSMISSION)
         }
 
+        // the caller stopped waiting while the stream was starting
+        if (request.signal?.aborted === true) return stream.destroy()
+
         reply.resolve(stream)
       } else {
         reply.resolve(payload)
@@ -549,4 +693,85 @@ const DEFAULT = 'application/json'
 
 const RETRANSMISSION = /** @type {Error} */ Symbol('retransmission')
 
+/**
+ * What a caller passed, settled once: a timeout becomes the moment the Request expires, so that
+ * every attempt of it shares one deadline.
+ *
+ * @param {comq.Encoding | comq.RequestOptions} [options]
+ * @returns {comq.Terms}
+ */
+function terms (options) {
+  if (typeof options !== 'object' || options === null) return { encoding: options }
+
+  const { encoding, timeout, signal } = options
+  const signals = []
+
+  if (signal !== undefined) signals.push(signal)
+  if (timeout !== undefined) signals.push(AbortSignal.timeout(timeout))
+
+  return {
+    encoding,
+    expires: timeout === undefined ? undefined : Date.now() + timeout,
+    signal: signals.length === 0 ? undefined : AbortSignal.any(signals)
+  }
+}
+
+/**
+ * Waits for a promise, or for the signal to abort, whichever comes first. Declaring a channel,
+ * a queue or publishing waits out back pressure and a lost connection, and a caller that has
+ * stopped waiting is released from all of it.
+ *
+ * @template T
+ * @param {Promise<T>} promise
+ * @param {AbortSignal} [signal]
+ * @returns {Promise<T>}
+ */
+async function abortable (promise, signal) {
+  if (signal === undefined) return await promise
+
+  if (signal.aborted) {
+    // it settles later, with nobody waiting for it
+    promise.catch(() => undefined)
+
+    throw signal.reason
+  }
+
+  let abort
+
+  const aborted = new Promise((_resolve, reject) => { abort = () => reject(signal.reason) })
+
+  signal.addEventListener('abort', abort, { once: true })
+
+  try {
+    return await Promise.race([promise, aborted])
+  } finally {
+    signal.removeEventListener('abort', abort)
+  }
+}
+
+/**
+ * A verdict answers what should happen to a message now that it has failed and nobody
+ * is waiting for it. A Producer has a caller waiting, and what it is owed is a reply,
+ * so `Park` is a category error there rather than a policy choice — comq's own type
+ * vocabulary already draws the line between a Consumer and a Producer.
+ *
+ * It cannot be caught at wiring time, since nothing there knows what a producer will
+ * throw. Caught here instead and re-thrown as an ordinary rejection, which retries and
+ * eventually parks, carrying an explanation the parked message keeps as its reason.
+ *
+ * @param {comq.Producer} producer
+ * @param {any} payload
+ */
+async function produce (producer, payload) {
+  try {
+    return await producer(payload)
+  } catch (exception) {
+    if (verdictOf(exception) !== PARK) throw exception
+
+    throw new Error('Park is not applicable to a reply producer: a Request has a caller ' +
+      'awaiting a reply, so it is retried and parked on the count like any other failure',
+    { cause: exception })
+  }
+}
+
 exports.IO = IO

package/source/shards/channel.js

@@ -1,6 +1,7 @@
 'use strict'
 
 const { Promex } = require('promex')
+const { RETRY_PREFIX } = require('../channel')
 const events = require('../events')
 const emitter = require('../emitter')
 
@@ -68,6 +69,14 @@ class Channel {
     await this.#every((channel) => channel.bound(exchange, queue, key, consumer))
   }
 
+  /**
+   * A key is held once any shard holds it. A shard where another connection holds it goes on
+   * claiming it, and holds it as well once it is let go.
+   */
+  async held (exchange, queue, key, consumer) {
+    await Promise.any(this.#apply((channel) => channel.held(exchange, queue, key, consumer)))
+  }
+
   async send (queue, buffer, options) {
     await this.#one((channel) => channel.send(queue, buffer, options))
   }
@@ -203,9 +212,11 @@ class Channel {
     const report = () => this.#diagnostics.emit(RETURN, message, channel.index)
     const attempt = (message.properties.headers?.[RETURN_HEADER] ?? 0) + 1
     const rest = this.#pool.filter((one) => one !== channel)
+    const { exchange, routingKey } = message.fields
 
-    // only replies are published to the default exchange, and only they are mandatory
-    const exhausted = message.fields.exchange !== DEFAULT ||
+    // a failed message waits on an exchange of comq's own, a fanout that is declared as one
+    // where it is consumed, and declaring it on another shard as anything else is refused
+    const exhausted = exchange.startsWith(RETRY_PREFIX) ||
       attempt >= this.#connections.length ||
       rest.length === 0
 
@@ -219,7 +230,13 @@ class Channel {
 
     const next = rest[Math.floor(Math.random() * rest.length)]
 
-    next.fire(message.fields.routingKey, message.content, properties).catch(report)
+    // a Request under a key goes through its routed exchange, which `route` declares on that
+    // shard before publishing: publishing to an exchange a broker lacks closes the connection
+    const retried = exchange === DEFAULT
+      ? next.fire(routingKey, message.content, properties)
+      : next.route(exchange, routingKey, message.content, properties)
+
+    retried.catch(report)
   }
 
   /**

package/source/unroutable.js

@@ -0,0 +1,27 @@
+'use strict'
+
+/**
+ * A Request the broker returned instead of routing: nothing was bound under its key, so it
+ * reached no one and did not run.
+ */
+class Unroutable extends Error {
+  /** @type {string} */
+  exchange
+
+  /** @type {string} */
+  key
+
+  /**
+   * @param {string} exchange
+   * @param {string} key
+   */
+  constructor (exchange, key) {
+    super(`Nothing is bound to '${exchange}' under '${key}'`)
+
+    this.name = 'Unroutable'
+    this.exchange = exchange
+    this.key = key
+  }
+}
+
+exports.Unroutable = Unroutable

package/source/verdicts.js

@@ -0,0 +1,54 @@
+'use strict'
+
+/**
+ * How a consumer says what should happen to a message it could not handle.
+ *
+ * The brand is a registered symbol rather than the class identity: comq is a library,
+ * and a dependency that pins it while the application resolves its own tree makes two
+ * copies of it the ordinary outcome. `instanceof` is silently `false` across those,
+ * which would read a `Park` as an unclassified rejection and retry it to exhaustion
+ * before parking it anyway. The global symbol registry is shared; a class is not.
+ */
+const VERDICT = Symbol.for('comq.verdict')
+
+const RETRY = 'retry'
+const PARK = 'park'
+
+/**
+ * Whatever the consumer needed was briefly not there. This is what an unclassified
+ * rejection already means, so throwing it changes nothing but the reader's certainty.
+ */
+class Retry extends Error {
+  [VERDICT] = RETRY
+
+  name = 'Retry'
+}
+
+/**
+ * This consumer will never process this message, however many times it is handed over.
+ * The message is kept rather than retried.
+ */
+class Park extends Error {
+  [VERDICT] = PARK
+
+  name = 'Park'
+}
+
+/**
+ * A rejection nobody classified is a rejection nobody chose: it means Retry.
+ *
+ * @param {any} exception
+ * @returns {'retry' | 'park'}
+ */
+const verdictOf = (exception) => {
+  const verdict = exception?.[VERDICT]
+
+  return verdict === PARK || verdict === RETRY ? verdict : RETRY
+}
+
+exports.Retry = Retry
+exports.Park = Park
+exports.verdictOf = verdictOf
+exports.VERDICT = VERDICT
+exports.RETRY = RETRY
+exports.PARK = PARK

package/test/amqplib.mock.js

@@ -14,6 +14,7 @@ class Channel extends EventEmitter {
   assertQueue = jest.fn(async (name) => ({ queue: name ?? generate() }))
   assertExchange = jest.fn(async () => undefined)
   bindQueue = jest.fn(async () => undefined)
+  unbindQueue = jest.fn(async () => undefined)
   publish = jest.fn((_0, _1, _2, _3, resolve) => resolve?.(null))
   close = jest.fn(async () => undefined)
 }

package/test/channel.held.test.js

@@ -0,0 +1,237 @@
+'use strict'
+
+// region setup
+
+const { generate } = require('randomstring')
+const { timeout, until } = require('./helpers')
+
+const { amqplib } = require('./amqplib.mock')
+const fixtures = require('./channel.fixtures')
+const { create } = require('../source/channel')
+
+/** @type {jest.MockedObject<comq.amqp.Connection>} */
+let connection
+
+/** @type {comq.Topology} */
+let topology
+
+/** @type {comq.Channel} */
+let channel
+
+/** @type {jest.MockedObject<comq.amqp.Channel>} */
+let chan
+
+const exchange = generate()
+const queue = generate()
+const key = generate()
+const consumer = jest.fn()
+
+beforeEach(async () => {
+  jest.clearAllMocks()
+
+  global.COMQ_TESTING_CLAIM_BACKOFF = { base: 5, max: 5 }
+
+  connection = await amqplib.connect()
+  topology = fixtures.preset()
+  channel = await create(connection, topology)
+  chan = await getCreatedChannel(connection)
+})
+
+afterEach(() => {
+  delete global.COMQ_TESTING_CLAIM_BACKOFF
+})
+
+// endregion
+
+describe('held', () => {
+  it('should assert a direct exchange', async () => {
+    await channel.held(exchange, queue, key, consumer)
+
+    expect(chan.assertExchange).toHaveBeenCalledWith(exchange, 'direct', expect.anything())
+  })
+
+  it('should declare the queue exclusive on a channel of its own', async () => {
+    await channel.held(exchange, queue, key, consumer)
+
+    const [probe] = await getProbes(connection)
+
+    expect(probe.assertQueue).toHaveBeenCalledWith(queue, { exclusive: true })
+    expect(probe.close).toHaveBeenCalled()
+  })
+
+  it('should bind the queue under the key', async () => {
+    await channel.held(exchange, queue, key, consumer)
+
+    expect(chan.bindQueue).toHaveBeenCalledWith(queue, exchange, key)
+  })
+
+  it('should consume the queue', async () => {
+    await channel.held(exchange, queue, key, consumer)
+
+    expect(chan.consume).toHaveBeenCalledWith(queue, expect.any(Function), expect.any(Object))
+  })
+
+  it('should claim the queue again while another connection holds it', async () => {
+    const taken = jest.fn()
+
+    channel.diagnose('taken', taken)
+    lock(connection, { times: 2 })
+
+    await channel.held(exchange, queue, key, consumer)
+
+    expect(taken).toHaveBeenCalledTimes(2)
+    expect(taken).toHaveBeenCalledWith(queue)
+    expect(chan.consume).toHaveBeenCalledWith(queue, expect.any(Function), expect.any(Object))
+  })
+
+  it('should stop claiming once sealed', async () => {
+    lock(connection)
+
+    const holding = channel.held(exchange, queue, key, consumer)
+
+    await timeout(20)
+    await channel.seal()
+    await holding
+
+    expect(chan.bindQueue).not.toHaveBeenCalled()
+    expect(chan.consume).not.toHaveBeenCalled()
+  })
+
+  it('should reject with any other refusal', async () => {
+    lock(connection, { code: 403 })
+
+    await expect(channel.held(exchange, queue, key, consumer)).rejects.toMatchObject({ code: 403 })
+  })
+})
+
+describe('seal', () => {
+  beforeEach(async () => {
+    await channel.held(exchange, queue, key, consumer)
+  })
+
+  it('should withdraw the key', async () => {
+    await channel.seal()
+
+    expect(chan.unbindQueue).toHaveBeenCalledWith(queue, exchange, key)
+  })
+
+  it('should withdraw the key before it stops consuming', async () => {
+    await channel.seal()
+
+    const [unbound] = chan.unbindQueue.mock.invocationCallOrder
+    const [cancelled] = chan.cancel.mock.invocationCallOrder
+
+    expect(unbound).toBeLessThan(cancelled)
+  })
+})
+
+describe('recovery', () => {
+  const other = generate()
+
+  beforeEach(async () => {
+    await channel.held(exchange, queue, key, consumer)
+    await channel.consume(other, consumer)
+  })
+
+  afterEach(async () => {
+    await channel.seal()
+  })
+
+  it('should hold the queue on the new connection', async () => {
+    const replacement = await amqplib.connect()
+
+    await channel.recover(replacement)
+
+    const repl = await getCreatedChannel(replacement)
+
+    expect(await until(() => repl.bindQueue.mock.calls.some(([bound]) => bound === queue), 1000)).toStrictEqual(true)
+    expect(repl.bindQueue).toHaveBeenCalledWith(queue, exchange, key)
+  })
+
+  it('should restore the rest while another connection holds the queue', async () => {
+    const replacement = await amqplib.connect()
+
+    lock(replacement, { main: true })
+
+    const recovered = channel.recover(replacement).then(() => true)
+    const hung = timeout(200).then(() => false)
+
+    await expect(Promise.race([recovered, hung])).resolves.toStrictEqual(true)
+
+    const repl = await getCreatedChannel(replacement)
+
+    expect(repl.consume).toHaveBeenCalledWith(other, expect.any(Function), expect.any(Object))
+    expect(repl.bindQueue).not.toHaveBeenCalledWith(queue, exchange, key)
+  })
+
+  it('should hold the queue once it is let go', async () => {
+    const replacement = await amqplib.connect()
+
+    lock(replacement, { main: true, times: 2 })
+
+    await channel.recover(replacement)
+
+    const repl = await getCreatedChannel(replacement)
+
+    expect(await until(() => repl.bindQueue.mock.calls.some(([bound]) => bound === queue), 1000)).toStrictEqual(true)
+    expect(repl.bindQueue).toHaveBeenCalledWith(queue, exchange, key)
+  })
+})
+
+/**
+ * Makes the channels a connection creates from now on refuse an exclusive queue, the way a
+ * broker does: by closing the channel, with the reason emitted as its error.
+ *
+ * @param {jest.MockedObject<comq.amqp.Connection>} conn
+ * @param {{ times?: number, code?: number, main?: boolean }} [options]
+ * `main` says the channel to be created first is the channel under test, which is left alone
+ */
+function lock (conn, { times = Infinity, code = 405, main = false } = {}) {
+  const create = conn.createChannel.getMockImplementation()
+  let skip = main && !topology.confirms
+  let refused = 0
+
+  conn.createChannel.mockImplementation(async () => {
+    const created = await create()
+
+    if (skip) {
+      skip = false
+
+      return created
+    }
+
+    if (refused < times) {
+      refused++
+
+      created.assertQueue.mockImplementation(async () => {
+        created.emit('error', Object.assign(new Error('Refused'), { code }))
+
+        throw new Error('Channel closed')
+      })
+    }
+
+    return created
+  })
+}
+
+/**
+ * @param {jest.MockedObject<comq.amqp.Connection>} conn
+ * @returns {Promise<jest.MockedObject<comq.amqp.Channel>>}
+ */
+function getCreatedChannel (conn) {
+  const method = `create${topology.confirms ? 'Confirm' : ''}Channel`
+
+  return conn[method].mock.results[0].value
+}
+
+/**
+ * The channels a connection created to declare an exclusive queue on.
+ *
+ * @param {jest.MockedObject<comq.amqp.Connection>} conn
+ * @returns {Promise<jest.MockedObject<comq.amqp.Channel>[]>}
+ */
+async function getProbes (conn) {
+  const created = await Promise.all(conn.createChannel.mock.results.map((result) => result.value))
+
+  return topology.confirms ? created : created.slice(1)
+}