sproutboat 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -10,6 +10,37 @@ maintained going forward by the `release` skill.
 
 ## Unreleased
 
+## [0.33.0] - 2026-10-25
+
+Built on `@sproutboat/runtime` 0.32.0, `@sproutboat/wire` 0.20.0 and
+`@sproutboat/config` 0.6.0.
+
+### Added
+
+- **Queue names and consumer settings.** A `queues` entry may be
+  `{ "binding": "JOBS", "queue": "jobs", "max_batch_size": 10, "max_batch_timeout": 1,
+  "max_retries": 3, "retry_delay": 0, "dead_letter_queue": "failed" }`. The settings
+  are named as in wrangler's `queues.consumers`, and `id` is optional there. `batch.queue`
+  is the queue's name. The build bakes the settings into `bindings.json` as `queueConfig`,
+  and `deploy` pins a provisioned id into such an object. These apply at every compatibility
+  date.
+- **Queues like Cloudflare's from compatibility date 2026-10-31.**
+  - `send()` and `sendBatch()` return Promises of the queue's backlog, and `metrics()` is new.
+  - Bodies keep their content type (`json`, `text`, `bytes`, `v8`).
+  - Arguments are checked with workerd's errors.
+  - Messages carry `timestamp` as a Date of when they were sent, and `retry({ delaySeconds })`.
+  - The first of `ack()` and `retry()` wins.
+  - By default a retry is immediate, with at most 3 retries before the message is dropped or
+    sent to the dead letter queue.
+  - Queues conformance: 17/46 before, 41/46 after, standalone and through `sproutboat dev`.
+    The other 5 cases follow Cloudflare's documented behaviour where miniflare differs: real
+    backlog metrics, and first call wins.
+
+### Changed
+
+- `types/sproutboat.d.ts`: the Queues types follow Workers (`QueueSendResult`,
+  `QueueMetrics`, readonly message fields, `metadata`, retry options).
+
 ## [0.32.0] - 2026-10-25
 
 Built on `@sproutboat/runtime` 0.31.0, `@sproutboat/toolchain` 0.16.1 and

package/README.md

@@ -129,7 +129,7 @@ complete export. Existing output files require `--force`.
   "kv_namespaces": ["CACHE"],                 // bare name, or { "binding": "CACHE", "id": "kv_..." }
   "d1_databases": ["DB"],
   "r2_buckets": ["UPLOADS"],
-  "queues": ["JOBS"],
+  "queues": ["JOBS"],                         // or { "binding": "JOBS", "queue": "jobs", "max_retries": 3, "dead_letter_queue": "failed" }
   "analytics_engine_datasets": ["METRICS"],   // bare name only, no id
   "durable_objects": { "COUNTER": "Counter" },
   "ratelimiters": [{ "binding": "API", "limit": 100, "period": 60 }], // env.API.limit({ key })

package/SURFACE.md

@@ -3,7 +3,7 @@
 > Generated by `src/surface.test.ts` from `src/surface.ts` + the pinned
 > toolchain constants. Do not edit by hand — run `UPDATE_SURFACE=1 bun test`.
 
-**Package:** `sproutboat` 0.32.0
+**Package:** `sproutboat` 0.33.0
 
 ## Commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "keywords": [
     "cli",
