Durable Objects Scaling - Sharding by ID, Hot Objects, Location Hints, Limits & Cost

# SIMULATION (not Cloudflare code): sizing shards for a hot counter.
# Per-object capacity uses the docs' guidance: soft limit ~1,000 req/s for simple work,
# ~200-500 req/s when each request writes storage. We plan with a conservative 400 req/s.
import math, random

PER_OBJECT = 400
for name, rps in [("per-user cart", 3), ("one chat room", 150), ("global like counter", 12_000), ("launch-day signup counter", 60_000)]:
    shards = max(1, math.ceil(rps / PER_OBJECT * 1.5))   # 1.5x headroom for skew and bursts
    print(f"{name:<26} {rps:>7,} req/s -> {shards:>4} object(s)")

# Random shard choice is not perfectly even: check the hottest shard against capacity.
random.seed(7)
rps, shards = 12_000, 45
counts = [0] * shards
for _ in range(rps):            # one second of traffic
    counts[random.randrange(shards)] += 1
print(f"12,000 req/s over {shards} shards: mean={rps / shards:.0f} hottest={max(counts)} coldest={min(counts)} (cap {PER_OBJECT})")
# Reads must fan in: one read = 45 RPCs. Cache the total for a few seconds if reads are frequent.
print(f"read cost: 1 total = {shards} RPCs; at 50 reads/s that is {50 * shards:,} RPCs/s -> cache it or roll up with an alarm")

per-user cart                    3 req/s ->    1 object(s)
one chat room                  150 req/s ->    1 object(s)
global like counter         12,000 req/s ->   45 object(s)
launch-day signup counter   60,000 req/s ->  225 object(s)
12,000 req/s over 45 shards: mean=267 hottest=313 coldest=234 (cap 400)
read cost: 1 total = 45 RPCs; at 50 reads/s that is 2,250 RPCs/s -> cache it or roll up with an alarm

// SIMULATION (not Cloudflare code): one global rate-limiter object vs one object per API key.
// Each object is single-threaded; we model it as a queue served at CAP req/s. Values are example numbers.
const CAP = 800;                      // what one object can serve per second for this workload
const keys = 50, perKeyRps = 60;      // 50 tenants x 60 req/s = 3,000 req/s total
const QUEUE_LIMIT = 2_000;            // beyond this the runtime answers "Durable Object is overloaded"

function simulate(objects: number, seconds: number) {
  const arrivalsPerObject = (keys * perKeyRps) / objects;
  let queue = 0, overloaded = 0, served = 0;
  for (let s = 0; s < seconds; s++) {
    queue += arrivalsPerObject;
    const done = Math.min(queue, CAP); served += done; queue -= done;
    if (queue > QUEUE_LIMIT) { overloaded += queue - QUEUE_LIMIT; queue = QUEUE_LIMIT; }
  }
  const waitSec = queue / CAP;
  return { objects, perObjectRps: arrivalsPerObject, served: Math.round(served * objects), overloadedErrors: Math.round(overloaded * objects), queueDelayMs: Math.round(waitSec * 1000) };
}
console.log("global singleton :", JSON.stringify(simulate(1, 10)));
console.log("per-key objects  :", JSON.stringify(simulate(keys, 10)));

global singleton : {"objects":1,"perObjectRps":3000,"served":8000,"overloadedErrors":20000,"queueDelayMs":2500}
per-key objects  : {"objects":50,"perObjectRps":60,"served":30000,"overloadedErrors":0,"queueDelayMs":0}

// RateLimiter: one object per (tenant or API key). Token bucket persisted in the object's SQLite.
import { DurableObject } from "cloudflare:workers";
import type { Env } from "./index";

export type Decision = { allowed: boolean; remaining: number; retryAfterMs: number };

