queen-mq 1.2.0 → 2.0.0

package/test-v2/http-unit/pushStatus.test.js

@@ -0,0 +1,142 @@
+/**
+ * Push per-item statuses.
+ *
+ * POST /api/v1/push answers 201 with one result per item, in input order, and
+ * a refused item fails INSIDE a successful request, so the per-item status is
+ * the only signal that a message was not stored. The statuses brokers send:
+ *
+ *   queued     stored                                            (every broker)
+ *   duplicate  its transactionId is already stored               (every broker)
+ *   error      refused, no per-item message                      (2.x)
+ *   failed     refused, with `error`                             (1.x)
+ *   buffered   written to the broker's failover file, replayed   (1.x)
+ *
+ * The client used to look for `failed` only, so a 2.x refusal (`error`) was
+ * neither reported nor thrown: push() resolved as if the message were stored.
+ * Found 2026-10-02 against 2.0.0-beta.6, which answers `error` when a
+ * partition's planned append exceeds QUEEN_RAFT_ENTRY_MAX_BYTES.
+ */
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Queen } from '../../client-v2/index.js'
+import { withPlanServer } from '../kv-unit/_planServer.js'
+
+const QUEUE = 'test-push-status'
+
+const item = (index, status, extra = {}) => ({
+  index,
+  message_id: `0199aaaa-0000-7000-8000-00000000000${index}`,
+  transaction_id: `tx-${index}`,
+  queueName: QUEUE,
+  status,
+  ...extra
+})
+
+// The exact shape 2.0.0-beta.6 answered for an item it refused (no offset,
+// no error text).
+const created = (results) => ({ status: 201, body: results })
+
+async function withQueen(response, run) {
+  await withPlanServer([response], response, async (url, hits) => {
+    const queen = new Queen({ url, handleSignals: false, retryAttempts: 1 })
+    try {
+      await run(queen, hits)
+    } finally {
+      await queen.close()
+    }
+  })
+}
+
+describe('push — a refused item is reported, whatever the broker calls it', () => {
+  it('a 2.x `error` item makes push() reject, carrying the per-item results', async () => {
+    await withQueen(created([item(0, 'error')]), async (queen) => {
+      await assert.rejects(
+        async () => { await queen.queue(QUEUE).push([{ data: { n: 1 } }]) },
+        (err) => {
+          assert.match(err.message, /rejected by the broker/)
+          assert.match(err.message, /"error"/, 'the status the broker answered is named')
+          assert.deepEqual(err.results.map(r => r.status), ['error'])
+          return true
+        }
+      )
+    })
+  })
+
+  it('a 2.x `error` item goes to onError, and the stored ones still go to onSuccess', async () => {
+    await withQueen(created([item(0, 'queued', { offset: 0 }), item(1, 'error')]), async (queen) => {
+      let failedItems = null
+      let failure = null
+      let succeeded = null
+      const res = await queen.queue(QUEUE)
+        .push([{ data: { n: 1 } }, { data: { n: 2 } }])
+        .onError(async (items, err) => { failedItems = items; failure = err })
+        .onSuccess(async (items) => { succeeded = items })
+
+      assert.ok(Array.isArray(res), 'with onError the call resolves with the broker results')
+      assert.equal(failedItems.length, 1)
+      assert.deepEqual(failedItems[0].payload, { n: 2 })
+      assert.equal(failedItems[0].result.status, 'error')
+      assert.match(failure.message, /rejected by the broker/)
+      assert.equal(succeeded.length, 1)
+      assert.deepEqual(succeeded[0].payload, { n: 1 })
+    })
+  })
+
+  it('a 1.x `failed` item is reported with the broker\'s own text', async () => {
+    await withQueen(created([item(0, 'failed', { error: 'File buffer write failed' })]), async (queen) => {
+      await assert.rejects(
+        async () => { await queen.queue(QUEUE).push([{ data: { n: 1 } }]) },
+        (err) => { assert.equal(err.message, 'File buffer write failed'); return true }
+      )
+    })
+  })
+
+  it('a status this client does not know is a failure, not a silent success', async () => {
+    await withQueen(created([item(0, 'refused-by-something-new')]), async (queen) => {
+      await assert.rejects(
+        async () => { await queen.queue(QUEUE).push([{ data: { n: 1 } }]) },
+        (err) => { assert.match(err.message, /refused-by-something-new/); return true }
+      )
+    })
+  })
+
+  it('several refused items: one error for the call, counting them', async () => {
+    await withQueen(created([item(0, 'error'), item(1, 'queued', { offset: 0 }), item(2, 'error')]), async (queen) => {
+      await assert.rejects(
+        async () => { await queen.queue(QUEUE).push([{ data: 1 }, { data: 2 }, { data: 3 }]) },
+        (err) => { assert.match(err.message, /^2 of 3 pushed items rejected/); return true }
+      )
+    })
+  })
+})
+
+describe('push — accepted statuses stay accepted', () => {
+  it('`queued` resolves with the broker results and reaches onSuccess', async () => {
+    await withQueen(created([item(0, 'queued', { offset: 7 })]), async (queen) => {
+      let succeeded = null
+      const res = await queen.queue(QUEUE).push([{ data: { n: 1 } }]).onSuccess(async (items) => { succeeded = items })
+      assert.equal(res[0].status, 'queued')
+      assert.equal(succeeded.length, 1)
+    })
+  })
+
+  it('a 1.x `buffered` item is accepted: the broker owns its delivery', async () => {
+    await withQueen(created([item(0, 'buffered')]), async (queen) => {
+      let succeeded = null
+      const res = await queen.queue(QUEUE).push([{ data: { n: 1 } }]).onSuccess(async (items) => { succeeded = items })
+      assert.equal(res[0].status, 'buffered')
+      assert.equal(succeeded.length, 1)
+    })
+  })
+
+  it('`duplicate` goes to onDuplicate and is not a failure', async () => {
+    await withQueen(created([item(0, 'duplicate', { offset: 3 })]), async (queen) => {
+      let dups = null
+      const res = await queen.queue(QUEUE).push([{ data: { n: 1 } }]).onDuplicate(async (items) => { dups = items })
+      assert.equal(res[0].status, 'duplicate')
+      assert.equal(dups.length, 1)
+    })
+  })
+})

