queen-mq 0.16.0 → 1.0.3

package/client-v2/kv/Kv.js

@@ -0,0 +1,432 @@
+/**
+ * The KV surface (PLAN_KV_TIMERS.md §5, §8.1).
+ *
+ * Seven operations, five code paths: get, getMany, getPrefix, put,
+ * putIfAbsent (an alias that desugars to put with expect:0 inside the stored
+ * procedure), delete, incr. Plus two conveniences this client owns: `once`,
+ * which is the idempotency marker written the way people actually reach for
+ * it, and `listAll`, which walks the keyset cursor of getPrefix.
+ *
+ * EVERYTHING GOES THROUGH `POST /api/v1/kv`, INCLUDING THE SINGLE-KEY READS.
+ * The path routes (`GET|PUT|DELETE /api/v1/kv/:ns/*key`) exist and are correct,
+ * but they are sugar "for the three cases people write by hand" (§8.1). An SDK
+ * is not one of them, and the batch route buys three things a path route
+ * cannot: it is the ONLY surface that accepts `incr` and `getPrefix`, so one
+ * transport serves all seven ops; it never has to percent-encode a key into a
+ * URL; and it keeps keys out of access logs, proxy samples and tracing spans,
+ * which is the same reasoning §5.5 applies to prefixes and which does not stop
+ * being true for a key.
+ *
+ * THE STATUS-CODE RULE YOU WILL NOTICE FIRST (§8.1): the HTTP status describes
+ * the outcome of the CALL, never the verdict of the predicate. An absent key, a
+ * lost putIfAbsent race, a delete that hit nothing -- all 200, with an explicit
+ * field in the body. `applied:false` is the single most frequent outcome of
+ * this product and it is not an error.
+ *
+ * WHICH LEADS TO THE ONE TRAP THIS LANGUAGE CANNOT DEFEND AGAINST
+ * STRUCTURALLY (§10.4): **every write returns an OBJECT, and objects are
+ * always truthy**.
+ *
+ *     if (await kv.delete(ns, key)) { ... }        // ALWAYS TAKEN. A bug.
+ *     const r = await kv.delete(ns, key)
+ *     if (r.applied) { ... }                       // the field is the answer
+ *
+ * That holds for all five writes -- put, putIfAbsent, delete, incr, once (whose
+ * field is `won`).
+ *
+ * AND THE ONE ABOUT EXPIRY (§5.7): a key that has expired is never returned and
+ * never counts as existing, even before the sweeper has pruned it. A `put`
+ * does NOT inherit the previous TTL -- that is not expressible, because a put
+ * that silently inherited an expiry is the fastest way to make a marker
+ * immortal.
+ */
+
+import * as logger from '../utils/logger.js'
+import { resolveExpiry } from './expiry.js'
+
+// ---------------------------------------------------------------------------
+// Op builders. Shared with TransactionBuilder, which puts the very same
+// objects in the `kv` array of a bundle -- one definition of the wire shape,
+// so the standalone route and the transaction rider can never drift.
+//
+// An entry is `{ base, expiry }`: `base` is the finished op minus its expiry,
+// `expiry` is the caller's sugar, unresolved. `materializeKvOp` resolves it,
+// and it is called at SEND time -- immediately here, at commit() there --
+// because `until` is an instant and freezing it when the op was queued would
+// ship a TTL that is already stale.
+// ---------------------------------------------------------------------------
+
+function requireName(value, what) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`kv: ${what} must be a non-empty string, got ${JSON.stringify(value)}`)
+  }
+  return value
+}
+
+/**
+ * §5.3: an explicitly undefined or null `expect` is a CLIENT-SIDE BUG, never a
+ * silent downgrade to upsert. The caller wrote the word `expect`, so they
+ * declared the intention to fence; sending the op without it would perform the
+ * unconditional write the fence existed to prevent.
+ */
+function withExpect(base, opts) {
+  if ('expect' in opts) {
+    if (opts.expect === undefined || opts.expect === null) {
+      throw new Error(
+        'kv: `expect` was written but has no value. An absent expect is not an upsert — it is a bug in the ' +
+        'caller: drop the field to mean "unconditional", or pass 0 to mean "must not exist".'
+      )
+    }
+    base.expect = opts.expect
+  }
+  return base
+}
+
+function withRequired(base, opts) {
+  if (opts.required === true) base.required = true
+  return base
+}
+
+export const kvOp = {
+  get(ns, key) {
+    return { base: { op: 'get', ns: requireName(ns, 'ns'), key: requireName(key, 'key') }, expiry: null }
+  },
+
+  getMany(ns, keys) {
+    requireName(ns, 'ns')
+    if (!Array.isArray(keys) || keys.length === 0) {
+      throw new Error('kv: getMany needs a non-empty array of keys')
+    }
+    keys.forEach(k => requireName(k, 'key'))
+    return { base: { op: 'getMany', ns, keys: [...keys] }, expiry: null }
+  },
+
+  getPrefix(ns, prefix, opts = {}) {
+    requireName(ns, 'ns')
+    // A namespace is not a table to enumerate: the empty prefix is the declared
+    // boundary, not an oversight (§5.5).
+    requireName(prefix, 'prefix')
+    const base = { op: 'getPrefix', ns, prefix }
+    if (opts.limit !== undefined) base.limit = opts.limit
+    if (opts.after !== undefined && opts.after !== null) base.after = opts.after
+    if (opts.keysOnly === true) base.keysOnly = true
+    return { base, expiry: null }
+  },
+
+  put(ns, key, value, opts = {}) {
+    requireName(ns, 'ns')
+    requireName(key, 'key')
+    const base = { op: 'put', ns, key, value }
+    return { base: withRequired(withExpect(base, opts), opts), expiry: opts }
+  },
+
+  putIfAbsent(ns, key, value, opts = {}) {
+    requireName(ns, 'ns')
+    requireName(key, 'key')
+    if ('expect' in opts) {
+      throw new Error('kv: putIfAbsent IS expect:0 — passing a different expect is a contradiction the broker rejects')
+    }
+    const base = { op: 'putIfAbsent', ns, key, value }
+    return { base: withRequired(base, opts), expiry: opts }
+  },
+
+  delete(ns, key, opts = {}) {
+    requireName(ns, 'ns')
+    requireName(key, 'key')
+    const base = { op: 'delete', ns, key }
+    return { base: withRequired(withExpect(base, opts), opts), expiry: null }
+  },
+
+  incr(ns, key, delta = 1, opts = {}) {
+    requireName(ns, 'ns')
+    requireName(key, 'key')
+    if ('expect' in opts) {
+      // §5.4: incr is the way OUT of CAS. A precondition on it would
+      // reintroduce the very loop it exists to remove.
+      throw new Error('kv: incr takes no expect — it is the escape from the CAS loop, not another CAS')
+    }
+    if (typeof delta !== 'number' || !Number.isFinite(delta)) {
+      throw new Error(`kv: incr needs a finite numeric delta, got ${JSON.stringify(delta)}`)
+    }
+    const base = { op: 'incr', ns, key, delta }
+    if (opts.min !== undefined) base.min = opts.min
+    if (opts.max !== undefined) base.max = opts.max
+    return { base: withRequired(base, opts), expiry: opts }
+  }
+}
+
+/** Finish one op: merge the resolved expiry into the base. */
+export function materializeKvOp(entry, nowMs = Date.now()) {
+  if (!entry.expiry) return { ...entry.base }
+  return { ...entry.base, ...resolveExpiry(entry.expiry, nowMs) }
+}
+
+// ---------------------------------------------------------------------------
+// Response handling.
+// ---------------------------------------------------------------------------
+
+/**
+ * The KV routes put the CODE in `error` (§9.5's closed taxonomy) and have no
+ * separate `code` field, while the proxy's own refusals do. HttpClient maps
+ * `body.error` onto `.message`, so on these routes the message IS the code.
+ * Copying it into `.code` -- without ever overwriting a proxy-set one -- is
+ * what lets callers branch on `err.code` here exactly as they do on a proxy
+ * 403, and never on prose, which is forbidden everywhere in this codebase.
+ */
+function decorate(error) {
+  if (error && !error.code && typeof error.message === 'string') {
+    error.code = error.message
+  }
+  return error
+}
+
+/** A lost `required` gate arrives as HTTP 200 with this envelope (§8.3). */
+function isPrecondition(body) {
+  return body && typeof body === 'object' && body.ok === false && body.reason === 'kv_precondition'
+}
+
+/**
+ * Render a precondition verdict as a WriteResult, so that `applied` remains
+ * THE field to read whichever way the verdict arrived. `precondition:true`
+ * says the transaction was rolled back rather than merely refused, and
+ * `kvReason` is preserved under the name `reason` the other path uses.
+ */
+function preconditionResult(body, op, key) {
+  return {
+    op,
+    key,
+    applied: false,
+    precondition: true,
+    reason: body.kvReason ?? null,
+    value: body.value,
+    version: body.version,
+    failedIndex: body.failedIndex
+  }
+}
+
+/**
+ * §5.4: past 2^53 `JSON.parse` loses precision SILENTLY, and `incr` runs on
+ * `numeric` server-side while `version` is a BIGINT. A rate limiter reading a
+ * counter that is quietly wrong is worse than one that fails, so this raises.
+ */
+function assertSafeNumber(value, what) {
+  if (typeof value === 'number' && Math.abs(value) > Number.MAX_SAFE_INTEGER) {
+    throw new Error(
+      `kv: ${what} is ${value}, beyond 2^53 — JSON.parse has already lost precision on it. ` +
+      'Refusing to hand back a number that is silently wrong.'
+    )
+  }
+  return value
+}
+
+export class Kv {
+  #httpClient
+
+  constructor(httpClient) {
+    this.#httpClient = httpClient
+  }
+
+  /**
+   * The one path to the broker. Returns either `{ results }` (index-aligned to
+   * the ops, §6.4) or `{ precondition }` for the 200-with-`ok:false` verdict.
+   */
+  async #apply(entries) {
+    const now = Date.now()
+    const operations = entries.map(e => materializeKvOp(e, now))
+    logger.log('Kv.apply', { count: operations.length, ops: operations.map(o => o.op) })
+
+    let body
+    try {
+      body = await this.#httpClient.post('/api/v1/kv', { operations })
+    } catch (error) {
+      logger.error('Kv.apply', { error: error.message, status: error.status, code: error.code })
+      throw decorate(error)
+    }
+
+    if (isPrecondition(body)) return { precondition: body }
+
+    const results = body && Array.isArray(body.results) ? body.results : null
+    if (!results) {
+      throw new Error('kv: unexpected response envelope — expected {"results":[...]}')
+    }
+    // The stored procedure guarantees one result per op and raises rather than
+    // returning a short array (§6.4). A short one here means something between
+    // the two rewrote the answer, and attributing result i to op j is how a
+    // caller ends up trusting the wrong verdict.
+    if (results.length !== operations.length) {
+      throw new Error(`kv: got ${results.length} results for ${operations.length} operations`)
+    }
+    return { results }
+  }
+
+  async #one(entry) {
+    const { results, precondition } = await this.#apply([entry])
+    if (precondition) return { precondition }
+    return { result: results[0] }
+  }
+
+  /** A read result, unwrapped. Reads have no precondition to lose. */
+  async #read(entry) {
+    const { result, precondition } = await this.#one(entry)
+    if (precondition) {
+      // Unreachable by construction (`required` is a write-only escalation),
+      // and therefore exactly the kind of thing that must not silently return
+      // `undefined` if the broker's envelope ever changes shape.
+      throw new Error(`kv: ${entry.base.op} came back as a precondition verdict, which a read cannot lose`)
+    }
+    return result
+  }
+
+  /** A write result, with the precondition envelope folded into the same shape. */
+  async #write(entry) {
+    const { result, precondition } = await this.#one(entry)
+    if (precondition) return preconditionResult(precondition, entry.base.op, entry.base.key)
+    if (typeof result.applied !== 'boolean') {
+      throw new Error(`kv: ${entry.base.op} result carries no \`applied\` field; refusing to guess the verdict`)
+    }
+    return result
+  }
+
+  // -------------------------------------------------------------- reads
+
+  /**
+   * One key. Returns the ROW, not the value:
+   * `{found, key, value?, version?, expiresAt?, updatedAt?}`.
+   *
+   * `found` is separate from `value` because `null` is a legal JSONB value
+   * (§5.5): `{found:true, value:null}` and `{found:false}` are different
+   * things, and an SDK that returned "the value or null" would collapse them.
+   */
+  async get(ns, key) {
+    return this.#read(kvOp.get(ns, key))
+  }
+
+  /**
+   * Many keys of one namespace. Returns `{rows, missing, truncated}`.
+   *
+   * `missing` is EXPLICIT: absence is a datum, not a hole the caller computes
+   * by difference. `truncated` means the byte budget cut the page -- those
+   * keys are in neither list, because calling them absent would be a lie.
+   */
+  async getMany(ns, keys) {
+    return this.#read(kvOp.getMany(ns, keys))
+  }
+
+  /**
+   * One page of a prefix scan: `{rows, truncated, nextAfter}`.
+   *
+   * `limit` is CLAMPED by the broker (default 100, ceiling 1000) and never
+   * rejected, plus a byte ceiling on the aggregate, with `truncated` telling
+   * the truth about both. `after` is an exclusive keyset cursor, not an
+   * offset.
+   *
+   * EACH PAGE IS ITS OWN SNAPSHOT. It is not an instant of the namespace: with
+   * `after` it can miss a key inserted behind the cursor. Good for compacting
+   * state, not for an exact count.
+   */
+  async getPrefix(ns, prefix, opts = {}) {
+    return this.#read(kvOp.getPrefix(ns, prefix, opts))
+  }
+
+  /**
+   * Every row under a prefix, one page at a time.
+   *
+   * An ASYNC GENERATOR, not an array: the page count is not knowable in
+   * advance, and a method that quietly buffered a namespace into memory would
+   * be the one thing this API is careful not to offer.
+   *
+   *     for await (const row of kv.listAll(ns, 'quota:acme:')) { ... }
+   *
+   * It inherits getPrefix's snapshot caveat, one page at a time.
+   */
+  async *listAll(ns, prefix, opts = {}) {
+    let after = opts.after
+    for (;;) {
+      const page = await this.getPrefix(ns, prefix, { ...opts, after })
+      for (const row of page.rows || []) yield row
+      if (!page.truncated) return
+      if (!page.nextAfter) return
+      after = page.nextAfter
+    }
+  }
+
+  // ------------------------------------------------------------- writes
+
+  /**
+   * Write a value. Exactly one of `ttlSeconds` (or its sugar `ttl` / `until`)
+   * and `forever:true` is required -- the broker owns that rule so all seven
+   * clients inherit it.
+   *
+   * `expect` is the optimistic lock: `0` means "must not exist" (and wins even
+   * against an expired row not yet pruned), `N > 0` is a pure UPDATE that
+   * creates NOTHING when it matches no row. The version handed to a loser is
+   * ADVISORY -- never reuse it blindly as a fencing token.
+   *
+   * `required:true` escalates a lost precondition into a rolled-back
+   * transaction; on this route that comes back as a WriteResult with
+   * `precondition:true`, and inside a bundle it is what makes `commit()`
+   * return the verdict.
+   *
+   * Returns a WriteResult: `{applied, op, key, value, version, reason?}`.
+   * ALWAYS TRUTHY -- read `applied`.
+   */
+  async put(ns, key, value, opts = {}) {
+    return this.#write(kvOp.put(ns, key, value, opts))
+  }
+
+  /** put with `expect:0`, under the name of the thing. Same WriteResult, and the loser gets the winner's value. */
+  async putIfAbsent(ns, key, value, opts = {}) {
+    return this.#write(kvOp.putIfAbsent(ns, key, value, opts))
+  }
+
+  /**
+   * Delete a key, optionally fenced with `expect`.
+   *
+   * Returns a WriteResult. `if (await kv.delete(...))` is ALWAYS TRUE and is a
+   * bug: read `.applied`.
+   */
+  async delete(ns, key, opts = {}) {
+    return this.#write(kvOp.delete(ns, key, opts))
+  }
+
+  /**
+   * Add `delta` to a numeric key, atomically and without a CAS loop.
+   *
+   * With `max`, **`applied` IS the admission decision**: an increment that
+   * would break the ceiling does not apply, does not saturate and does not
+   * truncate -- it comes back `applied:false, reason:'limit'` with the CURRENT
+   * value. Comparing client-side after incrementing means the request that
+   * broke the ceiling has already consumed budget.
+   *
+   * The TTL is CREATE-ONLY: a live row keeps its expiry, so a fixed-window
+   * limiter actually closes its window. An expired row counts as zero and
+   * starts a new window, which is what makes the limiter one call.
+   */
+  async incr(ns, key, delta = 1, opts = {}) {
+    const res = await this.#write(kvOp.incr(ns, key, delta, opts))
+    assertSafeNumber(res.value, `the counter at ${key}`)
+    return res
+  }
+
+  /**
+   * The idempotency marker, written the way it is actually used:
+   *
+   *     const { won } = await kv.once('test-idem', orderId, { ttl: '24h' })
+   *     if (!won) return                       // somebody already did this
+   *
+   * `putIfAbsent` with a default value of `true`. Returns `{won, value,
+   * version, result}` -- `value` being the WINNER's value, so the loser never
+   * needs a second round trip.
+   *
+   * And the sentence that has to travel with it: **putIfAbsent plus a TTL is
+   * not a distributed lock** (§5.7). A lock that expires is not revoked; the
+   * old holder keeps working, it simply no longer has the row. The defence is
+   * fencing -- carry the `version` as `expect` on every later write -- and
+   * that limits the damage rather than removing it.
+   */
+  async once(ns, key, opts = {}) {
+    const value = opts.value !== undefined ? opts.value : true
+    const res = await this.putIfAbsent(ns, key, value, opts)
+    return { won: res.applied === true, value: res.value, version: res.version, result: res }
+  }
+}

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/client-v2/streams/runtime/Runner.js

