@babelqueue/redis 1.1.0 → 1.3.0

package/dist/index.js

@@ -1,4 +1,5 @@
 // src/index.ts
+import { randomBytes } from "crypto";
 import { annotate, BabelQueueError, EnvelopeCodec, UnknownUrnError, UnknownUrnStrategy } from "@babelqueue/core";
 
 // src/headers.ts
@@ -13,6 +14,109 @@ function sanitizeHeaders(headers) {
   return out;
 }
 
+// src/poison-record.ts
+var JSON_SPACE = /^[ \t\r\n]+|[ \t\r\n]+$/g;
+function strictUtf8(bytes) {
+  try {
+    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+}
+function assertJsonObject(deadLetter) {
+  let parsed;
+  try {
+    parsed = JSON.parse(deadLetter);
+  } catch {
+    throw new TypeError("deadLetter must be the JSON text of a single object");
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new TypeError("deadLetter must be the JSON text of a single object");
+  }
+}
+function buildPoisonRecord(body, deadLetter) {
+  assertJsonObject(deadLetter);
+  const text = strictUtf8(body);
+  if (text !== null && isSpliceableObject(text)) {
+    const trimmed = text.replace(JSON_SPACE, "");
+    const inner = trimmed.slice(1, -1).replace(JSON_SPACE, "");
+    return inner === "" ? `{"dead_letter":${deadLetter}}` : `${trimmed.slice(0, -1)},"dead_letter":${deadLetter}}`;
+  }
+  const raw = text !== null ? `"raw":${JSON.stringify(text)}` : `"raw":${JSON.stringify(Buffer.from(body).toString("base64"))},"raw_encoding":"base64"`;
+  return `{${raw},"dead_letter":${deadLetter}}`;
+}
+function isSpliceableObject(text) {
+  try {
+    JSON.parse(text);
+  } catch {
+    return false;
+  }
+  let i = 0;
+  while (i < text.length && isJsonSpace(text.charCodeAt(i))) i++;
+  if (text[i] !== "{") return false;
+  let depth = 0;
+  let expectKey = false;
+  while (i < text.length) {
+    const c = text[i];
+    if (c === "{" || c === "[") {
+      depth++;
+      expectKey = c === "{" && depth === 1;
+      i++;
+    } else if (c === "}" || c === "]") {
+      depth--;
+      i++;
+    } else if (c === ",") {
+      expectKey = depth === 1;
+      i++;
+    } else if (c === '"') {
+      const end = scanJsonString(text, i);
+      if (end < 0) return false;
+      if (depth === 1 && expectKey) {
+        if (JSON.parse(text.slice(i, end)) === "dead_letter") return false;
+        expectKey = false;
+      }
+      i = end;
+    } else {
+      i++;
+    }
+  }
+  return true;
+}
+function isJsonSpace(c) {
+  return c === 32 || c === 9 || c === 13 || c === 10;
+}
+function scanJsonString(text, start) {
+  let i = start + 1;
+  while (i < text.length) {
+    const c = text[i];
+    if (c === '"') return i + 1;
+    if (c !== "\\") {
+      i++;
+      continue;
+    }
+    if (text[i + 1] !== "u") {
+      i += 2;
+      continue;
+    }
+    const cp = hex4(text, i + 2);
+    if (cp < 0) return -1;
+    i += 6;
+    if (cp >= 55296 && cp <= 56319) {
+      if (text[i] !== "\\" || text[i + 1] !== "u") return -1;
+      const lo = hex4(text, i + 2);
+      if (lo < 56320 || lo > 57343) return -1;
+      i += 6;
+    } else if (cp >= 56320 && cp <= 57343) {
+      return -1;
+    }
+  }
+  return -1;
+}
+function hex4(text, at) {
+  const digits = text.slice(at, at + 4);
+  return /^[0-9a-fA-F]{4}$/.test(digits) ? parseInt(digits, 16) : -1;
+}
+
 // src/index.ts
 function redisValue(envelope) {
   return EnvelopeCodec.encode(envelope);
@@ -44,56 +148,540 @@ function unframe(value) {
 function headersOf(value) {
   return unframe(value)[1];
 }
-var RedisPublisher = class _RedisPublisher {
-  constructor(client, queue) {
+var ZSET_KEY_PREFIX = "queues:";
+function zsetKeys(queue, prefix = ZSET_KEY_PREFIX) {
+  const ready = `${prefix}${queue}`;
+  return { ready, delayed: `${ready}:delayed`, reserved: `${ready}:reserved`, notify: `${ready}:notify` };
+}
+var LUA = {
+  /** KEYS=[q, q:processing, q:processing:deadlines] ARGV=[deadline, token]. Returns the raw body or nil. */
+  legacyReserve: `
+local raw = redis.call('LMOVE', KEYS[1], KEYS[2], 'LEFT', 'RIGHT')
+if not raw then return false end
+redis.call('ZADD', KEYS[3], ARGV[1], ARGV[2] .. ':' .. raw)
+return raw
+`,
+  /** KEYS=[q, q:processing, q:processing:deadlines] ARGV=[floor(now), batch]. Returns the count moved. */
+  legacySweep: `
+local batch = tonumber(ARGV[2])
+local members
+if batch > 0 then
+  members = redis.call('ZRANGEBYSCORE', KEYS[3], '-inf', ARGV[1], 'LIMIT', 0, batch)
+else
+  members = redis.call('ZRANGEBYSCORE', KEYS[3], '-inf', ARGV[1])
+end
+local moved = 0
+for _, m in ipairs(members) do
+  if #m >= 34 and string.sub(m, 33, 33) == ':' then
+    local raw = string.sub(m, 34)
+    if redis.call('LREM', KEYS[2], 1, raw) == 1 then
+      redis.call('RPUSH', KEYS[1], raw)
+      moved = moved + 1
+    end
+  end
+  redis.call('ZREM', KEYS[3], m)
+end
+return moved
+`,
+  /** KEYS=[q:processing, q:processing:deadlines] ARGV=[token, raw]. 1 if the reservation was live. */
+  legacyAck: `
+if redis.call('ZREM', KEYS[2], ARGV[1] .. ':' .. ARGV[2]) == 1 then
+  redis.call('LREM', KEYS[1], 1, ARGV[2])
+  return 1
+end
+return 0
+`,
+  /** KEYS=[q, q:processing, q:processing:deadlines] ARGV=[token, raw, body]. */
+  legacyRelease: `
+if redis.call('ZREM', KEYS[3], ARGV[1] .. ':' .. ARGV[2]) == 1 then
+  redis.call('LREM', KEYS[2], 1, ARGV[2])
+  redis.call('RPUSH', KEYS[1], ARGV[3])
+  return 1
+end
+return 0
+`,
+  /** KEYS=[q:processing, q:processing:deadlines, dlq] ARGV=[token, raw, body]. */
+  legacyDeadLetter: `
+if redis.call('ZREM', KEYS[2], ARGV[1] .. ':' .. ARGV[2]) == 1 then
+  redis.call('LREM', KEYS[1], 1, ARGV[2])
+  redis.call('RPUSH', KEYS[3], ARGV[3])
+  return 1
+end
+return 0
+`,
+  /**
+   * KEYS=[q, q:reserved, q:notify] ARGV=[expiry]. Returns `{job, reserved, flag}` or nil; flag `'1'`
+   * is poison (`reserved == job`), `'0'` a delivered body. Nothing after the LPOP may raise, so the
+   * re-encode is guarded too: lua-cjson decodes `1e999` / `NaN` / `Infinity` but refuses to encode
+   * them, and a bare `cjson.encode` here would lose the already-popped message (broker-bindings
+   * section 1.1, ADR-0033 A1). An unencodable body takes the poison path.
+   */
+  zsetReserve: `
+local job = redis.call('LPOP', KEYS[1])
+if not job then return false end
+local ok, decoded = pcall(cjson.decode, job)
+if ok and type(decoded) == 'table' and type(decoded['attempts']) == 'number' then
+  decoded['attempts'] = decoded['attempts'] + 1
+  local eok, reserved = pcall(cjson.encode, decoded)
+  if eok and type(reserved) == 'string' then
+    redis.call('ZADD', KEYS[2], ARGV[1], reserved)
+    redis.call('LPOP', KEYS[3])
+    return {job, reserved, '0'}
+  end
+end
+redis.call('ZADD', KEYS[2], ARGV[1], job)
+return {job, job, '1'}
+`,
+  /** KEYS=[source zset, q, q:notify] ARGV=[floor(now), batch]. Returns the count moved. */
+  zsetMigrate: `
+local batch = tonumber(ARGV[2])
+local val
+if batch > 0 then
+  val = redis.call('ZRANGEBYSCORE', KEYS[1], '-inf', ARGV[1], 'LIMIT', 0, batch)
+else
+  val = redis.call('ZRANGEBYSCORE', KEYS[1], '-inf', ARGV[1])
+end
+if #val > 0 then
+  redis.call('ZREMRANGEBYRANK', KEYS[1], 0, #val - 1)
+  for i = 1, #val, 100 do
+    redis.call('RPUSH', KEYS[2], unpack(val, i, math.min(i + 99, #val)))
+  end
+  for _ = 1, #val do
+    redis.call('RPUSH', KEYS[3], '1')
+  end
+end
+return #val
+`,
+  /** KEYS=[q, q:notify] ARGV=[body]. */
+  zsetPush: `
+redis.call('RPUSH', KEYS[1], ARGV[1])
+redis.call('RPUSH', KEYS[2], '1')
+return 1
+`,
+  /** KEYS=[q:reserved] ARGV=[member]. */
+  zsetAck: `
+return redis.call('ZREM', KEYS[1], ARGV[1])
+`,
+  /** KEYS=[q:delayed, q:reserved] ARGV=[member, score, body]. The ZADD is unconditional. */
+  zsetRelease: `
+redis.call('ZREM', KEYS[2], ARGV[1])
+redis.call('ZADD', KEYS[1], ARGV[2], ARGV[3])
+return 1
+`,
+  /**
+   * KEYS=[q:reserved, dlq] ARGV=[member, body]. Terminal-failure dead-letter, gated on the ZREM like
+   * the legacy scripts: a late dead-letter whose reservation was already recovered (back on `<q>`)
+   * writes nothing, so the body is never both ready and dead-lettered. A poison reservation uses
+   * `zsetDeadLetterPoison` instead (unconditional, as the contract requires).
+   */
+  zsetDeadLetter: `
+if redis.call('ZREM', KEYS[1], ARGV[1]) == 1 then
+  redis.call('RPUSH', KEYS[2], ARGV[2])
+  return 1
+end
+return 0
+`,
+  /**
+   * KEYS=[q:reserved, dlq] ARGV=[member, body]. The poison dead-letter (broker-bindings section 1.1):
+   * the SDK MUST write the message to the DLQ and `ZREM` it, unconditionally. Two byte-equal poison
+   * bodies reserved together share one `:reserved` member, so a `ZREM` gate would drop the second
+   * copy without ever writing it.
+   */
+  zsetDeadLetterPoison: `
+redis.call('RPUSH', KEYS[2], ARGV[2])
+redis.call('ZREM', KEYS[1], ARGV[1])
+return 1
+`
+};
+function readValue(value) {
+  if (!Buffer.isBuffer(value)) return [String(value), void 0];
+  const text = value.toString("utf8");
+  return [text, Buffer.from(text, "utf8").equals(value) ? void 0 : value];
+}
+function storedValue(reservation) {
+  return reservation.rawBytes ?? reservation.raw;
+}
+function zsetMember(reservation) {
+  return reservation.reservedBytes ?? reservation.reserved;
+}
+function newReservationToken() {
+  return randomBytes(16).toString("hex");
+}
+function validateRetryAfter(value) {
+  if (value === void 0) return 90;
+  if (value === null) return null;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new BabelQueueError(`Invalid retryAfter ${String(value)}: must be a non-negative number of seconds, or null.`);
+  }
+  return value;
+}
+var RedisQueue = class {
+  constructor(client, queue, options = {}) {
     this.client = client;
     this.queue = queue;
+    this.layout = options.layout ?? "legacy";
+    if (this.layout !== "legacy" && this.layout !== "zset") {
+      throw new BabelQueueError(`Unknown Redis layout ${String(this.layout)}: expected "legacy" or "zset".`);
+    }
+    this.retryAfter = validateRetryAfter(options.retryAfter);
+    const batch = options.migrationBatchSize ?? -1;
+    this.migrationBatchSize = Number.isFinite(batch) && batch > 0 ? Math.floor(batch) : -1;
+    this.clock = options.clock ?? (() => Date.now() / 1e3);
+    this.warn = options.onWarn ?? ((message) => console.warn(message));
+    this.deadLetterKey = options.deadLetterQueue === void 0 ? `${queue}.dlq` : options.deadLetterQueue;
+    this.keys = this.layout === "zset" ? zsetKeys(queue, options.keyPrefix) : { ready: queue, delayed: "", reserved: "", notify: "" };
+    this.processingKey = queue + (options.processingSuffix ?? ":processing");
+    this.deadlinesKey = `${this.processingKey}:deadlines`;
   }
   client;
   queue;
-  /** A publisher over `client`, producing to the list named `queue`. */
-  static create(client, queue) {
-    return new _RedisPublisher(client, queue);
+  layout;
+  retryAfter;
+  migrationBatchSize;
+  deadLetterKey;
+  /** The zset keys (zset layout) — also usable to inspect the legacy ready list via `ready`. */
+  keys;
+  processingKey;
+  deadlinesKey;
+  clock;
+  warn;
+  /**
+   * Run a script. `binary` (or any `Buffer` argument) selects the client's `evalBuffer`, when it has one,
+   * so replies and arguments are exact bytes.
+   */
+  run(script, keys, args, binary = false) {
+    const useBuffer = (binary || args.some((a) => Buffer.isBuffer(a))) && this.client.evalBuffer !== void 0;
+    if (useBuffer) return this.client.evalBuffer(script, keys.length, ...keys, ...args);
+    return this.client.eval(script, keys.length, ...keys, ...args);
+  }
+  nowSeconds() {
+    return Math.floor(this.clock());
+  }
+  deadlineScore() {
+    return this.retryAfter === null ? "+inf" : String(this.nowSeconds() + this.retryAfter);
+  }
+  /** Append a body to the ready list (zset: also one `:notify` token). */
+  async push(body) {
+    if (this.layout === "zset") {
+      await this.run(LUA.zsetPush, [this.keys.ready, this.keys.notify], [body]);
+    } else {
+      await this.client.rpush(this.queue, body);
+    }
   }
   /**
-   * Build + `RPUSH` the canonical envelope; returns the message id (`meta.id`). When
-   * `options.headers` carries any out-of-band header (e.g. a `traceparent`, ADR-0028) the value
-   * pushed is a transport-owned frame that wraps the envelope; otherwise the bare envelope is
-   * pushed byte-for-byte (GR-1, no regression).
+   * Schedule a body for `delay` seconds from now: `ZADD <q>:delayed floor(now)+ceil(delay)` with
+   * the body byte-for-byte and no `:notify` token. Zset layout only.
+   */
+  async pushDelayed(body, delay) {
+    if (this.layout !== "zset") {
+      throw new BabelQueueError('A delayed publish requires layout "zset"; the legacy layout has no delayed set.');
+    }
+    if (typeof delay !== "number" || !Number.isFinite(delay) || delay < 0) {
+      throw new BabelQueueError(`Invalid delay ${String(delay)}: must be a non-negative number of seconds.`);
+    }
+    await this.client.zadd(this.keys.delayed, this.nowSeconds() + Math.ceil(delay), body);
+  }
+  /** Zset: move due `:delayed` items, then due `:reserved` ones (skipped if `retryAfter` is null). */
+  async migrate() {
+    if (this.layout !== "zset") return 0;
+    let moved = await this.migrateFrom(this.keys.delayed);
+    if (this.retryAfter !== null) moved += await this.migrateFrom(this.keys.reserved);
+    return moved;
+  }
+  async migrateFrom(source) {
+    const moved = await this.run(
+      LUA.zsetMigrate,
+      [source, this.keys.ready, this.keys.notify],
+      [this.nowSeconds(), this.migrationBatchSize]
+    );
+    return Number(moved);
+  }
+  /** Legacy: move expired reservations back onto the ready list (body untouched). */
+  async sweep() {
+    if (this.layout !== "legacy") return 0;
+    const moved = await this.run(
+      LUA.legacySweep,
+      [this.queue, this.processingKey, this.deadlinesKey],
+      [this.nowSeconds(), this.migrationBatchSize]
+    );
+    return Number(moved);
+  }
+  /** Recovery and migration for the layout; runs before every reserve. */
+  async maintain() {
+    return this.layout === "zset" ? this.migrate() : this.sweep();
+  }
+  /** One non-blocking reserve, preceded by the layout's migrate / sweep. */
+  async reserve() {
+    if (this.client.evalBuffer === void 0) {
+      throw new BabelQueueError(
+        "The Redis client must provide evalBuffer (ioredis does) to consume: invalid UTF-8 is poison and its exact bytes must be read (broker-bindings.md section 1.1)."
+      );
+    }
+    await this.maintain();
+    return this.layout === "zset" ? this.reserveZset() : this.reserveLegacy();
+  }
+  async reserveLegacy() {
+    const token = newReservationToken();
+    const reply = await this.run(
+      LUA.legacyReserve,
+      [this.queue, this.processingKey, this.deadlinesKey],
+      [this.deadlineScore(), token],
+      true
+    );
+    if (typeof reply !== "string" && !Buffer.isBuffer(reply)) return { outcome: "empty" };
+    const [raw, rawBytes] = readValue(reply);
+    const reservation = { layout: "legacy", raw, token };
+    if (rawBytes) reservation.rawBytes = rawBytes;
+    return { outcome: "delivered", raw, reservation };
+  }
+  async reserveZset() {
+    const reply = await this.run(
+      LUA.zsetReserve,
+      [this.keys.ready, this.keys.reserved, this.keys.notify],
+      [this.deadlineScore()],
+      true
+    );
+    if (!Array.isArray(reply) || reply.length < 2) return { outcome: "empty" };
+    const [raw, rawBytes] = readValue(reply[0]);
+    const [reserved, reservedBytes] = readValue(reply[1]);
+    const reservation = { layout: "zset", raw, reserved };
+    if (rawBytes) reservation.rawBytes = rawBytes;
+    if (reservedBytes) reservation.reservedBytes = reservedBytes;
+    const poison = reply.length >= 3 ? readValue(reply[2])[0] === "1" : raw === reserved;
+    if (poison) return { outcome: "poison", raw, reservation: { ...reservation, poison: true } };
+    return { outcome: "delivered", raw, reservation, attempts: attemptsOf(raw) + 1 };
+  }
+  /** Acknowledge. Legacy: false (plus a warning) if the reservation had already expired. */
+  async ack(reservation) {
+    if (reservation.layout === "zset") {
+      return Number(await this.run(LUA.zsetAck, [this.keys.reserved], [zsetMember(reservation)])) === 1;
+    }
+    const live = await this.run(LUA.legacyAck, [this.processingKey, this.deadlinesKey], [reservation.token, storedValue(reservation)]);
+    return this.liveOrWarn(live, reservation);
+  }
+  /**
+   * Give a reservation back. Legacy: the body (default: `raw`) goes to the ready list, gated on the
+   * deadline member; `delay` is ignored. Zset: one script `ZREM`s the `:reserved` member and `ZADD`s
+   * `<q>:delayed` at `floor(now)+ceil(delay)` with the body (default: `raw` re-encoded with
+   * `attempts + 1`, every other key preserved).
+   */
+  async release(reservation, delay = 0, body) {
+    if (reservation.layout === "zset") {
+      if (typeof delay !== "number" || !Number.isFinite(delay) || delay < 0) {
+        throw new BabelQueueError(`Invalid delay ${String(delay)}: must be a non-negative number of seconds.`);
+      }
+      const bumped = body ?? bumpAttempts(reservation.raw);
+      await this.run(
+        LUA.zsetRelease,
+        [this.keys.delayed, this.keys.reserved],
+        [zsetMember(reservation), this.nowSeconds() + Math.ceil(delay), bumped]
+      );
+      return true;
+    }
+    const live = await this.run(
+      LUA.legacyRelease,
+      [this.queue, this.processingKey, this.deadlinesKey],
+      [reservation.token, storedValue(reservation), body ?? storedValue(reservation)]
+    );
+    return this.liveOrWarn(live, reservation);
+  }
+  /** Write `body` (default: `raw`) to the dead-letter list and settle the reservation. */
+  async deadLetter(reservation, body) {
+    const payload = body ?? reservation.raw;
+    if (this.deadLetterKey === null) return this.ack(reservation);
+    if (reservation.layout === "zset" && reservation.poison === true) {
+      await this.run(
+        LUA.zsetDeadLetterPoison,
+        [this.keys.reserved, this.deadLetterKey],
+        [zsetMember(reservation), payload]
+      );
+      return true;
+    }
+    if (reservation.layout === "zset") {
+      const settled = await this.run(
+        LUA.zsetDeadLetter,
+        [this.keys.reserved, this.deadLetterKey],
+        [zsetMember(reservation), payload]
+      );
+      if (Number(settled) === 1) return true;
+      this.warn(
+        `reservation expired: queue "${this.queue}" reservation was already recovered or settled; nothing dead-lettered`
+      );
+      return false;
+    }
+    const live = await this.run(
+      LUA.legacyDeadLetter,
+      [this.processingKey, this.deadlinesKey, this.deadLetterKey],
+      [reservation.token, storedValue(reservation), payload]
+    );
+    return this.liveOrWarn(live, reservation);
+  }
+  liveOrWarn(reply, reservation) {
+    if (Number(reply) === 1) return true;
+    this.warn(
+      `reservation expired: queue "${this.queue}" token ${reservation.token} was already swept or settled; left the queue untouched`
+    );
+    return false;
+  }
+};
+function attemptsOf(raw) {
+  try {
+    const decoded = JSON.parse(raw);
+    const attempts = decoded?.attempts;
+    return typeof attempts === "number" ? attempts : 0;
+  } catch {
+    return 0;
+  }
+}
+function bumpAttempts(raw) {
+  let decoded;
+  try {
+    decoded = JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+  if (decoded === null || typeof decoded !== "object" || Array.isArray(decoded)) return raw;
+  const scan = scanTopLevel(raw);
+  const spans = scan.members.filter((member) => member.key === "attempts");
+  const last = spans[spans.length - 1];
+  const current = last === void 0 ? null : raw.slice(last.start, last.end);
+  const next = current !== null && NUMBER_LITERAL.test(current) ? incrementNumberLiteral(current) : "1";
+  if (last === void 0) {
+    const member = `"attempts":${next}`;
+    return `${raw.slice(0, scan.close)}${scan.members.length > 0 ? "," : ""}${member}${raw.slice(scan.close)}`;
+  }
+  let result = raw;
+  for (const span of [...spans].reverse()) result = `${result.slice(0, span.start)}${next}${result.slice(span.end)}`;
+  return result;
+}
+var NUMBER_LITERAL = /^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
+function incrementNumberLiteral(literal) {
+  if (/^-?\d+$/.test(literal)) return (BigInt(literal) + 1n).toString();
+  return String(Number(literal) + 1);
+}
+function scanTopLevel(text) {
+  const members = [];
+  const skipSpace = (from) => {
+    let i2 = from;
+    while (i2 < text.length && " 	\n\r".includes(text.charAt(i2))) i2++;
+    return i2;
+  };
+  const stringEnd = (from) => {
+    let i2 = from + 1;
+    while (text.charAt(i2) !== '"') i2 += text.charAt(i2) === "\\" ? 2 : 1;
+    return i2 + 1;
+  };
+  let i = skipSpace(text.indexOf("{") + 1);
+  while (text.charAt(i) !== "}") {
+    if (text.charAt(i) === ",") i = skipSpace(i + 1);
+    const keyEnd = stringEnd(i);
+    const key = JSON.parse(text.slice(i, keyEnd));
+    i = skipSpace(skipSpace(keyEnd) + 1);
+    const start = i;
+    let depth = 0;
+    while (i < text.length) {
+      const c = text.charAt(i);
+      if (c === '"') {
+        i = stringEnd(i);
+        continue;
+      }
+      if (c === "{" || c === "[") depth++;
+      else if (c === "}" || c === "]") {
+        if (depth === 0) break;
+        depth--;
+      } else if (c === "," && depth === 0) break;
+      i++;
+    }
+    let end = i;
+    while (end > start && " 	\n\r".includes(text.charAt(end - 1))) end--;
+    members.push({ key, start, end });
+    i = skipSpace(i);
+  }
+  return { members, close: i };
+}
+var RedisPublisher = class _RedisPublisher {
+  constructor(client, queue, options) {
+    this.queue = queue;
+    this.transport = new RedisQueue(client, queue, options);
+  }
+  queue;
+  transport;
+  /** A publisher over `client`, producing to the queue named `queue`. */
+  static create(client, queue, options = {}) {
+    return new _RedisPublisher(client, queue, options);
+  }
+  /**
+   * Build + push the canonical envelope; returns the message id (`meta.id`). Legacy layout: a
+   * non-empty `options.headers` pushes a transport-owned frame (ADR-0028), otherwise the bare
+   * envelope byte-for-byte. Zset layout: always the bare envelope (A3); with `options.delay > 0`
+   * it goes to `<q>:delayed` instead of the ready list.
    */
   async publish(urn, data, options = {}) {
+    const delay = options.delay ?? 0;
+    if (typeof delay !== "number" || !Number.isFinite(delay) || delay < 0) {
+      throw new BabelQueueError(`Invalid delay ${String(delay)}: must be a non-negative number of seconds.`);
+    }
+    if (delay > 0 && this.transport.layout !== "zset") {
+      throw new BabelQueueError('A delayed publish requires layout "zset"; the legacy layout has no delayed set.');
+    }
     const envelope = EnvelopeCodec.make(urn, data, { queue: this.queue, traceId: options.traceId });
-    await this.client.rpush(this.queue, frameValue(redisValue(envelope), options.headers));
+    const body = redisValue(envelope);
+    if (this.transport.layout === "zset") {
+      if (delay > 0) await this.transport.pushDelayed(body, delay);
+      else await this.transport.push(body);
+    } else {
+      await this.transport.push(frameValue(body, options.headers));
+    }
     return envelope.meta.id;
   }
 };
+var SLEEP_START_MS = 100;
+var SLEEP_CAP_MS = 1e3;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 var RedisConsumer = class {
   constructor(client, queue, handlers, options = {}) {
     this.client = client;
     this.queue = queue;
     this.handlers = handlers;
     this.options = options;
-    this.processing = queue + (options.processingSuffix ?? ":processing");
+    this.transport = new RedisQueue(client, queue, options);
     this.blockTimeout = options.blockTimeout ?? 5;
     this.maxTries = options.maxTries ?? 3;
-    this.dlq = options.deadLetterQueue === void 0 ? `${queue}.dlq` : options.deadLetterQueue;
     this.unknownUrn = options.unknownUrn ?? UnknownUrnStrategy.FAIL;
   }
   client;
   queue;
   handlers;
   options;
-  processing;
+  transport;
   blockTimeout;
   maxTries;
-  dlq;
   unknownUrn;
+  /** The underlying transport (for diagnostics and tests). */
+  get redisQueue() {
+    return this.transport;
+  }
   /** Reserve + route + settle one message. Returns true if one was handled, false on timeout. */
   async poll() {
-    const raw = await this.client.brpoplpush(this.queue, this.processing, this.blockTimeout);
-    if (raw == null) return false;
-    await this.handle(raw);
-    return true;
+    const startedAt = Date.now();
+    let wait = SLEEP_START_MS;
+    for (; ; ) {
+      const result = await this.transport.reserve();
+      if (result.outcome !== "empty") {
+        await this.dispatch(result);
+        return true;
+      }
+      const remainingMs = this.blockTimeout * 1e3 - (Date.now() - startedAt);
+      if (remainingMs <= 0) return false;
+      if (this.transport.layout === "zset") {
+        await this.client.blpop(this.transport.keys.notify, Math.min(1, remainingMs / 1e3));
+      } else {
+        await sleep(Math.min(wait, remainingMs));
+        wait = Math.min(wait * 2, SLEEP_CAP_MS);
+      }
+    }
   }
   /** Poll while `shouldContinue` returns true. */
   async run(shouldContinue) {
@@ -101,87 +689,131 @@ var RedisConsumer = class {
       await this.poll();
     }
   }
+  async dispatch(result) {
+    const reservation = result.reservation;
+    if (result.outcome === "poison" || reservation.rawBytes !== void 0) {
+      const error = new BabelQueueError("Rejected an undecodable BabelQueue message from Redis.");
+      this.report(error, null, reservation.raw);
+      await this.transport.deadLetter(reservation, this.poisonRecord(reservation, error));
+      return;
+    }
+    await this.handle(reservation);
+  }
   /**
-   * Route + settle one reserved element. Exposed for testing.
+   * Route + settle one reserved message. Exposed for testing.
    *
-   * `raw` is the **stored** list value (the `LREM` ack handle); it may be a transport-owned header
-   * frame or a bare envelope. It is unframed first so the envelope is decoded from the verbatim
-   * wire body while the carried out-of-band headers (e.g. a `traceparent`, ADR-0028) are surfaced
-   * to the handler. Settling/dead-lettering still operate on the original stored value.
+   * Legacy layout: `reservation.raw` may be a transport-owned header frame or a bare envelope; it is
+   * unframed first so the envelope is decoded from the verbatim wire body while the carried headers
+   * (e.g. a `traceparent`, ADR-0028) reach the handler. The zset layout is never framed (A3).
    */
-  async handle(raw) {
-    const [body, headers] = unframe(raw);
+  async handle(reservation) {
+    const raw = reservation.raw;
+    if (reservation.rawBytes !== void 0) {
+      const error = new BabelQueueError("Rejected a non-UTF-8 BabelQueue message from Redis.");
+      this.report(error, null, raw);
+      await this.transport.deadLetter(reservation, this.poisonRecord(reservation, error));
+      return;
+    }
+    const [body, headers] = reservation.layout === "legacy" ? unframe(raw) : [raw, {}];
     const decoded = EnvelopeCodec.decode(body);
     if (!EnvelopeCodec.accepts(decoded)) {
-      this.report(new BabelQueueError("Rejected a non-conformant BabelQueue envelope from Redis."), decoded, raw);
-      await this.deadLetterRaw(raw);
-      await this.settle(raw);
+      const error = new BabelQueueError("Rejected a non-conformant BabelQueue envelope from Redis.");
+      this.report(error, decoded, raw);
+      await this.transport.deadLetter(reservation, this.poisonRecord(reservation, error));
       return;
     }
     const envelope = decoded;
     const urn = EnvelopeCodec.urn(envelope);
     const handler = this.handlers[urn];
     if (!handler) {
-      await this.onUnknownUrn(envelope, urn, raw);
+      await this.onUnknownUrn(envelope, urn, reservation);
       return;
     }
     try {
       await handler(envelope, raw, headers);
-      await this.settle(raw);
     } catch (error) {
       this.report(error, envelope, raw);
-      await this.retryOrDeadLetter(envelope, raw, error);
+      await this.retryOrDeadLetter(envelope, reservation, error);
+      return;
     }
+    await this.transport.ack(reservation);
   }
-  async onUnknownUrn(envelope, urn, raw) {
+  async onUnknownUrn(envelope, urn, reservation) {
     switch (this.unknownUrn) {
       case UnknownUrnStrategy.DELETE:
-        await this.settle(raw);
+        await this.transport.ack(reservation);
         return;
       case UnknownUrnStrategy.DEAD_LETTER:
-        await this.deadLetter(envelope, "unknown_urn");
-        await this.settle(raw);
+        await this.deadLetter(envelope, reservation, "unknown_urn");
         return;
       case UnknownUrnStrategy.RELEASE:
-        await this.requeue(envelope);
-        await this.settle(raw);
+        await this.requeue(envelope, reservation);
         return;
       default: {
         const error = new UnknownUrnError(urn);
-        this.report(error, envelope, raw);
-        throw error;
+        this.report(error, envelope, reservation.raw);
+        await this.retryOrDeadLetter(envelope, reservation, error);
+        return;
       }
     }
   }
-  async retryOrDeadLetter(envelope, raw, error) {
-    if ((envelope.attempts ?? 0) + 1 < this.maxTries) {
-      await this.requeue(envelope);
+  async retryOrDeadLetter(envelope, reservation, error) {
+    const counted = (envelope.attempts ?? 0) + 1;
+    if (counted < this.maxTries) {
+      await this.requeue(envelope, reservation);
     } else {
-      await this.deadLetter(envelope, "failed", error);
+      await this.deadLetter(
+        envelope,
+        reservation,
+        error instanceof UnknownUrnError ? "unknown_urn" : "failed",
+        error,
+        counted
+      );
     }
-    await this.settle(raw);
   }
-  /** Republish with `attempts + 1` onto the work list (at-least-once retry). */
-  async requeue(envelope) {
+  /** Give the message back with `attempts + 1` (at-least-once retry). */
+  async requeue(envelope, reservation) {
+    if (reservation.layout === "zset") {
+      await this.transport.release(reservation, 0);
+      return;
+    }
     const bumped = { ...envelope, attempts: (envelope.attempts ?? 0) + 1 };
-    await this.client.rpush(this.queue, redisValue(bumped));
+    await this.transport.release(reservation, 0, redisValue(bumped));
   }
-  async deadLetter(envelope, reason, error) {
-    if (!this.dlq) return;
-    const annotated = annotate(envelope, reason, envelope.meta?.queue ?? this.queue, {
-      attempts: envelope.attempts ?? 0,
+  /**
+   * Write the annotated envelope to the DLQ. `counted` is given on the exhaustion path (retries used up): the
+   * delivered attempts plus one for the current delivery, written to both `dead_letter.attempts` and the
+   * record's top-level `attempts`, like Go and Python. A direct dead-letter that makes no retry decision
+   * (`unknownUrn: dead_letter`) omits it and records the delivered value, which is informational.
+   */
+  async deadLetter(envelope, reservation, reason, error, counted) {
+    const attempts = counted ?? envelope.attempts ?? 0;
+    const annotated = annotate({ ...envelope, attempts }, reason, envelope.meta?.queue ?? this.queue, {
+      attempts,
       error: error instanceof Error ? error.message : null,
       exception: error instanceof Error ? error.name : null
     });
-    await this.client.rpush(this.dlq, redisValue(annotated));
-  }
-  async deadLetterRaw(raw) {
-    if (!this.dlq) return;
-    await this.client.rpush(this.dlq, raw);
+    await this.transport.deadLetter(reservation, redisValue(annotated));
   }
-  /** Remove the element from the reservation list (acknowledge). */
-  async settle(raw) {
-    await this.client.lrem(this.processing, 1, raw);
+  /**
+   * The poison DLQ record of a reservation (ADR-0035, broker-bindings section 1.1): the delivered body (a legacy
+   * header frame is unwrapped first) with a `dead_letter` block of reason `poison`. A strict JSON object is
+   * spliced, anything else is wrapped as `{"raw", "dead_letter"}`.
+   *
+   * A body that is not valid UTF-8 is read as exact bytes (`evalBuffer`, see {@link RedisClient.evalBuffer}) and
+   * kept as stored (no frame is peeled off it), so it lands in the base64 wrapper, never as U+FFFD text.
+   */
+  poisonRecord(reservation, cause) {
+    const exact = reservation.rawBytes;
+    const [body] = exact !== void 0 || reservation.layout !== "legacy" ? [reservation.raw] : unframe(reservation.raw);
+    const counted = attemptsOf(body);
+    const attempts = Number.isSafeInteger(counted) && counted >= 0 ? counted : 0;
+    const deadLetter = annotate({ attempts }, "poison", this.queue, {
+      attempts,
+      error: cause.message,
+      exception: cause.name
+    }).dead_letter;
+    return buildPoisonRecord(exact ?? Buffer.from(body, "utf8"), JSON.stringify(deadLetter));
   }
   report(error, envelope, raw) {
     this.options.onError?.(error, envelope, raw);
@@ -189,11 +821,16 @@ var RedisConsumer = class {
 };
 export {
   FRAME_KEY,
+  LUA,
   RedisConsumer,
   RedisPublisher,
+  RedisQueue,
+  ZSET_KEY_PREFIX,
   frameValue,
   headersOf,
+  newReservationToken,
   redisValue,
-  unframe
+  unframe,
+  zsetKeys
 };
 //# sourceMappingURL=index.js.map