package/test-v2/http-unit/renew.test.js

@@ -0,0 +1,96 @@
+/**
+ * Queen.renew() outcome.
+ *
+ * POST /api/v1/lease/:leaseId/extend answers HTTP 200 whether or not anything
+ * was renewed. `success` in the body is the only signal, and the client used
+ * to ignore it: renewing a lease that had expired, or that an ack had already
+ * released, reported `success: true` with `newExpiresAt: null` (found
+ * 2026-10-02 against 2.0.0-beta.6). The bodies below are what brokers send:
+ *
+ *   1.x and 2.x: {leaseId, success, renewed, newExpiresAt, expiresAt, lease_expires_at}
+ *   C++:         [{index, leaseId, success, error, expiresAt}]
+ */
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Queen } from '../../client-v2/index.js'
+import { withPlanServer } from '../kv-unit/_planServer.js'
+
+const LEASE = '01a0fcf2-1a28-7001-8810-d74deda1fd42'
+const EXPIRES = '2026-10-02T14:09:40.273Z'
+
+// What 2.0.0-beta.6 answered for a live lease covering two partitions, and
+// for a lease that no longer exists.
+const renewed = (leaseId = LEASE) => ({
+  leaseId, success: true, renewed: 2, newExpiresAt: EXPIRES, expiresAt: EXPIRES, lease_expires_at: EXPIRES
+})
+const notRenewed = (leaseId = LEASE) => ({
+  leaseId, success: false, renewed: 0, newExpiresAt: null, expiresAt: null, lease_expires_at: null
+})
+
+async function withQueen(plan, run) {
+  await withPlanServer(plan, { status: 200, body: renewed() }, async (url, hits) => {
+    const queen = new Queen({ url, handleSignals: false, retryAttempts: 1 })
+    try {
+      await run(queen, hits)
+    } finally {
+      await queen.close()
+    }
+  })
+}
+
+describe('Queen.renew — the broker\'s verdict, not the HTTP status', () => {
+  it('a renewed lease reports success, its new expiry, and how many partitions it covers', async () => {
+    await withQueen([{ body: renewed() }], async (queen, hits) => {
+      const res = await queen.renew(LEASE)
+      assert.deepEqual(res, { leaseId: LEASE, success: true, newExpiresAt: EXPIRES, renewed: 2 })
+      assert.equal(hits[0].url, `/api/v1/lease/${LEASE}/extend`)
+    })
+  })
+
+  it('a lease that is gone reports failure, with a reason', async () => {
+    await withQueen([{ body: notRenewed() }], async (queen) => {
+      const res = await queen.renew({ leaseId: LEASE, transactionId: 'tx-1' })
+      assert.equal(res.success, false)
+      assert.equal(res.renewed, 0)
+      assert.equal(res.newExpiresAt, null)
+      assert.match(res.error, /not renewed/)
+    })
+  })
+
+  it('an array of messages answers one outcome per distinct lease', async () => {
+    const other = '01a0fcf2-0000-7000-8000-000000000000'
+    await withQueen([{ body: renewed() }, { body: notRenewed(other) }], async (queen, hits) => {
+      const res = await queen.renew([
+        { leaseId: LEASE, transactionId: 'tx-1' },
+        { leaseId: LEASE, transactionId: 'tx-2' },
+        { leaseId: other, transactionId: 'tx-3' }
+      ])
+      assert.equal(hits.length, 2, 'one call per lease, not per message')
+      assert.deepEqual(res.map(r => [r.leaseId, r.success]), [[LEASE, true], [other, false]])
+    })
+  })
+
+  it('reads the C++ broker\'s array, including its error text', async () => {
+    await withQueen([
+      { body: [{ index: 0, leaseId: LEASE, success: true, error: null, expiresAt: EXPIRES }] },
+      { body: [{ index: 0, leaseId: LEASE, success: false, error: 'Lease already expired', expiresAt: null }] }
+    ], async (queen) => {
+      const ok = await queen.renew(LEASE)
+      assert.equal(ok.success, true)
+      assert.equal(ok.newExpiresAt, EXPIRES)
+      const gone = await queen.renew(LEASE)
+      assert.equal(gone.success, false)
+      assert.equal(gone.error, 'Lease already expired')
+    })
+  })
+
+  it('an HTTP failure is still a failed renewal, not a throw', async () => {
+    await withQueen([{ status: 500, body: { error: 'boom' } }], async (queen) => {
+      const res = await queen.renew(LEASE)
+      assert.equal(res.success, false)
+      assert.ok(res.error)
+    })
+  })
+})

