queen-mq 0.16.0 → 1.0.0

package/client-v2/Queen.js

@@ -15,6 +15,42 @@ import { CLIENT_DEFAULTS } from './utils/defaults.js'
 import { validateUrl, validateUrls } from './utils/validation.js'
 import * as logger from './utils/logger.js'
 
+// Both /api/v1/ack and /api/v1/ack/batch respond with a top-level JSON array,
+// one item per acknowledgment in request order:
+//   [{index, transactionId, success, error, queueName, partitionName, leaseReleased, dlq}]
+// (see queen.ack_messages_v2 / routes/ack.cpp). A rejected ack/nack (e.g.
+// "Invalid or expired lease") still arrives as HTTP 200 with success=false on
+// the item, so the per-item flag is the only signal that the broker accepted it.
+
+function normalizeAckItem(item, index) {
+  if (item === null || typeof item !== 'object') {
+    throw new Error(`Unexpected ack result item at index ${index}`)
+  }
+  let success = typeof item.success === 'boolean' ? item.success : true
+  let error = typeof item.error === 'string' && item.error.length > 0 ? item.error : null
+  if (error) success = false
+  if (!success && !error) error = 'Acknowledgment rejected by server'
+  return { ...item, success, error }
+}
+
+// expected is the number of acknowledgments sent, so a truncated or misaligned
+// response fails loudly instead of being misattributed to the wrong message.
+function parseAckResults(result, expected) {
+  if (Array.isArray(result)) {
+    if (result.length !== expected) {
+      throw new Error(`Ack response has ${result.length} results, expected ${expected}`)
+    }
+    return result.map(normalizeAckItem)
+  }
+
+  // Top-level error envelope: the whole request was rejected.
+  if (result && typeof result === 'object' && typeof result.error === 'string' && result.error.length > 0) {
+    return Array.from({ length: expected }, () => ({ success: false, error: result.error }))
+  }
+
+  throw new Error('Unexpected ack response format: missing per-item result array')
+}
+
 export class Queen {
   #httpClient
   #bufferManager
@@ -87,7 +123,7 @@ export class Queen {
   }
 
   #createHttpClient() {
-    const { urls, timeoutMillis, retryAttempts, retryDelayMillis, loadBalancingStrategy, affinityHashRing, healthRetryAfterMillis, enableFailover, bearerToken, headers } = this.#config
+    const { urls, timeoutMillis, retryAttempts, retryDelayMillis, loadBalancingStrategy, affinityHashRing, healthRetryAfterMillis, enableFailover, bearerToken, headers, hostHeader, retry429 } = this.#config
 
     if (urls.length === 1) {
       // Single server
@@ -97,7 +133,9 @@ export class Queen {
         retryAttempts,
         retryDelayMillis,
         bearerToken,
-        headers
+        headers,
+        hostHeader,
+        retry429
       })
     }
 
@@ -113,7 +151,9 @@ export class Queen {
       retryDelayMillis,
       enableFailover,
       bearerToken,
-      headers
+      headers,
+      hostHeader,
+      retry429
     })
   }
 
