queen-mq 2.3.0 → 2.7.0

package/README.md

@@ -799,6 +799,48 @@ other than the lost precondition still throws.
 
 ---
 
+## Reads by Offset
+
+Two queue methods read a partition's log by position, over `POST /api/v1/fetch` and
+`POST /api/v1/partitions/changed`. Neither takes a lease, moves a cursor or needs an ack: two
+readers asking the same question get the same answer, and no consumer group notices them. They
+suit a replay, an audit, a sink that keeps its own position, and a service that rebuilds an entity
+from its partition.
+
+```javascript
+// Every record of these partitions, from the oldest one still kept.
+const read = await queen.queue('orders').fetch(['customer-42', 'customer-7'])
+const part = read.get('customer-42')
+part.records          // [{ offset, transactionId, payload, ts }, ...] in offset order
+part.nextOffset       // where to start next time to read only what is new
+part.highWatermark    // the next offset the partition will assign
+part.logStartOffset   // the oldest offset retention kept
+
+// Only what came after an earlier read.
+const later = await queen.queue('orders').fetch(['customer-42'], {
+  offsets: { 'customer-42': part.nextOffset }
+})
+
+// The partitions written at or after a time, every page of them, in creation order.
+const { partitions, safeTime } = await queen.queue('orders').changedSince(new Date(Date.now() - 600_000))
+partitions.map(p => p.name)   // each is { name, id, lastOffset, logStart, lastWriteAt }
+
+// Next time, only what changed after that answer.
+const next = await queen.queue('orders').changedSince(safeTime)
+```
+
+`fetch` reads each partition up to where it ended when the call first read it: it asks for 1000
+partitions per request, and asks again until each one is read. A partition whose start retention
+deleted is read from its oldest kept record. It answers a `Map` in the order the partitions were
+named; a partition nobody wrote, or of a queue that does not exist, has no records.
+`options.maxBytes` caps the payload bytes of one request (default 8 MiB).
+
+`changedSince` takes a `Date`, epoch milliseconds or an ISO-8601 string; without one it lists every
+partition of the queue. `safeTime` is the broker's time up to which every write is counted in the
+answer: pass it as the next `since`, and never compare it with your own clock.
+
+---
+
 ## Examples
 
 ### Complete Pipeline with Consumer Groups
@@ -934,6 +976,16 @@ throws before any request when the builder has `.commitOnDelivery()`.
 
 `.autoAck()` is `consume()`'s ack after your handler and has no effect on a pop.
 
