A Cloudflare Durable Object handles one event at a time, yet two document edits that each await a call to another service overwrite each other; why?
answer
- single-threaded is not one-request-at-a-time
- what an await lets in
- input gates around storage
- read, await elsewhere, write
- finish outside I/O first
basics
~20 sA Durable Object runs one piece of JavaScript at a time, but awaiting non-storage I/O such as fetch() or another object's stub lets other requests run; input gates only hold events back during the object's own storage calls.
solid answer
~40 sA Durable Object is single-threaded and cooperatively multitasked: while one request's code runs synchronously nothing else runs, but at every `await` other events may be delivered. Cloudflare adds **input gates**: while the object awaits its own storage (`ctx.storage.get()` / `put()`), new events are held back, so a storage-only read-modify-write is safe, and `ctx.storage.sql.exec()` is synchronous and never yields at all. An `await fetch()` to a permissions service, or an RPC call to another object, is not storage, so the gate opens and a second edit can read the same old revision. Both then write `revision + 1` and one edit is lost. Fix it by doing the outside call first and then reading and writing with no `await` in between, or by re-checking the revision after the await.
code
javascript · 49 linesimport { DurableObject } from "cloudflare:workers";
export class AccessList extends DurableObject {
async canEdit(userId) {
return userId.startsWith("user-");
}
}
export class DocumentRoom extends DurableObject {
constructor(ctx, env) {
super(ctx, env);
ctx.storage.sql.exec(
"CREATE TABLE IF NOT EXISTS doc (id INTEGER PRIMARY KEY, version INTEGER NOT NULL)"
);
ctx.storage.sql.exec("INSERT OR IGNORE INTO doc (id, version) VALUES (1, 0)");
}
// Racy: reads, awaits another object, then writes what it read earlier.
async applyEditRacy(userId) {
const { version } = this.ctx.storage.sql.exec("SELECT version FROM doc WHERE id = 1").one();
const allowed = await this.env.ACL.getByName("acl").canEdit(userId);
if (!allowed) throw new Error("forbidden");
this.ctx.storage.sql.exec("UPDATE doc SET version = ? WHERE id = 1", version + 1);
return version + 1;
}
// Safe: finish the outside call first, then read and write with no await between.
async applyEdit(userId) {
const allowed = await this.env.ACL.getByName("acl").canEdit(userId);
if (!allowed) throw new Error("forbidden");
const { version } = this.ctx.storage.sql.exec("SELECT version FROM doc WHERE id = 1").one();
this.ctx.storage.sql.exec("UPDATE doc SET version = ? WHERE id = 1", version + 1);
return version + 1;
}
async version() {
return this.ctx.storage.sql.exec("SELECT version FROM doc WHERE id = 1").one().version;
}
}
export default {
async fetch(request, env) {
const url = new URL(request.url);
const mode = url.searchParams.get("mode") === "racy" ? "applyEditRacy" : "applyEdit";
const doc = env.DOCUMENT.getByName(`doc-${mode}`);
await Promise.all(Array.from({ length: 10 }, (_, i) => doc[mode](`user-${i}`)));
return Response.json({ mode, edits: 10, version: await doc.version() });
},
};go deeper
Recall that a Durable Object runs one piece of JavaScript at a time, but an await can let another request in.
Explain input gates: storage awaits hold new events back, sql.exec() never yields, and other awaits such as fetch() let requests interleave.
Diagnose silent lost updates by finding non-storage awaits between a read and its write, and fix them by reordering or re-checking.
Set a team rule for object methods: no outside I/O between reading and writing shared state, and reviews that look for it.
## Single-threaded does not mean one request at a time Each **Durable Object** instance runs its JavaScript on a single thread, like code in a browser tab. Two requests never execute JavaScript *simultaneously*. But JavaScript is **cooperatively multitasked**: whenever a method reaches an `await`, it yields, and the runtime may deliver another event (an RPC call, a `fetch()` to the object, an alarm) to the same instance before the first method resumes. So requests can **interleave** at await points. That is the trap in the question. A document object does this: 1. Read the current revision from storage. 2. `await` a permissions check on another service (a `fetch()`, or an RPC to another Durable Object). 3. Write `revision + 1`. While edit A waits in step 2, edit B arrives, reads the *same* revision, and also waits. Both resume and write the same `revision + 1`. One edit silently vanishes. Firing ten concurrent edits at such a method under `wrangler dev` leaves the revision at 1, not 10. ## What input gates protect, and what they do not Cloudflare's runtime adds **input gates** so that the common case is correct without locks: - While an object is waiting on **its own storage** (the asynchronous key-value calls `ctx.storage.get()`, `put()`, `delete()`), the input gate is closed: no new events are delivered until the storage call completes and the method continues. A read-modify-write made only of storage calls is therefore safe. - The SQL API, `ctx.storage.sql.exec()`, is **synchronous**: it never yields, so a run of SQL statements with no `await` between them cannot be interrupted. - Any **other** asynchronous work opens the gate: `fetch()`, an RPC call through another object's stub, a call to a different binding, a timer. Other events may run during that await. | Awaited operation | Can another request run meanwhile? | |---|---| | `await this.ctx.storage.get("rev")` | No, the input gate holds new events | | `this.ctx.storage.sql.exec(...)` (no await) | No, it is synchronous | | `await fetch("https://...")` | Yes | | `await this.env.ACL.getByName("acl").canEdit(id)` | Yes | | `await new Promise(r => setTimeout(r, 10))` | Yes | A companion mechanism, the **output gate**, holds the object's outgoing messages until its pending storage writes are durable; that, along with `blockConcurrencyWhile()`, belongs with the object's storage. ## Fixing the lost update Pick the cheapest option that fits: - **Reorder.** Do the outside call first, then read and write with no `await` between them. Because SQL calls are synchronous (and storage awaits keep the gate closed), the read-check-write becomes atomic with respect to other requests. - **Re-check after the await.** If the decision depends on state read before the outside call, read the revision again afterwards and reject or retry when it moved (optimistic concurrency). - **Express the change as one statement.** `UPDATE doc SET revision = revision + 1` does not depend on a value held in a JavaScript variable across an await. - **Avoid holding in-memory fields across an await.** A class field read before the await and written after it has exactly the same race. The heavy-handed alternative is blocking every other event until the method finishes. That serialises the object completely and, held across a slow external call, cuts its throughput to roughly one request per call duration; it is a last resort, not the default. ## How to diagnose it in production - The symptom is **missing writes without errors**: two clients both get success, but only one change is visible. - Look for any `await` that is not a storage call between a read and the write that depends on it. - Check helper methods too: an innocent-looking `await this.audit(...)` that posts to a logging endpoint opens the gate just as a permissions call does. - Reproduce locally with `Promise.all()` over a handful of concurrent calls to one stub; the race shows up immediately in `wrangler dev`. The interview point is precise: the actor-style guarantee is about *one event executing at a time*, and Cloudflare's input gates extend it across storage awaits, not across every await.
- Is a read-modify-write that awaits ctx.storage.get() and then ctx.storage.put() safe in a Durable Object?Yes, as long as nothing else is awaited in between. While the object waits on its own storage, the input gate holds new events back, so no other request can read the old value in that window. Insert a fetch() or another object's call between the two and the protection is gone.
- Does creating a new stub per request in the calling Worker prevent this race?No. Every stub for that ID reaches the same single instance, and the interleaving happens inside the object at its await points. The fix belongs in the object's method: reorder the outside call, re-check after it, or make the update a single statement.
- A Durable Object runs each request start to finish before the next one
- Input gates protect every await, including fetch() to another service
- Awaiting ctx.storage.get() lets other requests change the value meanwhile
- The runtime throws an error when two requests interleave
- Using a new stub per request serialises the object's methods