queen-mq 2.0.4 → 2.3.0

package/test-v2/locks.js

@@ -0,0 +1,277 @@
+/**
+ * Locks integration suite: `queen.lock`, `queen.semaphore`, `queen.locks`,
+ * `kv.check` and `transaction().guard(lock)` against a real broker.
+ *
+ * Repeatable for the reason kv.js gives: every run starts on a fresh broker.
+ * Every lock here is named under `test-` and carries a lifetime, so a run that
+ * goes wrong leaves nothing that does not expire by itself.
+ *
+ * What only a real broker can show, and what these are for:
+ *   * one holder: two handles, one permit;
+ *   * the retry of a call whose answer was lost comes back with the SAME
+ *     permit (the owner);
+ *   * an expired lock goes to the next handle with a HIGHER token, and the
+ *     old handle's guarded step commits nothing — the message is not pushed;
+ *   * a guarded step survives the lock's own renewal;
+ *   * a semaphore never grants more than its limit to a crowd.
+ */
+
+import { sleep } from './_kvtimers.js'
+
+const fail = (message) => ({ success: false, message })
+
+/** A broker alone raises its cluster version to 5 on its first tick; `check` needs it. */
+async function checksAreServed(client) {
+  for (let i = 0; i < 100; i++) {
+    try {
+      await client.kv.check('test-locks-probe', 'k', { expect: 0 })
+      return
+    } catch (error) {
+      if (error.status !== 503) throw error
+      await sleep(100)
+    }
+  }
+  throw new Error('the broker never served a check (cluster version below 5?)')
+}
+
+async function drain(client, queue) {
+  const seen = []
+  for (;;) {
+    const msgs = await client.queue(queue).batch(50).wait(false).pop()
+    if (!msgs || msgs.length === 0) return seen
+    seen.push(...msgs.map(m => m.data))
+    await client.ack(msgs, true)
+  }
+}
+
+export async function lockHasOneHolderAndAGuardedStepCommits(client) {
+  await checksAreServed(client)
+  const name = 'test-lock/one-holder'
+  const a = client.lock(name, { ttl: '30s' })
+  const b = client.lock(name, { ttl: '30s' })
+  try {
+    if ((await a.acquire()) !== true) return fail('the first handle did not acquire')
+    if ((await b.acquire()) !== false) return fail('a second handle acquired a held lock')
+    if (a.token === null || a.slot !== 0) return fail(`the holder has no token or slot: ${a.token} ${a.slot}`)
+
+    const who = await client.locks.get(name)
+    if (who.held !== true || who.holders.length !== 1 || who.holders[0].owner !== a.owner ||
+        who.holders[0].token !== a.token || !who.holders[0].expiresAt) {
+      return fail(`get does not show the holder: ${JSON.stringify(who)}`)
+    }
+
+    // The permit is a KV row and nothing else.
+    const row = await client.kv.get('queen-locks', `${name}#0`)
+    if (row.found !== true || row.version !== a.token || row.value.owner !== a.owner) {
+      return fail(`the permit's row is not what the lock says: ${JSON.stringify(row)}`)
+    }
+
+    const queue = 'test-lock-one-holder'
+    const res = await client.transaction()
+      .guard(a)
+      .queue(queue).push([{ data: { step: 1 } }])
+      .commit()
+    if (res.success !== true) return fail(`the holder's guarded step did not commit: ${JSON.stringify(res)}`)
+    const got = await drain(client, queue)
+    if (got.length !== 1 || got[0].step !== 1) return fail(`expected the one guarded message, got ${JSON.stringify(got)}`)
+
+    if ((await a.release()) !== true) return fail('release did not remove the permit')
+    if ((await b.acquire()) !== true) return fail('the lock was not free after its release')
+    return { success: true, message: 'one holder, get and the KV row agree, a guarded step commits, release frees it' }
+  } finally {
+    await a.release().catch(() => {})
+    await b.release().catch(() => {})
+  }
+}
+
+export async function lockRetryWithTheSameOwnerIsTheSamePermit(client) {
+  const name = 'test-lock/retry-owner'
+  const owner = `test-owner-${Date.now()}`
+  // What a client does when the answer to its acquire never arrived: the same
+  // call again.
+  const first = await client.locks.acquire(name, { ttl: '30s', owner })
+  const again = await client.locks.acquire(name, { ttl: '30s', owner })
+  if (first.acquired !== true || again.acquired !== true) {
+    return fail(`both attempts must answer the permit: ${JSON.stringify([first, again])}`)
+  }
+  if (again.already !== true || again.token !== first.token) {
+    return fail(`the retry must answer the SAME permit, marked already: ${JSON.stringify(again)}`)
+  }
+  // The same for a renew: its answer is lost, the old token is sent again.
+  const renewed = await client.locks.renew(name, { token: first.token, ttl: '30s', owner })
+  const resent = await client.locks.renew(name, { token: first.token, ttl: '30s', owner })
+  if (renewed.renewed !== true || resent.renewed !== true || !(resent.token > renewed.token)) {
+    return fail(`a renew sent again by its owner must be carried through: ${JSON.stringify([renewed, resent])}`)
+  }
+  // Somebody else's stale token is not.
+  const stranger = await client.locks.renew(name, { token: first.token, ttl: '30s', owner: 'somebody-else' })
+  if (stranger.renewed !== false || stranger.reason !== 'lost' || stranger.holders[0].owner !== owner) {
+    return fail(`a stranger's stale token must be lost: ${JSON.stringify(stranger)}`)
+  }
+  const done = await client.locks.release(name, { token: resent.token })
+  return {
+    success: done.released === true,
+    message: 'acquire and renew sent again by their owner answer the permit; a stranger\'s stale token is lost'
+  }
+}
+
+export async function lockExpiredIsTakenOverAndTheOldHolderCommitsNothing(client) {
+  await checksAreServed(client)
+  const name = 'test-lock/expiry'
+  const queue = 'test-lock-expiry'
+  // The old holder does not renew: it is "paused" for longer than its lease.
+  const old = client.lock(name, { ttl: '1s', autoRenew: false })
+  const next = client.lock(name, { ttl: '30s' })
+  try {
+    if (!(await old.acquire())) return fail('the first holder did not acquire')
+    const oldToken = old.token
+    const staleGuard = old.guard()
+    await sleep(1300)
+
+    if (!(await next.acquire())) return fail('an expired lock was not free for the next holder')
+    if (!(next.token > oldToken)) return fail(`the next holder's token ${next.token} is not above ${oldToken}`)
+
+    // The old holder wakes up and sends the step it was about to send.
+    const stale = await client.transaction()
+      .kv.check(staleGuard.ns, staleGuard.key, { expect: staleGuard.expect, required: true })
+      .queue(queue).push([{ data: { from: 'old' } }])
+      .commit()
+    if (stale.success !== false || stale.reason !== 'kv_precondition') {
+      return fail(`the old holder's step must roll back: ${JSON.stringify(stale)}`)
+    }
+    if (old.held !== false) return fail('a handle past its lifetime must not claim to hold')
+
+    const ok = await client.transaction().guard(next).queue(queue).push([{ data: { from: 'next' } }]).commit()
+    if (ok.success !== true) return fail(`the new holder's step did not commit: ${JSON.stringify(ok)}`)
+
+    const got = await drain(client, queue)
+    if (got.length !== 1 || got[0].from !== 'next') {
+      return fail(`only the new holder's message may exist, got ${JSON.stringify(got)}`)
+    }
+    return { success: true, message: 'takeover with a higher token; the old holder\'s guarded step pushed nothing' }
+  } finally {
+    await next.release().catch(() => {})
+  }
+}
+
+export async function lockGuardedStepSurvivesItsOwnRenewal(client) {
+  await checksAreServed(client)
+  const name = 'test-lock/renew-under-load'
+  const queue = 'test-lock-renew'
+  // A short lease renewed every 100 ms, and steps committed as fast as they
+  // go: some of them are judged after a renew moved the token.
+  const lock = client.lock(name, { ttl: '2s', renewEvery: '100ms' })
+  try {
+    if (!(await lock.acquire())) return fail('did not acquire')
+    const first = lock.token
+    let committed = 0
+    const end = Date.now() + 1500
+    while (Date.now() < end) {
+      const res = await client.transaction()
+        .guard(lock)
+        .queue(queue).push([{ data: { n: committed } }])
+        .commit()
+      if (res.success !== true) return fail(`step ${committed} did not commit while the lock was held: ${JSON.stringify(res)}`)
+      committed++
+    }
+    if (!(lock.token > first)) return fail('the lock never renewed during the run; the test proved nothing')
+    if (lock.held !== true) return fail('the lock was lost under its own renewal')
+    const got = await drain(client, queue)
+    if (got.length !== committed) return fail(`${committed} steps committed, ${got.length} messages exist`)
+    return { success: true, message: `${committed} guarded steps across ${lock.token - first > 0 ? 'several' : 'no'} renewals, each committed once` }
+  } finally {
+    await lock.release().catch(() => {})
+  }
+}
+
+export async function lockRunHoldsForTheWorkAndWaitsItsTurn(client) {
+  const name = 'test-lock/run'
+  const order = []
+  const work = (id, ms) => async () => {
+    order.push(`${id}:in`)
+    await sleep(ms)
+    order.push(`${id}:out`)
+    return id
+  }
+  const a = client.lock(name, { ttl: '10s' })
+  const b = client.lock(name, { ttl: '10s' })
+  const [ra, rb] = await Promise.all([
+    a.run(work('a', 300), { wait: '10s' }),
+    b.run(work('b', 50), { wait: '10s' })
+  ])
+  if (!ra.acquired || !rb.acquired) return fail(`both must get their turn: ${JSON.stringify([ra, rb])}`)
+  // Never interleaved: in, out, in, out.
+  const interleaved = order[0].split(':')[0] !== order[1].split(':')[0]
+  if (interleaved || order.length !== 4) return fail(`the two runs overlapped: ${order.join(' ')}`)
+  const none = await client.lock(name, { ttl: '10s' }).run(async () => {
+    return client.lock(name, { ttl: '10s' }).run(async () => 'inner')
+  })
+  if (none.value.acquired !== false) return fail('a second handle ran inside the first one\'s hold')
+  const free = await client.locks.get(name)
+  return {
+    success: free.held === false,
+    message: `two runs took turns (${order.join(' ')}), and the lock is free afterwards`
+  }
+}
+
+export async function semaphoreNeverGrantsMoreThanItsLimit(client) {
+  const name = 'test-sem/crowd'
+  const LIMIT = 3
+  const permits = Array.from({ length: 12 }, () => client.semaphore(name, LIMIT, { ttl: '30s' }))
+  try {
+    const got = await Promise.all(permits.map(p => p.acquire()))
+    let holders = permits.filter((_, i) => got[i])
+    if (holders.length < 1 || holders.length > LIMIT) return fail(`${holders.length} permits granted of ${LIMIT}`)
+    // A crowd can leave a permit free (each gives up after a few lost races):
+    // one at a time, it fills.
+    for (const p of permits) {
+      if (holders.length === LIMIT) break
+      if (!p.held && await p.acquire()) holders.push(p)
+    }
+    if (holders.length !== LIMIT) return fail(`the semaphore did not fill: ${holders.length} of ${LIMIT}`)
+    const slots = new Set(holders.map(p => p.slot))
+    if (slots.size !== LIMIT) return fail(`two holders share a slot: ${[...slots]}`)
+
+    const extra = client.semaphore(name, LIMIT, { ttl: '30s' })
+    if (await extra.acquire()) return fail('a permit past the limit was granted')
+    const who = await client.locks.get(name)
+    if (who.holders.length !== LIMIT) return fail(`get shows ${who.holders.length} holders of ${LIMIT}`)
+
+    // One leaves, the waiter gets exactly that slot.
+    const freed = holders[0].slot
+    const waiting = extra.acquire({ wait: '5s' })
+    await sleep(200)
+    await holders[0].release()
+    if (!(await waiting)) return fail('a waiter did not get the freed permit')
+    if (extra.slot !== freed) return fail(`the waiter got slot ${extra.slot}, not the freed ${freed}`)
+    await extra.release()
+    return { success: true, message: `a crowd of 12 on ${LIMIT} permits: never more than ${LIMIT}, a freed slot goes to the waiter` }
+  } finally {
+    await Promise.all(permits.map(p => p.release().catch(() => {})))
+  }
+}
+
+export async function kvCheckLooksAndGatesWithoutWriting(client) {
+  await checksAreServed(client)
+  const ns = 'test-kv-check'
+  const put = await client.kv.put(ns, 'state', { n: 1 }, { ttl: '10m' })
+  const held = await client.kv.check(ns, 'state', { expect: put.version })
+  if (held.applied !== true || held.version !== put.version || 'value' in held) {
+    return fail(`a held check answers its version and no value: ${JSON.stringify(held)}`)
+  }
+  const stale = await client.kv.check(ns, 'state', { expect: put.version + 1000 })
+  if (stale.applied !== false || stale.reason !== 'version' || stale.value.n !== 1) {
+    return fail(`a lost check answers what a reader sees: ${JSON.stringify(stale)}`)
+  }
+  const absent = await client.kv.check(ns, 'nobody', { expect: 0 })
+  if (absent.applied !== true) return fail(`expect: 0 on an absent key must hold: ${JSON.stringify(absent)}`)
+  const row = await client.kv.get(ns, 'state')
+  if (row.version !== put.version) return fail('a check moved the version it read')
+
+  // The gate: a batch-wide precondition on a key the batch does not write.
+  const gated = await client.kv.check(ns, 'state', { expect: put.version + 1000, required: true })
+  if (gated.applied !== false || gated.precondition !== true) {
+    return fail(`a required check that loses is a precondition verdict: ${JSON.stringify(gated)}`)
+  }
+  return { success: true, message: 'check holds, loses with the current row, takes expect:0, and never writes' }
+}