export class RateLimiter extends DurableObject<Env> {
  private tokens = -1;  // in-memory copy; -1 means "not loaded yet" (fresh instance or after eviction)
  private updated = 0;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    ctx.blockConcurrencyWhile(async () => {
      ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS bucket(id INTEGER PRIMARY KEY CHECK(id = 1), tokens REAL, updated INTEGER)");
      const row = ctx.storage.sql.exec("SELECT tokens, updated FROM bucket").toArray()[0];
      if (row) { this.tokens = row.tokens as number; this.updated = row.updated as number; }
    });
  }

  // capacity = burst size, refillPerSec = sustained rate. Whole method is synchronous => atomic per key.
  take(capacity: number, refillPerSec: number, cost = 1): Decision {
    const now = Date.now();
    if (this.tokens < 0) { this.tokens = capacity; this.updated = now; }
    // Refill based on elapsed time, capped at capacity.
    this.tokens = Math.min(capacity, this.tokens + ((now - this.updated) / 1000) * refillPerSec);
    this.updated = now;
    let allowed = false;
    if (this.tokens >= cost) { this.tokens -= cost; allowed = true; }
    // Persist so an eviction cannot hand a client a fresh full bucket. Output gate holds the reply until durable.
    this.ctx.storage.sql.exec(
      "INSERT INTO bucket(id, tokens, updated) VALUES (1, ?, ?) ON CONFLICT(id) DO UPDATE SET tokens = excluded.tokens, updated = excluded.updated",
      this.tokens, this.updated);
    const deficit = Math.max(0, cost - this.tokens);
    return { allowed, remaining: Math.floor(this.tokens), retryAfterMs: allowed ? 0 : Math.ceil((deficit / refillPerSec) * 1000) };
  }
}

7 rapid calls (status:remaining:retryAfterMs) -> 200:4:0  200:3:0  200:2:0  200:1:0  200:0:0  429:0:946  429:0:940
after 2.1s -> 200 {"allowed":true,"remaining":1,"retryAfterMs":0}

// LeaseLock: one object per lock name. Leases expire; every grant carries a monotonically increasing fencing token.
import { DurableObject } from "cloudflare:workers";
import type { Env } from "./index";

type Lease = { owner: string; token: number; expiresAt: number };

export class LeaseLock extends DurableObject<Env> {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    ctx.blockConcurrencyWhile(async () => {
      ctx.storage.sql.exec(`CREATE TABLE IF NOT EXISTS lease(id INTEGER PRIMARY KEY CHECK(id = 1),
        owner TEXT, token INTEGER NOT NULL, expires_at INTEGER NOT NULL)`);
    });
  }

  private current(): Lease | null {
    const r = this.ctx.storage.sql.exec("SELECT owner, token, expires_at FROM lease").toArray()[0];
    return r ? { owner: r.owner as string, token: r.token as number, expiresAt: r.expires_at as number } : null;
  }

  // acquire is synchronous until the setAlarm call, so check-then-grant cannot interleave with another acquire.
  async acquire(owner: string, ttlMs: number): Promise<{ ok: boolean; token?: number; holder?: string; expiresAt: number }> {
    const now = Date.now();
    const cur = this.current();
    if (cur && cur.owner && cur.expiresAt > now && cur.owner !== owner) {
      return { ok: false, holder: cur.owner, expiresAt: cur.expiresAt };
    }
    const token = (cur?.token ?? 0) + 1;  // fencing token never goes backwards, even across expiry
    const expiresAt = now + ttlMs;
    this.ctx.storage.sql.exec(
      "INSERT INTO lease(id, owner, token, expires_at) VALUES (1, ?, ?, ?) ON CONFLICT(id) DO UPDATE SET owner = excluded.owner, token = excluded.token, expires_at = excluded.expires_at",
      owner, token, expiresAt);
    await this.ctx.storage.setAlarm(expiresAt); // wake up to clear the lease even if nobody calls us
    return { ok: true, token, expiresAt };
  }

  release(owner: string, token: number): boolean {
    const cur = this.current();
    if (!cur || cur.owner !== owner || cur.token !== token) return false; // stale holder cannot release a newer lease
    this.ctx.storage.sql.exec("UPDATE lease SET owner = NULL, expires_at = 0 WHERE id = 1");
    return true;
  }

  // Downstream services should reject writes whose token is lower than the highest they have seen.
  async alarm(): Promise<void> {
    const cur = this.current();
    if (cur && cur.owner && cur.expiresAt <= Date.now()) {
      this.ctx.storage.sql.exec("UPDATE lease SET owner = NULL WHERE id = 1");
    } else if (cur && cur.owner) {
      await this.ctx.storage.setAlarm(cur.expiresAt); // lease was renewed; re-arm for the new expiry
    }
  }
}

A acquire -> {"ok":true,"token":1}
B acquire while A holds -> {"ok":false,"holder":"worker-a"}
B acquire after A expired -> {"ok":true,"token":2}
A (stale, token 1) tries release -> {"released":false}

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]