comq 0.21.0 → 0.22.0

package/features/closing.feature

@@ -0,0 +1,32 @@
+Feature: Abandoning the Replies a close is waiting for
+
+  A consumer callback may call out while it runs, and a close waits for every callback to return.
+  Where the answer that callback waits for is the one thing going away with the close, the two
+  wait for each other. Abandoning ends that wait.
+
+  Background:
+    Given an active connection to the broker
+
+  Scenario: Abandoning lets a close finish
+    Given a producer replying `upstream` queue by requesting the `downstream` queue
+    When the consumer sends a request to the `upstream` queue
+    And the producer is handling the request
+    And the connection abandons its replies
+    Then the connection closes within 1000ms
+    And the producer was told its reply is abandoned
+    And the consumer was told its own reply is abandoned
+
+  Scenario: A close already under way is told to stop waiting
+    Given a producer replying `upstream` queue by requesting the `downstream` queue
+    When the consumer sends a request to the `upstream` queue
+    And the producer is handling the request
+    And the connection has started closing
+    And the connection abandons its replies
+    Then the connection closes within 1000ms
+
+  Scenario: A Request made once the Replies are abandoned is refused
+    Given a producer replying `upstream` queue by requesting the `downstream` queue
+    When the consumer sends a request to the `upstream` queue
+    And the producer is handling the request
+    And the connection abandons its replies
+    Then a request to the `downstream` queue is refused as abandoned

package/features/steps/closing.js

@@ -0,0 +1,109 @@
+'use strict'
+
+const assert = require('node:assert')
+const { Given, When, Then } = require('@cucumber/cucumber')
+const { Abandoned } = require('../../')
+const { timeout } = require('../../test/helpers')
+
+Given('a producer replying {token} queue by requesting the {token} queue',
+  /**
+   * @param {string} queue
+   * @param {string} downstream
+   * @this {comq.features.Context}
+   */
+  async function (queue, downstream) {
+    this.handling = new Promise((resolve) => { this.handled = resolve })
+
+    const producer = async (request) => {
+      const reply = this.io.request(downstream, request)
+
+      this.handled()
+
+      try {
+        return await reply
+      } catch (error) {
+        // recorded rather than rethrown: what this asserts is what the caller was told,
+        // and a rejected producer would have the delivery retried on top of it
+        this.abandoned = error
+
+        return null
+      }
+    }
+
+    await this.io.reply(queue, producer)
+  })
+
+When('the producer is handling the request',
+  /**
+   * @this {comq.features.Context}
+   */
+  async function () {
+    await this.handling
+
+    // the consumer's own Request is outstanding as well, and abandoning abandons that one too;
+    // its outcome is taken here so that it is asserted rather than left to surface as an
+    // unhandled rejection
+    this.reply.catch((error) => { this.refused = error })
+  })
+
+When('the connection has started closing',
+  /**
+   * @this {comq.features.Context}
+   */
+  async function () {
+    this.closing = this.io.close()
+  })
+
+When('the connection abandons its replies',
+  /**
+   * @this {comq.features.Context}
+   */
+  async function () {
+    await this.io.abandon()
+  })
+
+Then('the connection closes within {number}ms',
+  /**
+   * @param {number} ms
+   * @this {comq.features.Context}
+   */
+  async function (ms) {
+    const io = this.io
+
+    // taken off the world so that the hook on the way out does not await a close
+    // this may have just proven does not end
+    this.io = undefined
+    this.connected = false
+
+    const closing = io.close().then(() => true, () => true)
+    const closed = await Promise.race([closing, timeout(ms).then(() => false)])
+
+    assert.ok(closed, `The connection did not close within ${ms}ms`)
+  })
+
+Then('the producer was told its reply is abandoned',
+  /**
+   * @this {comq.features.Context}
+   */
+  async function () {
+    assert.ok(this.abandoned instanceof Abandoned,
+      `The producer was told ${this.abandoned ?? 'nothing'}`)
+  })
+
+Then('the consumer was told its own reply is abandoned',
+  /**
+   * @this {comq.features.Context}
+   */
+  async function () {
+    assert.ok(this.refused instanceof Abandoned,
+      `The consumer was told ${this.refused ?? 'nothing'}`)
+  })
+
+Then('a request to the {token} queue is refused as abandoned',
+  /**
+   * @param {string} queue
+   * @this {comq.features.Context}
+   */
+  async function (queue) {
+    await assert.rejects(() => this.io.request(queue, null), Abandoned)
+  })