package/test-v2/kv-unit/timerWire.test.js

@@ -10,7 +10,7 @@
  *      a tenant that is over quota -- while the fire never stops by itself, so
  *      that tenant keeps producing messages it cannot stop.
  *   2. delayMs, never delaySeconds and never an absolute instant (§4.2,
- *      §20.6). One clock, Postgres's. `deliverAt` in an op is a 22023.
+ *      §20.6). One clock, the broker's. `deliverAt` in an op is a 22023.
  *   3. The payload is base64 (§6.2), and the SDK encodes it, so a caller never
  *      has to know.
  *   4. `txn` is mandatory on a schedule and is echoed on `absent`, which is

package/test-v2/kv-unit/txnWire.test.js

@@ -181,11 +181,19 @@ describe('Transaction wire — the verdict that must not throw', () => {
   })
 
   it('commit() still THROWS on every other failure', async () => {
-    const rejected = ok({ transactionId: 'txn-1', success: false, reason: 'ack_rejected', error: 'QTXN invalid or expired lease', results: [] })
+    // The body a 2.0 broker answers for an ack whose lease is gone (a 1.x
+    // broker spelled the reason ack_rejected).
+    const rejected = ok({
+      transactionId: 'txn-1',
+      success: false,
+      reason: 'rejected_ack',
+      error: 'QTXN 1 acked message(s) on partition 3 are not leased by this worker or were already acked; the transaction rolled back',
+      results: []
+    })
     await withQueen([rejected], async (queen) => {
       await assert.rejects(() => queen.transaction().ack(MSG).commit(), (e) => {
         assert.match(e.message, /QTXN/)
-        assert.equal(e.reason, 'ack_rejected', 'the closed-taxonomy reason travels on the error, so nobody matches the message')
+        assert.equal(e.reason, 'rejected_ack', 'the broker\'s reason travels on the error, so nobody matches the message')
         return true
       })
     })
@@ -220,3 +228,94 @@ describe('Transaction wire — the verdict that must not throw', () => {
     })
   })
 })
