queen-mq 1.0.3 → 1.0.6

package/client-v2/buffer/MessageBuffer.js

@@ -1,7 +1,43 @@
 /**
- * Message buffer for a single queue
+ * Message buffer for a single queue/partition.
+ *
+ * This is the client-side linger: single pushes accumulate here and leave as
+ * one request once `messageCount` messages are waiting, or `timeMillis` has
+ * passed since the first one arrived. Two properties beyond that batching are
+ * load-bearing, and neither existed before 2026-08-20:
+ *
+ *  - `maxSize` is a BLOCKING bound, not a hint. `add()` returns a promise that
+ *    does not resolve while the buffer is full, so a producer that outruns the
+ *    flush pipeline is paced down to the drain rate instead of growing the
+ *    heap. Measured on the Go client, whose buffer had exactly this shape:
+ *    filling at 1.46M msg/s against a 1.0M msg/s flush pipeline accumulated
+ *    20.9M messages (11.7 GB of RSS) in 45 seconds and lost every one of them
+ *    at process exit, with ZERO client-side errors reported anywhere. The
+ *    bounded version sustained 881,148 msg/s with exact send/receive parity
+ *    (39,655,787 = 39,655,787) and 71 MB of RSS.
+ *
+ *  - A batch that fails to send is put BACK at the front of the buffer, in
+ *    order, and retried after `retryDelayMillis`. It is never dropped. Before
+ *    this, the flusher took the batch out before the POST and only logged the
+ *    failure, so up to `messageCount` messages vanished per failed request.
+ *
+ * Together those two turn a broker outage into blocked producers with bounded
+ * memory, instead of silent loss.
+ *
+ * BLOCKING IDIOM: JavaScript is single-threaded, so "block" cannot mean
+ * "occupy the thread" -- that would starve the very flush that frees the
+ * capacity being waited for. It means an awaitable gate: parked adds hold a
+ * promise that the flusher resolves after each drained batch (and `stop()`
+ * rejects). No spin loop, no setInterval poll: the event loop is free to run
+ * the flush while producers wait.
+ *
+ * Buffered messages still live only in this process's memory. A crash, or a
+ * `process.exit()` that skips `close()`, loses them -- buffering belongs on
+ * telemetry-shaped traffic, not on anything that must not be lost.
  */
 
