queen-mq 1.0.0 → 1.0.3

package/client-v2/kv/expiry.js

@@ -0,0 +1,148 @@
+/**
+ * Expiry sugar for the KV surface, and the ONE duration parser this SDK has.
+ *
+ * PLAN_KV_TIMERS.md §20.1 ratified `ttlSeconds` as the wire's unit: the server
+ * speaks seconds everywhere (`dedup_window_seconds`, `lease_seconds`,
+ * `retention_seconds`), so the product keeps ONE duration convention and the
+ * SDKs do the converting. `ttlMillis` does not exist in any client and must not
+ * be added -- it would reintroduce, through the service entrance, the double
+ * convention that decision removed.
+ *
+ * §20.6 is the other half of the rule, and it is what this file's parser
+ * serves twice: DURATIONS THAT CAN BE SUB-SECOND ARE IN MILLISECONDS, THE ONES
+ * THAT CANNOT ARE IN SECONDS. A 250 ms retry backoff is a real and central use
+ * of timers, so their wire is `delayMs`; a sub-second TTL is not a real use for
+ * anybody, so the KV wire is `ttlSeconds`. The parser below returns
+ * MILLISECONDS -- the finer of the two -- and each caller converts.
+ *
+ * NOT EXPORTED FROM THE BARREL, deliberately (§10.4). The client's stated
+ * convention is "a number with the unit in its name", and this is its first
+ * string duration. Confining the parser to this file is what keeps it from
+ * becoming a general-purpose utility that then has to accept every format
+ * anybody ever wrote.
+ *
+ * ROUNDING IS ALWAYS UP. A TTL rounded down can expire a marker BEFORE the
+ * window it was supposed to cover, which is the failure this feature exists to
+ * prevent; rounding up costs at most a second of retention.
+ */
+
+const UNIT_MS = {
+  ms: 1,
+  s: 1000,
+  m: 60 * 1000,
+  h: 60 * 60 * 1000,
+  d: 24 * 60 * 60 * 1000
+}
+
+// One or more <number><unit> pairs: '30s', '1h30m', '250ms'. Anchored, so a
+// typo is an error and never a silent partial parse ('1hour' does not become
+// one hour).
+const DURATION_RE = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/
+
+/**
+ * Parse a duration STRING into milliseconds. Numbers are refused on purpose:
+ * `{ ttl: 5000 }` cannot be read as seconds or milliseconds without guessing,
+ * and guessing here would be a factor-of-1000 bug in somebody's retention.
+ * The numeric spellings are the ones with the unit in the name --
+ * `ttlSeconds` and `delayMs`.
+ */
+export function parseDurationMs(value) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(
+      `duration must be a string with a unit, e.g. '250ms', '30s', '15m', '24h', '7d' — got ${JSON.stringify(value)}. ` +
+      'For a plain number use ttlSeconds (KV) or delayMs (timers), which carry their unit in the name.'
+    )
+  }
+  const parts = value.trim().toLowerCase().match(/\d+(?:\.\d+)?[a-z]+/g)
+  const joined = parts ? parts.join('') : ''
+  if (!parts || joined !== value.trim().toLowerCase()) {
+    throw new Error(`invalid duration '${value}': expected <number><unit> parts, e.g. '30s' or '1h30m'`)
+  }
+  let ms = 0
+  for (const part of parts) {
+    const m = DURATION_RE.exec(part)
+    if (!m) {
+      throw new Error(`invalid duration '${value}': unknown unit in '${part}' (use ms, s, m, h, d)`)
+    }
+    ms += Number(m[1]) * UNIT_MS[m[2]]
+  }
+  if (!(ms > 0)) {
+    throw new Error(`invalid duration '${value}': must be greater than zero`)
+  }
+  return ms
+}
+
+/** Milliseconds since the epoch for a Date, an ISO string or an epoch number. */
+function instantMs(value) {
+  if (value instanceof Date) {
+    const t = value.getTime()
+    if (Number.isNaN(t)) throw new Error('until: invalid Date')
+    return t
+  }
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string') {
+    const t = Date.parse(value)
+    if (Number.isNaN(t)) throw new Error(`until: '${value}' is not a parseable date`)
+    return t
+  }
+  throw new Error(`until must be a Date, an ISO 8601 string or an epoch-milliseconds number — got ${typeof value}`)
+}
+
+/**
+ * Resolve the expiry fields of one KV write into the CANONICAL wire shape.
+ *
+ * Returns `{ ttlSeconds }`, `{ forever: true }`, or `{}`.
+ *
+ * The empty answer is deliberate and is the reason this function validates so
+ * little: §5.1's rule -- exactly one of `ttlSeconds` and `forever:true`, zero
+ * or two being the same error -- lives in `kv_apply_v1`, so that all seven
+ * clients AND the embedded broker (which never passes through an HTTP handler)
+ * inherit it without a line of their own. Re-implementing it here would give
+ * the product two places that can disagree about when a key dies. What IS
+ * checked here is only what the server cannot see, because it is sugar that
+ * never reaches it: two spellings of the same field, a `forever` that is not
+ * `true`, and an `until` already in the past.
+ *
+ * `nowMs` is a parameter so the conversion happens at SEND time. In a
+ * transaction the ops are built when the caller writes them and sent at
+ * `commit()`, and an `until` frozen at build time would ship a TTL that is
+ * already stale by however long the bundle took to assemble.
+ */
+export function resolveExpiry(opts = {}, nowMs = Date.now()) {
+  const spellings = ['ttlSeconds', 'ttl', 'until'].filter(k => opts[k] !== undefined)
+  if (spellings.length > 1) {
+    throw new Error(
+      `expiry declared twice (${spellings.join(' and ')}): ttlSeconds is the canonical field, ` +
+      '`ttl` is a duration string and `until` is an instant — pick one'
+    )
+  }
+
+  const out = {}
+
+  if (opts.forever !== undefined) {
+    if (opts.forever !== true) {
+      throw new Error('forever must be exactly true; there is no forever:false — omit it and declare a TTL')
+    }
+    out.forever = true
+  }
+
+  if (opts.ttlSeconds !== undefined) {
+    out.ttlSeconds = opts.ttlSeconds
+  } else if (opts.ttl !== undefined) {
+    out.ttlSeconds = Math.ceil(parseDurationMs(opts.ttl) / 1000)
+  } else if (opts.until !== undefined) {
+    const deltaMs = instantMs(opts.until) - nowMs
+    const seconds = Math.ceil(deltaMs / 1000)
+    if (seconds <= 0) {
+      throw new Error(
+        `until is already in the past (${Math.round(deltaMs)}ms from now): a key written with a dead ` +
+        'TTL would be refused by the broker, and a key written with none would be immortal'
+      )
+    }
+    out.ttlSeconds = seconds
+  }
+
+  // Both declared: forwarded as-is on purpose, so the broker gives its own
+  // `kv_expiry_not_specified` verdict and there is one rule, in one place.
+  return out
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "queen-mq",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "type": "module",
   "description": "Partitioned message queue on PostgreSQL — broker client + fluent streaming SDK (windows, joins, gates) in one package",
   "main": "client-v2/index.js",
   "scripts": {
-    "test": "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js test-v2/streams-unit/ack.test.js test-v2/http-unit/retry429.test.js test-v2/http-unit/hostHeader.test.js && node test-v2/run.js human",
-    "test:unit": "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js test-v2/streams-unit/ack.test.js test-v2/http-unit/retry429.test.js test-v2/http-unit/hostHeader.test.js",
+    "test": "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js test-v2/streams-unit/ack.test.js test-v2/http-unit/retry429.test.js test-v2/http-unit/hostHeader.test.js test-v2/kv-unit/kvWire.test.js test-v2/kv-unit/timerWire.test.js test-v2/kv-unit/txnWire.test.js && node test-v2/run.js human",
+    "test:unit": "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js test-v2/streams-unit/ack.test.js test-v2/http-unit/retry429.test.js test-v2/http-unit/hostHeader.test.js test-v2/kv-unit/kvWire.test.js test-v2/kv-unit/timerWire.test.js test-v2/kv-unit/txnWire.test.js",
     "test:unit:e2e": "node --test test-v2/streams-unit/e2e.test.js",
     "test:integration": "node test-v2/run.js human",
     "test:streams": "node test-v2/run.js stream",
@@ -28,16 +28,24 @@
   },
   "author": "Smartness",
   "license": "Apache-2.0",
+  "homepage": "https://queenmq.com",
   "repository": {
     "type": "git",
     "url": "https://github.com/queen-mq/queen"
   },
+  "bugs": {
+    "url": "https://github.com/queen-mq/queen/issues"
+  },
   "keywords": [
     "message-queue",
     "queue",
+    "postgres",
+    "postgresql",
     "broker",
     "message-queue-system",
     "fifo",
+    "consumer-groups",
+    "dead-letter-queue",
     "streaming",
     "stream-processing",
     "rate-limiter",

package/test-v2/_kvtimers.js

@@ -0,0 +1,71 @@
+/**
+ * Shared helpers for the kv and timers integration suites.
+ *
+ * Deliberately NOT registered in run.js: that runner treats every export of a
+ * registered module as a test function, so a helper exported from kv.js would
+ * be executed as a test and reported as one.
+ *
+ * WHY THERE IS NO AVAILABILITY PROBE HERE ANY MORE. There used to be one, plus
+ * a `skipped()` verdict, because `QUEEN_KV_ENABLED` and `QUEEN_TIMERS_ENABLED`
+ * were boot flags that defaulted to false: with them off the routes were not
+ * registered and every call here answered 404, so a red suite was the DEFAULT
+ * configuration's own fault and the skip existed to stop that training everyone
+ * to ignore the colour.
+ *
+ * Those flags are gone. Kv and timers are not features, they are the broker:
+ * there is no `QUEEN_PUSH_ENABLED` either. Every cell that runs this binary has
+ * both surfaces, so these suites RUN, and a 404 from any of them is a bug in
+ * the broker, not a configuration to detect. A test that skips is a test that
+ * says nothing, and that was only tolerable while the 404 was legitimate.
+ *
+ * What still exists is the operator's RUNTIME kill switch (`kv_enabled`,
+ * `timers_schedule_enabled`, `timers_fire_enabled` in `queen.system_state`) --
+ * the maintenance-mode lever, pulled live during an incident. It answers 503
+ * with `Retry-After` on the kv/timer routes and 403 on a `kv`/`timers` rider
+ * inside a transaction, never 404. If a run here ever goes red against that,
+ * the switch is down on the rig and somebody pulled it; it is not something
+ * these tests should paper over.
+ */
+
+export const KV_NS = 'test-kv'
+export const TIMER_QUEUE = 'test-timers'
+
+export const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms))
+
+/**
+ * Poll a queue until `match` accepts a message, or the deadline passes.
+ *
+ * WHY THIS IS A POLL AND NOT A LONG POLL, MEASURED ON A REAL RIG. A timer's
+ * delivery is committed by the sweeper INSIDE PostgreSQL
+ * (`log_timers_fire_v1` = DELETE + push in one transaction), so it does not
+ * pass through the broker's push handler and the destination partition is not
+ * marked ready in that broker's hot list. A consumer therefore sees the
+ * message only at the next hot-list reseed: on a default broker
+ * (QUEEN_HOTLIST_RESEED_MS = 30000) a timer scheduled for +300 ms was measured
+ * arriving at +30.7 s, and a 20 s long poll timed out with the message already
+ * committed in the log.
+ *
+ * That is a broker property, not a client one, and it is why these tests
+ * assert ARRIVAL and never latency: `deliverAt` is "not before", never
+ * "exactly at". The deadline here is generous on purpose -- it is sized
+ * against the reseed period, not against the delay under test.
+ */
+export async function popUntil(client, queueName, match, timeoutMs = 60000) {
+  const deadline = Date.now() + timeoutMs
+  for (;;) {
+    const messages = await client.queue(queueName).batch(10).wait(false).pop()
+    const hit = messages.filter(match)
+    if (hit.length > 0) return hit
+    // Anything else in this queue is a stranger -- a delivery left behind by an
+    // earlier run of this same test. It is ACKED rather than ignored, and that
+    // is not tidiness: queue-mode delivery is ordered, so an unacked stranger
+    // holds its lease and blocks the cursor, and the message under test would
+    // never be reached inside any deadline. This is the shape of the failure
+    // that a "wait longer" would never have fixed.
+    for (const stranger of messages) {
+      await client.ack(stranger)
+    }
+    if (Date.now() > deadline) return []
+    await sleep(500)
+  }
+}

