Durable Objects Real-Time - WebSocket Hibernation, Alarms, Chat, Presence & Collaborative Editing

// ChatRoom: one Durable Object per room. Hibernatable WebSockets + SQLite history + an alarm for retention.
import { DurableObject } from "cloudflare:workers";
import type { Env } from "./index";

type Attachment = { user: string; joinedAt: number }; // survives hibernation (max 16,384 bytes serialized)
const HISTORY_LIMIT = 50;              // messages replayed to a new joiner
const RETENTION_MS = 7 * 24 * 3600e3;  // prune messages older than 7 days

export class ChatRoom extends DurableObject<Env> {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    // Runs on every cold start AND every wake from hibernation, so keep it cheap.
    ctx.blockConcurrencyWhile(async () => {
      // SQL calls are synchronous; blockConcurrencyWhile guarantees no event runs before the schema exists.
      ctx.storage.sql.exec(`CREATE TABLE IF NOT EXISTS messages(
        id INTEGER PRIMARY KEY AUTOINCREMENT, user TEXT NOT NULL, body TEXT NOT NULL, ts INTEGER NOT NULL)`);
    });
    // Answered by the runtime without waking the object (no duration billed).
    ctx.setWebSocketAutoResponse(new WebSocketRequestResponsePair("ping", "pong"));
  }

  async fetch(request: Request): Promise<Response> {
    const user = new URL(request.url).searchParams.get("user") ?? "anon";
    const pair = new WebSocketPair();
    const [client, server] = Object.values(pair);
    // Hibernation API: the runtime owns the socket. Do NOT call server.accept().
    this.ctx.acceptWebSocket(server, [user]); // tag = user, so getWebSockets(user) finds all their tabs
    server.serializeAttachment({ user, joinedAt: Date.now() } satisfies Attachment);
    // Replay recent history to the joiner only. toArray() consumes the cursor before any await.
    const history = this.ctx.storage.sql
      .exec("SELECT user, body, ts FROM messages ORDER BY id DESC LIMIT ?", HISTORY_LIMIT)
      .toArray().reverse();
    server.send(JSON.stringify({ type: "history", messages: history }));
    this.broadcast({ type: "presence", online: this.online() });
    // Make sure a retention alarm exists (only one alarm per object; check before setting).
    if ((await this.ctx.storage.getAlarm()) === null) {
      await this.ctx.storage.setAlarm(Date.now() + 3600e3);
    }
    return new Response(null, { status: 101, webSocket: client });
  }

  // Called once per incoming frame; the object may have been hibernated a moment ago.
  async webSocketMessage(ws: WebSocket, raw: string | ArrayBuffer): Promise<void> {
    const { user } = ws.deserializeAttachment() as Attachment; // in-memory fields are gone after hibernation
    const body = typeof raw === "string" ? raw : new TextDecoder().decode(raw);
    if (body.length > 4000) { ws.send(JSON.stringify({ type: "error", reason: "too large" })); return; }
    const ts = Date.now();
    // Not awaited: the output gate holds the broadcast below until this write is durable.
    this.ctx.storage.sql.exec("INSERT INTO messages(user, body, ts) VALUES (?, ?, ?)", user, body, ts);
    this.broadcast({ type: "message", user, body, ts });
  }

  async webSocketClose(ws: WebSocket, code: number, reason: string): Promise<void> {
    // With compatibility_date >= 2026-04-07 the runtime completes the close handshake for us.
    this.broadcast({ type: "presence", online: this.online(ws) });
  }

  async webSocketError(ws: WebSocket): Promise<void> {
    this.broadcast({ type: "presence", online: this.online(ws) });
  }

  // Alarm handlers can run more than once: deleting by age is naturally idempotent.
  async alarm(): Promise<void> {
    this.ctx.storage.sql.exec("DELETE FROM messages WHERE ts < ?", Date.now() - RETENTION_MS);
    if (this.ctx.getWebSockets().length > 0) await this.ctx.storage.setAlarm(Date.now() + 3600e3);
  }

  private online(exclude?: WebSocket): string[] {
    const users = this.ctx.getWebSockets()
      .filter((s) => s !== exclude)
      .map((s) => (s.deserializeAttachment() as Attachment).user);
    return [...new Set(users)].sort();
  }

  // Fan-out: one serialization, N sends. A send to a dead socket throws, so isolate failures per client.
  private broadcast(msg: unknown): void {
    const frame = JSON.stringify(msg);
    for (const s of this.ctx.getWebSockets()) {
      try { s.send(frame); } catch { /* socket already closing; webSocketClose will clean up presence */ }
    }
  }
}

bob received:
   {"type":"history","messages":[{"user":"alice","body":"hello before bob joined","ts":<t>}]}
   {"type":"presence","online":["alice","bob"]}
   {"type":"message","user":"bob","body":"hi alice","ts":<t>}
