Cloudflare Durable Objects - Single-Instance Actors, Edge State & When to Use Them

// Front Worker: stateless router. Picks WHICH object handles a request, then calls it over RPC.
import { ChatRoom } from "./chat";
import { Counter, shardedIncrement, shardedRead } from "./counter";
import { RateLimiter } from "./ratelimit";
import { LeaseLock } from "./lease";
import { Inventory } from "./inventory";

export { ChatRoom, Counter, RateLimiter, LeaseLock, Inventory };

export interface Env {
  CHAT_ROOM: DurableObjectNamespace<ChatRoom>;
  COUNTER: DurableObjectNamespace<Counter>;
  RATE_LIMITER: DurableObjectNamespace<RateLimiter>;
  LEASE: DurableObjectNamespace<LeaseLock>;
  INVENTORY: DurableObjectNamespace<Inventory>;
}

const json = (v: unknown, status = 200) =>
  new Response(JSON.stringify(v), { status, headers: { "content-type": "application/json" } });

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    const [, kind, name = "default", action = ""] = url.pathname.split("/");
    const q = url.searchParams;

    switch (kind) {
      case "chat": {
        // Validate in the Worker so junk requests are not billed against the object.
        if (request.headers.get("Upgrade") !== "websocket") return json({ error: "expected websocket" }, 426);
        // Same name => same object, worldwide. locationHint only matters on the very first get.
        const stub = env.CHAT_ROOM.getByName(`room:${name}`, { locationHint: "enam" });
        return stub.fetch(request); // WebSocket upgrades still go through fetch()
      }
      case "counter": {
        const stub = env.COUNTER.getByName(name);
        return json({ value: action === "inc" ? await stub.increment(Number(q.get("by") ?? 1)) : await stub.get() });
      }
      case "sharded": {
        const shards = Number(q.get("shards") ?? 8);
        if (action === "inc") return json({ shardValue: await shardedIncrement(env, name, shards) });
        return json(await shardedRead(env, name, shards));
      }
      case "rl": {
        const d = await env.RATE_LIMITER.getByName(`key:${name}`).take(5, 1); // burst 5, 1 token/sec
        return json(d, d.allowed ? 200 : 429);
      }
      case "lease": {
        const stub = env.LEASE.getByName(`lock:${name}`);
        if (action === "acquire") return json(await stub.acquire(q.get("owner") ?? "?", Number(q.get("ttl") ?? 30000)));
        if (action === "release") return json({ released: await stub.release(q.get("owner") ?? "?", Number(q.get("token"))) });
        return json({ error: "unknown action" }, 400);
      }
      case "inv": {
        const stub = env.INVENTORY.getByName(`sku:${name}`);
        if (action === "reset") { await stub.reset(Number(q.get("qty") ?? 3)); return json({ qty: await stub.qty() }); }
        if (action === "racy") return json({ result: await stub.reserveRacy() });
        if (action === "claim") return json({ result: await stub.reserveClaimFirst() });
        if (action === "cas") return json({ result: await stub.reserveCas() });
        return json({ qty: await stub.qty() });
      }
    }
    return json({ error: "not found" }, 404);
  },
} satisfies ExportedHandler<Env>;

// Counter: one object per counter name. Sharded counters spread one hot name across N objects.
import { DurableObject } from "cloudflare:workers";
import type { Env } from "./index";

export class Counter extends DurableObject<Env> {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    ctx.blockConcurrencyWhile(async () => {
      ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS kv(k TEXT PRIMARY KEY, v INTEGER NOT NULL)");
    });
  }

  // RPC method: callers do `await stub.increment(5)`; no Request/Response parsing.
  increment(by = 1): number {
    // UPSERT + RETURNING is one synchronous statement: atomic, no await, no interleaving.
    return this.ctx.storage.sql
      .exec("INSERT INTO kv(k, v) VALUES ('n', ?) ON CONFLICT(k) DO UPDATE SET v = v + excluded.v RETURNING v", by)
      .one().v as number;
  }

  get(): number {
    const rows = this.ctx.storage.sql.exec("SELECT v FROM kv WHERE k = 'n'").toArray();
    return rows.length ? (rows[0].v as number) : 0;
  }
}

// Worker-side helpers for a sharded counter: writes pick a random shard, reads fan in all shards.
export async function shardedIncrement(env: Env, name: string, shards: number): Promise<number> {
  const shard = Math.floor(Math.random() * shards);
  return env.COUNTER.getByName(`${name}#${shard}`).increment(1);
}

export async function shardedRead(env: Env, name: string, shards: number): Promise<{ total: number; perShard: number[] }> {
  const perShard = await Promise.all(
    Array.from({ length: shards }, (_, i) => env.COUNTER.getByName(`${name}#${i}`).get()),
  );
  return { total: perShard.reduce((a, b) => a + b, 0), perShard };
}

inc -> { value: 1 }
inc -> { value: 2 }
inc -> { value: 3 }
after 200 concurrent incs -> { value: 203 }
sharded total -> 400 perShard -> [43,52,64,41,40,49,54,57]