package/test-v2/run.js

@@ -17,6 +17,7 @@ import * as semanticsTests from './semantics.js'
 import * as ackWindowTests from './ackwindow.js'
 import * as kvTests from './kv.js'
 import * as timerTests from './timers.js'
+import * as lockTests from './locks.js'
 import * as streamTests from './stream/index.js'
 import * as docsTests from './docs.js'
 import { LoadBalancer } from '../client-v2/http/LoadBalancer.js';
@@ -115,6 +116,7 @@ async function main() {
         ackWindowTests,
         kvTests,
         timerTests,
+        lockTests,
         docsTests
     ]
     

package/test-v2/wire-unit/_wireServer.js

@@ -0,0 +1,47 @@
+/**
+ * A real node:http server for the binary wire forms: it records every request
+ * with its body as bytes (kv-unit/_planServer.js reads bodies as text, which a
+ * binary push body does not survive) and answers what `answer(hit)` returns:
+ * `{ status, contentType, body }`, body a Buffer or a string.
+ */
+
+import { createServer } from 'node:http'
+
+export function withWireServer(answer, run) {
+  const hits = []
+
+  const server = createServer((req, res) => {
+    const chunks = []
+    req.on('data', chunk => chunks.push(chunk))
+    req.on('end', () => {
+      const hit = { method: req.method, url: req.url, headers: req.headers, raw: Buffer.concat(chunks) }
+      hits.push(hit)
+      const { status = 200, contentType = 'application/json', body = '' } = answer(hit) || {}
+      if (status === 204) {
+        res.writeHead(204)
+        res.end()
+        return
+      }
+      res.writeHead(status, { 'Content-Type': contentType })
+      res.end(body)
+    })
+  })
+
+  return new Promise((resolve, reject) => {
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address()
+      const teardown = () => new Promise(r => server.close(r))
+      Promise.resolve()
+        .then(() => run(`http://127.0.0.1:${port}`, hits))
+        .then(
+          async (value) => { await teardown(); resolve(value) },
+          async (err) => { await teardown(); reject(err) }
+        )
+    })
+  })
+}
+
+export function query(url) {
+  const i = url.indexOf('?')
+  return new URLSearchParams(i < 0 ? '' : url.slice(i + 1))
+}

