@sproutboat/wire 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @sproutboat/wire
 
+## 0.20.0
+
+### Minor Changes
+
+- 482a55c: Queues like Cloudflare's, from compatibility date 2026-10-31, with queue names and consumer
+  settings in `sproutboat.jsonc` at every date.
+  
+  - **Config (`@sproutboat/config`):** a `queues` entry may be `{ "binding": "QUEUE", "queue": "q",
+    "max_batch_size": 10, "max_batch_timeout": 1, "max_retries": 3, "retry_delay": 0,
+    "dead_letter_queue": "dlq" }`, the settings named as in wrangler's `queues.consumers`; `id`
+    is optional there. `queueSettings()` normalizes the entries for the build, and `pinBindingId`
+    adds an id to such an object.
+  - **Names and settings, at every date (opt-in):** `batch.queue` is the queue's name (the binding
+    name when unset). `max_batch_size` (1 to 100, default 10) and `max_batch_timeout` (0 to 60 s,
+    default 0: delivered at once, where Cloudflare waits up to 5 s) shape batches; `max_retries`,
+    `retry_delay` and `dead_letter_queue` decide what a retry does. A dead letter queue the worker
+    doesn't bind keeps its messages until one does.
+  - **From 2026-10-31:**
+    - `send()` and `sendBatch()` return Promises of `{ metadata: { metrics } }`, the queue's backlog
+      after the send as Cloudflare documents it (miniflare answers zeros); `metrics()` is added.
+    - Bodies keep their content type: `json` (the default), `text`, `bytes` (arrives as an
+      ArrayBuffer) and `v8` (structured clone). A string that looks like JSON or a number arrives as
+      the same string.
+    - workerd's argument errors: an undefined or BigInt `json` body, a `text` body that isn't a
+      string, an unknown content type, a body over 128 KiB, an empty batch, more than 100 messages
+      or 256 KiB in a batch, a batch that isn't iterable.
+    - A message is `{ id, timestamp, body, attempts }`, `timestamp` a Date of when it was sent, with
+      `ack()` and `retry({ delaySeconds })` on its prototype; a batch has `queue`, `messages` and
+      `metadata`, with `ackAll()` and `retryAll({ delaySeconds })`. The first of `ack()` and `retry()`
+      wins, and a message's own call wins over `ackAll()`/`retryAll()`, as Cloudflare documents
+      (miniflare lets a later `retryAll()` win).
+    - By default a message is retried at once, 3 times, then dropped or sent to the dead letter
+      queue. Earlier dates keep 5 s between attempts and 5 attempts.
+  - **Stores (embedded transport and `@sproutboat/wire`'s broker):** messages keep their send time
+    (an additive `sent_at` column), `queue.send` answers the backlog when asked, `queue.metrics` is
+    new, and a batch's outcome may carry retry delays and messages for the dead letter queue. An
+    older broker ignores those and retries as before; bodies sent from 2026-10-31 are tagged text, so
+    they travel through it unchanged.
+
+### Patch Changes
+
+- Updated dependencies [482a55c]
+  - @sproutboat/runtime@0.32.0
+
+## 0.19.1
+
+### Patch Changes
+
+- Updated dependencies [a04d0aa]
+  - @sproutboat/runtime@0.31.0
+
 ## 0.19.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutboat/wire",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -23,6 +23,6 @@
   },
   "dependencies": {
     "@sproutboat/assets": "^0.3.0",
-    "@sproutboat/runtime": "^0.30.0"
+    "@sproutboat/runtime": "^0.32.0"
   }
 }

package/src/broker.test.ts

@@ -1025,6 +1025,67 @@ test("Queues: send enqueues; the consumer delivers a batch and acked messages ar
   await expect(b.dispatch({ op: "queue.send", queue: "NOPE", body: "x" })).rejects.toThrow("not bound");
 });
 
