durable objects & queues

9 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Durable Objects in Pages requires separate Worker

To use Durable Objects with Cloudflare Pages, you must create a separate Worker with a Durable Object and declare a binding to it in both Production and Preview environments. Using Durable Objects with Workers is simpler and recommended.

Queue Consumers only supported in Workers

Queue Consumers are only supported in Cloudflare Workers, not in Pages. Queue Producers are supported in both.

Use Queues for single-step async and background work

Use Queues when you need to decouple a producer from a consumer. Queues are a message broker: one Worker sends a message, another Worker processes it later. They are the right choice for fan-out (one event triggers many consumers), buffering and batching (aggregate messages before writing to a downstream service), and simple single-step background jobs (send an email, fire a webhook, write a log). Queues provide at-least-once delivery with configurable retries per message.

Use Workflows for multi-step durable background work

Use Workflows when the background work has multiple steps that depend on each other. Workflows are a durable execution engine: each step's return value is persisted, and if a step fails, only that step is retried—not the entire job. They are the right choice for multi-step processes (charge a card, then create a shipment, then send a confirmation), long-running tasks that need to pause and resume (wait hours or days for an external event or human approval via step.waitForEvent()), and complex conditional logic where later steps depend on earlier results. Workflows can run for hours, days, or weeks.

Use Queues and Workflows together for high-throughput processing

Use Queues and Workflows together when a high-throughput entry point feeds into complex processing. For example, a Queue can buffer incoming orders, and the consumer can create a Workflow instance for each order that requires multi-step fulfillment.

Durable Objects with Hibernation API for WebSockets

Use Durable Objects with the Hibernation API for reliable, long-lived WebSocket connections. Plain Workers can upgrade HTTP connections to WebSockets, but they lack persistent state and hibernation. If the isolate is evicted, the connection is lost. Durable Objects keep WebSocket connections open even while the object is evicted from memory, and automatically wake up when a message arrives. Use this.ctx.acceptWebSocket() instead of ws.accept() to enable hibernation. Use setWebSocketAutoResponse for ping/pong heartbeats that do not wake the object.

runInDurableObject replaces Durable Object helper functions

The functions getMiniflareDurableObjectStorage(), getMiniflareDurableObjectState(), getMiniflareDurableObjectInstance(), and runWithMiniflareDurableObjectGates() are all replaced with a single runInDurableObject() function from the 'cloudflare:test' module. This function accepts a DurableObjectStub with a callback accepting the Durable Object instance and corresponding DurableObjectState as arguments, ensuring instances are accessed with the correct request context and gating behavior.

runDurableObjectAlarm replaces flushMiniflareDurableObjectAlarms

The flushMiniflareDurableObjectAlarms() function is replaced with runDurableObjectAlarm() from the 'cloudflare:test' module. This function accepts a single DurableObjectStub and returns a Promise that resolves to true if an alarm was scheduled and the alarm() handler was executed, or false otherwise. To flush multiple instances' alarms, call runDurableObjectAlarm() in a loop.

listDurableObjectIds replaces getMiniflareDurableObjectIds

The getMiniflareDurableObjectIds() function is replaced with listDurableObjectIds() from the 'cloudflare:test' module. The new function accepts a DurableObjectNamespace instance instead of a namespace string for stricter typing. The listDurableObjectIds() function respects storage isolation, so IDs of objects created in other test files will not be returned.

Give your agent this brain