+import { BUFFER_DEFAULTS } from '../utils/defaults.js'
+
 export class MessageBuffer {
   #queueAddress
   #messages = []
@@ -10,15 +46,93 @@ export class MessageBuffer {
   #timer = null
   #firstMessageTime = null
   #flushing = false
+  #stopped = false
+  // Adds parked on the maxSize bound. Each entry can be woken (capacity freed)
+  // or failed (stop, or the caller's AbortSignal).
+  #waiters = []
+  // Counts adds that have been woken but have not resumed yet. JS resumes an
+  // awaiting function on a later microtask, so the waiter list is already empty
+  // while those adds are still in flight; without this counter BufferManager
+  // could drop the buffer entry out of its map in that window and the resumed
+  // add would append to an orphan nobody ever flushes.
+  #parked = 0
+  #stopWaiters = []
 
   constructor(queueAddress, options, flushCallback) {
     this.#queueAddress = queueAddress
-    this.#options = options
+    this.#options = MessageBuffer.normalizeOptions(options)
     this.#flushCallback = flushCallback
   }
 
-  add(formattedMessage) {
-    // Set first message time if this is the first message
+  /**
+   * Fill in defaults and enforce the bound's invariants.
+   *
+   * `maxSize: 0` (or absent) means the DEFAULT bound, never "unbounded":
+   * unbounded is the defect this knob exists to close, so opting out of
+   * backpressure is deliberately not expressible. The floor keeps the bound
+   * sane when a caller sets a `messageCount` larger than their `maxSize` --
+   * a buffer that must block before it can even assemble one batch would
+   * deadlock against its own flush threshold.
+   */
+  static normalizeOptions(options) {
+    // The caller's raw options, NOT BUFFER_DEFAULTS spread over them: the bound
+    // is derived from whatever messageCount this buffer ended up with, so
+    // `buffer({ messageCount: 10 })` gets a bound of 40, not the 400 that suits
+    // the default batch of 100. Unknown keys are carried through untouched.
+    const provided = options || {}
+
+    const messageCount = provided.messageCount > 0 ? provided.messageCount : BUFFER_DEFAULTS.messageCount
+    const timeMillis = provided.timeMillis > 0 ? provided.timeMillis : BUFFER_DEFAULTS.timeMillis
+
+    let maxSize = provided.maxSize > 0 ? provided.maxSize : 4 * messageCount
+    if (maxSize < messageCount) maxSize = messageCount
+
+    const retryDelayMillis = provided.retryDelayMillis > 0
+      ? provided.retryDelayMillis
+      : BUFFER_DEFAULTS.retryDelayMillis
+
+    return { ...provided, messageCount, timeMillis, maxSize, retryDelayMillis }
+  }
+
+  /**
+   * Append one message, waiting for room if the buffer is at its bound.
+   *
+   * Resolves once the message is in the buffer. Rejects if the buffer is
+   * stopped while parked, or if `signal` aborts -- an add that could not be
+   * buffered must never look like a successful push.
+   *
+   * @param {object} formattedMessage
+   * @param {{ signal?: AbortSignal }} [opts]
+   */
+  async add(formattedMessage, { signal } = {}) {
+    if (this.#stopped) {
+      throw new Error(`Queen buffer ${this.#queueAddress} is stopped: message not buffered`)
+    }
+    if (signal?.aborted) throw abortReason(signal)
+
+    // BACKPRESSURE. Re-checked in a loop, not once: a broadcast wakes every
+    // parked add, and the first ones to resume can fill the room that was
+    // freed, so the rest have to park again.
+    while (this.#messages.length >= this.#options.maxSize && !this.#stopped) {
+      // Being at the bound means producers outran the flusher. Make sure one is
+      // actually running before parking -- the time-based flush may be a full
+      // `timeMillis` away, and nothing else will start it.
+      this.#triggerFlush()
+      // The counter is held across the resumption itself, not just the wait:
+      // see #parked for why the window between "woken" and "resumed" matters.
+      this.#parked++
+      try {
+        await this.#waitForCapacity(signal)
+      } finally {
+        this.#parked--
+      }
+      if (signal?.aborted) throw abortReason(signal)
+    }
+
+    if (this.#stopped) {
+      throw new Error(`Queen buffer ${this.#queueAddress} stopped while waiting for capacity: message not buffered`)
+    }
+
     if (this.#messages.length === 0) {
       this.#firstMessageTime = Date.now()
       this.#startTimer()
@@ -26,77 +140,146 @@ export class MessageBuffer {
 
     this.#messages.push(formattedMessage)
 
-    // Check if we should flush based on size
     if (this.#messages.length >= this.#options.messageCount) {
       this.#triggerFlush()
     }
   }
 
+  #waitForCapacity(signal) {
+    return new Promise((resolve, reject) => {
+      const waiter = { resolve, reject, signal, onAbort: null }
+
+      waiter.settle = (fn, arg) => {
+        const index = this.#waiters.indexOf(waiter)
+        if (index !== -1) this.#waiters.splice(index, 1)
+        if (waiter.onAbort) signal.removeEventListener('abort', waiter.onAbort)
+        fn(arg)
+      }
+
+      if (signal) {
+        waiter.onAbort = () => waiter.settle(reject, abortReason(signal))
+        signal.addEventListener('abort', waiter.onAbort, { once: true })
+      }
+
+      this.#waiters.push(waiter)
+    })
+  }
+
+  /**
+   * Wake every parked add. Called by the flusher after a batch is definitively
+   * gone (the POST succeeded), not when the batch is merely taken out of the
+   * buffer: a batch that fails goes straight back, and waking on extraction
+   * would let producers refill against room that never actually freed.
+   */
+  wakeWaiters() {
+    const waiters = this.#waiters.slice()
+    for (const waiter of waiters) waiter.settle(waiter.resolve)
+  }
+
   #startTimer() {
     if (this.#timer) return // Timer already running
 
+    // Deliberately NOT unref()'d: a short script that pushes and returns must
+    // stay alive long enough for the time-based flush to fire.
     this.#timer = setTimeout(() => {
+      this.#timer = null
       this.#triggerFlush()
     }, this.#options.timeMillis)
   }
 
   #triggerFlush() {
-    if (this.#flushing || this.#messages.length === 0) return
-
-    // Clear timer
-    if (this.#timer) {
-      clearTimeout(this.#timer)
-      this.#timer = null
-    }
-
-    // Trigger flush via callback
+    if (this.#flushing || this.#stopped || this.#messages.length === 0) return
     this.#flushCallback(this.#queueAddress)
   }
 
-  extractMessages(batchSize = null) {
-    // If no batch size specified, extract all messages
-    if (batchSize === null || batchSize >= this.#messages.length) {
-      const messages = [...this.#messages]
-      this.#messages = []
-      this.#firstMessageTime = null
-      this.#flushing = false
-
-      if (this.#timer) {
-        clearTimeout(this.#timer)
-        this.#timer = null
-      }
+  /**
+   * Claim the right to flush this buffer. Returns false when a flush is already
+   * running: one drain loop per buffer, so a burst of adds past the threshold
+   * cannot start a second sender that would interleave batches out of order.
+   */
+  beginFlush() {
+    if (this.#flushing || this.#stopped || this.#messages.length === 0) return false
+    this.#flushing = true
+    this.cancelTimer()
+    return true
+  }
 
-      return messages
-    }
+  /**
+   * Release the flush claim. Anything still buffered (a batch put back by a
+   * failed send, or messages added while the drain was stopping) gets a fresh
+   * timer, so it cannot sit there unnoticed until the next add.
+   */
+  endFlush() {
+    this.#flushing = false
+    if (this.#messages.length > 0 && !this.#stopped) this.#startTimer()
+  }
 
-    // Extract a batch of messages
+  /**
+   * Take up to `batchSize` messages off the front.
+   *
+   * `splice` returns a fresh array, so the batch does not alias the buffer's
+   * storage and putting it back cannot corrupt what is left behind. (The Go
+   * reference has to copy explicitly there -- its slices do alias.)
+   */
+  takeBatch(batchSize) {
     const messages = this.#messages.splice(0, batchSize)
-    
-    // If buffer is now empty, reset state
-    if (this.#messages.length === 0) {
-      this.#firstMessageTime = null
-      this.#flushing = false
-      
-      if (this.#timer) {
-        clearTimeout(this.#timer)
-        this.#timer = null
-      }
-    }
-
+    if (this.#messages.length === 0) this.#firstMessageTime = null
     return messages
   }
 
-  setFlushing(value) {
-    this.#flushing = value
+  /**
+   * Put a failed batch back at the FRONT, preserving order: these messages were
+   * queued before everything still in the buffer, and a retry must not reorder
+   * a partition's lane. Occupancy can overshoot maxSize by this one batch --
+   * documented on BUFFER_DEFAULTS.maxSize.
+   */
+  restoreBatch(messages) {
+    if (messages.length === 0) return
+    this.#messages.unshift(...messages)
+    if (this.#firstMessageTime === null) this.#firstMessageTime = Date.now()
   }
 
-  forceFlush() {
-    // Immediately trigger flush, ignoring timers
-    if (this.#timer) {
-      clearTimeout(this.#timer)
-      this.#timer = null
+  /**
+   * Sleep, but return early if the buffer is stopped. Used for the retry delay
+   * between attempts at a failed batch: a shutdown must not wait out a delay
+   * that only exists to pace a broker that is not answering.
+   */
+  sleepUnlessStopped(millis) {
+    if (this.#stopped || millis <= 0) return Promise.resolve()
+    return new Promise(resolve => {
+      let timer = null
+      const wake = () => {
+        if (timer) clearTimeout(timer)
+        const index = this.#stopWaiters.indexOf(wake)
+        if (index !== -1) this.#stopWaiters.splice(index, 1)
+        resolve()
+      }
+      timer = setTimeout(wake, millis)
+      this.#stopWaiters.push(wake)
+    })
+  }
+
+  /**
+   * Stop accepting messages and wake everything parked, so shutdown cannot
+   * hang. Parked adds REJECT rather than resolve: their message was never
+   * buffered, and reporting success for a message that was dropped on the floor
+   * is the failure mode this whole change exists to remove.
+   */
+  stop() {
+    if (this.#stopped) return
+    this.#stopped = true
+    this.cancelTimer()
+
+    const waiters = this.#waiters.slice()
+    for (const waiter of waiters) {
+      waiter.settle(
+        waiter.reject,
+        new Error(`Queen buffer ${this.#queueAddress} stopped while waiting for capacity: message not buffered`)
+      )
     }
-    this.#triggerFlush()
+
+    const sleepers = this.#stopWaiters.splice(0, this.#stopWaiters.length)
+    for (const wake of sleepers) wake()
   }
 
   cancelTimer() {
@@ -115,18 +298,39 @@ export class MessageBuffer {
     return this.#options
   }
 
+  get isFlushing() {
+    return this.#flushing
+  }
+
+  get isStopped() {
+    return this.#stopped
+  }
+
+  /** True while any add is parked on the bound, or woken but not yet resumed. */
+  get hasParkedAdds() {
+    return this.#waiters.length > 0 || this.#parked > 0
+  }
+
   get firstMessageAge() {
     return this.#firstMessageTime ? Date.now() - this.#firstMessageTime : 0
   }
 
   cleanup() {
-    if (this.#timer) {
-      clearTimeout(this.#timer)
-      this.#timer = null
-    }
+    this.stop()
     this.#messages = []
     this.#firstMessageTime = null
     this.#flushing = false
   }
 }
 
+/**
+ * The reason an AbortSignal carries, or a plain AbortError when the runtime
+ * (or the caller's controller) did not set one.
+ */
+function abortReason(signal) {
+  if (signal.reason instanceof Error) return signal.reason
+  const error = new Error('Queen buffered push aborted while waiting for buffer capacity')
+  error.name = 'AbortError'
+  if (signal.reason !== undefined) error.cause = signal.reason
+  return error
+}

package/client-v2/builders/QueueBuilder.js

@@ -138,6 +138,21 @@ export class QueueBuilder {
     return this
   }
 
+  /**
+   * Batch pushes client-side instead of sending each one.
+   *
+   * @param {object} options
+   * @param {number} [options.messageCount=100] - flush once this many messages are waiting
+   * @param {number} [options.timeMillis=1000] - flush this long after the first message arrives
+   * @param {number} [options.maxSize] - backpressure bound: past this many buffered
+   *   messages `push()` WAITS for the flusher instead of growing the heap.
+   *   Defaults to 4 x messageCount, floored at messageCount. There is no
+   *   unbounded setting: unbounded is what lost 20.9M messages in the
+   *   2026-08-20 measurement.
+   * @param {number} [options.retryDelayMillis=250] - delay before retrying a batch
+   *   whose POST failed. Failed batches are re-queued at the front of the
+   *   buffer and retried, never dropped.
+   */
   buffer(options) {
     this.#bufferOptions = options
     return this
@@ -622,20 +637,42 @@ class PushBuilder {
   async #execute() {
     logger.log('PushBuilder.execute', { queue: this.#queueName, partition: this.#partition, count: this.#formattedItems.length, buffered: !!this.#bufferOptions })
     
-    // Client-side buffering
+    // Client-side buffering. Awaited, one message at a time: addMessage is
+    // where the maxSize backpressure bound is applied, so a buffered push
+    // resolves only once every item is actually IN the buffer. Firing these
+    // off without awaiting would report success for messages the buffer never
+    // accepted -- the exact failure this bound exists to remove.
     if (this.#bufferOptions) {
-      for (const item of this.#formattedItems) {
-        const queueAddress = `${this.#queueName}/${this.#partition}`
-        this.#bufferManager.addMessage(queueAddress, item, this.#bufferOptions)
+      const queueAddress = `${this.#queueName}/${this.#partition}`
+      const accepted = []
+
+      try {
+        for (const item of this.#formattedItems) {
+          await this.#bufferManager.addMessage(queueAddress, item, this.#bufferOptions)
+          accepted.push(item)
+        }
+      } catch (error) {
+        // The buffer refused this message (the client is closing, or the wait
+        // for capacity was aborted). Report the items that did NOT make it, the
+        // same way the immediate push below reports rejected items -- counting
+        // them as buffered would be the false success this bound removes.
+        const unbuffered = this.#formattedItems.slice(accepted.length)
+        logger.error('PushBuilder.execute', { status: 'not-buffered', count: unbuffered.length, error: error.message })
+        if (this.#onErrorCallback) {
+          await this.#onErrorCallback(unbuffered, error)
+          return null
+        }
+        throw error
       }
-      const result = { buffered: true, count: this.#formattedItems.length }
-      
-      logger.log('PushBuilder.execute', { status: 'buffered', count: this.#formattedItems.length })
-      
+
+      const result = { buffered: true, count: accepted.length }
+
+      logger.log('PushBuilder.execute', { status: 'buffered', count: accepted.length })
+
       if (this.#onSuccessCallback) {
-        await this.#onSuccessCallback(this.#formattedItems)
+        await this.#onSuccessCallback(accepted)
       }
-      
+
       return result
     }
 

package/client-v2/utils/defaults.js

@@ -75,6 +75,20 @@ export const POP_DEFAULTS = {
 
 export const BUFFER_DEFAULTS = {
   messageCount: 100,                   // Flush after 100 messages
-  timeMillis: 1000                     // Or flush after 1 second
+  timeMillis: 1000,                    // Or flush after 1 second
+  // Backpressure bound: once this many messages are waiting, a buffered push
+  // WAITS for the flusher to drain below it instead of growing the heap. 0 (or
+  // absent) means 4 x messageCount -- "unbounded" is deliberately not
+  // expressible, because unbounded was the defect. Measured motivation
+  // (2026-08-20): without a bound, a producer filling at 1.46M msg/s against a
+  // 1.0M msg/s flush pipeline accumulated 20.9M messages (11.7 GB) in 45
+  // seconds and lost every one of them at process exit, with zero client-side
+  // errors. The bound is approximate: a batch that fails to send is put back,
+  // so occupancy can briefly overshoot by up to one messageCount.
+  maxSize: 400,
+  // How long the flusher waits before retrying a batch whose POST failed. The
+  // batch is re-queued at the front of the buffer and retried until it lands
+  // (or the buffer is stopped) -- never dropped. 0 means 250.
+  retryDelayMillis: 250
 }
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "queen-mq",
-  "version": "1.0.3",
+  "version": "1.0.6",
   "type": "module",
   "description": "Partitioned message queue on PostgreSQL — broker client + fluent streaming SDK (windows, joins, gates) in one package",
   "main": "client-v2/index.js",
   "scripts": {
-    "test": "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js test-v2/streams-unit/ack.test.js test-v2/http-unit/retry429.test.js test-v2/http-unit/hostHeader.test.js test-v2/kv-unit/kvWire.test.js test-v2/kv-unit/timerWire.test.js test-v2/kv-unit/txnWire.test.js && node test-v2/run.js human",
-    "test:unit": "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js test-v2/streams-unit/ack.test.js test-v2/http-unit/retry429.test.js test-v2/http-unit/hostHeader.test.js test-v2/kv-unit/kvWire.test.js test-v2/kv-unit/timerWire.test.js test-v2/kv-unit/txnWire.test.js",
+    "test": "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js test-v2/streams-unit/ack.test.js test-v2/http-unit/retry429.test.js test-v2/http-unit/hostHeader.test.js test-v2/kv-unit/kvWire.test.js test-v2/kv-unit/timerWire.test.js test-v2/kv-unit/txnWire.test.js test-v2/buffer-unit/buffer.test.js && node test-v2/run.js human",
+    "test:unit": "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js test-v2/streams-unit/ack.test.js test-v2/http-unit/retry429.test.js test-v2/http-unit/hostHeader.test.js test-v2/kv-unit/kvWire.test.js test-v2/kv-unit/timerWire.test.js test-v2/kv-unit/txnWire.test.js test-v2/buffer-unit/buffer.test.js",
     "test:unit:e2e": "node --test test-v2/streams-unit/e2e.test.js",
     "test:integration": "node test-v2/run.js human",
     "test:streams": "node test-v2/run.js stream",