Cloudflare Durable Objects: A Deep Dive

┌─────────────────────────────────────────┐
│         Durable Object "room:lobby"     │
│                                         │
│  ┌─────────────┐    ┌────────────────┐  │
│  │  Compute    │    │  Storage       │  │
│  │  (JS code)  │◄──►│  (SQLite/KV)   │  │
│  │             │    │                │  │
│  │  + memory   │    │  private to    │  │
│  │  state      │    │  this object   │  │
│  └─────────────┘    └────────────────┘  │
└─────────────────────────────────────────┘
         ▲
         │ requests processed one-at-a-time
    ┌────┴────┐
    │ Client  │
    └─────────┘

Traditional (Shared State):        Actor Model:
┌──────────────────┐              ┌─────────┐  ┌─────────┐
│   Shared State   │              │ Actor A │  │ Actor B │
│   (database)     │              │ state   │  │ state   │
└────────┬─────────┘              └────┬────┘  └────┬────┘
    ▲    │    ▲                        │            │
    │    │    │                        └─────►◄─────┘
┌───┴────┴────┴───┐                      messages
│ Thread Thread   │
│ (locks needed)  │
└─────────────────┘

// Traditional: Race condition possible
async function incrementCounter(db, userId) {
  const count = await db.get(userId);  // Thread 1 reads: 5
  // Thread 2 also reads: 5
  await db.set(userId, count + 1);     // Thread 1 writes: 6
  // Thread 2 writes: 6 (should be 7!)
}
 
// Durable Object: No race condition
export class Counter {
  async increment() {
    const count = await this.state.storage.get("count") || 0;
    await this.state.storage.put("count", count + 1);
    // Single-threaded: always correct
  }
}

Request arrives
     │
     ▼
┌─────────────────┐
│  constructor()  │  ← Object created, in-memory state initialized
│  runs           │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Active         │  ← Processing requests, storage + memory available
│  (in memory)    │
└────────┬────────┘
         │
         │ 70-140 seconds idle
         ▼
┌─────────────────┐
│  Evicted        │  ← In-memory state LOST, storage KEPT
│  (inactive)     │
└────────┬────────┘
         │
         │ next request arrives
         ▼
┌─────────────────┐
│  constructor()  │  ← Recreated, read state back from storage
│  runs again     │
└─────────────────┘

await this.state.storage.deleteAll();
await this.state.storage.deleteAlarm(); // if alarms were set
// Object will be garbage collected after eviction

export class UserSession {
  constructor(state, env) {
    this.state = state;
    this.cache = null;  // ⚠️ In-memory, will be lost
  }
 
  async fetch(request) {
    // ✅ Persists forever
    await this.state.storage.put("lastSeen", Date.now());
 
    // ⚠️ Lost after ~2 min idle
    this.cache = { expensive: "computation" };
 
    // ✅ Pattern: Hydrate from storage if needed
    if (!this.cache) {
      this.cache = await this.state.storage.get("cachedData");
    }
  }
}

D1 (Traditional):               Durable Objects:
┌─────────────────────┐        ┌──────────┐ ┌──────────┐ ┌──────────┐
│  users table        │        │ user:1   │ │ user:2   │ │ user:3   │
│  ┌────┬──────────┐  │        │ ┌──────┐ │ │ ┌──────┐ │ │ ┌──────┐ │
│  │ 1  │ alice    │  │        │ │SQLite│ │ │ │SQLite│ │ │ │SQLite│ │
│  │ 2  │ bob      │  │        │ └──────┘ │ │ └──────┘ │ │ └──────┘ │
│  │ 3  │ charlie  │  │        └──────────┘ └──────────┘ └──────────┘
│  └────┴──────────┘  │              ▲           ▲           ▲
└─────────────────────┘         isolated    isolated    isolated
         ▲
    query across

// ✅ D1 can do this
SELECT * FROM users WHERE country = 'Japan'
SELECT COUNT(*) FROM orders WHERE status = 'pending'
SELECT * FROM products ORDER BY price LIMIT 10
 
// ❌ Durable Objects cannot query across objects
// You must know the object ID upfront

// Object ID: room:{roomId}
export class ChatRoom {
  constructor(state, env) {
    this.state = state;
    this.sessions = [];  // Active WebSocket connections
  }
 
  async fetch(request) {
    if (request.headers.get("Upgrade") === "websocket") {
      const [client, server] = Object.values(new WebSocketPair());
      this.sessions.push(server);
      server.accept();
 
      server.addEventListener("message", async (event) => {
        // Save to SQLite
        await this.state.storage.sql.exec(
          "INSERT INTO messages (text, ts) VALUES (?, ?)",
          event.data, Date.now()
        );
 
        // Broadcast to all — no race conditions!
        for (const session of this.sessions) {
          session.send(event.data);
        }
      });
 
      return new Response(null, { status: 101, webSocket: client });
    }
  }
}