# SIMULATION (not Cloudflare code): how a name becomes exactly one live object, worldwide.
# Models: idFromName = deterministic hash, a global directory that records where an ID lives,
# and "create near the first caller". Latencies are illustrative example values, not measurements.
import hashlib

def id_from_name(namespace: str, name: str) -> str:
    # Real IDs are 64 hex digits derived from the name within one namespace; we mimic the shape.
    return hashlib.sha256(f"{namespace}/{name}".encode()).hexdigest()

directory = {}   # id -> colo hosting the single live instance
instances = {}   # id -> in-memory state of that instance

def call(caller_colo: str, namespace: str, name: str, op: str):
    oid = id_from_name(namespace, name)
    if oid not in directory:
        # first use of a NAMED id: the system must make sure nobody else created it elsewhere
        directory[oid] = caller_colo                 # created near the first caller
        instances[oid] = {"messages": []}
        route = f"created in {caller_colo} (first use, global uniqueness check)"
    else:
        route = f"routed {caller_colo} -> {directory[oid]}"
    instances[oid]["messages"].append(op)            # all ops land on the SAME instance
    return oid[:12], route, len(instances[oid]["messages"])

for colo, op in [("ORD", "alice: hi"), ("FRA", "bob: hallo"), ("SIN", "chen: hello"), ("ORD", "alice: welcome")]:
    print(colo, "->", *call(colo, "ChatRoom", "room:42", op))
print("other room ->", *call("FRA", "ChatRoom", "room:43", "dana: new room"))
print("same name, other class ->", id_from_name("Counter", "room:42")[:12], "(different namespace, different object)")
print("live instances:", len(instances), "| messages in room:42:", instances[id_from_name("ChatRoom", "room:42")]["messages"])

ORD -> 8f48c4f635be created in ORD (first use, global uniqueness check) 1
FRA -> 8f48c4f635be routed FRA -> ORD 2
SIN -> 8f48c4f635be routed SIN -> ORD 3
ORD -> 8f48c4f635be routed ORD -> ORD 4
other room -> 0e05675e891b created in FRA (first use, global uniqueness check) 1
same name, other class -> 8873a7984c55 (different namespace, different object)
live instances: 2 | messages in room:42: ['alice: hi', 'bob: hallo', 'chen: hello', 'alice: welcome']

// SIMULATION / decision helper (not Cloudflare code): pick a store from the requirements.
type Need = {
  coordination: boolean;      // many clients must see one serialized order of updates
  perEntityState: boolean;    // state partitions cleanly by user / room / tenant / doc
  readHeavyGlobal: boolean;   // mostly reads, tolerate ~60 s staleness across locations
  bigBlobs: boolean;          // files / media / large objects
  crossEntitySql: boolean;    // ad hoc queries and joins ACROSS all entities
  asyncWork: boolean;         // fire-and-forget jobs with retries
  realtime: boolean;          // WebSockets / presence
};

function choose(n: Need): string {
  if (n.bigBlobs) return "R2 (blob store), keep metadata elsewhere";
  if (n.asyncWork && !n.coordination) return "Queues (at-least-once jobs)";
  if (n.coordination || n.realtime) {
    if (n.crossEntitySql) return "Durable Objects for the hot path + D1/Postgres for reporting";
    return n.perEntityState ? "Durable Objects (one object per entity)" : "Durable Objects, but find a partition key first";
  }
  if (n.readHeavyGlobal) return "Workers KV (eventually consistent edge cache)";
  if (n.crossEntitySql) return "D1 or Postgres (one shared SQL database)";
  return "plain stateless Worker";
}

const base: Need = { coordination: false, perEntityState: false, readHeavyGlobal: false, bigBlobs: false, crossEntitySql: false, asyncWork: false, realtime: false };
const cases: [string, Partial<Need>][] = [
  ["chat room with presence", { coordination: true, realtime: true, perEntityState: true }],
  ["feature-flag config read on every request", { readHeavyGlobal: true }],
  ["seat booking per venue", { coordination: true, perEntityState: true }],
  ["user avatar uploads", { bigBlobs: true }],
  ["send welcome emails", { asyncWork: true }],
  ["finance dashboard across all tenants", { crossEntitySql: true }],
  ["per-tenant rate limit + monthly report", { coordination: true, perEntityState: true, crossEntitySql: true }],
  ["one global leaderboard, 50k writes/s", { coordination: true }],
];
for (const [name, n] of cases) console.log(name.padEnd(42), "->", choose({ ...base, ...n }));

chat room with presence                    -> Durable Objects (one object per entity)
feature-flag config read on every request  -> Workers KV (eventually consistent edge cache)
seat booking per venue                     -> Durable Objects (one object per entity)
user avatar uploads                        -> R2 (blob store), keep metadata elsewhere
send welcome emails                        -> Queues (at-least-once jobs)
finance dashboard across all tenants       -> D1 or Postgres (one shared SQL database)
per-tenant rate limit + monthly report     -> Durable Objects for the hot path + D1/Postgres for reporting
one global leaderboard, 50k writes/s       -> Durable Objects, but find a partition key first