In Cloudflare Queues, how does a producer Worker send an order event, and how does a consumer Worker receive it?
answer
- two config arrays, one per role
- a binding method on env
- a third handler beside fetch
- batch.messages, each with four fields
basics
~20 sA producer Worker binds the queue under queues.producers and calls env.ORDERS.send(body) or sendBatch(); a consumer Worker listed under queues.consumers exports a queue(batch, env, ctx) handler and reads batch.messages, each with id, timestamp, attempts and body.
solid answer
~40 sBoth sides are configured in the Wrangler file. The producer gets a binding in `queues.producers` (`binding` plus `queue`), and code calls `await env.ORDERS.send(order)` for one message or `env.ORDERS.sendBatch([{ body }])` for up to 100; the promise resolves once the message is written to disk. The consumer Worker is attached with an entry in `queues.consumers` and exports `queue(batch, env, ctx)` beside `fetch`. Cloudflare pushes messages in batches: `batch.queue` names the queue and `batch.messages` holds `Message` objects with a system-generated `id`, a `timestamp` `Date`, the `attempts` count starting at 1, and the `body`. Delivery is at-least-once and ordering is best effort, so the consumer should key its writes on a field the producer put in the body, such as the order ID.
code
json · 9 lines{
"name": "orders-ingest",
"main": "src/index.js",
"compatibility_date": "2026-10-10",
"queues": {
"producers": [{ "binding": "ORDERS", "queue": "orders" }],
"consumers": [{ "queue": "orders" }]
}
}go deeper
Recall the two config arrays, the send() and sendBatch() binding methods, and the queue(batch, env, ctx) handler with the four message fields.
Explain that send() resolves only once the message is stored, that one queue has one active consumer, and that ordering is best effort.
Show how at-least-once delivery shapes the consumer: deduplicate on a producer-supplied business key, never on the system-generated message.id.
Frame when a producer and consumer should be separate Workers with separate deploys, and how body schemas are versioned so old and new consumers both read them.
## Two roles, one queue **Cloudflare Queues** is a message queue that Workers write to and read from. A Worker that writes is a **producer**; a Worker that reads is a **consumer**. One Worker can be both, and in the order-ingestion example below one API Worker enqueues order events while a separate fulfilment Worker drains them into a database. A queue is created once, for example with `wrangler queues create orders`, and then each Worker declares how it relates to that queue in its Wrangler configuration file. ## The producer side A producer needs a **binding**: an entry in the `queues.producers` array with a `binding` name (the property that appears on `env`) and the `queue` name. The binding object exposes three methods: - `send(body, options?)` writes one message. The body can be any value the structured clone algorithm supports, and it must stay under **128 KB** (1 KB here is 1,000 bytes, and about 100 bytes of internal metadata count toward it). - `sendBatch(messages, options?)` writes many at once. Each item is a `MessageSendRequest` of the form `{ body, contentType?, delaySeconds? }`; a call carries at most **100 messages** and at most **256 KB** in total. - `metrics()` returns the queue's current `backlogCount`, `backlogBytes` and oldest message timestamp. Both send methods return a promise that resolves **when the message is confirmed written to disk**, and rejects when the write fails, for example when the producer exceeds the per-queue throughput limit (5,000 messages per second) and gets a `Too Many Requests` error. Awaiting that promise before answering the client is what makes "accepted" mean "stored". ## The consumer side A consumer is a Worker with a `queue()` handler on its default export, connected to the queue by an entry in `queues.consumers` (or with `wrangler queues consumer add`). Each queue has **one active consumer**, but one consumer Worker may serve several queues and branch on `batch.queue`. Cloudflare does not invoke the handler for an empty queue; it **pushes** batches when messages are waiting. The handler receives a `MessageBatch`: | Member | What it holds | |---|---| | `batch.queue` | the name of the queue this batch came from | | `batch.messages` | a read-only array of `Message` objects | | `message.id` | a unique, system-generated ID | | `message.timestamp` | a `Date` recording when the message was sent | | `message.attempts` | how many times delivery has been attempted, starting at 1 | | `message.body` | the deserialised body the producer sent | `batch.ackAll()`, `batch.retryAll()`, `message.ack()` and `message.retry()` also live here; how they work, and what happens when the handler throws, is covered with Queues failure handling. ## Two promises the platform does not make 1. **Exactly-once delivery.** Queues delivers **at least once**: a message can, rarely, arrive twice. Because `message.id` is generated by Queues, a producer that resends after a failed call creates a second message with a new ID. The safer deduplication key is a value the producer put in the body, such as `orderId`, used as the primary key of the insert. 2. **Ordering.** The order of `batch.messages` is best effort and is not guaranteed to match publish order. A consumer that needs the latest state of an order should compare a version or timestamp carried in the body, not rely on array position. ## First mistakes to avoid - **Putting the binding in the wrong array.** `queues.producers` creates `env.ORDERS`; `queues.consumers` attaches a `queue()` handler. A producer listed only under `consumers` has no `send()` to call. - **Not awaiting `send()`.** An unawaited send can fail without the client ever hearing about it, so the API's `202` stops meaning "stored". - **Expecting a schedule.** The consumer runs when messages are waiting, not on a timer; with an empty queue it does not run at all. - **Sending values JSON cannot carry.** With the default `json` content type, a `Date` arrives as a string and a `Map` as an empty object. - **Treating a batch as a transaction.** A batch is a delivery unit, not a guarantee that its messages belong together or arrive together. ## Putting it together The configuration below declares both roles in one Worker for brevity; in production the producer and consumer are often separate Workers, each with only its own half of the `queues` block. The `queues` key is not inherited by named Wrangler environments, so each environment must declare it again. - Producer: `fetch` validates the order and awaits `env.ORDERS.send(order)`, then returns `202`. - Consumer: `queue` walks `batch.messages` and writes each `message.body` keyed on `orderId`. - Typing: in TypeScript, `Queue<Order>` on the producer and `ExportedHandler<Env, Order>` on the consumer type `message.body`. The older Service Worker form, `addEventListener('queue', ...)`, still exists but is deprecated; new consumers use the ES module `export default { queue }` handler shown here.
- Can one consumer Worker read from several Cloudflare queues, and how does it tell their batches apart?Yes. Add one `queues.consumers` entry per queue to the same Worker. Each invocation still carries messages from a single queue, and `batch.queue` holds that queue's name, so the handler can `switch (batch.queue)` and route log events, order events and email jobs to different code. Each queue still has only one active consumer.
- Why is message.id a poor key for deduplicating orders written by a Cloudflare Queues consumer?Queues generates `message.id` when the message is written. If a producer's `send()` fails mid-flight and the code sends again, the second copy gets a new ID even though it is the same order. A business key the producer puts in the body, such as `orderId`, stays the same across resends and redeliveries, so it makes the right primary key.
- The consumer Worker polls the queue from its fetch handler.
- A queue can have several active Worker consumers sharing the load.
- Messages arrive in exactly the order the producer sent them.
- message.attempts starts at 0 on the first delivery.
- The queue binding goes under queues.consumers on the producer Worker.