+test("Queues: send reports the backlog; batches carry send times, metrics and the batch settings", async () => {
+  const delivered: JsonObject[] = [];
+  const fetchImpl: FetchLike = async (_url, init) => {
+    const body = obj(parseJsonValue(String(init?.body)));
+    delivered.push(body);
+    return new Response(JSON.stringify({ ack: arr(body.messages).map((m) => obj(m).id), retry: [] }), { status: 200 });
+  };
+  const b = make({
+    bindings: {
+      queues: ["JOBS"],
+      queueConfig: [{ binding: "JOBS", queue: "jobs", maxBatchSize: 2, maxBatchTimeout: 1 }],
+    },
+    sproutUrl: "http://127.0.0.1:1/",
+    fetchImpl,
+  });
+  const before = Date.now();
+  const sent = await b.dispatch({ op: "queue.send", queue: "JOBS", body: "one", metrics: true });
+  expect(obj(sent.metrics)).toMatchObject({ backlogCount: 1, backlogBytes: 3 });
+  expect(Number(obj(sent.metrics).oldestMessageTimestamp)).toBeGreaterThanOrEqual(before);
+  expect(await b.dispatch({ op: "queue.metrics", queue: "JOBS" })).toMatchObject({ metrics: { backlogCount: 1 } });
+  // One message waits for max_batch_timeout (1 s); three fill a batch of two at once.
+  await Bun.sleep(700);
+  expect(delivered.length).toBe(0);
+  await Bun.sleep(900);
+  expect(delivered.length).toBe(1);
+  const batch = obj(delivered[0]);
+  expect(Number(obj(arr(batch.messages)[0]).timestamp)).toBeGreaterThanOrEqual(before);
+  expect(obj(obj(batch.metadata).metrics).backlogCount).toBe(1);
+  await b.dispatch({ op: "queue.send_batch", queue: "JOBS", messages: [{ body: "a" }, { body: "b" }, { body: "c" }] });
+  await Bun.sleep(600);
+  expect(arr(obj(delivered[1]).messages).length).toBe(2);
+});
+
+test("Queues: retry delays from the sprout, and messages past max_retries move to the dead letter queue", async () => {
+  const delivered: JsonObject[] = [];
+  const fetchImpl: FetchLike = async (_url, init) => {
+    const body = obj(parseJsonValue(String(init?.body)));
+    delivered.push(body);
+    const ids = arr(body.messages).map((m) => String(obj(m).id));
+    if (body.queue === "DLQ") return new Response(JSON.stringify({ ack: ids, retry: [] }), { status: 200 });
+    // The first delivery retries at once; the second sends the message to the dead letter queue.
+    const second = Number(obj(arr(body.messages)[0]).attempts) > 1;
+    return new Response(
+      JSON.stringify(
+        second
+          ? { ack: [], retry: ids, delays: {}, dead: ids, deadLetter: "DLQ" }
+          : { ack: [], retry: ids, delays: Object.fromEntries(ids.map((id) => [id, 0])), dead: [] },
+      ),
+      { status: 200 },
+    );
+  };
+  const b = make({ bindings: { queues: ["JOBS", "DLQ"] }, sproutUrl: "http://127.0.0.1:1/", fetchImpl });
+  await b.dispatch({ op: "queue.send", queue: "JOBS", body: "work" });
+  await Bun.sleep(1800);
+  expect(delivered.map((d) => [d.queue, obj(arr(d.messages)[0]).attempts, obj(arr(d.messages)[0]).body])).toEqual([
+    ["JOBS", 1, "work"],
+    ["JOBS", 2, "work"],
+    ["DLQ", 1, "work"],
+  ]);
+});
+
 test("assets.get: serves a bound file, falls back per not_found_handling", async () => {
   const dir = mkdtempSync(join(tmpdir(), "sb-assets-"));
   const assetsDir = join(dir, "assets");

package/src/broker.ts

@@ -48,6 +48,15 @@ export type Bindings = {
   d1: string[];
   r2: string[];
   queues: string[];
+  /** Each queue binding's name and consumer settings (`queueSettings` in @sproutboat/config).
+   *  The broker reads the batch settings; the sprout applies the retry settings. */
+  queueConfig?: Array<{
+    binding: string;
+    queue: string;
+    maxBatchSize?: number;
+    maxBatchTimeout?: number;
+    maxRetries?: number;
+  }>;
   analytics: string[];
   do: Array<{ binding: string; className: string }>;
   /** #48 — worker-to-worker: binding name -> the project it calls. */
@@ -369,6 +378,14 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         .some((c) => c.name === "claim_token")
     )
       conn.exec("ALTER TABLE mq ADD COLUMN claim_token TEXT NOT NULL DEFAULT ''");
+    // When the message was sent (message.timestamp); 0 for messages queued before the column.
+    if (
+      !conn
+        .query<{ name: string }, []>("PRAGMA table_info(mq)")
+        .all()
+        .some((c) => c.name === "sent_at")
+    )
+      conn.exec("ALTER TABLE mq ADD COLUMN sent_at INTEGER NOT NULL DEFAULT 0");
     return conn;
   };
 
@@ -647,6 +664,20 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
   const requireD1 = bound(bindings.d1, "D1 database");
   const requireR2 = bound(bindings.r2, "R2 bucket");
   const requireQueue = bound(bindings.queues, "queue");
+  /** A queue's backlog as Queues reports it: live messages, their bytes, the oldest send time. */
+  const queueBacklog = (store: Database, part: string): JsonObject => {
+    const r = store
+      .query<{ n: number; bytes: number; oldest: number | null }, [string]>(
+        "SELECT COUNT(*) AS n, COALESCE(SUM(LENGTH(CAST(body AS BLOB))), 0) AS bytes, MIN(NULLIF(sent_at, 0)) AS oldest FROM mq WHERE queue = ? AND dead = 0",
+      )
+      .get(part);
+    return { backlogCount: r?.n ?? 0, backlogBytes: r?.bytes ?? 0, oldestMessageTimestamp: r?.oldest ?? 0 };
+  };
+  /** Where a queue partition named by the sprout lives: a bound queue, or "#name" (a dead
+   *  letter queue the sprout does not bind) in the per-broker db. */
+  const queueStore = (part: string): { store: Database; part: string } =>
+    part.startsWith("#") ? { store: db, part } : storeFor("queue", requireQueue(part));
+  const queueSettingsOf = (binding: string) => bindings.queueConfig?.find((q) => q.binding === binding);
   const requireAe = bound(bindings.analytics, "analytics dataset");
   const rateLimiterNames = bindings.ratelimiters.map((r) => r.binding);
   const requireRateLimiter = bound(rateLimiterNames, "rate limiter");
@@ -1750,21 +1781,29 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
 
       case "queue.send": {
         const { store, part: q } = storeFor("queue", requireQueue(msg.queue));
-        const at = Date.now() + Math.max(0, Number(msg.delaySeconds) || 0) * 1000;
+        const now = Date.now();
+        const at = now + Math.max(0, Number(msg.delaySeconds) || 0) * 1000;
         store
-          .query("INSERT INTO mq (queue, id, body, visible_at) VALUES (?, ?, ?, ?)")
-          .run(q, newId(), str(msg.body), at);
-        return { ok: true };
+          .query("INSERT INTO mq (queue, id, body, visible_at, sent_at) VALUES (?, ?, ?, ?, ?)")
+          .run(q, newId(), str(msg.body), at, now);
+        return msg.metrics === true ? { ok: true, metrics: queueBacklog(store, q) } : { ok: true };
       }
       case "queue.send_batch": {
         const { store, part: q } = storeFor("queue", requireQueue(msg.queue));
         const msgs = Array.isArray(msg.messages) ? msg.messages.map((m) => jsonObject(m) ?? {}) : [];
-        const ins = store.query("INSERT INTO mq (queue, id, body, visible_at) VALUES (?, ?, ?, ?)");
+        const ins = store.query("INSERT INTO mq (queue, id, body, visible_at, sent_at) VALUES (?, ?, ?, ?, ?)");
+        const now = Date.now();
         store.transaction(() => {
           for (const m of msgs)
-            ins.run(q, newId(), str(m.body), Date.now() + Math.max(0, Number(m.delaySeconds) || 0) * 1000);
+            ins.run(q, newId(), str(m.body), now + Math.max(0, Number(m.delaySeconds) || 0) * 1000, now);
         })();
-        return { ok: true, count: msgs.length };
+        return msg.metrics === true
+          ? { ok: true, count: msgs.length, metrics: queueBacklog(store, q) }
+          : { ok: true, count: msgs.length };
+      }
+      case "queue.metrics": {
+        const { store, part: q } = storeFor("queue", requireQueue(msg.queue));
+        return { ok: true, metrics: queueBacklog(store, q) };
       }
 
       case "ae.write": {
@@ -2212,18 +2251,30 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     if (!opts.sproutUrl || !dispatchEnabled() || closed) return;
     for (const binding of bindings.queues) {
       const { store, part } = storeFor("queue", binding);
+      const settings = queueSettingsOf(binding);
+      const size = Math.min(100, Math.max(1, Number(settings?.maxBatchSize) || QUEUE_BATCH));
+      const wait = Math.max(0, Number(settings?.maxBatchTimeout) || 0) * 1000;
+      // Deliveries that never came back (the sprout died or timed out each time) stop after
+      // 5 attempts, or max_retries + 1 when that is more.
+      const cap = Math.max(QUEUE_MAX_ATTEMPTS, (settings?.maxRetries ?? 3) + 1);
       const now = Date.now();
       const claim = randomBytes(24).toString("hex");
       const rows = store
         .transaction(() => {
           store
             .query("UPDATE mq SET dead = 1 WHERE queue = ? AND visible_at <= ? AND attempts >= ?")
-            .run(part, now, QUEUE_MAX_ATTEMPTS);
+            .run(part, now, cap);
           const due = store
-            .query<{ id: string; body: string; attempts: number }, [string, number, number]>(
-              "SELECT id, body, attempts FROM mq WHERE queue = ? AND dead = 0 AND visible_at <= ? ORDER BY visible_at LIMIT ?",
+            .query<
+              { id: string; body: string; attempts: number; sent_at: number; visible_at: number },
+              [string, number, number]
+            >(
+              "SELECT id, body, attempts, sent_at, visible_at FROM mq WHERE queue = ? AND dead = 0 AND visible_at <= ? ORDER BY visible_at LIMIT ?",
             )
-            .all(part, now, QUEUE_BATCH);
+            .all(part, now, size);
+          // max_batch_timeout: a batch short of max_batch_size waits until its oldest
+          // message has been due that long.
+          if (wait > 0 && due.length > 0 && due.length < size && due[0].visible_at + wait > now) return [];
           for (const row of due)
             store
               .query(
@@ -2239,14 +2290,18 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         messages: rows.map((r) => ({
           id: r.id,
           body: r.body,
-          timestamp: now,
+          timestamp: r.sent_at || now,
           attempts: r.attempts + 1,
         })),
+        metadata: { metrics: queueBacklog(store, part) },
       }).then(async (res) => {
         if (closed || !dispatchEnabled()) return;
         const claimed = new Set(rows.map((r) => r.id));
         let ack = rows.map((r) => r.id);
         let retry: string[] = [];
+        let dead: string[] = [];
+        let deadLetter = "";
+        let delays: JsonObject | null = null;
         if (res?.ok) {
           try {
             const parsed = jsonObject(parseJsonValue(await res.text()));
@@ -2254,6 +2309,11 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
               Array.isArray(v) ? v.filter(isString).filter((id) => claimed.has(id)) : null;
             ack = (parsed && ids(parsed.ack)) ?? ack;
             retry = (parsed && ids(parsed.retry)) ?? [];
+            // From runtime 0.32: retry delays, and messages past max_retries (to the dead
+            // letter queue when one is named). An older sprout sends neither.
+            dead = (parsed && ids(parsed.dead)) ?? [];
+            deadLetter = parsed && isString(parsed.deadLetter) ? parsed.deadLetter : "";
+            delays = (parsed && jsonObject(parsed.delays ?? null)) ?? null;
           } catch {
             ack = [];
             retry = rows.map((r) => r.id);
@@ -2264,19 +2324,68 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         }
         if (closed || !dispatchEnabled()) return;
         const retrySet = new Set(retry);
+        const deadSet = new Set(dead);
+        let target: { store: Database; part: string } | null = null;
+        if (dead.length && deadLetter) {
+          try {
+            target = queueStore(deadLetter);
+          } catch {
+            target = null; // not a queue this broker serves: mark them dead instead
+          }
+        }
+        // Into the dead letter queue first, then out of this one: a crash between the two
+        // leaves a copy in each rather than none.
+        if (target && target.store !== store) {
+          const moved = store.query<{ id: string; body: string; sent_at: number }, [string, string, string, number]>(
+            "SELECT id, body, sent_at FROM mq WHERE queue = ? AND id = ? AND claim_token = ? AND visible_at > ?",
+          );
+          const found = dead.flatMap((id) => moved.all(part, id, claim, Date.now()));
+          const ins = target.store.query(
+            "INSERT OR IGNORE INTO mq (queue, id, body, visible_at, sent_at) VALUES (?, ?, ?, ?, ?)",
+          );
+          const at = Date.now();
+          const into = target;
+          into.store.transaction(() => {
+            for (const r of found) ins.run(into.part, r.id, r.body, at, r.sent_at);
+          })();
+        }
         store
           .transaction(() => {
+            const at = Date.now();
+            for (const id of dead) {
+              if (target && target.store === store)
+                store
+                  .query(
+                    "UPDATE mq SET queue = ?, visible_at = ?, attempts = 0, claim_token = '', dead = 0 WHERE queue = ? AND id = ? AND claim_token = ? AND visible_at > ?",
+                  )
+                  .run(target.part, at, part, id, claim, at);
+              else if (target)
+                store
+                  .query("DELETE FROM mq WHERE queue = ? AND id = ? AND claim_token = ? AND visible_at > ?")
+                  .run(part, id, claim, at);
+              else
+                store
+                  .query(
+                    "UPDATE mq SET dead = 1, claim_token = '' WHERE queue = ? AND id = ? AND claim_token = ? AND visible_at > ?",
+                  )
+                  .run(part, id, claim, at);
+            }
             for (const id of ack)
-              if (!retrySet.has(id))
+              if (!retrySet.has(id) && !deadSet.has(id))
                 store
                   .query("DELETE FROM mq WHERE queue = ? AND id = ? AND claim_token = ? AND visible_at > ?")
-                  .run(part, id, claim, Date.now());
-            for (const id of retry)
+                  .run(part, id, claim, at);
+            for (const id of retry) {
+              if (deadSet.has(id)) continue;
+              const seconds = delays ? Number(delays[id]) : NaN;
+              const delay = Number.isFinite(seconds) ? Math.max(0, seconds) * 1000 : 5_000;
+              // With runtime delays, max_retries is the sprout's: only the delivery cap applies.
               store
                 .query(
                   "UPDATE mq SET visible_at = ?, claim_token = '', dead = CASE WHEN attempts >= ? THEN 1 ELSE 0 END WHERE queue = ? AND id = ? AND claim_token = ? AND visible_at > ?",
                 )
-                .run(Date.now() + 5_000, QUEUE_MAX_ATTEMPTS, part, id, claim, Date.now());
+                .run(at + delay, delays ? cap : QUEUE_MAX_ATTEMPTS, part, id, claim, at);
+            }
           })
           .immediate();
       });