@@ -195,7 +235,7 @@ export class Queen {
     // Handle batch acknowledgment
     if (Array.isArray(message)) {
       if (message.length === 0) {
-        return { processed: 0, results: [] }
+        return { success: true, processed: 0, results: [] }
       }
 
       // Check if messages have individual status
@@ -277,13 +317,19 @@ export class Queen {
           consumerGroup: context.group || null
         })
 
-        if (result && result.error) {
-          logger.error('Queen.ack', { type: 'batch', error: result.error })
-          return { success: false, error: result.error }
+        const results = parseAckResults(result, acknowledgments.length)
+        const failed = results.filter(r => !r.success)
+
+        if (failed.length > 0) {
+          const error = failed.length === 1
+            ? failed[0].error
+            : `${failed.length} of ${results.length} acknowledgments rejected: ${failed[0].error}`
+          logger.error('Queen.ack', { type: 'batch', error, failed: failed.length, count: results.length })
+          return { success: false, error, results }
         }
 
-        logger.log('Queen.ack', { type: 'batch', success: true, count: acknowledgments.length })
-        return { success: true, ...result }
+        logger.log('Queen.ack', { type: 'batch', success: true, count: results.length })
+        return { success: true, processed: results.length, results }
       } catch (error) {
         logger.error('Queen.ack', { type: 'batch', error: error.message })
         return { success: false, error: error.message }
@@ -321,13 +367,14 @@ export class Queen {
     try {
       const result = await this.#httpClient.post('/api/v1/ack', body)
 
-      if (result && result.error) {
-        logger.error('Queen.ack', { type: 'single', transactionId, error: result.error })
-        return { success: false, error: result.error }
-      }
+      const [ackResult] = parseAckResults(result, 1)
 
-      logger.log('Queen.ack', { type: 'single', transactionId, success: true })
-      return { success: true, ...result }
+      if (!ackResult.success) {
+        logger.error('Queen.ack', { type: 'single', transactionId, error: ackResult.error })
+      } else {
+        logger.log('Queen.ack', { type: 'single', transactionId, success: true })
+      }
+      return ackResult
     } catch (error) {
       logger.error('Queen.ack', { type: 'single', transactionId, error: error.message })
       return { success: false, error: error.message }
@@ -512,6 +559,15 @@ export class Queen {
     }
     this.#shutdownHandlers = []
 
+    // Release the HTTP agent's keep-alive sockets — without this the Node
+    // event loop stays pinned by open sockets and the process never exits
+    // naturally after close().
+    try {
+      await this.#httpClient.destroy()
+    } catch (error) {
+      logger.warn('Queen.close', { error: error.message, phase: 'http-destroy' })
+    }
+
     logger.log('Queen.close', 'Client closed successfully')
   }
 }

package/client-v2/README.md

@@ -104,6 +104,43 @@ const queen = new Queen({
 })
 ```
 
+### Connecting Through a Hosted Proxy (Cluster Selection)
+
+A Queen proxy deployment routes each request to a tenant cluster using the
+**Host header** (its first DNS label is the cluster slug). Normally you don't
+have to think about it — every cluster has its own hostname, so pointing the
+client at that hostname is all it takes:
+
+```javascript
+const queen = new Queen({
+  url: 'https://acme.eu1.queenmq.cloud',   // Host follows from the URL
+  bearerToken: process.env.QUEEN_API_KEY
+})
+```
+
+When the base URL can't be the cluster's hostname — an IP or a shared cell
+endpoint, a local rig, a staging box, split-horizon DNS — use `hostHeader` to
+advertise the cluster host while the connection still goes to the configured
+address (the same thing `curl --resolve` does; TLS SNI and certificate
+validation follow `hostHeader`, not the address):
+
+```javascript
+const queen = new Queen({
+  url: 'https://10.0.0.7:6711',            // where we connect
+  hostHeader: 'acme.eu1.queenmq.cloud',    // which cluster we ask for
+  bearerToken: process.env.QUEEN_API_KEY
+})
+```
+
+`hostHeader` takes a bare authority (`'acme'`, `'acme.eu1.queenmq.cloud'`,
+`'acme.local:6711'`) — not a URL. It works with `urls: [...]` too: every
+backend is dialed as usual, and all of them get the same Host.
+
+> ⚠️ `headers: { Host: '...' }` **cannot** work in JavaScript: `Host` is a
+> WHATWG forbidden header name and `fetch()` drops it. Rather than let that
+> silently route you to the wrong cluster, the client maps it onto
+> `hostHeader` and warns once. Set `hostHeader` directly.
+
 ---
 
 ## Part 1: Hello Queue!

package/client-v2/builders/QueueBuilder.js

@@ -335,8 +335,10 @@ export class QueueBuilder {
 
       // Generate affinity key for consistent routing to same backend
       const affinityKey = this.#getAffinityKey()
-      
-      const result = await this.#httpClient.get(`${path}?${params}`, this.#timeoutMillis + 5000, affinityKey)
+
+      // 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)
 
       if (!result || !result.messages) {
         logger.log('QueueBuilder.pop', { status: 'no-messages' })
@@ -347,8 +349,12 @@ export class QueueBuilder {
       logger.log('QueueBuilder.pop', { status: 'success', count: messages.length })
       return messages
     } catch (error) {
-      // Return empty array on error instead of throwing
-      logger.error('QueueBuilder.pop', { error: error.message })
+      // Return empty array on error instead of throwing. This also covers a
+      // 429 whose retry429 policy was exhausted (bounded pop, or an explicit
+      // maxAttempts override) and a terminal 403 (e.g. cluster_suspended) --
+      // both are logged with their `.code` rather than raising, matching this
+      // method's existing swallow-to-[] contract.
+      logger.error('QueueBuilder.pop', { error: error.message, status: error.status, code: error.code })
       return []
     }
   }

package/client-v2/builders/TransactionBuilder.js

@@ -3,6 +3,8 @@
  */
 
 import * as logger from '../utils/logger.js'
+import { generateUUID } from './QueueBuilder.js'
+import { isValidUUID } from '../utils/validation.js'
 
 export class TransactionBuilder {
   #httpClient
@@ -82,16 +84,26 @@ export class TransactionBuilder {
               payloadValue = item
             }
 
+            // Same contract as QueueBuilder.push: the caller's transactionId is
+            // what makes a retried transaction idempotent inside the dedup
+            // window, so it has to reach the wire. Absent, mint one here rather
+            // than leaving the broker to do it, so the id is knowable client
+            // side either way.
             const result = {
               queue: queueName,
-              payload: payloadValue
+              payload: payloadValue,
+              transactionId: item.transactionId || generateUUID()
             }
-            
+
             // Add partition if set
             if (partition !== null) {
               result.partition = partition
             }
 
+            if (item.traceId && isValidUUID(item.traceId)) {
+              result.traceId = item.traceId
+            }
+
             return result
           })
         })

package/client-v2/consumer/ConsumerManager.js

@@ -144,9 +144,11 @@ export class ConsumerManager {
       }
 
       try {
-        // Pop messages with affinity key for consistent routing
+        // Pop messages with affinity key for consistent routing. wait=true is
+        // 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)
+        const result = await this.#httpClient.get(`${path}?${baseParams}`, clientTimeout, affinityKey, wait ? 'pop' : null)
 
         // Handle empty response
         if (!result || !result.messages || result.messages.length === 0) {
@@ -188,9 +190,18 @@ export class ConsumerManager {
             for (const message of messages) {
               if (signal && signal.aborted) break
 
-              await this.#processMessage(message, handler, autoAck, group)
+              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 (limit && processedCount >= limit) break
             }
           } else {
@@ -216,6 +227,20 @@ export class ConsumerManager {
           continue // Retry on timeout
         }
 
+        // 429 (rate limited): HttpClient already retries this internally
+        // with backoff (unbounded for wait=true pop, per retry429 policy) --
+        // this branch is a defensive fallback for the case where an explicit
+        // retry429.maxAttempts override got exhausted. Back off and keep
+        // polling instead of hot-looping or rethrowing/dying.
+        if (error.status === 429) {
+          const retryAfterMs = typeof error.retryAfterSeconds === 'number' && error.retryAfterSeconds >= 0
+            ? error.retryAfterSeconds * 1000
+            : 1000
+          logger.warn('ConsumerManager.worker', { workerId, status: 'rate-limited', code: error.code, retryAfterMs })
+          await new Promise(resolve => setTimeout(resolve, retryAfterMs))
+          continue
+        }
+
         // Check if network error
         const isNetworkError = error.message?.includes('fetch failed') ||
                               error.message?.includes('ECONNREFUSED') ||
@@ -228,8 +253,18 @@ export class ConsumerManager {
           continue
         }
 
+        // 403 (forbidden): terminal. cluster_suspended in particular can
+        // never resolve itself, and none of the other proxy codes
+        // (storage_quota_exceeded / feature_gated / forbidden) are worth
+        // hot-looping either -- stop this worker and surface the error
+        // (with .code) to the caller instead of retrying.
+        if (error.status === 403) {
+          logger.error('ConsumerManager.worker', { workerId, status: 'forbidden', code: error.code, error: error.message })
+          throw error
+        }
+
         // Other errors - rethrow
-        logger.error('ConsumerManager.worker', { workerId, error: error.message })
+        logger.error('ConsumerManager.worker', { workerId, error: error.message, code: error.code })
         throw error
       }
     }
@@ -237,6 +272,11 @@ export class ConsumerManager {
     logger.log('ConsumerManager.worker', { workerId, status: 'stopped', processedCount })
   }
 
+  /**
+   * Returns true when the message was handled (and acked) successfully,
+   * false when it was nacked — the caller must abandon the rest of the
+   * popped batch (the nack released the lease server-side).
+   */
   async #processMessage(message, handler, autoAck, group) {
     try {
       await handler(message)
@@ -244,18 +284,26 @@ export class ConsumerManager {
       // Auto-ack on success if enabled
       if (autoAck) {
         const context = group ? { group } : {}
-        await this.#queen.ack(message, true, context)
-        logger.log('ConsumerManager.processMessage', { transactionId: message.transactionId, status: 'acked' })
+        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 } : {}
-        await this.#queen.ack(message, false, context)
+        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
+        return false
       }
       logger.error('ConsumerManager.processMessage', { transactionId: message.transactionId, error: error.message })
       throw error
@@ -269,13 +317,17 @@ export class ConsumerManager {
       // Auto-ack on success if enabled
       if (autoAck) {
         const context = group ? { group } : {}
-        await this.#queen.ack(messages, true, context)
-        logger.log('ConsumerManager.processBatch', { count: messages.length, status: 'acked' })
+        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 } : {}
+        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