package/package.json

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

package/readme.md

@@ -734,6 +734,28 @@ Sending Requests, receiving Replies, and emitting Events will still be available
 Keys held by [`back`](#addressed-requests) are withdrawn first, so a call published from then on is
 refused.
 
+### Abandoning
+
+`async IO.abandon(): void`
+
+Stop waiting for Replies.
+
+A [close](#disconnection) waits for every `producer` and `consumer` call to return, and such a
+call may itself 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.
+
+`IO.abandon()` ends that wait:
+
+- every outstanding Reply is rejected with `Abandoned`, so a caller inside a `producer` or
+  `consumer` is told at once rather than held;
+- a Request made from then on is refused with `Abandoned`, so a callback cannot start another
+  wait on the way out.
+
+The Requests those Replies belonged to were sent and may well be processed; what is given up is
+this side's interest in the answers. It may be called before a close or while one is already under
+way, which is how a close that has begun is told to stop waiting.
+
 ### Disconnection
 
 `async IO.close(): void`
@@ -742,6 +764,9 @@ refused.
 2. Wait for any outstanding messages to be processed[^2] and acknowledged.
 3. Close the connection.
 
+Step 2 still runs where the Replies have been [abandoned](#abandoning): each message is processed
+to a verdict and acknowledged, and what was given up is the waiting rather than the drain.
+
 [^2]: Therefore, if the underlying connection is lost, `.close()` will only be completed once the
 connection is [recovered](#connection-tolerance).
 

package/source/abandoned.js

@@ -0,0 +1,15 @@
+'use strict'
+
+/**
+ * A Reply nobody is waiting for any more, or a Request made once the waiting has stopped. The
+ * Request itself was sent and may well be processed; what was given up is the answer.
+ */
+class Abandoned extends Error {
+  constructor () {
+    super('The connection no longer waits for a Reply')
+
+    this.name = 'Abandoned'
+  }
+}
+
+exports.Abandoned = Abandoned

package/source/batch.js

@@ -10,9 +10,9 @@
  * 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.
+ * This belongs in amqplib, whose `Mux` writes the frames one at a time, and where corking that
+ * loop is six lines and needs no wrapping of a socket the library does not own. It is done here
+ * until amqplib carries it, and goes when it does.
  *
  * @param {import('node:net').Socket} socket
  */

package/source/index.js

@@ -4,6 +4,7 @@ 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
@@ -12,3 +13,4 @@ exports.Retry = Retry
 exports.Park = Park
 exports.Unroutable = Unroutable
 exports.Interrupted = Interrupted
+exports.Abandoned = Abandoned

package/source/io.js

@@ -6,6 +6,7 @@ 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')
@@ -39,6 +40,9 @@ 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 = []
 
@@ -250,6 +254,30 @@ 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)
@@ -425,6 +453,9 @@ 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 properties = { ...request.properties }

package/types/index.d.ts

@@ -38,3 +38,9 @@ export class Unroutable extends Error {
 export class Interrupted extends Error {
   readonly reason: string
 }
+
+/**
+ * A Reply nobody is waiting for any more, or a Request made once the waiting has stopped.
+ * See `IO.abandon`.
+ */
+export class Abandoned extends Error {}

package/types/io.d.ts

@@ -119,6 +119,12 @@ declare namespace comq {
 
     seal(): Promise<void>
 
+    /**
+     * Stops waiting for Replies: every one still outstanding is rejected with `Abandoned`, and a
+     * Request made from now on is refused with it. Callable while a close is already under way.
+     */
+    abandon(): Promise<void>
+
     close(): Promise<void>
 
     diagnose(event: 'open', listener: (index?: number) => void): void