queen-mq 2.0.0 → 2.0.3

package/test-v2/consumer-unit/stopOnAbort.test.js

@@ -0,0 +1,537 @@
+/**
+ * consume() — what aborting its signal does.
+ *
+ * The rule: stopping a consumer never strands a message. The long poll in
+ * flight is closed, so the broker stops handing this consumer messages (a
+ * broker hands nothing to a poll whose caller is gone, and releases what a
+ * forwarded pop claimed for one). A message the client already holds but has
+ * not handed to the handler goes back with a `retry` ack: the lease is
+ * released, the message is redelivered first, and no retry is charged.
+ *
+ * Before: the signal was only checked between polls. A poll open at the
+ * abort stayed open for up to its timeout, the broker could still hand it a
+ * message, and each() then dropped that message without settling it. The
+ * partition stayed blocked until the lease expired (measured against 2.0.1:
+ * the full lease, 60-180 s on a rolling restart, every restart).
+ */
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { createServer } from 'node:http'
+import { readFile } from 'node:fs/promises'
+import vm from 'node:vm'
+
+import { Queen } from '../../client-v2/index.js'
+import { HttpClient } from '../../client-v2/http/HttpClient.js'
+import { LoadBalancer } from '../../client-v2/http/LoadBalancer.js'
+
+const GROUP = 'workers'
+
+const message = (n) => ({
+  id: `msg-${n}`,
+  transactionId: `tx-${n}`,
+  partitionId: '7',
+  partition: 'p1',
+  leaseId: 'lease-1',
+  consumerGroup: GROUP,
+  data: { n },
+  createdAt: '2026-10-06T10:00:00.000Z'
+})
+
+/**
+ * A fake broker. A pop answers the next batch of `pops`; once they run out it
+ * is held open, like a long poll on an idle queue, and recorded as `closed`
+ * when the client goes away. `ackStatus` answers acks (default: accepted).
+ */
+async function startBroker(pops = [], { ackStatus = 200 } = {}) {
+  const queue = [...pops]
+  const requests = []
+  const held = []
+  const server = createServer((req, res) => {
+    let raw = ''
+    req.on('data', chunk => { raw += chunk })
+    req.on('end', () => {
+      const body = raw ? JSON.parse(raw) : null
+      const path = req.url.split('?')[0]
+      const record = { method: req.method, path, body, closed: false }
+      requests.push(record)
+      if (req.method === 'GET' && path.startsWith('/api/v1/pop')) {
+        const batch = queue.shift()
+        if (batch) {
+          res.writeHead(200, { 'Content-Type': 'application/json' })
+          res.end(JSON.stringify({ success: true, consumerGroup: GROUP, messages: batch }))
+          return
+        }
+        res.on('close', () => { if (!res.writableEnded) record.closed = true })
+        held.push(res)
+        return
+      }
+      if (req.method === 'POST' && (path === '/api/v1/ack' || path === '/api/v1/ack/batch')) {
+        const acks = body.acknowledgments || [body]
+        res.writeHead(ackStatus, { 'Content-Type': 'application/json' })
+        res.end(ackStatus === 200
+          ? JSON.stringify(acks.map((a, i) => ({ index: i, transactionId: a.transactionId, success: true, error: null, leaseReleased: true })))
+          : '{"error":"unavailable"}')
+        return
+      }
+      res.writeHead(404, { 'Content-Type': 'application/json' })
+      res.end('{"error":"not found"}')
+    })
+  })
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve))
+  return {
+    url: `http://127.0.0.1:${server.address().port}`,
+    requests,
+    pops: () => requests.filter(r => r.method === 'GET' && r.path.startsWith('/api/v1/pop')),
+    acks: () => requests.filter(r => r.method === 'POST' && r.path.startsWith('/api/v1/ack')),
+    async stop() {
+      for (const res of held) if (!res.writableEnded && !res.destroyed) { res.writeHead(204); res.end() }
+      server.closeAllConnections()
+      await new Promise(resolve => server.close(resolve))
+    }
+  }
+}
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+
+/** Resolves with 'resolved' / 'rejected: …', or 'pending' if it took longer than `ms`. */
+const settleWithin = (promise, ms) => Promise.race([
+  Promise.resolve(promise).then(() => 'resolved', e => `rejected: ${e.message}`),
+  sleep(ms).then(() => 'pending')
+])
+
+const settledStatuses = (acks) => acks.flatMap(a => (a.body.acknowledgments || [a.body]).map(x => `${x.transactionId}:${x.status}`))
+
+describe('consume() — aborting the signal never strands a message', () => {
+  it('closes the long poll in flight, and the consumer ends at once', async () => {
+    const broker = await startBroker()
+    const queen = new Queen({ url: broker.url, handleSignals: false })
+    try {
+      const ac = new AbortController()
+      const running = queen.queue('orders').group(GROUP).timeoutMillis(30000)
+        .consume(async () => {}, { signal: ac.signal })
+      const outcome = settleWithin(running, 2000)
+      await sleep(150)
+      assert.equal(broker.pops().length, 1, 'one long poll is open')
+
+      ac.abort()
+
+      assert.equal(await outcome, 'resolved', 'consume() resolves without waiting out the 30 s poll')
+      await sleep(50)
+      assert.equal(broker.pops()[0].closed, true, 'the client closed the poll it had open')
+      assert.equal(broker.pops().length, 1, 'and opened no other')
+    } finally {
+      await queen.close()
+      await broker.stop()
+    }
+  })
+
+  it('is not a backend failure: the poll does not fail over to another node', async () => {
+    const a = await startBroker()
+    const b = await startBroker()
+    const queen = new Queen({ urls: [a.url, b.url], enableFailover: true, loadBalancingStrategy: 'affinity', handleSignals: false })
+    try {
+      const ac = new AbortController()
+      const running = queen.queue('orders').group(GROUP).timeoutMillis(30000)
+        .consume(async () => {}, { signal: ac.signal })
+      const outcome = settleWithin(running, 2000)
+      await sleep(150)
+
+      ac.abort()
+
+      assert.equal(await outcome, 'resolved')
+      await sleep(50)
+      assert.equal(a.pops().length + b.pops().length, 1, 'the abort did not fail over to the other node')
+    } finally {
+      await queen.close()
+      await a.stop()
+      await b.stop()
+    }
+  })
+
+  it('HttpClient: an aborted request rejects as aborted, and leaves every node healthy', async () => {
+    const a = await startBroker()
+    const b = await startBroker()
+    const lb = new LoadBalancer([a.url, b.url], 'affinity')
+    const http = new HttpClient({ loadBalancer: lb, enableFailover: true, retryAttempts: 3 })
+    try {
+      const ac = new AbortController()
+      const request = http.get('/api/v1/pop/queue/orders?wait=true&timeout=30000', 35000, 'orders:*:workers', 'pop', ac.signal)
+      const settled = request.then(() => null, e => e)
+      await sleep(150)
+
+      ac.abort()
+
+      const error = await settled
+      assert.equal(error?.aborted, true, 'the rejection says the caller aborted it')
+      assert.equal(a.pops().length + b.pops().length, 1, 'no other node was tried')
+      for (const [url, status] of lb.getHealthStatus()) {
+        assert.equal(status.healthy, true, `${url} is still healthy`)
+      }
+    } finally {
+      await a.stop()
+      await b.stop()
+    }
+  })
+
+  it('wait(false): an abort while a pop is in flight ends the consumer without an error', async () => {
+    const broker = await startBroker()
+    const queen = new Queen({ url: broker.url, handleSignals: false })
+    try {
+      const ac = new AbortController()
+      const running = queen.queue('orders').group(GROUP).wait(false).timeoutMillis(30000)
+        .consume(async () => {}, { signal: ac.signal })
+      const outcome = settleWithin(running, 2000)
+      await sleep(150)
+
+      ac.abort()
+
+      assert.equal(await outcome, 'resolved', 'consume() resolves, it does not reject')
+    } finally {
+      await queen.close()
+      await broker.stop()
+    }
+  })
+
+  it('each(): the messages not yet handed to the handler go back with a retry ack', async () => {
+    const broker = await startBroker([[message(1), message(2), message(3)]])
+    const queen = new Queen({ url: broker.url, handleSignals: false })
+    try {
+      const ac = new AbortController()
+      const seen = []
+      const running = queen.queue('orders').group(GROUP).batch(3).each()
+        .consume(async (msg) => { seen.push(msg.transactionId); ac.abort() }, { signal: ac.signal })
+
+      assert.equal(await settleWithin(running, 2000), 'resolved')
+      assert.deepEqual(seen, ['tx-1'], 'nothing is handed to the handler after the stop')
+      assert.deepEqual(settledStatuses(broker.acks()), ['tx-1:completed', 'tx-2:retry', 'tx-3:retry'],
+        'the one in the handler finishes; the other two are released, not dropped')
+      const release = broker.acks().at(-1).body
+      for (const a of release.acknowledgments || [release]) {
+        assert.equal(a.leaseId ?? release.leaseId, 'lease-1', 'the release names the lease it gives back')
+      }
+    } finally {
+      await queen.close()
+      await broker.stop()
+    }
+  })
+
+  it('each() with a limit: the messages past the limit go back too, instead of staying leased', async () => {
+    const broker = await startBroker([[message(1), message(2), message(3)]])
+    const queen = new Queen({ url: broker.url, handleSignals: false })
+    try {
+      const seen = []
+      const running = queen.queue('orders').group(GROUP).batch(3).each().limit(1)
+        .consume(async (msg) => { seen.push(msg.transactionId) })
+
+      assert.equal(await settleWithin(running, 2000), 'resolved')
+      assert.deepEqual(seen, ['tx-1'])
+      assert.deepEqual(settledStatuses(broker.acks()), ['tx-1:completed', 'tx-2:retry', 'tx-3:retry'])
+    } finally {
+      await queen.close()
+      await broker.stop()
+    }
+  })
+
+  it('a release that cannot be delivered does not fail the consumer: the lease is the fallback', async () => {
+    const broker = await startBroker([[message(1), message(2)]], { ackStatus: 503 })
+    const queen = new Queen({ url: broker.url, handleSignals: false, retryAttempts: 1 })
+    try {
+      const ac = new AbortController()
+      const running = queen.queue('orders').group(GROUP).batch(2).each().autoAck(false)
+        .consume(async () => { ac.abort() }, { signal: ac.signal })
+
+      assert.equal(await settleWithin(running, 3000), 'resolved', 'consume() still resolves')
+      assert.ok(settledStatuses(broker.acks()).includes('tx-2:retry'), 'the release was attempted')
+    } finally {
+      await queen.close()
+      await broker.stop()
+    }
+  })
+})
+
+/**
+ * A server that sends the headers and half a JSON body, then stalls. Each
+ * request is counted; `closeAll` ends the stalled bodies.
+ */
+async function startStallingServer() {
+  let hits = 0
+  const open = []
+  const server = createServer((req, res) => {
+    hits++
+    res.writeHead(200, { 'Content-Type': 'application/json' })
+    res.write('{"value":')
+    open.push(res)
+  })
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve))
+  return {
+    url: `http://127.0.0.1:${server.address().port}`,
+    hits: () => hits,
+    async stop() {
+      for (const res of open) if (!res.destroyed) res.destroy()
+      server.closeAllConnections()
+      await new Promise(resolve => server.close(resolve))
+    }
+  }
+}
+
+/** Resolves once fetch has handed back the response headers for a URL with `prefix`. */
+function onResponseHeaders(prefix) {
+  const original = globalThis.fetch
+  let ready
+  const promise = new Promise(resolve => { ready = resolve })
+  globalThis.fetch = async (...args) => {
+    const response = await original(...args)
+    if (String(args[0]).startsWith(prefix)) setImmediate(ready)
+    return response
+  }
+  return { ready: promise, restore() { globalThis.fetch = original } }
+}
+
+describe('HttpClient — a response whose body is still being read', () => {
+  it('an abort during the body read is a caller abort: no node is marked unhealthy', async () => {
+    const a = await startStallingServer()
+    const b = await startStallingServer()
+    const lb = new LoadBalancer([a.url, b.url], 'affinity')
+    const http = new HttpClient({ loadBalancer: lb, enableFailover: true, retryAttempts: 1 })
+    const headers = onResponseHeaders('http://127.0.0.1:')
+    try {
+      const ac = new AbortController()
+      const settled = http.get('/status', 10000, 'key', null, ac.signal).then(() => null, e => e)
+      await headers.ready
+
+      ac.abort()
+
+      const error = await settled
+      assert.equal(error?.aborted, true, 'the rejection says the caller aborted it')
+      assert.equal(a.hits() + b.hits(), 1, 'no other node was tried')
+      for (const [url, status] of lb.getHealthStatus()) {
+        assert.equal(status.healthy, true, `${url} is still healthy`)
+      }
+    } finally {
+      headers.restore()
+      await http.destroy()
+      await a.stop()
+      await b.stop()
+    }
+  })
+
+  it('the request timeout also bounds the body read', async () => {
+    const server = await startStallingServer()
+    const http = new HttpClient({ baseUrl: server.url, retryAttempts: 1 })
+    try {
+      const started = Date.now()
+      const outcome = await settleWithin(http.get('/status', 300), 3000)
+      assert.match(outcome, /^rejected: Request timeout/, 'a stalled body ends as a timeout, not a hang')
+      assert.ok(Date.now() - started < 2000)
+    } finally {
+      await http.destroy()
+      await server.stop()
+    }
+  })
+})
+
+describe('consume() — a pop response that has started arriving', () => {
+  it('is read to the end after a stop, and its message goes back with a retry ack', async () => {
+    // The broker granted the lease when it sent the headers: from then on the
+    // message is this consumer's to give back, which needs the body.
+    const message1 = message(1)
+    const body = JSON.stringify({ success: true, consumerGroup: GROUP, messages: [message1] })
+    let finish
+    const finished = new Promise(resolve => { finish = resolve })
+    let pops = 0
+    const acks = []
+    const server = createServer((req, res) => {
+      let raw = ''
+      req.on('data', chunk => { raw += chunk })
+      req.on('end', () => {
+        if (req.method === 'GET') {
+          pops++
+          res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) })
+          res.write(body.slice(0, body.length / 2))
+          finished.then(() => { if (!res.destroyed) res.end(body.slice(body.length / 2)) })
+          return
+        }
+        const parsed = JSON.parse(raw)
+        const items = parsed.acknowledgments || [parsed]
+        acks.push(...items)
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify(items.map((a, i) => ({ index: i, transactionId: a.transactionId, success: true, error: null, leaseReleased: true }))))
+      })
+    })
+    await new Promise(resolve => server.listen(0, '127.0.0.1', resolve))
+    const url = `http://127.0.0.1:${server.address().port}`
+    const queen = new Queen({ url, handleSignals: false, retryAttempts: 1 })
+    const headers = onResponseHeaders(url)
+    try {
+      const stop = new AbortController()
+      const seen = []
+      const running = Promise.resolve(queen.queue('orders').group(GROUP).batch(1).each()
+        .consume(async (m) => { seen.push(m.transactionId) }, { signal: stop.signal }))
+      await headers.ready
+
+      stop.abort()
+      finish()
+
+      assert.equal(await settleWithin(running, 2000), 'resolved')
+      assert.deepEqual(seen, [], 'nothing is handed to the handler after the stop')
+      assert.equal(pops, 1)
+      assert.deepEqual(acks.map(a => `${a.transactionId}:${a.status}`), ['tx-1:retry'],
+        'the message in the half-read response is given back, not left to its lease')
+    } finally {
+      finish()
+      headers.restore()
+      await queen.close()
+      server.closeAllConnections()
+      await new Promise(resolve => server.close(resolve))
+    }
+  })
+})
+
+/** A server that answers every request with `status` (and Retry-After), counting them. */
+async function startRefusingServer(status, retryAfterSeconds = null) {
+  let hits = 0
+  let firstHit
+  const hit = new Promise(resolve => { firstHit = resolve })
+  const server = createServer((req, res) => {
+    hits++
+    const headers = { 'Content-Type': 'application/json' }
+    if (retryAfterSeconds != null) headers['Retry-After'] = String(retryAfterSeconds)
+    res.writeHead(status, headers)
+    res.end('{"error":"refused"}', () => firstHit())
+  })
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve))
+  return {
+    url: `http://127.0.0.1:${server.address().port}`,
+    hits: () => hits,
+    firstHit: hit,
+    async stop() {
+      server.closeAllConnections()
+      await new Promise(resolve => server.close(resolve))
+    }
+  }
+}
+
+/** A server that drops every connection without answering. */
+async function startDroppingServer() {
+  let hits = 0
+  let firstHit
+  const hit = new Promise(resolve => { firstHit = resolve })
+  const server = createServer((req) => { hits++; req.socket.destroy(); firstHit() })
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve))
+  return {
+    url: `http://127.0.0.1:${server.address().port}`,
+    hits: () => hits,
+    firstHit: hit,
+    async stop() {
+      server.closeAllConnections()
+      await new Promise(resolve => server.close(resolve))
+    }
+  }
+}
+
+/** Aborts once the client is inside its wait, and measures how long stopping takes. */
+async function abortDuringWait(server, running, ac) {
+  await server.firstHit
+  await sleep(100) // the client has read the answer and is now waiting
+  const started = performance.now()
+  ac.abort()
+  const outcome = await settleWithin(running, 3000)
+  return { outcome, elapsed: performance.now() - started }
+}
+
+describe('a stop during a wait between attempts', () => {
+  it('HttpClient: a 429 backoff ends at once', async () => {
+    const server = await startRefusingServer(429, 2)
+    const http = new HttpClient({ baseUrl: server.url, retryAttempts: 1 })
+    try {
+      const ac = new AbortController()
+      const running = http.get('/api/v1/pop/queue/orders?wait=true', 10000, null, 'pop', ac.signal).then(() => null, e => { throw e })
+      const errorP = running.catch(e => e)
+      const { elapsed } = await abortDuringWait(server, running, ac)
+      const error = await errorP
+      assert.equal(error?.aborted, true)
+      assert.equal(server.hits(), 1, 'no attempt after the stop')
+      assert.ok(elapsed < 250, `stopping took ${Math.round(elapsed)} ms, not the 2 s Retry-After`)
+    } finally {
+      await http.destroy()
+      await server.stop()
+    }
+  })
+
+  it('HttpClient: the backoff before retrying a 5xx ends at once', async () => {
+    const server = await startRefusingServer(503)
+    const http = new HttpClient({ baseUrl: server.url, retryAttempts: 3, retryDelayMillis: 2000 })
+    try {
+      const ac = new AbortController()
+      const running = http.get('/status', 10000, null, null, ac.signal)
+      const errorP = running.catch(e => e)
+      const { elapsed } = await abortDuringWait(server, running, ac)
+      const error = await errorP
+      assert.equal(error?.aborted, true)
+      assert.equal(server.hits(), 1, 'no attempt after the stop')
+      assert.ok(elapsed < 250, `stopping took ${Math.round(elapsed)} ms, not the 2 s backoff`)
+    } finally {
+      await http.destroy()
+      await server.stop()
+    }
+  })
+
+  it('consume(): the pause after a 429 the client gave up retrying ends at once', async () => {
+    const server = await startRefusingServer(429, 2)
+    const queen = new Queen({ url: server.url, handleSignals: false, retryAttempts: 1, retry429: { maxAttempts: 1 } })
+    try {
+      const ac = new AbortController()
+      const running = Promise.resolve(queen.queue('orders').group(GROUP).consume(async () => {}, { signal: ac.signal }))
+      const { outcome, elapsed } = await abortDuringWait(server, running, ac)
+      assert.equal(outcome, 'resolved')
+      assert.ok(elapsed < 250, `stopping took ${Math.round(elapsed)} ms, not the 2 s Retry-After`)
+    } finally {
+      await queen.close()
+      await server.stop()
+    }
+  })
+
+  it('consume(): the pause after a network error ends at once', async () => {
+    const server = await startDroppingServer()
+    const queen = new Queen({ url: server.url, handleSignals: false, retryAttempts: 1 })
+    try {
+      const ac = new AbortController()
+      const running = Promise.resolve(queen.queue('orders').group(GROUP).consume(async () => {}, { signal: ac.signal }))
+      const { outcome, elapsed } = await abortDuringWait(server, running, ac)
+      assert.equal(outcome, 'resolved')
+      assert.ok(elapsed < 250, `stopping took ${Math.round(elapsed)} ms, not the 1 s pause`)
+    } finally {
+      await queen.close()
+      await server.stop()
+    }
+  })
+})
+
+describe('README — the "Stopping a consumer" example', () => {
+  it('starts consuming before the stop, not after it', async () => {
+    const broker = await startBroker()
+    const queen = new Queen({ url: broker.url, handleSignals: false })
+    const readme = await readFile(new URL('../../README.md', import.meta.url), 'utf8')
+    const section = readme.slice(readme.indexOf('**Stopping a consumer**'))
+    const snippet = section.match(/```javascript\n([\s\S]*?)```/)[1]
+    let shutdown
+    const context = vm.createContext({
+      queen, AbortController, Promise,
+      processTask: async () => {},
+      process: { once(event, fn) { assert.equal(event, 'SIGTERM'); shutdown = fn } }
+    })
+    try {
+      vm.runInContext(snippet, context)
+      await sleep(150)
+      const popsBeforeStop = broker.pops().length
+
+      await shutdown()
+
+      assert.equal(popsBeforeStop, 1, 'the example is consuming before SIGTERM')
+    } finally {
+      await queen.close().catch(() => {})
+      await broker.stop()
+    }
+  })
+})

