queen-mq 1.3.0 → 2.0.2

package/client-v2/builders/QueueBuilder.js

@@ -16,6 +16,20 @@ import { checkConflationResponse, CONFLATION_UNSUPPORTED } from '../utils/confla
 import { popSizing, parseAutopilotDecision } from '../utils/autopilot.js'
 import * as logger from '../utils/logger.js'
 
+// Per-item push statuses that mean the broker took the message: `queued`
+// (stored), and `buffered` (a 1.x broker wrote it to its failover file and
+// replays it into storage itself). Every other status is a rejection: `error`
+// from a 2.x broker, which carries no per-item message, and `failed` from a
+// 1.x broker, which does. Unknown statuses count as rejections too: a status
+// 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
@@ -37,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
@@ -293,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
@@ -336,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
@@ -354,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,
@@ -364,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,
@@ -389,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
@@ -408,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.
    *
@@ -429,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
@@ -450,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)
@@ -475,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
@@ -509,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
@@ -542,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
@@ -849,24 +906,40 @@ class PushBuilder {
         for (let i = 0; i < results.length; i++) {
           const result = results[i]
           const originalItem = this.#formattedItems[i]
+          const status = result && typeof result === 'object' ? result.status : undefined
 
-          if (result.status === 'duplicate') {
+          if (status === 'duplicate') {
             duplicates.push({ ...originalItem, result })
-          } else if (result.status === 'failed') {
-            failed.push({ ...originalItem, result, error: result.error })
-          } else if (result.status === 'queued') {
+          } else if (ACCEPTED_PUSH_STATUSES.has(status)) {
             successful.push({ ...originalItem, result })
+          } else {
+            const error = result && typeof result.error === 'string' && result.error.length > 0
+              ? result.error
+              : `push rejected by the broker (item status: ${status === undefined ? 'missing' : JSON.stringify(status)})`
+            failed.push({ ...originalItem, result, error })
           }
         }
 
+        // One error for the whole call, built once so the callback and the
+        // throw describe the failure the same way. `results` is the broker's
+        // per-item answer in input order: the items that did go through are
+        // in it too, which is what a caller needs to retry only the rest.
+        let failure = null
+        if (failed.length > 0) {
+          failure = new Error(failed.length === 1
+            ? failed[0].error
+            : `${failed.length} of ${results.length} pushed items rejected: ${failed[0].error}`)
+          failure.results = results
+          logger.error('PushBuilder.execute', { status: 'failed', count: failed.length, total: results.length, error: failed[0].error })
+        }
+
         // Call appropriate callbacks
         if (duplicates.length > 0 && this.#onDuplicateCallback) {
           await this.#onDuplicateCallback(duplicates, new Error('Duplicate transaction IDs detected'))
         }
 
-        if (failed.length > 0 && this.#onErrorCallback) {
-          const error = new Error(failed[0].error || 'Push failed')
-          await this.#onErrorCallback(failed, error)
+        if (failure && this.#onErrorCallback) {
+          await this.#onErrorCallback(failed, failure)
         }
 
         if (successful.length > 0 && this.#onSuccessCallback) {
@@ -874,9 +947,8 @@ class PushBuilder {
         }
 
         // Only throw if no error callback is defined
-        if (failed.length > 0 && !this.#onErrorCallback) {
-          logger.error('PushBuilder.execute', { status: 'failed', count: failed.length })
-          throw new Error(failed[0].error || 'Push failed')
+        if (failure && !this.#onErrorCallback) {
+          throw failure
         }
 
         logger.log('PushBuilder.execute', { status: 'success', successful: successful.length, duplicates: duplicates.length, failed: failed.length })

package/client-v2/builders/TimerBuilder.js

@@ -24,8 +24,8 @@
  *    bundle's fate; see TransactionBuilder, which says so where it happens.)
  *
  * 2. ONLY RELATIVE DURATIONS, IN MILLISECONDS (§4.2, §20.6). `delayMs`, never
- *    `delaySeconds` and never an absolute instant: `deliver_at` is computed in
- *    Postgres, so there is ONE clock and no broker's skew can enter. The rule
+ *    `delaySeconds` and never an absolute instant: `deliver_at` is computed on
+ *    the broker's clock, so there is ONE clock and no client's skew can enter. The rule
  *    of the product is "durations that can be sub-second are in milliseconds,
  *    the ones that cannot are in seconds" -- a 250 ms retry backoff is a real
  *    and central use of timers, which is why this wire is the millisecond one.

package/client-v2/builders/TransactionBuilder.js

@@ -30,6 +30,7 @@ import { generateUUID } from './QueueBuilder.js'
 import { isValidUUID } from '../utils/validation.js'
 import { kvOp, materializeKvOp } from '../kv/Kv.js'
 import { TimerBuilder } from './TimerBuilder.js'
+import { consumerGroupOf } from '../utils/consumerGroup.js'
 
 export class TransactionBuilder {
   #httpClient
@@ -46,10 +47,21 @@ export class TransactionBuilder {
     this.#httpClient = httpClient
   }
 
+  /**
+   * Ack popped messages as part of this transaction.
+   *
+   * The consumer group defaults to the one each message was popped under
+   * (`message.consumerGroup`, which every pop answers with), because the lease
+   * an ack has to match belongs to that group: an ack that names no group is
+   * judged in queue mode, and a message popped by a group then fails with
+   * `rejected_ack`. Pass `{ consumerGroup }` (or `{ group }`, the key
+   * `queen.ack()` takes) to override it.
+   */
   ack(messages, status = 'completed', context = {}) {
     const msgs = Array.isArray(messages) ? messages : [messages]
-    
-    logger.log('TransactionBuilder.ack', { count: msgs.length, status, consumerGroup: context.consumerGroup })
+    const explicitGroup = context.consumerGroup || context.group || null
+
+    logger.log('TransactionBuilder.ack', { count: msgs.length, status, consumerGroup: explicitGroup })
 
     msgs.forEach(msg => {
       const transactionId = typeof msg === 'string' ? msg : (msg.transactionId || msg.id)
@@ -72,9 +84,18 @@ export class TransactionBuilder {
         status
       }
 
-      // Add consumerGroup if provided in context
-      if (context.consumerGroup) {
-        operation.consumerGroup = context.consumerGroup
+      const consumerGroup = explicitGroup || consumerGroupOf(msg)
+      if (consumerGroup) {
+        operation.consumerGroup = consumerGroup
+      }
+
+      // Each ack names its own lease. A Queen 2 broker fences an ack with the
+      // lease the operation carries, and lends it one from requiredLeases only
+      // when the bundle names a single lease: in a bundle spanning two leases,
+      // an ack without its own would be applied whoever holds its partition
+      // now. 1.x brokers read the operation's lease before requiredLeases too.
+      if (leaseId) {
+        operation.leaseId = leaseId
       }
 
       this.#operations.push(operation)
@@ -204,7 +225,7 @@ export class TransactionBuilder {
    *
    * `putIfAbsent` with `required:true`, so a marker that already exists ABORTS
    * the transaction: the push and the ack roll back together with it. That is
-   * what makes "the email is sent exactly once" a property of the database
+   * what makes "the email is sent exactly once" a property of the broker
    * rather than a hope about redelivery.
    *
    * The verdict is RETURNED by `commit()`, not thrown -- see there.
@@ -303,9 +324,14 @@ export class TransactionBuilder {
 
         logger.error('TransactionBuilder.commit', { error: result.error, reason: result.reason })
         const error = new Error(result.error || 'Transaction failed')
-        // The closed-taxonomy code travels ON the error, so no caller ever has
-        // to match the message: bad_request | duplicate | ack_rejected |
-        // timer_horizon_exceeded | payload_too_large | misaligned | db_error.
+        // The broker's reason code travels ON the error, so no caller ever has
+        // to match the message. The ones worth branching on from a 2.x broker:
+        // bad_request, duplicate (a pushed transactionId is already stored),
+        // rejected_ack (an acked message is no longer leased by this worker, or
+        // was popped under a different consumer group than the ack names), and
+        // too_large. A 1.x broker spells the ack one ack_rejected, and also
+        // sends timer_horizon_exceeded, payload_too_large, misaligned and
+        // db_error.
         if (result.reason) error.reason = result.reason
         error.result = result
         throw error

package/client-v2/consumer/ConsumerManager.js

@@ -211,20 +211,25 @@ export class ConsumerManager {
         try {
           // Process messages
           if (each) {
-            // Process one at a time
+            // 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 message of messages) {
               if (signal && signal.aborted) 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 (autoAck && !ok) {
-                logger.warn('ConsumerManager.worker', { workerId, status: 'batch-abandoned-after-nack', remaining: messages.length - messages.indexOf(message) - 1 })
-                break
+              if (!ok) {
+                nackedPartitions.add(partition)
+                logger.warn('ConsumerManager.worker', { workerId, status: 'partition-abandoned-after-nack', partition })
               }
 
               if (limit && processedCount >= limit) break
@@ -316,62 +321,83 @@ export class ConsumerManager {
   async #processMessage(message, handler, autoAck, group) {
     try {
       await handler(message)
-
-      // Auto-ack on success if enabled
-      if (autoAck) {
-        const context = group ? { group } : {}
-        const res = await this.#queen.ack(message, true, context)
-        if (res && res.success === false) {
-          logger.error('ConsumerManager.processMessage', { transactionId: message.transactionId, status: 'ack-rejected', error: res.error })
-        } else {
-          logger.log('ConsumerManager.processMessage', { transactionId: message.transactionId, status: 'acked' })
-        }
-      }
-      return true
     } catch (error) {
-      // Auto-nack on error if enabled
-      if (autoAck) {
-        const context = group ? { group, error: error.message } : { error: error.message }
-        const res = await this.#queen.ack(message, false, context)
-        if (res && res.success === false) {
-          logger.error('ConsumerManager.processMessage', { transactionId: message.transactionId, status: 'nack-rejected', error: res.error })
-        }
-        logger.error('ConsumerManager.processMessage', { transactionId: message.transactionId, error: error.message, status: 'nacked' })
-        // Don't rethrow when autoAck is enabled - NACK was already sent
-        // This allows the consumer to continue and retry
-        return false
+      await this.#nackFailed(message, error, autoAck, group, 'ConsumerManager.processMessage')
+      return false
+    }
+
+    // Auto-ack on success if enabled
+    if (autoAck) {
+      const context = group ? { group } : {}
+      const res = await this.#queen.ack(message, true, context)
+      if (res && res.success === false) {
+        logger.error('ConsumerManager.processMessage', { transactionId: message.transactionId, status: 'ack-rejected', error: res.error })
+      } else {
+        logger.log('ConsumerManager.processMessage', { transactionId: message.transactionId, status: 'acked' })
       }
-      logger.error('ConsumerManager.processMessage', { transactionId: message.transactionId, error: error.message })
-      throw error
     }
+    return true
   }
 
   async #processBatch(messages, handler, autoAck, group) {
     try {
       await handler(messages)
+    } catch (error) {
+      await this.#nackFailed(messages, error, autoAck, group, 'ConsumerManager.processBatch')
+      return
+    }
 
-      // Auto-ack on success if enabled
-      if (autoAck) {
-        const context = group ? { group } : {}
-        const res = await this.#queen.ack(messages, true, context)
-        if (res && res.success === false) {
-          logger.error('ConsumerManager.processBatch', { count: messages.length, status: 'ack-rejected', error: res.error })
-        } else {
-          logger.log('ConsumerManager.processBatch', { count: messages.length, status: 'acked' })
-        }
+    // Auto-ack on success if enabled
+    if (autoAck) {
+      const context = group ? { group } : {}
+      const res = await this.#queen.ack(messages, true, context)
+      if (res && res.success === false) {
+        logger.error('ConsumerManager.processBatch', { count: messages.length, status: 'ack-rejected', error: res.error })
+      } else {
+        logger.log('ConsumerManager.processBatch', { count: messages.length, status: 'acked' })
       }
-    } catch (error) {
-      // Auto-nack on error if enabled
-      if (autoAck) {
-        const context = group ? { group, error: error.message } : { error: error.message }
-        await this.#queen.ack(messages, false, context)
-        logger.error('ConsumerManager.processBatch', { count: messages.length, error: error.message, status: 'nacked' })
-        // Don't rethrow when autoAck is enabled - NACK was already sent
-        // This allows the consumer to continue and retry
-        return
+    }
+  }
+
+  /**
+   * A handler threw: nack what it was given, and let the worker keep
+   * consuming. The same with `autoAck(false)`, which hands the SUCCESS path to
+   * the handler and not the failure path: a handler that threw did not get to
+   * settle its messages, and leaving them leased would hold the partition
+   * until the lease expires. Before this, a throw under autoAck(false) left
+   * the worker loop and stopped the consumer (the others kept running behind a
+   * consume() promise that had already rejected).
+   *
+   * The nack goes through the broker's retry budget like any other: the
+   * message is redelivered, and lands in the DLQ once the queue's retryLimit
+   * is spent. A message the handler already acked before throwing is already
+   * settled, so the broker refuses its nack and nothing changes for it. A
+   * handler that wants to decide for itself (ack, nack, DLQ, or stop)
+   * declares `.onError()`, which catches the error before it gets here.
+   */
+  async #nackFailed(messageOrMessages, error, autoAck, group, where) {
+    const batch = Array.isArray(messageOrMessages)
+    const subject = batch ? { count: messageOrMessages.length } : { transactionId: messageOrMessages.transactionId }
+    // A handler can throw anything, not only an Error.
+    const reason = error instanceof Error ? error.message : String(error)
+    logger.error(where, { ...subject, error: reason, status: 'handler-failed', autoAck })
+
+    const context = group ? { group, error: reason } : { error: reason }
+    try {
+      const res = await this.#queen.ack(messageOrMessages, false, context)
+      if (res && res.success === false) {
+        // Under autoAck(false) this is usually a handler that acked before it
+        // threw; with autoAck it means the lease ran out under the handler.
+        const log = autoAck ? logger.error : logger.warn
+        log(where, { ...subject, status: 'nack-rejected', error: res.error })
+      } else {
+        logger.log(where, { ...subject, status: 'nacked' })
       }
-      logger.error('ConsumerManager.processBatch', { count: messages.length, error: error.message })
-      throw error
+    } catch (nackError) {
+      // A message this client cannot even address (no partitionId) cannot be
+      // nacked; its lease expires and the broker redelivers it. Never a reason
+      // to stop the consumer.
+      logger.error(where, { ...subject, status: 'nack-failed', error: nackError.message })
     }
   }
 

package/client-v2/ephemeral/Ephemeral.js

@@ -11,18 +11,19 @@
  * WHAT THIS CLASS IS ABOUT, BEFORE ANY SIGNATURE: contents survive NOTHING
  * (§1.2). Not a restart, not a crash, not a deploy, not the ownership move that
  * a membership change causes. Treat a failover like a Redis restart. Declared
- * CONFIGURATION is durable -- it lives in PG and comes back after a restart, as
- * configured and EMPTY. There is no replay, no history, no subscriptionMode and
+ * CONFIGURATION is durable -- it lives in the broker's replicated log and comes
+ * back after a restart, as configured and EMPTY. There is no replay, no history, no subscriptionMode and
  * no DLQ, because none of those concepts has a referent when there is no
  * 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:
@@ -252,9 +253,9 @@ export class Ephemeral {
   // ------------------------------------------------------------ declaration
 
   /**
-   * Declare a queue and its bounds. Persists the OPTIONS in PG (§1.1): the
-   * configuration survives a restart, the contents never do, and the queue
-   * comes back declared and empty.
+   * Declare a queue and its bounds. Persists the OPTIONS in the broker's
+   * replicated log (§1.1): the configuration survives a restart, the contents
+   * never do, and the queue comes back declared and empty.
    *
    * Optional in every sense -- a push or a pop that names an unknown queue
    * creates it implicitly with the tenant defaults (§1.1). Declare when you
@@ -289,7 +290,7 @@ export class Ephemeral {
     return this.#call('POST', '/api/v1/ephemeral/reset', { queue }, { queue })
   }
 
-  /** Delete the queue: contents, cursors, and the declared configuration in PG. */
+  /** Delete the queue: contents, cursors, and the declared configuration. */
   async delete(queue) {
     requireQueue(queue)
     logger.log('Ephemeral.delete', { queue })
@@ -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 })
 
@@ -482,9 +500,7 @@ export class Ephemeral {
   /**
    * Every ephemeral queue this tenant currently has, declared and implicit.
    *
-   * Free to poll: the gauges are read out of the broker's own memory, with no
-   * database behind them -- unlike the durable meter, whose 1s poll is
-   * load-bearing on PG.
+   * Free to poll: the gauges are read out of the broker's own memory.
    */
   async queues() {
     logger.log('Ephemeral.queues', {})
@@ -549,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
+}