@@ -63,10 +63,10 @@
   "dependencies": {
     "@sproutboat/artifact": "^0.3.0",
     "@sproutboat/assets": "^0.3.0",
-    "@sproutboat/config": "^0.5.0",
-    "@sproutboat/runtime": "^0.31.0",
+    "@sproutboat/config": "^0.6.0",
+    "@sproutboat/runtime": "^0.32.0",
     "@sproutboat/toolchain": "^0.16.1",
-    "@sproutboat/wire": "^0.19.1"
+    "@sproutboat/wire": "^0.20.0"
   },
   "devDependencies": {
     "@oxlint/plugins": "1.85.0",
@@ -78,10 +78,10 @@
     "typescript": "7.0.2"
   },
   "optionalDependencies": {
-    "@sproutboat/cli-darwin-arm64": "0.32.0",
-    "@sproutboat/cli-darwin-x64": "0.32.0",
-    "@sproutboat/cli-linux-arm64": "0.32.0",
-    "@sproutboat/cli-linux-x64": "0.32.0"
+    "@sproutboat/cli-darwin-arm64": "0.33.0",
+    "@sproutboat/cli-darwin-x64": "0.33.0",
+    "@sproutboat/cli-linux-arm64": "0.33.0",
+    "@sproutboat/cli-linux-x64": "0.33.0"
   },
   "engines": {
     "node": ">=18"

package/src/build.ts

@@ -3,7 +3,7 @@ import { NATIVE_RESTORE_IDENTITY } from "./native-restore";
 import { cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { readAssetRules, walkAssets, type AssetManifest } from "./assets";
-import { resourceRefs, type SproutboatConfig } from "./config";
+import { queueSettings, resourceRefs, type SproutboatConfig } from "./config";
 import { ensureSqliteObject } from "./sqlite";
 import { sqliteStamp } from "./sqlite";
 import { bearsslStamp, ensureBearssl } from "./bearssl";
@@ -149,6 +149,9 @@ async function prepareBuild(input: BuildInput) {
     d1: refsByKind.d1.map((ref) => ref.binding),
     r2: refsByKind.r2.map((ref) => ref.binding),
     queues: refsByKind.queue.map((ref) => ref.binding),
+    // Each queue's name and consumer settings (runtime 0.32): the sprout names batches and
+    // applies retries with them, the broker batches with them. Older readers ignore it.
+    queueConfig: queueSettings(input.config.queues),
     analytics: input.config.analytics_engine_datasets ?? [],
     do: Object.entries(input.config.durable_objects ?? {}).map(([binding, className]) => ({ binding, className })),
     services: input.config.services ?? [],

package/types/sproutboat.d.ts

@@ -174,31 +174,64 @@ declare global {
 
   // ------------------------------------------------------------ Queues
 
+  type QueuesContentType = "json" | "text" | "bytes" | "v8";
+
   interface QueueSendOptions {
     delaySeconds?: number;
+    /** From compatibility date 2026-10-31. */
+    contentType?: QueuesContentType;
+  }
+
+  /** Cloudflare's QueueMetrics; `oldestMessageTimestamp` in ms since the epoch. */
+  interface QueueMetrics {
+    backlogCount: number;
+    backlogBytes: number;
+    oldestMessageTimestamp?: number;
   }
 
+  interface QueueSendResult {
+    metadata: { metrics: QueueMetrics };
+  }
+
+  /**
+   * From compatibility date 2026-10-31, send() and sendBatch() return Promises of the queue's
+   * backlog after the send, as on Workers; earlier dates return nothing at once.
+   */
   interface Queue<Body = unknown> {
-    /** Returns immediately. The batch reaches `queue()` out of band. */
-    send(body: Body, options?: QueueSendOptions): void;
-    sendBatch(messages: Array<{ body: Body; delaySeconds?: number }>): void;
+    send(body: Body, options?: QueueSendOptions): Promise<QueueSendResult>;
+    sendBatch(
+      messages: Iterable<{ body: Body; delaySeconds?: number; contentType?: QueuesContentType }>,
+      options?: { delaySeconds?: number },
+    ): Promise<QueueSendResult>;
+    /** From compatibility date 2026-10-31. */
+    metrics(): Promise<QueueMetrics>;
+  }
+
+  interface QueueRetryOptions {
+    delaySeconds?: number;
   }
 
   interface QueueMessage<Body = unknown> {
-    id: string;
-    timestamp: number;
-    body: Body;
-    /** Mark as handled. A message neither acked nor retried counts as acked. */
+    readonly id: string;
+    /** When it was sent: a Date from compatibility date 2026-10-31, epoch ms before. */
+    readonly timestamp: Date;
+    readonly body: Body;
+    /** 1 on the first delivery. */
+    readonly attempts: number;
+    /** Mark as handled. A message neither acked nor retried counts as acked (retried if queue() throws). */
     ack(): void;
-    /** Hand it back for another attempt. */
-    retry(): void;
+    /** Hand it back for another attempt. The first of ack() and retry() wins. */
+    retry(options?: QueueRetryOptions): void;
   }
 
   interface MessageBatch<Body = unknown> {
-    queue: string;
-    messages: Array<QueueMessage<Body>>;
+    /** The queue's name (`queue` in sproutboat.jsonc, else the binding name). */
+    readonly queue: string;
+    readonly messages: ReadonlyArray<QueueMessage<Body>>;
+    /** From compatibility date 2026-10-31. */
+    readonly metadata: { metrics: QueueMetrics };
     ackAll(): void;
-    retryAll(): void;
+    retryAll(options?: QueueRetryOptions): void;
   }
 
   // --------------------------------------------------- Durable Objects