alice received:
   {"type":"history","messages":[]}
   {"type":"presence","online":["alice"]}
   {"type":"message","user":"alice","body":"hello before bob joined","ts":<t>}
   {"type":"presence","online":["alice","bob"]}
   {"type":"message","user":"bob","body":"hi alice","ts":<t>}
   pong
alice after bob left: {"type":"presence","online":["alice"]}
plain GET to /chat -> 426 {"error":"expected websocket"}

// SIMULATION (not Cloudflare code): fan-out cost in one room object, with and without batching,
// plus a bounded per-client queue so one slow reader cannot grow memory forever.
const clients = 200, msgsPerSec = 200, seconds = 10, windowMs = 50;

// Without batching: every incoming message becomes one frame per client.
const framesNaive = msgsPerSec * seconds * clients;
// With batching: messages inside a 50 ms window are packed into one frame per client.
const windows = (seconds * 1000) / windowMs;
const framesBatched = windows * clients;
console.log(`naive   frames sent: ${framesNaive.toLocaleString()}`);
console.log(`batched frames sent: ${framesBatched.toLocaleString()} (${(framesNaive / framesBatched).toFixed(0)}x fewer, +<=${windowMs} ms latency)`);

// Slow consumer: drains 5 frames/s while we produce 20/s (one batch frame every 50 ms).
type Client = { queue: number; dropped: number; closed: boolean };
const fast: Client = { queue: 0, dropped: 0, closed: false };
const slow: Client = { queue: 0, dropped: 0, closed: false };
const CAP = 100; // per-client buffer cap, in frames
for (let t = 0; t < windows; t++) {
  for (const [c, drainPerWindow] of [[fast, 1], [slow, 0.25]] as [Client, number][]) {
    if (c.closed) continue;
    c.queue = Math.max(0, c.queue + 1 - drainPerWindow);
    if (c.queue > CAP) { c.dropped++; c.queue = CAP; }
    if (c.dropped > 20) c.closed = true; // policy: close with 1013 and let the client reconnect + resync
  }
}
console.log("fast client:", JSON.stringify(fast));
console.log("slow client:", JSON.stringify(slow), "<- disconnected instead of buffering without bound");

naive   frames sent: 400,000
batched frames sent: 40,000 (10x fewer, +<=50 ms latency)
fast client: {"queue":0,"dropped":0,"closed":false}
slow client: {"queue":100,"dropped":21,"closed":true} <- disconnected instead of buffering without bound

# SIMULATION (cost model, not Cloudflare code). Prices and rules are copied from the Durable Objects
# pricing page (Workers Paid): $0.15 per million requests over 1M included, $12.50 per million GB-s over
# 400,000 GB-s, 128 MB billed per object, incoming WebSocket messages billed 20:1, billable usage rounded
# UP to the next whole million, plus the $5 minimum. Reproduces the docs' Example 4.
import math

def cost(objects, conns, msgs_per_conn_per_min, active_seconds_per_object, days=30):
    connect_reqs = objects * conns
    ws_msgs = conns * msgs_per_conn_per_min * objects * 60 * 24 * days
    reqs = connect_reqs + ws_msgs / 20
    req_cost = math.ceil(max(0, reqs - 1e6) / 1e6) * 0.15
    gbs = objects * active_seconds_per_object * 0.128
    dur_cost = math.ceil(max(0, gbs - 400_000) / 1e6) * 12.50
    return reqs, gbs, req_cost, dur_cost, req_cost + dur_cost + 5

month = 60 * 60 * 24 * 30
# 100 rooms x 100 sockets, 1 msg/min each, 10 ms of JS per message => 1 s active per room per minute
hib = cost(100, 100, 1, 60 * 24 * 30 * 1)
std = cost(100, 100, 1, month)          # standard WebSocket API: object pinned in memory all month
for name, (reqs, gbs, rc, dc, total) in [("hibernation API", hib), ("standard API", std)]:
    print(f"{name:<16} billed reqs={reqs:>12,.0f}  GB-s={gbs:>12,.0f}  requests=${rc:>6.2f}  duration=${dc:>7.2f}  total=${total:>7.2f}/mo")
print(f"hibernation saves ${std[4] - hib[4]:.2f}/mo; docs Example 4 total = $20.65")

hibernation API  billed reqs=  21,610,000  GB-s=     552,960  requests=$  3.15  duration=$  12.50  total=$  20.65/mo
standard API     billed reqs=  21,610,000  GB-s=  33,177,600  requests=$  3.15  duration=$ 412.50  total=$ 420.65/mo
hibernation saves $400.00/mo; docs Example 4 total = $20.65