+
+// ---------------------------------------------------------------------------
+// The consumer group of an ack op. The lease an ack has to match belongs to
+// the group the message was popped under, and an op that names no group is
+// judged in queue mode: a message popped by a group and acked without one
+// rolled the whole bundle back with `rejected_ack` (found 2026-10-02 against
+// 2.0.0-beta.6). Every pop answers each message with its `consumerGroup`.
+// ---------------------------------------------------------------------------
+
+describe('Transaction wire — the ack op carries the group the message was popped under', () => {
+  const fromGroup = (group, n = 1) => ({
+    ...MSG,
+    transactionId: `aaaaaaaa-aaaa-7aaa-8aaa-00000000000${n}`,
+    consumerGroup: group
+  })
+
+  it('takes consumerGroup from the message when the caller names none', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      await queen.transaction().ack(fromGroup('workers')).commit()
+      assert.equal(hits[0].body.operations[0].consumerGroup, 'workers')
+    })
+  })
+
+  it('a queue-mode message adds no consumerGroup key, as before', async () => {
+    await withQueen([success(), success()], async (queen, hits) => {
+      await queen.transaction().ack(fromGroup('__QUEUE_MODE__')).commit()
+      await queen.transaction().ack(MSG).commit()   // hand-built, no group at all
+      for (const hit of hits) {
+        assert.deepEqual(Object.keys(hit.body.operations[0]).sort(), ['leaseId', 'partitionId', 'status', 'transactionId', 'type'])
+      }
+    })
+  })
+
+  it('an explicit group wins, as { consumerGroup } or as { group }', async () => {
+    await withQueen([success(), success()], async (queen, hits) => {
+      await queen.transaction().ack(fromGroup('workers'), 'completed', { consumerGroup: 'auditors' }).commit()
+      await queen.transaction().ack(fromGroup('workers'), 'completed', { group: 'auditors' }).commit()
+      assert.equal(hits[0].body.operations[0].consumerGroup, 'auditors')
+      assert.equal(hits[1].body.operations[0].consumerGroup, 'auditors')
+    })
+  })
+
+  it('messages from different groups each keep their own', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      await queen.transaction().ack([fromGroup('a', 1), fromGroup('b', 2)]).commit()
+      assert.deepEqual(hits[0].body.operations.map(op => op.consumerGroup), ['a', 'b'])
+    })
+  })
+})
+
+// The lease of an ack op. A Queen 2 broker fences each ack with the leaseId
+// the operation carries, and lends it one from requiredLeases only when every
+// lease in the bundle is the same lease. An ack whose lease travelled in
+// requiredLeases alone was applied unfenced in a bundle of two leases, even
+// after that lease expired and another consumer took the message (found
+// 2026-10-03 against 2.0.0-beta.6).
+// ---------------------------------------------------------------------------
+
+describe('Transaction wire — each ack op carries its own lease', () => {
+  const leased = (n, leaseId) => ({
+    transactionId: `aaaaaaaa-aaaa-7aaa-8aaa-00000000000${n}`,
+    partitionId: `pppppppp-pppp-7ppp-8ppp-00000000000${n}`,
+    ...(leaseId === undefined ? {} : { leaseId })
+  })
+
+  it('a bundle spanning two leases names each lease on its own ack', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      await queen.transaction()
+        .ack(leased(1, 'lease-1'))
+        .ack(leased(2, 'lease-2'))
+        .ack(leased(3))
+        .commit()
+
+      const [first, second, third] = hits[0].body.operations
+      assert.equal(first.leaseId, 'lease-1')
+      assert.equal(second.leaseId, 'lease-2')
+      assert.ok(!('leaseId' in third), 'a message without a lease adds no leaseId key')
+      assert.deepEqual(hits[0].body.requiredLeases, ['lease-1', 'lease-2'])
+    })
+  })
+
+  it('a null or empty lease adds no leaseId key either', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      await queen.transaction().ack([leased(1, null), leased(2, '')]).commit()
+      for (const op of hits[0].body.operations) {
+        assert.ok(!('leaseId' in op))
+      }
+      assert.deepEqual(hits[0].body.requiredLeases, [])
+    })
+  })
+})

package/test-v2/kv.js

@@ -1,15 +1,16 @@
 /**
  * KV integration suite (PLAN_KV_TIMERS.md §5, §8.3).
  *
- * Every test here is repeatable ONLY because run.js purges `queen.kv` for the
- * `test-%` namespaces before the run (§10.4): without that purge a
+ * Every test here is repeatable ONLY because every run starts on a fresh broker
+ * (test/run.sh creates the lane's data volume empty and destroys it with
+ * `down -v`): against a broker that kept the previous run's keys, a
  * `putIfAbsent` test is green on its first execution and red forever after,
- * and an `incr` test accumulates between runs. If you add a test here, its
- * namespace must start with `test-` or it will be the one that rots.
+ * and an `incr` test accumulates between runs. Keep the namespaces under
+ * `test-`, like every other fixture of the suite.
  *
  * And `forever` is BANNED in this file. A test that goes wrong with a TTL
  * leaves state that expires by itself; a test that goes wrong with `forever`
- * leaves immortal state in a shared database.
+ * leaves immortal state in a shared broker.
  */
 
 import { KV_NS, sleep } from './_kvtimers.js'

package/test-v2/pop.js