@@ -78,6 +78,17 @@ export class Runner {
     this._loopPromise          = null
     this._flushTimers          = []          // setInterval handles
     this._flushInFlight        = false
+    // Per-partition mutex between the pop/cycle loop and the idle-flush
+    // timer. Both paths are read(state) -> compute -> commit against the
+    // same (query_id, partition_id) state rows; the server's advisory
+    // lock only serialises the COMMITS, so an unsynchronised flush can
+    // read a window's acc, have the cycle emit+delete (or re-upsert) it,
+    // and then emit the same acc again — a duplicate emit (or, with the
+    // opposite interleave, drop a freshly-reduced value). Node is
+    // single-threaded but both paths interleave at await points, which is
+    // exactly where the read->compute->commit race bites. Serialising the
+    // two in-process paths removes the race at its source.
+    this._partitionMutexes     = new Map()   // partitionId -> tail promise
     this._recentPartitions     = new Map()   // partitionId -> { partitionName, touchedAt }
     this._partitionWatermarks  = new Map()   // partitionId -> wmMs (cache; PG is source of truth)
     this._stats = {
@@ -253,9 +264,38 @@ export class Runner {
     }
   }
 
+  // ------------------------------------------------- per-partition mutex
+
+  /**
+   * Run `fn` with the per-partition mutex held (see _partitionMutexes in
+   * the constructor). Implemented as a promise chain per partitionId: each
+   * entrant waits on the previous tail, so the cycle path and the
+   * idle-flush path can never interleave their read->compute->commit
+   * sections for the same partition. The returned promise settles like
+   * `fn()` (errors propagate to the caller); the stored tail never
+   * rejects, so a failed cycle doesn't poison the chain.
+   */
+  _withPartitionLock(partitionId, fn) {
+    const key = partitionId || 'unknown'
+    const tail = this._partitionMutexes.get(key) || Promise.resolve()
+    const run = tail.then(fn)
+    const next = run.then(() => {}, () => {})
+    this._partitionMutexes.set(key, next)
+    next.then(() => {
+      // GC: drop the entry once the chain drains.
+      if (this._partitionMutexes.get(key) === next) this._partitionMutexes.delete(key)
+    })
+    return run
+  }
+
   // ----------------------------------------------------------- cycle
 
   async _processPartitionCycle(group) {
+    // Mutual exclusion with the idle-flush timer (see _partitionMutexes).
+    return this._withPartitionLock(group.partitionId, () => this._processPartitionCycleInner(group))
+  }
+
+  async _processPartitionCycleInner(group) {
     const stages = this.stream.stages
     const partitionId = group.partitionId
     const partitionName = group.partitionName
@@ -787,6 +827,11 @@ export class Runner {
   }
 
   async _flushPartition(partitionId, partitionName) {
+    // Mutual exclusion with the pop/cycle loop (see _partitionMutexes).
+    return this._withPartitionLock(partitionId, () => this._flushPartitionInner(partitionId, partitionName))
+  }
+
+  async _flushPartitionInner(partitionId, partitionName) {
     const stages = this.stream.stages
     const window = stages.window
 

package/client-v2/utils/defaults.js

@@ -16,8 +16,27 @@ export const CLIENT_DEFAULTS = {
   healthRetryAfterMillis: 5000,        // Retry unhealthy backends after 5 seconds
   bearerToken: null,                   // Bearer token for proxy authentication
   headers: {},                         // Custom headers to include in every request
+  // Host to advertise on every request, independent of the address dialed.
+  // A queen_proxy deployment picks the tenant cluster from the Host header's
+  // first DNS label, so this selects a cluster when `url` points at a shared
+  // address (an IP, a cell endpoint, a local rig) instead of the cluster's own
+  // subdomain. Bare authority only: 'acme.eu1.queenmq.cloud' or 'acme:6711'.
+  // The connection still goes to `url`; only the request authority (and TLS
+  // SNI) is rewritten. In production each cluster has its own hostname, so the
+  // base URL usually carries the right Host and this stays null.
+  // NOTE: `headers: { Host }` cannot work (fetch forbids it) — it is mapped
+  // onto this option with a warning.
+  hostHeader: null,
   handleSignals: true,                 // Register SIGINT/SIGTERM handlers (disable when used as a library)
-  logger: null                         // Custom logger instance (must implement info/warn/error)
+  logger: null,                        // Custom logger instance (must implement info/warn/error)
+  // Backoff policy for HTTP 429 (rate limited) responses from a queen_proxy
+  // deployment. Optional -- omit for the defaults below. Shape:
+  //   { maxAttempts?: number, baseMs?: number, capMs?: number }
+  // maxAttempts defaults to 10 for push/admin calls; long-poll pop (wait=true)
+  // retries unboundedly (paced by backoff) unless maxAttempts is set here, in
+  // which case it applies to both. baseMs (500) / capMs (30000) size the
+  // exponential backoff used when the server doesn't send Retry-After.
+  retry429: undefined
 }
 
 export const QUEUE_DEFAULTS = {