package/test-v2/ackwindow.js

@@ -30,11 +30,12 @@ const TENANT = '00000000-0000-0000-0000-000000000001'
 
 function sleep(ms) { return new Promise(r => setTimeout(r, ms)) }
 
-async function popRetry(client, queue, { batch = 3, group = null, partition = null, tries = 30 } = {}) {
+async function popRetry(client, queue, { batch = 3, group = null, partition = null, tries = 30, mode = null } = {}) {
     for (let i = 0; i < tries; i++) {
         let b = client.queue(queue).batch(batch).wait(false)
         if (group) b = b.group(group)
         if (partition) b = b.partition(partition)
+        if (mode) b = b.subscriptionMode(mode)
         const msgs = await b.pop()
         if (msgs && msgs.length > 0) return msgs
         await sleep(150)
@@ -192,7 +193,9 @@ export async function emptyPartitionCursorSealsAfterRetention(client) {
         [0, 1, 2, 3, 4, 5].map(n => ({ data: { n }, transactionId: `${queue}-tx-${n}` })))
 
     // Consume + ack only the first two: committed lands at 1, the rest stays.
-    const first = await popRetry(client, queue, { batch: 2, group })
+    // First contact for g-seal, and the 6 messages are already pushed: the
+    // group has to ask for the backlog it is about to half-consume.
+    const first = await popRetry(client, queue, { batch: 2, group, mode: 'all' })
     if (first.length !== 2) return { success: false, message: `expected 2 messages, got ${first.length}` }
     const ackr = await client.ack(first, true, { group })
     if (ackr.success !== true) return { success: false, message: `ack failed: ${ackr.error}` }
@@ -245,7 +248,11 @@ export async function emptyPartitionCursorSealsAfterRetention(client) {
     })()
     if (!dpart0) return { success: false, message: 'delayed queue segments never appeared' }
 
-    const dempty = await client.queue(dqueue).partition('Default').group(group).batch(1).wait(false).pop()
+    // First contact for g-seal on THIS queue too (metadata is queue-scoped), and
+    // the 2 delayed messages are already pushed: under the default 'new' the
+    // cursor would seed at last_offset and the guard below could not tell a seed
+    // from a seal. 'all' seeds at -1, so a non -1 cursor can only be the seal.
+    const dempty = await client.queue(dqueue).partition('Default').group(group).subscriptionMode('all').batch(1).wait(false).pop()
     if (dempty && dempty.length > 0) return { success: false, message: 'delayed message delivered early?' }
     const dcommitted = await committedOf(dpart0.id, group)
     const dsegs = await segmentCount(dpart0.id)

package/test-v2/consume.js

@@ -10,7 +10,6 @@ export async function testConsumer(client) {
 
     let msgToReturn = null
 
-    // docs:start(js-consume)
     await client
     .queue('test-queue-v2-consume')
     .batch(1)
@@ -19,7 +18,6 @@ export async function testConsumer(client) {
     .consume(async msg => {
         msgToReturn = msg
     })
-    // docs:end
 
     return { success: msgToReturn !== null, message: 'Consumer test completed successfully' }
 }

package/test-v2/docs.js

@@ -0,0 +1,204 @@
+/**
+ * The tests behind the published examples.
+ *
+ * Every marked region in this file is rendered on queenmq.com: the homepage,
+ * the quickstart, the concept pages and the HTTP reference pull these exact
+ * lines through webdoc/scripts/gen-snippets.mjs. They are tests written to
+ * read as documentation: real queue names, a partition key that means
+ * something, and no test scaffolding inside a marked region. Assertions stay
+ * outside the markers.
+ *
+ * After editing a marked region, regenerate the partials with
+ * `pnpm --dir webdoc gen` or the docs CI check fails on drift. The queues used
+ * here (orders, payments, invoices) are wiped by cleanupTestData in run.js
+ * before every suite run, exactly like the test-% queues.
+ */
+
+export async function docsProduceAndConsume(client) {
+    // docs:start(js-push)
+    const res = await client
+      .queue('orders')
+      .partition('customer-42')
+      .push([{ data: { orderId: 9137, amount: 99.5 } }])
+    // docs:end
+    if (res[0].status !== 'queued') {
+        return { success: false, message: `Push not queued: ${JSON.stringify(res[0])}` }
+    }
+
+    // The consume loop acks each message when the callback resolves, so when
+    // the awaited chain returns, the billing group's cursor has moved.
+    // docs:start(js-consume)
+    await client
+      .queue('orders')
+      .group('billing')
+      .subscriptionMode('all')
+      .limit(1)
+      .each()
+      .consume(async (message) => {
+        console.log(message.data)
+      })
+    // docs:end
+
+    const drained = await client
+        .queue('orders')
+        .group('billing')
+        .batch(1)
+        .wait(false)
+        .pop()
+    if (drained.length !== 0) {
+        return { success: false, message: 'Billing group cursor did not advance after consume' }
+    }
+
+    // A raw pop on another cursor still sees the message: groups are fan-out.
+    // docs:start(js-pop)
+    const messages = await client
+      .queue('orders')
+      .batch(10)
+      .wait(true)
+      .pop()
+    // docs:end
+    if (messages.length !== 1 || messages[0].data.orderId !== 9137) {
+        return { success: false, message: `Fan-out pop expected the order back, got ${JSON.stringify(messages)}` }
+    }
+
+    return { success: true, message: 'Push, consume and fan-out pop all verified' }
+}
+
+export async function docsDeduplication(client) {
+    // The fixed transactionId below survives reruns because cleanupTestData
+    // purges log_txns for these queues before the suite starts.
+    // docs:start(js-push-dedup)
+    const first = await client
+      .queue('payments')
+      .partition('customer-42')
+      .push([{ transactionId: 'order-9137-paid', data: { orderId: 9137, amount: 99.5 } }])
+
+    const retry = await client
+      .queue('payments')
+      .partition('customer-42')
+      .push([{ transactionId: 'order-9137-paid', data: { orderId: 9137, amount: 99.5 } }])
+    // retry[0].status is 'duplicate': the second push wrote nothing
+    // and answers with the first message's id.
+    // docs:end
+    if (first[0].status !== 'queued') {
+        return { success: false, message: `First push not queued: ${JSON.stringify(first[0])}` }
+    }
+    if (retry[0].status !== 'duplicate') {
+        return { success: false, message: `Retry not deduplicated: ${JSON.stringify(retry[0])}` }
+    }
+    if (retry[0].message_id !== first[0].message_id) {
+        return { success: false, message: 'Duplicate did not answer with the original message id' }
+    }
+    return { success: true, message: 'Second push with the same transactionId wrote nothing' }
+}
+
+export async function docsReplayAndSeek(client) {
+    const seeded = await client.queue('orders').partition('customer-91').push([
+        { data: { orderId: 5001, amount: 12 } },
+        { data: { orderId: 5002, amount: 24 } },
+        { data: { orderId: 5003, amount: 36 } },
+    ])
+    if (!seeded.every(r => r.status === 'queued')) {
+        return { success: false, message: 'Seed pushes failed' }
+    }
+
+    // docs:start(js-replay)
+    // A fresh group with subscriptionMode('all') reads the whole retained
+    // lane from the beginning, without touching any other group's cursor.
+    const replayed = await client
+      .queue('orders')
+      .partition('customer-91')
+      .group('audit')
+      .subscriptionMode('all')
+      .batch(100)
+      .wait(true)
+      .pop()
+    // docs:end
+    const ids = replayed.map(m => m.data.orderId)
+    if (ids.length !== 3 || ids[0] !== 5001 || ids[1] !== 5002 || ids[2] !== 5003) {
+        return { success: false, message: `Replay expected [5001,5002,5003] in order, got ${JSON.stringify(ids)}` }
+    }
+
+    // docs:start(js-seek)
+    // Move the audit group's cursor back one hour. The seek also releases
+    // any live lease, so an in-flight batch is abandoned, not acked.
+    await client.admin.seekConsumerGroup('audit', 'orders', {
+      timestamp: new Date(Date.now() - 3600 * 1000).toISOString(),
+    })
+    // docs:end
+
+    const again = await client
+        .queue('orders')
+        .partition('customer-91')
+        .group('audit')
+        .batch(100)
+        .wait(true)
+        .pop()
+    const againIds = again.map(m => m.data.orderId)
+    if (againIds.length !== 3 || againIds[0] !== 5001) {
+        return { success: false, message: `Post-seek pop expected the lane again, got ${JSON.stringify(againIds)}` }
+    }
+    return { success: true, message: 'Replay from the beginning and seek-back both verified' }
+}
+
+export async function docsTransactionalHandoff(client) {
+    const seeded = await client
+        .queue('orders')
+        .partition('customer-77')
+        .push([{ data: { orderId: 4102, amount: 18 } }])
+    if (seeded[0].status !== 'queued') {
+        return { success: false, message: 'Seed push failed' }
+    }
+
+    // docs:start(js-transaction)
+    await client
+      .queue('orders')
+      .group('invoicing')
+      .subscriptionMode('all')
+      .each()
+      .autoAck(false) // the acknowledgement belongs to the transaction, not to the loop
+      .limit(1)
+      .idleMillis(5000)
+      .consume(async (message) => {
+        // commit() throws when the broker rejects the bundle, so reaching the
+        // line after it means the ack and the push are both durable.
+        await client
+          .transaction()
+          .queue('invoices')
+          .push([{ data: { orderId: message.data.orderId, invoiced: true } }])
+          .ack(message, 'completed', { consumerGroup: 'invoicing' })
+          .commit()
+      })
+    // docs:end
+
+    // The loop takes whichever order is oldest for this group, and other docs
+    // tests push to the same queue, so identity is checked against the orders
+    // that actually exist rather than against a hardcoded id. A throwaway group
+    // reads them without disturbing the invoicing cursor.
+    const everyOrder = await client
+        .queue('orders')
+        .group(`docs-audit-${Date.now()}`)
+        .subscriptionMode('all')
+        .batch(50)
+        .partitions(20)
+        .wait(false)
+        .pop()
+    const orderIds = everyOrder.map(m => m.data.orderId)
+
+    const invoiced = await client
+        .queue('invoices')
+        .batch(1)
+        .partitions(10)
+        .wait(true)
+        .pop()
+    if (invoiced.length !== 1 || !orderIds.includes(invoiced[0].data.orderId)) {
+        return {
+            success: false,
+            message: `Invoice not committed for a real order: ${JSON.stringify(invoiced)} against ${JSON.stringify(orderIds)}`,
+        }
+    }
+    if (invoiced[0].data.invoiced !== true) {
+        return { success: false, message: 'Invoice payload corrupted' }
+    }
+    return { success: true, message: 'Ack and next-stage push committed together' }
+}

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

@@ -95,7 +95,12 @@ describe('HttpClient — 429 retry policy', () => {
   it('falls back to exponential backoff when Retry-After is absent, and the gap grows', async () => {
     const plan = repeat(rateLimited(), 2)
     await withPlanServer(plan, { status: 200, body: { ok: true } }, async (url, hits) => {
-      const client = new HttpClient({ baseUrl: url, retry429: { baseMs: 20, capMs: 2000 } })
+      // baseMs has to be well above the event loop's scheduling noise. At 20ms
+      // a loaded runner added ~27ms to BOTH gaps, which collapses their ratio
+      // towards 1 (observed: 47ms then 54ms) and failed a test about growth
+      // that was working perfectly. The delay is additive, so the fix is a base
+      // big enough to dominate it, not a looser threshold.
+      const client = new HttpClient({ baseUrl: url, retry429: { baseMs: 100, capMs: 2000 } })
       try {
         const result = await client.get('/x')
         assert.deepEqual(result, { ok: true })

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

@@ -0,0 +1,65 @@
+/**
+ * A real node:http server driven by a canned response plan, recording every
+ * request it receives (method, url, parsed body).
+ *
+ * Same shape as test-v2/http-unit/retry429.test.js's withPlanServer and
+ * streams-unit/fakeServer.js -- no mocking framework, a real socket, real
+ * fetch, real JSON. The difference is that these tests assert the REQUEST,
+ * not the retry behaviour: the exact JSON body of every KV and timer
+ * operation is the contract towards the broker, and a plan server is the only
+ * place that contract can be pinned without a database.
+ */
+
+import { createServer } from 'node:http'
+
+export function withPlanServer(plan, defaultResponse, run) {
+  const hits = []
+  let index = 0
+
+  const server = createServer((req, res) => {
+    let raw = ''
+    req.on('data', chunk => { raw += chunk })
+    req.on('end', () => {
+      let body = null
+      if (raw.length > 0) {
+        try {
+          body = JSON.parse(raw)
+        } catch {
+          body = { __unparseable: raw }
+        }
+      }
+      hits.push({ method: req.method, url: req.url, raw, body })
+
+      const descriptor = index < plan.length ? plan[index] : defaultResponse
+      index++
+
+      const status = descriptor.status ?? 200
+      const headers = { 'Content-Type': 'application/json', ...(descriptor.headers || {}) }
+      res.writeHead(status, headers)
+      res.end(JSON.stringify(descriptor.body ?? { ok: true }))
+    })
+  })
+
+  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) }
+        )
+    })
+  })
+}
+
+/** One canned 200 with this JSON body. */
+export function ok(body) {
+  return { status: 200, body }
+}
+
+/** The KV batch envelope: {"results":[...]}, index-aligned to the input. */
+export function kvResults(...results) {
+  return ok({ results })
+}