@@ -226,11 +226,14 @@ export async function popV4DefaultOne(client) {
 
     await new Promise(r => setTimeout(r, 500))
 
-    // No .partitions() → max_partitions defaults to 1 → single partition.
+    // No .partitions() and autopilot off → the pre-1.2 default of one
+    // partition. (With autopilot on, the SDK default, an unset width is the
+    // broker's to pick: one consumer and four ready partitions take all four.)
     const res = await client
     .queue(queueName)
     .batch(100)
     .wait(false)
+    .autopilot(false)
     .pop()
 
     if (res.length !== 5) {
@@ -334,3 +337,27 @@ export async function popV4SharedLeaseRenew(client) {
     return { success: true, message: 'Shared leaseId renewed once and dedup confirmed' }
 }
 
+
+// renew() reports the broker's verdict (2026-10-02, 2.0.0-beta.6): the extend
+// route answers HTTP 200 whether or not anything was renewed, and a lease an
+// ack had already released came back success:true.
+export async function renewReportsAReleasedLease(client) {
+    const queueName = 'test-queue-v2-renew-released'
+    const queue = await client.queue(queueName).config({ leaseTime: 60 }).create()
+    if (!queue.configured) {
+        return { success: false, message: 'Queue not created' }
+    }
+    await client.queue(queueName).push([{ data: { n: 1 } }])
+
+    const [message] = await client.queue(queueName).batch(1).wait(false).pop()
+    if (!message) {
+        return { success: false, message: 'Nothing popped' }
+    }
+    const live = await client.renew(message)
+    await client.ack(message, true)
+    const released = await client.renew(message)
+
+    const success = live.success === true && typeof live.newExpiresAt === 'string' &&
+                    released.success === false && released.newExpiresAt === null && typeof released.error === 'string'
+    return { success, message: `live lease: ${JSON.stringify(live)}; after the ack: ${JSON.stringify(released)}` }
+}

package/test-v2/retention.js

@@ -1,6 +1,27 @@
 
-// To pass this test the server needs to 
-// be started with RETENTION_INTERVAL=2000
+// The sweep is periodic AND backs off, so the wait below is a bound, not a guess.
+//
+// retention.rs gives a partition a strike for every visit that deletes nothing
+// and skips it for BACKOFF_BASE_CYCLES (8) cycles after the first one. The
+// sweep that runs while these 100 messages are still younger than
+// `retentionSeconds` is exactly such a fruitless visit, so the partition is
+// parked for 8 * RETENTION_INTERVAL before anything can be deleted:
+//
+//     worst case = retentionSeconds + BACKOFF_BASE_CYCLES * RETENTION_INTERVAL
+//                = 10s             + 8                   * 5s (the default)
+//                = 50s
+//
+// The old wait was 15s, taken from a comment that assumed the broker ran with
+// RETENTION_INTERVAL=2000 -- which no stack in test/compose has ever set. It
+// could not pass once the backoff landed (751435f5), and it is why `suites (js)`
+// was 172/173 red on master for weeks. Measured on the single stack: still
+// present at 15s/25s/35s, deleted by 50s.
+//
+// Do NOT turn this into a poll loop: pop() CONSUMES, so a poll that pops early
+// empties the queue itself and the next read returns 0 whether retention ran or
+// not -- a test that passes for the wrong reason.
+const RETENTION_SWEEP_WAIT_MS = 65000
+
 export async function retentionTest(client) {
     const queueName = 'test-queue-retention-01';
     const queue = await client
@@ -20,7 +41,7 @@ export async function retentionTest(client) {
         .push([{ data: { message: i } }])
     }
 
-    await new Promise(resolve => setTimeout(resolve, 15000))
+    await new Promise(resolve => setTimeout(resolve, RETENTION_SWEEP_WAIT_MS))
 
     const messages = await client
     .queue(queueName)
@@ -32,12 +53,12 @@ export async function retentionTest(client) {
         return { success: true, message: 'Messages cleaned up' }
     }
 
-    return { success: false }
+    return { success: false, message: `retention left ${messages.length}/100 messages after ${RETENTION_SWEEP_WAIT_MS / 1000}s` }
 }
 
 
-// To pass this test the server needs to 
-// be started with RETENTION_INTERVAL=2000
+// maxWaitTimeSeconds eviction, which is a different retention phase with its own
+// backoff map -- so it is not subject to the bound above and 15s has held.
 export async function retentionTestMaxTime(client) {
     const queueName = 'test-queue-retention-02';
     const queue = await client
@@ -65,5 +86,5 @@ export async function retentionTestMaxTime(client) {
         return { success: true, message: 'Messages cleaned up' }
     }
 
-    return { success: false }
+    return { success: false, message: `max-wait eviction left ${messages.length}/100 messages` }
 }