package/test-v2/wire-unit/popFrames.test.js

@@ -0,0 +1,264 @@
+/**
+ * The framed pop answer (client-v2/http/popFrames.js), against hand-built
+ * answers and a server that plays them. What is at stake: a consumer that
+ * sets framedPop must be handed exactly the messages the JSON answer gives it,
+ * and one that does not set it must send the request every released broker
+ * knows.
+ */
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { zstdCompressSync } from 'node:zlib'
+
+import { Queen, CONFLATION_UNSUPPORTED } from '../../client-v2/index.js'
+import { decodePopFrames, isPopFrames } from '../../client-v2/http/popFrames.js'
+import { withWireServer, query } from './_wireServer.js'
+
+const u16 = (n) => { const b = Buffer.alloc(2); b.writeUInt16LE(n); return b }
+const u32 = (n) => { const b = Buffer.alloc(4); b.writeUInt32LE(n); return b }
+const u64 = (n) => { const b = Buffer.alloc(8); b.writeBigUInt64LE(BigInt(n)); return b }
+const text = (s) => Buffer.concat([u16(Buffer.byteLength(s)), Buffer.from(s)])
+
+/** One stored frame: u32 body_len | flags | id | [trace] | txn | [producer] | payload. */
+function storedFrame(id, txn, payload, { producer = null, trace = null } = {}) {
+  const idBytes = Buffer.alloc(16)
+  idBytes[0] = id
+  idBytes[6] = 0x70
+  idBytes[8] = 0x80
+  const body = Buffer.concat([
+    Buffer.of((trace ? 1 : 0) | (producer ? 2 : 0)),
+    idBytes,
+    trace ? Buffer.from(trace.replaceAll('-', ''), 'hex') : Buffer.alloc(0),
+    text(txn),
+    producer ? text(producer) : Buffer.alloc(0),
+    Buffer.from(payload)
+  ])
+  return Buffer.concat([u32(body.length), body])
+}
+
+/**
+ * A framed pop answer of one claim on partition 7 ("p7") of "orders", lease
+ * "lease-1": one record at base offset 10 holding `frames`, created at
+ * 2023-11-14T22:13:20Z, of which the claim covers start..=end.
+ */
+function framedAnswer(own, start, end, compress, frames) {
+  let raw = Buffer.concat(frames)
+  if (compress) raw = zstdCompressSync(raw)
+  return Buffer.concat([
+    Buffer.from('QPF1'), Buffer.of(1), u32(Buffer.byteLength(own)), Buffer.from(own),
+    text('orders'), text('lease-1'), text('__QUEUE_MODE__'),
+    u32(1), // claims
+    u64(7), text('p7'), u64(start), u64(end),
+    u32(3), // delivery attempt
+    u32(1), // records
+    u64(10), u64(1_700_000_000_000_000n), u32(frames.length), Buffer.of(compress ? 1 : 0), u32(raw.length), raw
+  ])
+}
+
+const twoFrames = () => [storedFrame(1, 't-10', '{"n":10}'), storedFrame(2, 't-11', '{"n":11,"s":"x"}', { producer: 'svc' })]
+
+// The JSON answer of the same two messages, as the broker renders it.
+const TWO_MESSAGES_JSON = '{"success":true,"queue":"orders","partition":"p7","partitionId":"7","leaseId":"lease-1","consumerGroup":"__QUEUE_MODE__","messages":[' +
+  '{"id":"01000000-0000-7000-8000-000000000000","transactionId":"t-10","traceId":null,"data":{"n":10},"producerSub":null,"createdAt":"2023-11-14T22:13:20.000Z","partitionId":"7","partition":"p7","leaseId":"lease-1","consumerGroup":"__QUEUE_MODE__","deliveryAttempt":3,"offset":10},' +
+  '{"id":"02000000-0000-7000-8000-000000000000","transactionId":"t-11","traceId":null,"data":{"n":11,"s":"x"},"producerSub":"svc","createdAt":"2023-11-14T22:13:20.000Z","partitionId":"7","partition":"p7","leaseId":"lease-1","consumerGroup":"__QUEUE_MODE__","deliveryAttempt":3,"offset":11}' +
+  '],"partitionsClaimed":1}'
+
+const json = (body) => ({ body })
+const framed = (body) => ({ contentType: 'application/x-queen-pop', body })
+const pops = (hits) => hits.filter(h => h.method === 'GET' && h.url.startsWith('/api/v1/pop'))
+
+async function withQueen(config, answer, run) {
+  await withWireServer(answer, async (url, hits) => {
+    const queen = new Queen({ url, handleSignals: false, retryAttempts: 1, ...config })
+    try {
+      await run(queen, hits)
+    } finally {
+      await queen.close()
+    }
+  })
+}
+
+describe('decodePopFrames', () => {
+  for (const compress of [false, true]) {
+    it(`unpacks ${compress ? 'a zstd' : 'a raw'} record into the JSON answer's object`, async () => {
+      const got = await decodePopFrames(framedAnswer('{"frames":true}', 10, 11, compress, twoFrames()))
+
+      assert.deepEqual(got, JSON.parse(TWO_MESSAGES_JSON))
+      assert.deepEqual(Object.keys(got.messages[0]), Object.keys(JSON.parse(TWO_MESSAGES_JSON).messages[0]))
+    })
+
+    it(`keeps only the messages inside the claim (${compress ? 'zstd' : 'raw'})`, async () => {
+      const got = await decodePopFrames(framedAnswer('{"frames":true}', 11, 11, compress, twoFrames()))
+
+      assert.equal(got.messages.length, 1)
+      assert.equal(got.messages[0].offset, 11)
+      assert.equal(got.messages[0].transactionId, 't-11')
+      assert.equal(got.messages[0].producerSub, 'svc')
+      assert.equal(got.messages[0].id, '02000000-0000-7000-8000-000000000000')
+    })
+  }
+
+  it('reads a trace id, an empty payload as null, and the answer without its own keys', async () => {
+    const trace = '0190aaaa-0000-4000-8000-000000000001'
+    const answer = framedAnswer('', 10, 11, false, [storedFrame(1, 't-10', '', { trace }), storedFrame(2, 't-11', '[1,"due"]')])
+    const got = await decodePopFrames(answer)
+
+    assert.equal(got.messages[0].traceId, trace)
+    assert.equal(got.messages[0].data, null)
+    assert.deepEqual(got.messages[1].data, [1, 'due'])
+
+    // Version 0 has no JSON object in front of the names.
+    const v0 = Buffer.concat([Buffer.from('QPF1'), Buffer.of(0), answer.subarray(9)])
+    assert.deepEqual(await decodePopFrames(v0), got)
+  })
+
+  it('adds the answer\'s own keys, without `frames`', async () => {
+    const own = '{"frames":true,"conflation":true,"autopilot":{"partitions":4,"batch":50}}'
+    const got = await decodePopFrames(framedAnswer(own, 10, 11, false, twoFrames()))
+
+    assert.equal('frames' in got, false)
+    assert.equal(got.conflation, true)
+    assert.deepEqual(got.autopilot, { partitions: 4, batch: 50 })
+  })
+
+  it('rejects damage', async () => {
+    const answer = framedAnswer('{"frames":true}', 10, 11, false, twoFrames())
+
+    assert.equal(isPopFrames(answer), true)
+    assert.equal(isPopFrames(Buffer.from(TWO_MESSAGES_JSON)), false)
+    await assert.rejects(decodePopFrames(answer.subarray(0, answer.length - 3)), /framed pop answer/)
+    await assert.rejects(decodePopFrames(Buffer.from(TWO_MESSAGES_JSON)), /not a framed pop answer/)
+
+    const future = Buffer.from(answer)
+    future[4] = 9
+    await assert.rejects(decodePopFrames(future), /unknown version 9/)
+
+    // A record that declares more frames than it holds.
+    const short = Buffer.from(answer)
+    const frames = twoFrames()
+    short.writeUInt32LE(3, short.length - frames[0].length - frames[1].length - 9)
+    await assert.rejects(decodePopFrames(short), /a record is shorter than its 3 frames/)
+
+    const badCodec = Buffer.from(answer)
+    badCodec[badCodec.length - frames[0].length - frames[1].length - 5] = 7
+    await assert.rejects(decodePopFrames(badCodec), /unknown codec 7/)
+  })
+})
+
+describe('pop — the default', () => {
+  it('sends no frames parameter', async () => {
+    await withQueen({}, () => json(TWO_MESSAGES_JSON), async (queen, hits) => {
+      const messages = await queen.queue('orders').batch(2).wait(false).pop()
+
+      assert.equal(messages.length, 2)
+      assert.equal(query(pops(hits)[0].url).has('frames'), false)
+    })
+  })
+})
+
+describe('pop — framedPop', () => {
+  for (const compress of [false, true]) {
+    it(`gives the messages of the JSON answer (${compress ? 'zstd' : 'raw'} record)`, async () => {
+      let want = null
+      await withQueen({}, () => json(TWO_MESSAGES_JSON), async (queen) => {
+        want = await queen.queue('orders').batch(2).wait(false).pop()
+      })
+
+      const answer = framedAnswer('{"frames":true}', 10, 11, compress, twoFrames())
+      await withQueen({ framedPop: true }, () => framed(answer), async (queen, hits) => {
+        const got = await queen.queue('orders').batch(2).wait(false).pop()
+
+        assert.equal(query(pops(hits)[0].url).get('frames'), 'true')
+        assert.equal(got.length, 2)
+        assert.deepEqual(got, want)
+      })
+    })
+  }
+
+  it('asks for frames on the partition and the namespace routes too', async () => {
+    await withQueen({ framedPop: true }, () => ({ status: 204 }), async (queen, hits) => {
+      await queen.queue('orders').partition('p7').wait(false).pop()
+      await queen.queue().namespace('ns').wait(false).pop()
+
+      const [byPartition, byNamespace] = pops(hits)
+      assert.ok(byPartition.url.startsWith('/api/v1/pop/queue/orders/partition/p7?'))
+      assert.equal(query(byPartition.url).get('frames'), 'true')
+      assert.ok(byNamespace.url.startsWith('/api/v1/pop?'))
+      assert.equal(query(byNamespace.url).get('frames'), 'true')
+    })
+  })
+
+  it('knows a framed answer by its first bytes, whatever its content type', async () => {
+    const answer = framedAnswer('{"frames":true}', 10, 11, false, twoFrames())
+    for (const contentType of ['application/octet-stream', 'application/json']) {
+      await withQueen({ framedPop: true }, () => ({ contentType, body: answer }), async (queen) => {
+        const got = await queen.queue('orders').batch(2).wait(false).pop()
+
+        assert.deepEqual(got.map(m => m.transactionId), ['t-10', 't-11'], contentType)
+      })
+    }
+  })
+
+  it('reads a JSON answer as always: a broker that does not know the parameter', async () => {
+    await withQueen({ framedPop: true }, () => json(TWO_MESSAGES_JSON), async (queen) => {
+      const got = await queen.queue('orders').batch(2).wait(false).pop()
+
+      assert.equal(got.length, 2)
+      assert.equal(got[1].transactionId, 't-11')
+      assert.equal(got[1].data.s, 'x')
+    })
+  })
+
+  it('reads an empty pop', async () => {
+    await withQueen({ framedPop: true }, () => ({ status: 204 }), async (queen) => {
+      assert.deepEqual(await queen.queue('orders').wait(false).pop(), [])
+    })
+  })
+
+  it('carries the autopilot\'s choice in the answer\'s own keys', async () => {
+    const own = '{"frames":true,"autopilot":{"partitions":4,"batch":50}}'
+    await withQueen({ framedPop: true }, () => framed(framedAnswer(own, 10, 11, false, twoFrames())), async (queen) => {
+      const { messages, autopilot } = await queen.queue('orders').wait(false).popResult()
+
+      assert.equal(messages.length, 2)
+      assert.deepEqual(autopilot, { partitions: 4, batch: 50, waitMillis: 0 })
+    })
+  })
+
+  it('carries the conflation echo, and still raises when the broker sent none', async () => {
+    const echoed = framedAnswer('{"frames":true,"conflation":true}', 10, 11, false, twoFrames())
+    await withQueen({ framedPop: true }, () => framed(echoed), async (queen) => {
+      const got = await queen.queue('orders').group('g').conflation(true).wait(false).pop()
+      assert.equal(got.length, 2)
+    })
+
+    const silent = framedAnswer('{"frames":true}', 10, 11, false, twoFrames())
+    await withQueen({ framedPop: true }, () => framed(silent), async (queen) => {
+      await assert.rejects(
+        queen.queue('orders').group('g2').conflation(true).wait(false).pop(),
+        { code: CONFLATION_UNSUPPORTED }
+      )
+    })
+  })
+})
+
+describe('consume — framedPop', () => {
+  // The consumer loop on framed answers: the handler gets every message of
+  // the claim, in order, and the loop stops at its limit.
+  it('hands the handler the messages of the claim, in order', async () => {
+    const answer = framedAnswer('{"frames":true}', 10, 11, true, twoFrames())
+    await withQueen({ framedPop: true }, () => framed(answer), async (queen, hits) => {
+      const seen = []
+      await queen.queue('orders').batch(2).wait(false).autoAck(false).each().limit(2)
+        .consume(async (message) => {
+          seen.push(`${message.transactionId}@${message.partitionId}/${message.leaseId}`)
+        })
+
+      assert.deepEqual(seen, ['t-10@7/lease-1', 't-11@7/lease-1'])
+      assert.ok(pops(hits).length >= 1)
+      for (const hit of pops(hits)) {
+        assert.equal(query(hit.url).get('frames'), 'true')
+      }
+    })
+  })
+})