queen-mq 2.0.0 → 2.0.3

package/README.md

@@ -22,7 +22,7 @@ Queen MQ is a partitioned message queue broker that keeps its state in its own r
 - **Consumer Groups** - Kafka-style consumer groups for scalability
 - **Flexible Semantics** - Exactly-once, at-least-once, and at-most-once delivery
 - **Transactions** - Atomic operations across push and ack
-- **High Performance** — 104K msg/s push, 165K msg/s fan-out with consumer groups on a single 32-core node ([benchmarks](https://github.com/queen-mq/queen/tree/master/benchmark-queen/2026-04-26))
+- **High Performance** — 1M msg/s in and out of one queue of 10M partitions on three nodes ([benchmarks](https://queenmq.com/benchmarks/))
 - **Subscription Modes** - Process from beginning, new messages only, or from timestamp
 - **Dead Letter Queue** - Automatic failure handling and monitoring
 - **Message Tracing** - Debug distributed workflows with trace timelines
@@ -192,8 +192,8 @@ Notes:
   the partition cap; either way it is clamped to 64, so a conflating pop returns
   at most 64 messages per round-trip whatever `batch` says.
 - Refused with 400 by the broker without a `.group(...)`, and together with
-  `.autoAck(true)` (auto-ack commits at delivery, which would turn the guarantee
-  above into at-most-once).
+  `.commitOnDelivery()` (a commit at delivery would turn the guarantee above
+  into at-most-once). `pop()` raises that 400 instead of returning `[]`.
 - Requires broker **>= 1.1.0**. An older broker ignores the flag and would
   quietly deliver the whole backlog, so the SDK raises
   `conflation was requested but this broker did not apply it` on the first
@@ -281,8 +281,9 @@ await queen.queue('tasks')
 
 **When the handler throws**, the consumer nacks what it was given (the message, or the whole batch)
 and keeps consuming. The broker redelivers it, and moves it to the dead letter queue once the queue's
-`retryLimit` is spent. With `.each()`, the rest of the popped batch is dropped after a nack: the
-broker redelivers it too.
+`retryLimit` is spent. With `.each()`, the later messages of the failed message's partition are
+skipped after a nack (the broker redelivers them too); the other partitions of the same pop are
+still handled.
 
 This is the same with `.autoAck(false)`. That setting hands the *success* path to your handler (it
 acks), not the failure path: a handler that threw never got to settle its messages. A message your
@@ -324,6 +325,36 @@ await queen.queue('tasks')
 Earlier versions stopped the consumer on a throw under `.autoAck(false)`: `consume()` rejected after
 the first failure, and the message stayed leased until its lease expired.
 
+**Stopping a consumer** (a graceful shutdown) is aborting its `signal`. The handler call in progress
+finishes, with its ack, and `consume()` resolves. Nothing is left leased:
+
+- The long poll in flight is closed at once. The broker hands nothing to a poll whose caller is gone,
+  so a message that arrives during the shutdown goes to another consumer straight away.
+- A pop answer that has already started arriving is read to the end: the broker leased its messages
+  when it sent it, and the body says which ones they are.
+- With `.each()`, messages already popped but not yet handed to the handler go back with a `retry`
+  ack. The broker releases their lease and redelivers them first, in order, without charging a
+  retry. The same happens to messages popped beyond `.limit()`.
+- A wait between attempts (a 429 backoff, a retry after a 5xx or a network error) ends at once.
+
+```javascript
+const stop = new AbortController()
+// consume() starts when awaited: Promise.resolve() starts it now and keeps the
+// promise that settles once the consumer has stopped.
+const consuming = Promise.resolve(queen.queue('tasks').group('workers').each()
+  .consume(async (message) => { await processTask(message.data) }, { signal: stop.signal }))
+
+process.once('SIGTERM', async () => {
+  stop.abort()
+  await consuming      // the message in the handler is finished and acked
+  await queen.close()
+})
+```
+
+Earlier versions checked the signal only between polls. A poll open at the abort stayed open for up
+to its timeout, and `.each()` dropped what it brought back without settling it, so its partition
+waited out the whole lease.
+
 ### Pop Messages (On-Demand Processing)
 
 ```javascript
@@ -794,8 +825,20 @@ const msgs = await queen.queue('q').batch(10).pop()
 const msgs = await queen.queue('q').batch(10).wait(true).pop()
 const msgs = await queen.queue('q').batch(200).partitions(50).pop()  // multi-partition pop
 const { messages, autopilot } = await queen.queue('q').popResult()   // + what the broker chose
+const msgs = await queen.queue('q').group('g').commitOnDelivery().pop()  // committed at delivery, nothing to ack
 ```
 
+A pop long-polls, waiting up to `timeoutMillis` (30 s) for a message, unless you call
+`.wait(false)`. Its messages come back leased, and the ack is yours.
+
+`.commitOnDelivery()` changes that for `pop()` and `popResult()`. The broker moves the group's
+cursor past the messages as it hands them out: there is no lease (`leaseId` is empty) and nothing
+to ack. This is at-most-once delivery: a crash after the pop loses the messages. The broker
+refuses it together with `.conflation()` (400). `consume()` always leases its messages, so it
+throws before any request when the builder has `.commitOnDelivery()`.
+
+`.autoAck()` is `consume()`'s ack after your handler and has no effect on a pop.
+
 ### Consume
 
 ```javascript
@@ -950,6 +993,18 @@ await queen.close()  // Flush buffers and close connections
 the broker. These values are what comes back with `.autopilot(false)` or
 `QUEEN_SDK_POP_AUTOPILOT=off`.
 
+### Pop Defaults
+
+```javascript
+{
+  batch: 1,              // autopilot OFF only, as for consume
+  wait: true,            // long-polls; .wait(false) returns at once
+  timeoutMillis: 30000,  // the long-poll limit
+  autoAck: false,        // consume()'s ack after the handler; no effect on pop()
+  commitOnDelivery: false // leased; .commitOnDelivery() commits at delivery (at-most-once)
+}
+```
+
 ---
 
 ## Logging

package/client-v2/Queen.js

@@ -319,8 +319,8 @@ export class Queen {
    *     creates it, which is what makes thousands of short-lived req/reply
    *     inboxes cheap (§1.1).
    *   * delivery is at-least-once while the owning broker lives, at-most-once
-   *     with `autoAck` (§1.3) -- NOT "at most once" as a class. Consumers still
-   *     need idempotency.
+   *     with `commitOnDelivery` (§1.3) -- NOT "at most once" as a class.
+   *     Consumers still need idempotency.
    *   * consumption semantics are the pop's `group`, exactly as on durable
    *     queues (§1.5): same group competes, own group fans out, no group is
    *     queue mode. There is no queue-level mode to set.

package/client-v2/README.md

@@ -1662,6 +1662,11 @@ const msgs = await queen.queue('q').partition('p1').pop()
 // capped at 200 total messages. All partitions share one leaseId.
 // Each returned message carries its own partitionId / partition / leaseId.
 const msgs = await queen.queue('q').batch(200).partitions(50).pop()
+
+// Commit at delivery: the broker moves the group's cursor past the messages
+// as it hands them out. No lease, nothing to ack, at-most-once: a crash after
+// the pop loses them. pop() and popResult() only; consume() throws.
+const msgs = await queen.queue('q').group('g').commitOnDelivery().pop()
 ```
 
 ### Consume
@@ -1915,8 +1920,9 @@ await queen.close()
 ```javascript
 {
   batch: 1,
-  wait: false,                        // No long polling
-  autoAck: false                      // Manual ack required
+  wait: true,                         // Long polling; .wait(false) returns at once
+  autoAck: false,                     // consume()'s ack after the handler; no effect on pop()
+  commitOnDelivery: false             // Manual ack required; .commitOnDelivery() commits at delivery
 }
 ```
 

package/client-v2/admin/Admin.js

@@ -101,15 +101,26 @@ export class Admin {
   }
 
   /**
-   * Clear all messages from a queue
+   * @deprecated The 2.x broker has no route that clears a queue, so this
+   *             always rejects, before any request. Seek each consumer group
+   *             to the end instead.
+   *
+   * The old DELETE /api/v1/queues/:name/clear answers 404 no_such_route on
+   * 2.x. A seek to the end moves one group's cursor past every queued message
+   * (and releases its live leases); the group of a pop without one is
+   * '__QUEUE_MODE__'. Deleting the queue is not a clear: it removes the queue
+   * itself, with its configuration.
    * @param {string} name - Queue name
-   * @param {string} [partition] - Optional partition to clear
-   * @returns {Promise<object>}
+   * @param {string} [partition] - Ignored
+   * @returns {Promise<never>}
    */
   async clearQueue(name, partition = null) {
     logger.log('Admin.clearQueue', { name, partition })
-    const queryString = partition ? `?partition=${encodeURIComponent(partition)}` : ''
-    return this.#httpClient.delete(`/api/v1/queues/${encodeURIComponent(name)}/clear${queryString}`)
+    throw new Error(
+      'Queen 2.x has no route that clears a queue. Move each consumer group past what is queued ' +
+      `with queen.admin.seekConsumerGroup(group, '${name}', { toEnd: true }); ` +
+      "a pop without a group reads as the group '__QUEUE_MODE__'."
+    )
   }
 
   /**
@@ -172,14 +183,25 @@ export class Admin {
   }
 
   /**
-   * Move a message to the Dead Letter Queue
+   * @deprecated The 2.x broker has no route that moves a message to the DLQ
+   *             by its address, so this always rejects, before any request.
+   *             Ack the leased message with the `dlq` status instead.
+   *
+   * The old POST /api/v1/messages/:partitionId/:transactionId/dlq answers 404
+   * no_such_route on 2.x. The broker files a dead letter when the consumer
+   * group acks the message with the `dlq` status while it holds the lease (an
+   * address alone cannot name the lease), or when a `failed` ack spends the
+   * queue's last retry.
    * @param {string} partitionId - Partition ID
    * @param {string} transactionId - Transaction ID
-   * @returns {Promise<object>}
+   * @returns {Promise<never>}
    */
   async moveMessageToDLQ(partitionId, transactionId) {
     logger.log('Admin.moveMessageToDLQ', { partitionId, transactionId })
-    return this.#httpClient.post(`/api/v1/messages/${partitionId}/${transactionId}/dlq`, {})
+    throw new Error(
+      'Queen 2.x has no route that moves a message to the DLQ by its address. Pop the message for ' +
+      "its consumer group and call queen.ack(message, 'dlq', { group }) while you hold its lease."
+    )
   }
 
   // ===========================

package/client-v2/builders/QueueBuilder.js

@@ -24,6 +24,12 @@ import * as logger from '../utils/logger.js'
 // this client cannot read is not a message it can report as stored.
 const ACCEPTED_PUSH_STATUSES = new Set(['queued', 'buffered'])
 
+// What consume() throws when the builder carries commitOnDelivery(): the loop
+// always pops leased and acks after the handler, so it cannot honour a commit
+// at delivery, and silently leasing would not be what the caller asked for.
+const COMMIT_ON_DELIVERY_NOT_FOR_CONSUME =
+  'commitOnDelivery() is a pop() option; consume() always leases its messages'
+
 export class QueueBuilder {
   #queen
   #httpClient
@@ -45,8 +51,14 @@ export class QueueBuilder {
   #batch = null
   #limit = CONSUME_DEFAULTS.limit
   #idleMillis = CONSUME_DEFAULTS.idleMillis
-  #autoAck = CONSUME_DEFAULTS.autoAck
-  #wait = CONSUME_DEFAULTS.wait
+  // autoAck and wait hold the USER's value, and null means the setter was never
+  // called: consume() applies CONSUME_DEFAULTS and pop() POP_DEFAULTS at
+  // emission time. autoAck is consume()'s alone; pop() never sends it.
+  #autoAck = null
+  #wait = null
+  // The pop's own option for the broker's commit at delivery: pop() and
+  // popResult() send it as autoAck=true, and consume() refuses it.
+  #commitOnDelivery = POP_DEFAULTS.commitOnDelivery
   #timeoutMillis = CONSUME_DEFAULTS.timeoutMillis
   #renewLease = CONSUME_DEFAULTS.renewLease
   #renewLeaseIntervalMillis = CONSUME_DEFAULTS.renewLeaseIntervalMillis
@@ -301,6 +313,12 @@ export class QueueBuilder {
     return this
   }
 
+  /**
+   * consume(): ack each message after the handler returns (default true; the
+   * client acks, nothing is sent with the pop). No effect on pop(): it never
+   * reaches the wire. For the broker's at-most-once commit at delivery on a
+   * pop, use commitOnDelivery().
+   */
   autoAck(enabled) {
     this.#autoAck = enabled
     return this
@@ -344,8 +362,9 @@ export class QueueBuilder {
    * that does not echo the flag rather than draining it silently.
    *
    * Refused by the broker (400) when combined with queue mode (no consumer
-   * group) or with autoAck, which commits at delivery and would turn the
-   * "the newest state is definitely processed" guarantee into at-most-once.
+   * group) or with commitOnDelivery(), which commits at delivery and would
+   * turn the "the newest state is definitely processed" guarantee into
+   * at-most-once. pop() raises that 400 instead of returning [].
    */
   conflation(enabled = true) {
     this.#conflation = !!enabled
@@ -362,6 +381,10 @@ export class QueueBuilder {
   // ===========================
 
   consume(handler, options = {}) {
+    if (this.#commitOnDelivery) {
+      throw new Error(COMMIT_ON_DELIVERY_NOT_FOR_CONSUME)
+    }
+
     const consumeOptions = {
       queue: this.#queueName,
       partition: this.#partition !== 'Default' ? this.#partition : null,
@@ -372,8 +395,8 @@ export class QueueBuilder {
       batch: this.#batch,
       limit: this.#limit,
       idleMillis: this.#idleMillis,
-      autoAck: this.#autoAck,
-      wait: this.#wait,
+      autoAck: this.#autoAck ?? CONSUME_DEFAULTS.autoAck,
+      wait: this.#wait ?? CONSUME_DEFAULTS.wait,
       timeoutMillis: this.#timeoutMillis,
       renewLease: this.#renewLease,
       renewLeaseIntervalMillis: this.#renewLeaseIntervalMillis,
@@ -397,6 +420,10 @@ export class QueueBuilder {
   // Pop Methods
   // ===========================
 
+  /**
+   * Long-poll: wait up to timeoutMillis for a message instead of returning
+   * empty at once. Default true for both pop() and consume().
+   */
   wait(enabled) {
     this.#wait = enabled
     return this
@@ -416,6 +443,24 @@ export class QueueBuilder {
     return this
   }
 
+  /**
+   * Commit the messages of pop() and popResult() at delivery.
+   *
+   * The broker moves the consumer group's cursor past the messages as it hands
+   * them out: no lease, nothing to ack (the messages come back with an empty
+   * leaseId). That is at-most-once: a crash after the pop loses them. The
+   * request carries autoAck=true, the parameter every 2.x broker reads.
+   *
+   * A pop option only: consume() always leases its messages, so it throws
+   * when this is set. The broker refuses it together with conflation() (400).
+   *
+   * @param {boolean} [enabled=true]
+   */
+  commitOnDelivery(enabled = true) {
+    this.#commitOnDelivery = !!enabled
+    return this
+  }
+
   /**
    * Claim messages and report what the broker chose for this pop.
    *
@@ -437,15 +482,17 @@ export class QueueBuilder {
   }
 
   async #popWithDecision() {
-    logger.log('QueueBuilder.pop', { queue: this.#queueName, partition: this.#partition, namespace: this.#namespace, task: this.#task, batch: this.#batch, wait: this.#wait, group: this.#group })
+    // For pop(), use POP defaults (not CONSUME defaults) for what the caller
+    // did not set. autoAck() is consume()'s ack after the handler and never
+    // reaches the wire; the broker's at-most-once autoAck travels only from
+    // commitOnDelivery(). Without it a pop comes back leased.
+    const effectiveWait = this.#wait ?? POP_DEFAULTS.wait
+
+    logger.log('QueueBuilder.pop', { queue: this.#queueName, partition: this.#partition, namespace: this.#namespace, task: this.#task, batch: this.#batch, wait: effectiveWait, group: this.#group })
     
     try {
       const path = this.#buildPopPath()
       
-      // For pop(), use POP defaults (not CONSUME defaults)
-      // Override autoAck to false unless explicitly set
-      const effectiveAutoAck = this.#autoAck !== CONSUME_DEFAULTS.autoAck ? this.#autoAck : POP_DEFAULTS.autoAck
-      
       // Batch, partitions and with them the autopilot flag. The RULE for which
       // of the three travel lives in one place (utils/autopilot.js) because
       // consume() builds its query string separately; only the PLACEMENT is
@@ -458,17 +505,18 @@ export class QueueBuilder {
         autopilot: this.#autopilotEnabled()
       })
 
-      // Build params with correct autoAck for pop
       const params = new URLSearchParams()
       if (sizing.autopilot) params.append('autopilot', 'true')
       if (sizing.batch !== null) params.append('batch', sizing.batch)
-      params.append('wait', this.#wait.toString())
+      params.append('wait', effectiveWait.toString())
       params.append('timeout', this.#timeoutMillis.toString())
 
       if (this.#group) params.append('consumerGroup', this.#group)
       if (this.#namespace) params.append('namespace', this.#namespace)
       if (this.#task) params.append('task', this.#task)
-      if (effectiveAutoAck) params.append('autoAck', 'true')
+      // Sent only when true, where earlier SDKs placed it: an absent autoAck
+      // is the broker's leased default.
+      if (this.#commitOnDelivery) params.append('autoAck', 'true')
       if (this.#subscriptionMode) params.append('subscriptionMode', this.#subscriptionMode)
       if (this.#subscriptionFrom) params.append('subscriptionFrom', this.#subscriptionFrom)
       if (sizing.partitions !== null) params.append('partitions', sizing.partitions)
@@ -483,7 +531,7 @@ export class QueueBuilder {
 
       // wait=true is a long-poll: on 429 it should back off and keep waiting
       // rather than give up after a handful of tries (retryKind: 'pop').
-      const result = await this.#httpClient.get(`${path}?${params}`, this.#timeoutMillis + 5000, affinityKey, this.#wait ? 'pop' : null)
+      const result = await this.#httpClient.get(`${path}?${params}`, this.#timeoutMillis + 5000, affinityKey, effectiveWait ? 'pop' : null)
 
       // Degrade-loudly (PLAN_CONFLATION §4), BEFORE the empty-response return:
       // an old broker's empty pop is a bodiless 204 (result === null), and that
@@ -517,8 +565,8 @@ export class QueueBuilder {
       // messages right now"; for a declared conflation it would mean "your
       // last-value policy is not in force and you will never be told", which is
       // the silent failure the feature is not allowed to have (§4). Both the
-      // missing-echo error and the broker's 400 refusals (queue mode / autoAck)
-      // are permanent config faults, so they raise.
+      // missing-echo error and the broker's 400 refusals (queue mode /
+      // commitOnDelivery) are permanent config faults, so they raise.
       if (error.code === CONFLATION_UNSUPPORTED || (this.#conflation && error.status === 400)) {
         logger.error('QueueBuilder.pop', { error: error.message, status: error.status, code: error.code, conflation: true })
         throw error
@@ -550,17 +598,18 @@ export class QueueBuilder {
 
   // NOTE: a second, DEAD copy of the pop parameter builder lived here and was
   // deleted with the kv/timers work (PLAN_KV_TIMERS.md §10.4). pop() builds its
-  // own params inline, above, because it has to override autoAck with the POP
-  // defaults; the dead copy did not. Anyone adding a parameter by looking for
-  // the method whose name says "build pop params" would have added it to the
-  // copy nobody calls: the pop would keep working and the parameter would
-  // simply never arrive, which reads as a server-side mystery and not as a
-  // client bug.
+  // own params inline, above, because it uses the POP defaults and carries
+  // commitOnDelivery, which consume() refuses. Anyone adding a parameter by
+  // looking for the method whose name says "build pop params" would have added
+  // it to the copy nobody calls: the pop would keep working and the parameter
+  // would simply never arrive, which reads as a server-side mystery and not as
+  // a client bug.
   //
   // The pair that is still live and MUST be kept in sync is pop()'s inline
   // params above and ConsumerManager#buildParams: every pop query parameter
   // (subscriptionMode, subscriptionFrom, partitions, conflation, ...) has to be
-  // appended in BOTH, because pop() and consume() share no builder.
+  // appended in BOTH, because pop() and consume() share no builder. The one
+  // exception is commitOnDelivery's autoAck=true: consume() throws instead.
 
   // ===========================
   // Buffer Management Methods

package/client-v2/consumer/ConsumerManager.js

@@ -7,6 +7,20 @@ import { checkConflationResponse, CONFLATION_UNSUPPORTED } from '../utils/confla
 import { popSizing, parseAutopilotDecision, emptyPollDelayMillis } from '../utils/autopilot.js'
 import { CONSUME_DEFAULTS } from '../utils/defaults.js'
 
+/** Wait `ms`, or less if the consumer is stopped meanwhile: the loop checks the signal next. */
+function pause(ms, signal) {
+  if (signal?.aborted) return Promise.resolve()
+  return new Promise(resolve => {
+    const done = () => {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', done)
+      resolve()
+    }
+    const timer = setTimeout(done, ms)
+    signal?.addEventListener('abort', done, { once: true })
+  })
+}
+
 export class ConsumerManager {
   #httpClient
   #queen
@@ -160,7 +174,10 @@ export class ConsumerManager {
         // a long-poll: mark it 'pop' so a 429 backs off and keeps waiting
         // instead of giving up after the bounded push-like attempt budget.
         const clientTimeout = wait ? timeoutMillis + 5000 : timeoutMillis
-        const result = await this.#httpClient.get(`${path}?${baseParams}`, clientTimeout, affinityKey, wait ? 'pop' : null)
+        // The signal closes the poll as well: a broker hands nothing to a poll
+        // whose caller is gone, so a stopped consumer is never given a message
+        // it would only sit on until the lease expires.
+        const result = await this.#httpClient.get(`${path}?${baseParams}`, clientTimeout, affinityKey, wait ? 'pop' : null, signal)
 
         // Degrade-loudly (PLAN_CONFLATION §4). Checked BEFORE the empty-response
         // branch on purpose: a pre-1.1.0 broker answers an empty pop with a
@@ -181,7 +198,7 @@ export class ConsumerManager {
             // pop engaged autopilot and the broker had an opinion (it knows the
             // arrival rate on this queue and this client does not), otherwise
             // the historical 100ms.
-            await new Promise(resolve => setTimeout(resolve, emptyPollDelayMillis(parseAutopilotDecision(result))))
+            await pause(emptyPollDelayMillis(parseAutopilotDecision(result)), signal)
             continue
           }
         }
@@ -211,23 +228,35 @@ export class ConsumerManager {
         try {
           // Process messages
           if (each) {
-            // Process one at a time
-            for (const message of messages) {
-              if (signal && signal.aborted) break
+            // Process one at a time. A nack releases the failed message's
+            // partition and clamps that partition's cursor at it: the later
+            // messages of THAT partition will be redelivered, so handling them
+            // now would only produce duplicates and rejected acks. The other
+            // partitions of a multi-partition pop are still leased to this
+            // worker, so their messages are handled now, not after the lease.
+            const nackedPartitions = new Set()
+            for (const [i, message] of messages.entries()) {
+              // Stopped, or the limit reached, with messages still in hand:
+              // give them back rather than leave them leased. Those of a
+              // nacked partition were already given back by the nack.
+              if ((signal && signal.aborted) || (limit && processedCount >= limit)) {
+                const unstarted = messages.slice(i).filter(m => !nackedPartitions.has(m.partitionId ?? m.partition))
+                if (unstarted.length > 0) {
+                  await this.#releaseUnstarted(unstarted, group, signal && signal.aborted ? 'aborted' : 'limit-reached')
+                }
+                break
+              }
+
+              const partition = message.partitionId ?? message.partition
+              if (nackedPartitions.has(partition)) continue
 
               const ok = await this.#processMessage(message, handler, autoAck, group)
               processedCount++
 
-              // A nack releases the lease and clamps the server cursor at the
-              // failed message: everything after it in this popped batch WILL
-              // be redelivered. Processing it now would only produce duplicates
-              // and rejected acks — abandon the rest of the batch.
               if (!ok) {
-                logger.warn('ConsumerManager.worker', { workerId, status: 'batch-abandoned-after-nack', remaining: messages.length - messages.indexOf(message) - 1 })
-                break
+                nackedPartitions.add(partition)
+                logger.warn('ConsumerManager.worker', { workerId, status: 'partition-abandoned-after-nack', partition })
               }
-
-              if (limit && processedCount >= limit) break
             }
           } else {
             // Process as batch
@@ -244,6 +273,13 @@ export class ConsumerManager {
         }
 
       } catch (error) {
+        // Stopped while a poll was open: the poll was closed, nothing was
+        // taken, the worker is done. Not an error, whatever the wait mode.
+        if (error.aborted || (signal && signal.aborted)) {
+          logger.log('ConsumerManager.worker', { workerId, status: 'aborted', processedCount })
+          break
+        }
+
         // Conflation faults are terminal and are classified FIRST, ahead of the
         // message-substring heuristics below: a consumer that asked for
         // last-value delivery and is not getting it must stop, not retry
@@ -273,7 +309,7 @@ export class ConsumerManager {
             ? error.retryAfterSeconds * 1000
             : 1000
           logger.warn('ConsumerManager.worker', { workerId, status: 'rate-limited', code: error.code, retryAfterMs })
-          await new Promise(resolve => setTimeout(resolve, retryAfterMs))
+          await pause(retryAfterMs, signal)
           continue
         }
 
@@ -285,7 +321,7 @@ export class ConsumerManager {
         if (isNetworkError) {
           logger.warn('ConsumerManager.worker', { workerId, error: 'network', message: error.message })
           // Wait before retry
-          await new Promise(resolve => setTimeout(resolve, 1000))
+          await pause(1000, signal)
           continue
         }
 
@@ -334,6 +370,26 @@ export class ConsumerManager {
     return true
   }
 
+  /**
+   * Hand back messages this worker holds but will not process (it was stopped,
+   * or reached its limit): a `retry` ack releases their lease, the broker
+   * redelivers them first, in order, and charges no retry. Best effort -- a
+   * release that fails leaves the message to its lease, as before.
+   */
+  async #releaseUnstarted(messages, group, reason) {
+    const subject = { count: messages.length, transactionIds: messages.map(m => m.transactionId) }
+    try {
+      const res = await this.#queen.ack(messages, 'retry', group ? { group } : {})
+      if (res && res.success === false) {
+        logger.warn('ConsumerManager.release', { ...subject, reason, status: 'release-rejected', error: res.error })
+      } else {
+        logger.log('ConsumerManager.release', { ...subject, reason, status: 'released' })
+      }
+    } catch (error) {
+      logger.warn('ConsumerManager.release', { ...subject, reason, status: 'release-failed', error: error.message })
+    }
+  }
+
   async #processBatch(messages, handler, autoAck, group) {
     try {
       await handler(messages)

package/client-v2/ephemeral/Ephemeral.js

@@ -17,12 +17,13 @@
  * history to have.
  *
  * DELIVERY IS NOT "AT MOST ONCE" (§1.3), and the docs must not say it is. The
- * class picks what can be LOST; the ack mode picks the guarantee. `autoAck`
- * advances the cursor at delivery and is at-most-once. The default -- explicit
- * ack -- is at-least-once for as long as the owning broker incarnation lives:
- * an unacked message redelivers when its lease expires, with `attempts`
- * incremented, until `retryLimit`, after which it is DROPPED and counted (no
- * DLQ, §9). Consumers still need idempotency, exactly as on durable queues.
+ * class picks what can be LOST; the ack mode picks the guarantee.
+ * `commitOnDelivery` advances the cursor at delivery and is at-most-once. The
+ * default -- explicit ack -- is at-least-once for as long as the owning broker
+ * incarnation lives: an unacked message redelivers when its lease expires,
+ * with `attempts` incremented, until `retryLimit`, after which it is DROPPED
+ * and counted (no DLQ, §9). Consumers still need idempotency, exactly as on
+ * durable queues.
  *
  * CONSUMPTION SEMANTICS COME FROM THE GROUP, EXACTLY AS ON THE DURABLE ENGINE
  * (§1.5). There is no queue-level mode to choose:
@@ -404,7 +405,23 @@ export class Ephemeral {
    *
    * `group` is the whole of the consumption semantics (§1.5): same group =
    * competing consumers, own group = fan-out, no group = queue mode.
-   * `autoAck:true` commits at delivery and is at-most-once.
+   *
+   * `commitOnDelivery:true` commits at delivery: the broker moves the group's
+   * cursor past the messages as it hands them out, with no lease and nothing
+   * to ack. That is at-most-once: a crash after the pop loses them. It
+   * travels as `autoAck=true`, the parameter the broker reads.
+   *
+   * @param {string} queue
+   * @param {object} [opts]
+   * @param {string} [opts.partition]
+   * @param {number} [opts.batch]
+   * @param {boolean} [opts.wait]
+   * @param {number} [opts.timeout] Milliseconds; `timeoutMillis` is the same.
+   * @param {string} [opts.group]
+   * @param {boolean} [opts.commitOnDelivery] Commit at delivery (at-most-once).
+   * @param {boolean} [opts.autoAck] Deprecated: the old name of
+   *   `commitOnDelivery`, still read with the same meaning. Pass one or the
+   *   other, not both.
    */
   async pop(queue, opts = {}) {
     requireQueue(queue)
@@ -413,6 +430,7 @@ export class Ephemeral {
     const group = opts.group ?? null
     const wait = opts.wait === true
     const timeoutMillis = resolveTimeout(opts)
+    const commitOnDelivery = resolveCommitOnDelivery(opts)
 
     const params = new URLSearchParams({ queue })
     if (partition !== null) params.append('partition', partition)
@@ -424,7 +442,7 @@ export class Ephemeral {
       params.append('timeout', String(timeoutMillis))
     }
     if (group !== null) params.append('group', group)
-    if (opts.autoAck === true) params.append('autoAck', 'true')
+    if (commitOnDelivery) params.append('autoAck', 'true')
 
     logger.log('Ephemeral.pop', { queue, partition, group, batch: opts.batch ?? null, wait })
 
@@ -547,3 +565,17 @@ function resolveTimeout(opts) {
   if (hasMillis) return opts.timeoutMillis
   return DEFAULT_WAIT_TIMEOUT_MILLIS
 }
+
+/**
+ * The pop's commit at delivery, from `commitOnDelivery` or its deprecated
+ * alias `autoAck`. Both spellings at once are refused, as for the timeout: two
+ * values for one setting would have to be resolved by a rule nobody reads.
+ */
+function resolveCommitOnDelivery(opts) {
+  const hasName = opts.commitOnDelivery !== undefined && opts.commitOnDelivery !== null
+  const hasAlias = opts.autoAck !== undefined && opts.autoAck !== null
+  if (hasName && hasAlias) {
+    throw new Error('ephemeral: pass either `commitOnDelivery` or its deprecated alias `autoAck`, not both')
+  }
+  return (hasName ? opts.commitOnDelivery : opts.autoAck) === true
+}