package/test-v2/ephemeral-unit/ephemeralWire.test.js

@@ -201,7 +201,7 @@ describe('ephemeral wire — pop', () => {
 
   it('pop puts every declared parameter on the query string, in order', async () => {
     await withEphemeral([popped(QUEUE, [])], async (eph, hits) => {
-      await eph.pop(QUEUE, { partition: 'room-7', batch: 10, wait: true, timeout: 2000, group: 'workers', autoAck: true })
+      await eph.pop(QUEUE, { partition: 'room-7', batch: 10, wait: true, timeout: 2000, group: 'workers', commitOnDelivery: true })
       assert.equal(
         hits[0].url,
         `/api/v1/ephemeral/pop?queue=${QUEUE}&partition=room-7&batch=10&wait=true&timeout=2000&group=workers&autoAck=true`
@@ -209,6 +209,29 @@ describe('ephemeral wire — pop', () => {
     })
   })
 
+  it('pop sends `commitOnDelivery` as autoAck=true, and nothing for false', async () => {
+    await withEphemeral([popped(QUEUE, []), popped(QUEUE, [])], async (eph, hits) => {
+      await eph.pop(QUEUE, { commitOnDelivery: true })
+      assert.equal(hits[0].url, `/api/v1/ephemeral/pop?queue=${QUEUE}&autoAck=true`)
+
+      await eph.pop(QUEUE, { commitOnDelivery: false })
+      assert.equal(hits[1].url, `/api/v1/ephemeral/pop?queue=${QUEUE}`)
+    })
+  })
+
+  it('pop still reads the deprecated `autoAck` as `commitOnDelivery`, and refuses both spellings', async () => {
+    await withEphemeral([popped(QUEUE, [])], async (eph, hits) => {
+      await eph.pop(QUEUE, { group: 'workers', autoAck: true })
+      assert.equal(hits[0].url, `/api/v1/ephemeral/pop?queue=${QUEUE}&group=workers&autoAck=true`)
+
+      await assert.rejects(
+        () => eph.pop(QUEUE, { commitOnDelivery: true, autoAck: true }),
+        /pass either `commitOnDelivery` or its deprecated alias `autoAck`, not both/
+      )
+      assert.equal(hits.length, 1)
+    })
+  })
+
   it('pop sends an explicit timeout whenever it waits, and none when it does not', async () => {
     // The HTTP deadline is set PAST the server's, so the broker's long poll
     // always ends the request first. Letting the two defaults drift apart is