+### Reads by Offset
+
+```javascript
+const read = await queen.queue('q').fetch(['p1', 'p2'])                          // Map: partition -> { records, nextOffset, ... }
+const later = await queen.queue('q').fetch(['p1'], { offsets: { p1: 42 }, maxBytes: 1 << 20 })
+const { partitions, safeTime } = await queen.queue('q').changedSince(since)     // Date, epoch ms, ISO string; null = all
+```
+
+No lease, no cursor, nothing to ack. See [Reads by Offset](#reads-by-offset).
+
 ### Consume
 
 ```javascript

package/client-v2/README.md

@@ -21,6 +21,7 @@ Welcome to Queen client! This is your friendly guide to mastering message queues
 - [Part 13: Callbacks & Error Handling](#part-13-callbacks--error-handling)
 - [Part 14: Graceful Shutdown](#part-14-graceful-shutdown)
 - [Part 15: Binary Push, Compression & Framed Pop](#part-15-binary-push-compression--framed-pop)
+- [Part 16: Reads by Offset - Replay Without a Lease](#part-16-reads-by-offset---replay-without-a-lease)
 - [Cheat Sheet](#cheat-sheet)
 
 ---
@@ -1669,6 +1670,55 @@ answers JSON.
 
 ---
 
+## Part 16: Reads by Offset - Replay Without a Lease
+
+A pop hands messages to one consumer and waits for its ack. Sometimes you only
+want to read: rebuild an entity from its partition, replay a day for an audit,
+copy a queue somewhere else. Two queue methods do that, and neither takes a
+lease, moves a cursor or needs an ack. Two readers asking the same question get
+the same answer, and no consumer group notices them.
+
+```javascript
+// Every record of these partitions, from the oldest one still kept
+const read = await queen.queue('orders').fetch(['customer-42', 'customer-7'])
+
+for (const [partition, part] of read) {
+  console.log(partition, part.records.map(r => r.payload))
+  // part.records: [{ offset, transactionId, payload, ts }, ...]
+  // part.nextOffset: where to start next time to read only what is new
+}
+
+// Only what came after that read
+const later = await queen.queue('orders').fetch(['customer-42'], {
+  offsets: { 'customer-42': read.get('customer-42').nextOffset }
+})
+```
+
+`fetch` reads each partition up to where it ended when the call first read it.
+It asks for 1000 partitions per request and asks again until each one is read,
+and a partition whose start retention deleted is read from its oldest kept
+record. A partition nobody wrote, or of a queue that does not exist, has no
+records. `maxBytes` caps the payload bytes of one request (default 8 MiB).
+
+To find out which partitions to read, ask which ones were written since a time:
+
+```javascript
+const { partitions, safeTime } = await queen.queue('orders')
+  .changedSince(new Date(Date.now() - 10 * 60_000))
+
+partitions.map(p => p.name)   // each { name, id, lastOffset, logStart, lastWriteAt }
+
+// Next time, only what changed after that answer
+const next = await queen.queue('orders').changedSince(safeTime)
+```
+
+`changedSince` follows every page of the answer and returns the partitions in
+the order they were created; without a time it lists all of them. `safeTime` is
+the broker's time up to which every write is counted in the answer: pass it as
+the next `since`, and never compare it with your own clock.
+
+---
+
 ## Cheat Sheet
 
 ### Connection

package/client-v2/builders/QueueBuilder.js

@@ -14,6 +14,7 @@ import { durableAddress } from '../buffer/sinks.js'
 import { QUEUE_DEFAULTS, CONSUME_DEFAULTS, POP_DEFAULTS } from '../utils/defaults.js'
 import { checkConflationResponse, CONFLATION_UNSUPPORTED } from '../utils/conflation.js'
 import { popSizing, parseAutopilotDecision } from '../utils/autopilot.js'
+import { fetchPartitions, partitionsChangedSince } from '../reads/offsetReads.js'
 import * as logger from '../utils/logger.js'
 
 // Per-item push statuses that mean the broker took the message: `queued`
@@ -632,6 +633,39 @@ export class QueueBuilder {
     await this.#bufferManager.flushBuffer(queueAddress)
   }
 
+  // ===========================
+  // Reads by offset
+  // ===========================
+
+  /**
+   * Every record of these partitions, read by offset: no lease, no cursor,
+   * nothing to ack. Answers a Map of partition name to
+   * `{ partition, records, highWatermark, logStartOffset, nextOffset }`.
+   *
+   *   const read = await queen.queue('orders').fetch(['customer-42', 'customer-7'])
+   *   read.get('customer-42').records.map(r => r.payload)
+   *
+   * `options.offsets` ({ name: offset } or a Map) starts a partition later than
+   * its oldest kept record, e.g. at the `nextOffset` of an earlier read.
+   * `options.maxBytes` caps the payload bytes of one call (default 8 MiB).
+   * See reads/offsetReads.js.
+   */
+  async fetch(partitions, options = {}) {
+    return fetchPartitions(this.#httpClient, this.#queueName, partitions, options)
+  }
+
+  /**
+   * The partitions written at or after `since` (a Date, epoch milliseconds or
+   * an ISO-8601 string; null lists them all): `{ partitions, safeTime }`.
+   * Pass `safeTime` as the next `since`.
+   *
+   *   const { partitions } = await queen.queue('orders').changedSince(new Date(Date.now() - 600_000))
+   *   partitions.map(p => p.name)
+   */
+  async changedSince(since = null) {
+    return partitionsChangedSince(this.#httpClient, this.#queueName, since)
+  }
+
   // ===========================
   // Dead Letter Queue Methods
   // ===========================

package/client-v2/consumer/ConsumerManager.js

@@ -22,6 +22,59 @@ function pause(ms, signal) {
   })
 }
 
+// After a pop that failed for a reason waiting can fix, the next one waits:
+// the broker's Retry-After when it sent one (1 s on its 503s), else 1 s
+// doubling with each failure in a row. Never more than 30 s, so a consumer
+// resumes within 30 s of the broker answering again; ±20 % so a fleet of
+// workers does not come back in step.
+const TRANSIENT_BASE_MILLIS = 1000
+const TRANSIENT_CAP_MILLIS = 30000
+
+/**
+ * Whether a failed pop is worth polling again, because the broker or the way
+ * to it could not answer for a while and waiting changes that:
+ *
+ * - HTTP 408, 429 or any 5xx. The broker's own retryable answers are all a 503
+ *   with Retry-After: no leader (`no_leader`, `retry`), an elapsed deadline
+ *   (`timeout`, "the request deadline elapsed"), a leader change mid-commit
+ *   (`outcome_unknown`), a standby cluster (`standby`). A 500 on a pop comes
+ *   from a node shutting down or a roll between versions; a 502 or 504 from a
+ *   gateway in front of a node that is restarting.
+ * - No HTTP answer at all: this client's request timeout, or a connection that
+ *   could not be made or was cut before or while the answer was read.
+ *
+ * Not worth it, so the consumer stops as before: a 503
+ * `raft_phase1_unsupported` (the broker cannot serve the route at all), every
+ * other 4xx (a request or a credential refused the same way next time), a stop
+ * by the caller, and an error without an HTTP status that is not a transport
+ * fault (a bug, a `hostHeader` this runtime cannot send).
+ */
+export function isTransientPopError(error) {
+  if (!error || error.aborted) return false
+  if (typeof error.status === 'number') {
+    if (error.code === 'raft_phase1_unsupported') return false
+    return error.status === 408 || error.status === 429 || error.status >= 500
+  }
+  const message = typeof error.message === 'string' ? error.message : ''
+  return error.name === 'AbortError' ||   // this client's request timeout
+    message.includes('fetch failed') ||   // no connection, or it dropped before the answer
+    message === 'terminated' ||           // it dropped while the answer was read
+    message.includes('ECONNREFUSED') || error.code === 'ECONNREFUSED'
+}
+
+/**
+ * The wait before the next pop, after `failures` transient failures in a row.
+ * `random` stands in for Math.random in tests.
+ */
+export function transientDelayMillis(failures, retryAfterSeconds, random = Math.random) {
+  const hasRetryAfter = typeof retryAfterSeconds === 'number' && Number.isFinite(retryAfterSeconds) && retryAfterSeconds >= 0
+  const base = hasRetryAfter
+    ? retryAfterSeconds * 1000
+    : TRANSIENT_BASE_MILLIS * 2 ** Math.max(0, failures - 1)
+  const jittered = Math.min(base, TRANSIENT_CAP_MILLIS) * (0.8 + 0.4 * random())
+  return Math.round(Math.min(jittered, TRANSIENT_CAP_MILLIS))
+}
+
 export class ConsumerManager {
   #httpClient
   #queen
@@ -154,6 +207,9 @@ export class ConsumerManager {
     
     let processedCount = 0
     let lastMessageTime = idleMillis ? Date.now() : null
+    // Pops that failed in a row for a reason waiting can fix, and since when.
+    let transientFailures = 0
+    let failingSince = null
 
     while (true) {
       // Check abort signal
@@ -187,6 +243,12 @@ export class ConsumerManager {
         // it would only sit on until the lease expires.
         const result = await this.#httpClient.get(`${path}?${baseParams}`, clientTimeout, affinityKey, wait ? 'pop' : null, signal)
 
+        if (transientFailures > 0) {
+          logger.warn('ConsumerManager.worker', { workerId, status: 'pop-recovered', failedPops: transientFailures, failingMillis: Date.now() - failingSince })
+          transientFailures = 0
+          failingSince = null
+        }
+
         // Degrade-loudly (PLAN_CONFLATION §4). Checked BEFORE the empty-response
         // branch on purpose: a pre-1.1.0 broker answers an empty pop with a
         // bodiless 204 (result === null), which is the first thing a consumer
@@ -299,37 +361,35 @@ export class ConsumerManager {
           throw error
         }
 
-        // Check if this is a timeout error (expected for long polling)
-        const isTimeoutError = error.name === 'AbortError' ||
-                              error.message?.includes('timeout')
-
-        if (isTimeoutError && wait) {
-          continue // Retry on timeout
-        }
-
-        // 429 (rate limited): HttpClient already retries this internally
-        // with backoff (unbounded for wait=true pop, per retry429 policy) --
-        // this branch is a defensive fallback for the case where an explicit
-        // retry429.maxAttempts override got exhausted. Back off and keep
-        // polling instead of hot-looping or rethrowing/dying.
-        if (error.status === 429) {
-          const retryAfterMs = typeof error.retryAfterSeconds === 'number' && error.retryAfterSeconds >= 0
-            ? error.retryAfterSeconds * 1000
-            : 1000
-          logger.warn('ConsumerManager.worker', { workerId, status: 'rate-limited', code: error.code, retryAfterMs })
-          await pause(retryAfterMs, signal)
+        // This client's own timeout on a long poll: the poll already waited
+        // its whole time, so poll again at once. Checked on the error's kind,
+        // not its text: a 4xx whose message says "timeout" is a refusal.
+        if (wait && error.name === 'AbortError' && error.status === undefined) {
           continue
         }
 
-        // Check if network error
-        const isNetworkError = error.message?.includes('fetch failed') ||
-                              error.message?.includes('ECONNREFUSED') ||
-                              error.code === 'ECONNREFUSED'
-
-        if (isNetworkError) {
-          logger.warn('ConsumerManager.worker', { workerId, error: 'network', message: error.message })
-          // Wait before retry
-          await pause(1000, signal)
+        // The broker, or the way to it, could not answer for a while: a
+        // leader election, a node restarting, a gateway timing out, a lost
+        // connection, a 429 the HttpClient stopped retrying. Wait, then poll
+        // again, for as long as it takes (see isTransientPopError). Before
+        // this only a 429 and a refused connection were retried here: on
+        // 2026-10-29 the 503s of a leader election stopped every consumer of
+        // a service whose process stayed up, and nothing was consumed until
+        // it was restarted by hand.
+        if (isTransientPopError(error)) {
+          transientFailures++
+          if (failingSince === null) failingSince = Date.now()
+          const delay = transientDelayMillis(transientFailures, error.retryAfterSeconds)
+          logger.warn('ConsumerManager.worker', {
+            workerId,
+            status: 'pop-failed-retrying',
+            httpStatus: error.status,
+            code: error.code,
+            error: error.message,
+            failedPops: transientFailures,
+            retryInMillis: delay
+          })
+          await pause(delay, signal)
           continue
         }
 
@@ -343,8 +403,10 @@ export class ConsumerManager {
           throw error
         }
 
-        // Other errors - rethrow
-        logger.error('ConsumerManager.worker', { workerId, error: error.message, code: error.code })
+        // Anything else stops this worker and rejects consume(): another 4xx
+        // (refused the same way next time), a 503 raft_phase1_unsupported, or
+        // an error that is not a transport fault.
+        logger.error('ConsumerManager.worker', { workerId, error: error.message, httpStatus: error.status, code: error.code })
         throw error
       }
     }

package/client-v2/http/HttpClient.js

@@ -468,11 +468,14 @@ export class HttpClient {
         // 'storage_quota_exceeded' | 'feature_gated' | 'forbidden' }. `.code`
         // is attached whenever the body has one so callers can branch without
         // string-matching `.message`.
-        if (response.status === 429) {
-          const retryAfterHeader = response.headers.get('retry-after')
-          const retryAfterSeconds = retryAfterHeader != null ? Number(retryAfterHeader) : NaN
-          error.retryAfterSeconds = Number.isFinite(retryAfterSeconds) ? retryAfterSeconds : null
-        }
+        //
+        // Retry-After is read on every error, not only a 429: the broker also
+        // sends it (1 s) with each 503 it means to be retried (no leader, a
+        // leader change, an elapsed deadline), and consume() waits that long
+        // before its next pop. null when absent or not a number of seconds.
+        const retryAfterHeader = response.headers.get('retry-after')
+        const retryAfterSeconds = retryAfterHeader != null ? Number(retryAfterHeader) : NaN
+        error.retryAfterSeconds = Number.isFinite(retryAfterSeconds) ? retryAfterSeconds : null
 
         try {
           const text = await response.text()

package/client-v2/reads/offsetReads.js

@@ -0,0 +1,252 @@
+/**
+ * Reads by offset and partition discovery, as two queue methods:
+ *
+ *   const read = await queen.queue('orders').fetch(['customer-42', 'customer-7'])
+ *   read.get('customer-42').records   // [{ offset, transactionId, payload, ts }, ...]
+ *
+ *   const { partitions, safeTime } = await queen.queue('orders').changedSince(since)
+ *
+ * `fetch` is `POST /api/v1/fetch` and `changedSince` is
+ * `POST /api/v1/partitions/changed`. Neither takes a lease, moves a cursor or
+ * needs an ack: two readers asking the same question get the same answer, and
+ * no consumer group notices them. Each is served from the answering node's own
+ * applied state.
+ *
+ * Both do the loops a caller of the raw routes has to write:
+ *
+ * - fetch asks for at most 1000 partitions per call, and asks again from one
+ *   past the last record until each partition reaches the high watermark its
+ *   first answer reported. A partition whose start was deleted by retention is
+ *   read from its oldest kept record (an offset below `logStartOffset` answers
+ *   OFFSET_OUT_OF_RANGE and no records, so a loop that does not restart there
+ *   silently reads nothing).
+ * - changedSince follows the page cursor (`next`) until the broker says the
+ *   pass is over, and answers the smallest `safeTime` of its pages.
+ */
+
+// The broker refuses more than 1024 entries in one call; 1000 leaves room.
+const ENTRIES_PER_CALL = 1000
+
+// Bytes of payload one call may carry: each entry's budget and the ceiling of
+// the whole call. 8 MiB is the most the broker reads for one entry.
+const DEFAULT_MAX_BYTES = 8 * 1024 * 1024
+
+// Partitions per discovery page: the broker's default and its ceiling.
+const CHANGED_PAGE = 1000
+
+const OFFSET_OUT_OF_RANGE = 'OFFSET_OUT_OF_RANGE'
+const UNKNOWN_TOPIC_OR_PARTITION = 'UNKNOWN_TOPIC_OR_PARTITION'
+
+// Every call of one read goes to the same node: a follower answers from what it
+// has applied, so two nodes can disagree about where a partition ends.
+const readAffinity = (queue) => `${queue}:*:__READ__`
+
+function partitionNames(partitions) {
+  const list = typeof partitions === 'string' ? [partitions] : partitions
+  if (!Array.isArray(list)) {
+    throw new Error('fetch: partitions must be a partition name or an array of names')
+  }
+  const names = []
+  const seen = new Set()
+  for (const p of list) {
+    const name = typeof p === 'number' && Number.isInteger(p) ? String(p) : p
+    if (typeof name !== 'string' || name.length === 0) {
+      throw new Error(`fetch: a partition name must be a non-empty string, got ${JSON.stringify(p)}`)
+    }
+    if (!seen.has(name)) {
+      seen.add(name)
+      names.push(name)
+    }
+  }
+  return names
+}
+
+function startOffsets(offsets) {
+  if (offsets == null) return new Map()
+  const entries = offsets instanceof Map ? [...offsets.entries()] : Object.entries(offsets)
+  const out = new Map()
+  for (const [name, offset] of entries) {
+    if (!Number.isSafeInteger(offset) || offset < 0) {
+      throw new Error(`fetch: offsets['${name}'] must be a non-negative integer, got ${JSON.stringify(offset)}`)
+    }
+    out.set(String(name), offset)
+  }
+  return out
+}
+
+function positiveInteger(value, what) {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error(`${what} must be a positive integer, got ${JSON.stringify(value)}`)
+  }
+  return value
+}
+
+/**
+ * Every record of `partitions`, read by offset: from each partition's offset in
+ * `options.offsets` (default 0, the oldest record still kept) up to where the
+ * partition ended when it was first read.
+ *
+ * Answers a Map, in the order the partitions were named, of
+ * `{ partition, records, highWatermark, logStartOffset, nextOffset }`:
+ * - `records`: `{ offset, transactionId, payload, ts }` in offset order. `ts` is
+ *   the time the push that wrote the record was stored.
+ * - `highWatermark`: the next offset the partition will assign;
+ *   `logStartOffset`: the oldest one retention kept.
+ * - `nextOffset`: where to start next time to read only what is new.
+ *
+ * A partition nobody has written, or of a queue that does not exist, answers no
+ * records. So does an offset past the end of the partition (`nextOffset` above
+ * `highWatermark` says so: the partition was deleted and written again).
+ */
+export async function fetchPartitions(httpClient, queue, partitions, options = {}) {
+  if (!queue) throw new Error('Queue name is required for fetch')
+  const names = partitionNames(partitions)
+  const offsets = startOffsets(options.offsets)
+  const maxBytes = positiveInteger(options.maxBytes ?? DEFAULT_MAX_BYTES, 'fetch: maxBytes')
+
+  const state = new Map()
+  for (const name of names) {
+    state.set(name, {
+      partition: name,
+      records: [],
+      highWatermark: 0,
+      logStartOffset: 0,
+      nextOffset: offsets.get(name) ?? 0,
+      // The high watermark of the first answer: the read ends there.
+      end: null
+    })
+  }
+
+  let pending = names
+  while (pending.length > 0) {
+    const again = []
+    for (let i = 0; i < pending.length; i += ENTRIES_PER_CALL) {
+      const chunk = pending.slice(i, i + ENTRIES_PER_CALL)
+      const body = {
+        entries: chunk.map(name => ({
+          queue,
+          partition: name,
+          offset: state.get(name).nextOffset,
+          maxBytes
+        })),
+        maxBytes
+      }
+      const answer = await httpClient.post('/api/v1/fetch', body, null, readAffinity(queue))
+      const entries = answer?.entries
+      if (!Array.isArray(entries) || entries.length !== chunk.length) {
+        throw new Error(`fetch ${queue}: the broker answered ${Array.isArray(entries) ? entries.length : 'no'} entries for ${chunk.length} asked`)
+      }
+
+      let delivered = 0
+      // Entries that came back empty while short of their end: the call's byte
+      // ceiling was spent by the entries before them.
+      const starved = []
+      chunk.forEach((name, j) => {
+        const entry = entries[j]
+        const s = state.get(name)
+        s.highWatermark = entry.highWatermark ?? s.highWatermark
+        s.logStartOffset = entry.logStartOffset ?? s.logStartOffset
+        if (entry.error) {
+          if (entry.error === OFFSET_OUT_OF_RANGE && s.nextOffset < s.logStartOffset) {
+            // Retention deleted what was asked for: go on from the oldest kept.
+            s.nextOffset = s.logStartOffset
+            if (s.end === null) s.end = s.highWatermark
+            if (s.nextOffset < s.end) again.push(name)
+            return
+          }
+          if (entry.error === OFFSET_OUT_OF_RANGE || entry.error === UNKNOWN_TOPIC_OR_PARTITION) {
+            return
+          }
+          throw new Error(`fetch ${queue}/${name}: the broker answered ${entry.error}`)
+        }
+        if (s.end === null) s.end = s.highWatermark
+        const records = Array.isArray(entry.records) ? entry.records : []
+        if (records.length > 0) {
+          delivered += records.length
+          for (const r of records) {
+            s.records.push({ offset: r.offset, transactionId: r.transactionId, payload: r.payload, ts: r.ts })
+          }
+          s.nextOffset = records[records.length - 1].offset + 1
+          if (s.nextOffset < s.end) again.push(name)
+        } else if (s.nextOffset < s.end) {
+          starved.push(name)
+        }
+      })
+      // An empty entry is asked again only when its call read something: a
+      // call that read nothing at all would answer the same next time.
+      if (delivered > 0) again.push(...starved)
+    }
+    pending = again
+  }
+
+  const out = new Map()
+  for (const name of names) {
+    const { partition, records, highWatermark, logStartOffset, nextOffset } = state.get(name)
+    out.set(name, { partition, records, highWatermark, logStartOffset, nextOffset })
+  }
+  return out
+}
+
+function sinceIso(since) {
+  if (since == null) return null
+  if (since instanceof Date) {
+    if (Number.isNaN(since.getTime())) throw new Error('changedSince: since is an invalid Date')
+    return since.toISOString()
+  }
+  if (typeof since === 'number') {
+    const d = new Date(since)
+    if (Number.isNaN(d.getTime())) throw new Error(`changedSince: since ${since} is not a time`)
+    return d.toISOString()
+  }
+  if (typeof since === 'string' && since.length > 0) return since
+  throw new Error(`changedSince: since must be a Date, epoch milliseconds or an ISO-8601 string, got ${JSON.stringify(since)}`)
+}
+
+/**
+ * The partitions of the queue written at or after `since`, in the order they
+ * were created: `{ partitions, safeTime }`. Each partition is
+ * `{ name, id, lastOffset, logStart, lastWriteAt }`; `lastOffset` is the offset
+ * of its last record (-1 when none).
+ *
+ * `since` is a Date, epoch milliseconds or an ISO-8601 string; null or absent
+ * lists every partition of the queue. A queue that does not exist has none.
+ *
+ * `safeTime` is the broker's time up to which every write is counted in this
+ * answer: pass it as the next `since` to see only what changed after this
+ * call. It comes from the broker's clock, never compare it with the local one.
+ */
+export async function partitionsChangedSince(httpClient, queue, since) {
+  if (!queue) throw new Error('Queue name is required for changedSince')
+  const from = sinceIso(since)
+  const partitions = []
+  let safeTime = null
+  let after = null
+  for (;;) {
+    const entry = { queue, limit: CHANGED_PAGE }
+    if (from !== null) entry.since = from
+    if (after !== null) entry.after = after
+    const answer = await httpClient.post('/api/v1/partitions/changed', { entries: [entry] }, null, readAffinity(queue))
+    // Pages served by different nodes: the smallest is the one that holds for
+    // all of them. The broker spells every one the same way, so the strings
+    // compare in time order.
+    if (typeof answer?.safeTime === 'string' && (safeTime === null || answer.safeTime < safeTime)) {
+      safeTime = answer.safeTime
+    }
+    const result = answer?.entries?.[0]
+    if (!result) throw new Error(`changedSince ${queue}: the broker answered no entry`)
+    if (result.error === UNKNOWN_TOPIC_OR_PARTITION) break
+    if (result.error) throw new Error(`changedSince ${queue}: the broker answered ${result.error}`)
+    for (const p of result.partitions || []) {
+      partitions.push({
+        name: p.name,
+        id: p.id ?? null,
+        lastOffset: p.lastOffset,
+        logStart: p.logStart,
+        lastWriteAt: p.lastWriteAt
+      })
+    }
+    if (!result.next) break
+    after = result.next
+  }
+  return { partitions, safeTime }
+}

package/client-v2/streams/operators/ReduceOperator.js

@@ -38,9 +38,16 @@ export class ReduceOperator {
    * }} ctx
    * @returns {Promise<{
    *   stateOps: Array<{type:'upsert'|'delete',key:string,value?:any}>,
-   *   emits: Array<{key:string, windowStart:number, windowKey:string, value:any}>
+   *   emits: Array<{key:string, windowStart:number, windowKey:string, value:any}>,
+   *   nextCloseMs: number|null
    * }>}
    *
+   * `nextCloseMs` is when the earliest window still open closes
+   * (`windowEnd + gracePeriodMs`, on the clock the windows are kept in),
+   * counting the stored windows this batch did not touch; null when nothing
+   * stays open. The Runner claims the partition then to close it, even if
+   * no more messages come.
+   *
    * Window-close semantics
    * ----------------------
    * A window is closed when the partition's stream time has advanced past
@@ -121,8 +128,13 @@ export class ReduceOperator {
 
     const stateOps = []
     const emits = []
+    let nextCloseMs = null
     for (const [stateKey, entry] of accumulators.entries()) {
-      const closed = (entry.windowEnd + gracePeriodMs) <= effectiveStreamTime
+      const closesAt = entry.windowEnd + gracePeriodMs
+      const closed = closesAt <= effectiveStreamTime
+      if (!closed && (nextCloseMs === null || closesAt < nextCloseMs)) {
+        nextCloseMs = closesAt
+      }
       if (closed) {
         emits.push({
           key: entry.key,
@@ -142,7 +154,7 @@ export class ReduceOperator {
         })
       }
     }
-    return { stateOps, emits }
+    return { stateOps, emits, nextCloseMs }
   }
 
   _initial() {