// Object ID: ratelimit:{identifier}
export class RateLimiter {
  async fetch(request) {
    const now = Date.now();
    const window = 60000; // 1 minute
    const limit = 100;
 
    const count = await this.state.storage.get("count") || 0;
    const windowStart = await this.state.storage.get("window") || now;
 
    // Reset window if expired
    if (now - windowStart > window) {
      await this.state.storage.put("count", 1);
      await this.state.storage.put("window", now);
      return Response.json({ allowed: true, remaining: limit - 1 });
    }
 
    // Check limit
    if (count >= limit) {
      return Response.json({ allowed: false, remaining: 0 }, { status: 429 });
    }
 
    // Increment — single-threaded, always accurate
    await this.state.storage.put("count", count + 1);
    return Response.json({ allowed: true, remaining: limit - count - 1 });
  }
}

// Object ID: lock:{resourceId}
export class DistributedLock {
  async fetch(request) {
    const { action, owner, ttl } = await request.json();
 
    if (action === "acquire") {
      const currentOwner = await this.state.storage.get("owner");
      const expiry = await this.state.storage.get("expiry");
 
      // Check if lock is held
      if (currentOwner && Date.now() < expiry) {
        return Response.json({ acquired: false, owner: currentOwner });
      }
 
      // Acquire lock
      await this.state.storage.put("owner", owner);
      await this.state.storage.put("expiry", Date.now() + ttl);
      return Response.json({ acquired: true });
    }
 
    if (action === "release") {
      const currentOwner = await this.state.storage.get("owner");
      if (currentOwner === owner) {
        await this.state.storage.delete("owner");
        await this.state.storage.delete("expiry");
        return Response.json({ released: true });
      }
      return Response.json({ released: false, error: "not owner" });
    }
  }
}

// Object ID: order:{orderId}
export class Order {
  async fetch(request) {
    const { event } = await request.json();
    const state = await this.state.storage.get("status") || "created";
 
    // State machine transitions
    const transitions = {
      created: { pay: "paid", cancel: "cancelled" },
      paid: { ship: "shipped", refund: "refunded" },
      shipped: { deliver: "delivered" },
    };
 
    const nextState = transitions[state]?.[event];
 
    if (!nextState) {
      return Response.json({ error: `Invalid transition: ${state} -> ${event}` }, { status: 400 });
    }
 
    // Update state and log history
    await this.state.storage.put("status", nextState);
    await this.state.storage.sql.exec(
      "INSERT INTO history (from_state, to_state, event, ts) VALUES (?, ?, ?, ?)",
      state, nextState, event, Date.now()
    );
 
    return Response.json({ previousState: state, currentState: nextState });
  }
}

// Object ID: doc:{docId}
// Combines: D1 (metadata), R2 (content), Durable Object (real-time)
export class Document {
  constructor(state, env) {
    this.state = state;
    this.env = env;
    this.editors = [];
    this.pendingChanges = [];
  }
 
  async fetch(request) {
    if (request.headers.get("Upgrade") === "websocket") {
      return this.handleWebSocket(request);
    }
 
    // HTTP: Get current document
    const content = await this.env.R2.get(`docs/${this.docId}`);
    return new Response(content.body);
  }
 
  async handleEdit(change) {
    this.pendingChanges.push(change);
 
    // Broadcast immediately to other editors
    this.editors.forEach(e => e.send(JSON.stringify(change)));
 
    // Batch save every 5 seconds
    if (!this.saveScheduled) {
      await this.state.storage.setAlarm(Date.now() + 5000);
      this.saveScheduled = true;
    }
  }
 
  async alarm() {
    // Merge changes and save to R2
    const merged = this.mergeChanges(this.pendingChanges);
    await this.env.R2.put(`docs/${this.docId}`, merged);
 
    // Update metadata in D1
    await this.env.DB.prepare(
      "UPDATE documents SET updated_at = ? WHERE id = ?"
    ).bind(Date.now(), this.docId).run();
 
    this.pendingChanges = [];
    this.saveScheduled = false;
  }
}

flowchart TB
    Q1{"Do you need to query<br/>across multiple entities?"}
    Q1 -->|Yes| D1_1["Use D1"]
    Q1 -->|No| Q2{"Do you need real-time<br/>coordination or WebSockets?"}
    Q2 -->|Yes| DO_1["Durable Objects ✓"]
    Q2 -->|No| Q3{"Is data naturally isolated<br/>per user/session/resource?"}
    Q3 -->|Yes| DO_2["Durable Objects ✓<br/>(simpler, colocated)"]
    Q3 -->|No| D1_2["Use D1"]

D1 = queryable data (users, products, history)
Durable Objects = real-time features (chat, collaboration)

R2 = blob storage (files, images)
D1 = metadata, search index
Durable Objects = real-time editing sessions

Good for: rate limiting, distributed locks, counters
Each object is independent, no cross-querying needed