Building Chat and Distributed Locks at the Edge Without Redis or WebSocket Servers — A Practical Guide to Cloudflare Durable Objects

flowchart TD
    C1[Client A] --> W1[Worker Edge Node 1]
    C2[Client B] --> W2[Worker Edge Node 2]
    C3[Client C] --> W3[Worker Edge Node 3]
    W1 --> DO[DO Instance room-123]
    W2 --> DO
    W3 --> DO
    DO --> SQLite[Dedicated SQLite]
    DO --> Mem[In-Memory State]

# wrangler.toml
[[durable_objects.bindings]]
name = "CHAT_ROOM"
class_name = "ChatRoom"
 
[durable_objects]
new_sqlite_classes = ["ChatRoom"]

export class ChatRoom extends DurableObject {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    this.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
      )
    `);
  }
}

export class ChatRoom extends DurableObject {
  // Hibernation API — only activated with the class method pattern
  async webSocketOpen(ws: WebSocket) { /* called once when a new connection is established */ }
  async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) { /* message received */ }
  async webSocketClose(ws: WebSocket, code: number, reason: string) { /* connection closed */ }
  async webSocketError(ws: WebSocket, error: unknown) { /* error occurred */ }
 
  // This disables Hibernation
  // server.addEventListener('message', handler)  ← do not use
}

// chat-room.ts
import { DurableObject } from "cloudflare:workers";
 
interface Env {
  CHAT_ROOM: DurableObjectNamespace<ChatRoom>;
}
 
interface SessionMeta {
  userId: string;
  username: string;
}
 
export class ChatRoom extends DurableObject {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    this.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
      )
    `);
  }
 
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
 
    if (url.pathname === "/websocket") {
      if (request.headers.get("Upgrade") !== "websocket") {
        return new Response("WebSocket upgrade required", { status: 426 });
      }
 
      const userId = url.searchParams.get("userId") ?? crypto.randomUUID();
      const username = url.searchParams.get("username") ?? "Anonymous";
 
      const [client, server] = Object.values(new WebSocketPair()) as [WebSocket, WebSocket];
 
      // Enable Hibernation — use acceptWebSocket
      this.ctx.acceptWebSocket(server);
 
      // Preserve session info across Hibernation cycles
      server.serializeAttachment({ userId, username } satisfies SessionMeta);
 
      return new Response(null, { status: 101, webSocket: client });
    }
 
    return new Response("Not Found", { status: 404 });
  }
 
  // Called once immediately after connection is established — ideal time to send history
  async webSocketOpen(ws: WebSocket) {
    const history = [...this.ctx.storage.sql.exec(
      "SELECT user, body, ts FROM messages ORDER BY id DESC LIMIT 50"
    )].reverse();
    ws.send(JSON.stringify({ type: "history", messages: history }));
  }
 
  async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) {
    const meta = ws.deserializeAttachment() as SessionMeta;
    const { body } = JSON.parse(message as string);
    const ts = Date.now();
 
    this.ctx.storage.sql.exec(
      "INSERT INTO messages (user, body, ts) VALUES (?, ?, ?)",
      meta.username,
      body,
      ts
    );
 
    const payload = JSON.stringify({ type: "message", user: meta.username, body, ts });
    for (const peer of this.ctx.getWebSockets()) {
      try {
        peer.send(payload);
      } catch {
        // Ignore already-closed connections
      }
    }
  }
 
  async webSocketClose(ws: WebSocket, code: number) {
    ws.close(code, "Connection closed");
  }
 
  async webSocketError(ws: WebSocket, _error: unknown) {
    ws.close(1011, "Server error");
  }
}

// worker.ts — acts as the router
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    const roomId = url.searchParams.get("room") ?? "general";
 
    // Same roomId → always the same DO instance, no matter where in the world it's called from
    const id = env.CHAT_ROOM.idFromName(roomId);
    const stub = env.CHAT_ROOM.get(id);
 
    return stub.fetch(request);
  },
};

# Add to wrangler.toml
[[durable_objects.bindings]]
name = "DISTRIBUTED_LOCK"
class_name = "DistributedLock"
 
[durable_objects]
new_sqlite_classes = ["ChatRoom", "DistributedLock"]

// distributed-lock.ts
import { DurableObject } from "cloudflare:workers";
 
interface Env {
  DISTRIBUTED_LOCK: DurableObjectNamespace<DistributedLock>;
}
 
export class DistributedLock extends DurableObject {
  private static readonly DEFAULT_TTL_MS = 30_000;
 
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    // One lock per instance — single-row table
    this.ctx.storage.sql.exec(`
      CREATE TABLE IF NOT EXISTS lock_state (
        owner      TEXT    NOT NULL,
        expires_at INTEGER NOT NULL
      )
    `);
  }
 
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    const action = url.pathname.slice(1);
    const { owner, ttlMs } = await request.json<{ owner: string; ttlMs?: number }>();
 
    switch (action) {
      case "acquire": return Response.json(await this.acquire(owner, ttlMs));
      case "release": return Response.json(await this.release(owner));
      case "renew":   return Response.json(await this.renew(owner, ttlMs));
      default:        return new Response("Not Found", { status: 404 });
    }
  }
 
  async acquire(
    owner: string,
    ttlMs = DistributedLock.DEFAULT_TTL_MS
  ): Promise<{ acquired: boolean }> {
    const expiresAt = Date.now() + ttlMs;
 
    const acquired = await this.ctx.storage.transaction(async () => {
      const existing = [...this.ctx.storage.sql.exec(
        "SELECT expires_at FROM lock_state LIMIT 1"
      )][0] as { expires_at: number } | undefined;
 
      if (existing && existing.expires_at > Date.now()) {
        return false;
      }
 
      // Expired or absent — replace with insert
      this.ctx.storage.sql.exec("DELETE FROM lock_state");
      this.ctx.storage.sql.exec(
        "INSERT INTO lock_state (owner, expires_at) VALUES (?, ?)",
        owner,
        expiresAt
      );
      return true;
    });
 
    if (acquired) {
      // Alarm auto-cleans on TTL expiry — no external cron needed
      await this.ctx.storage.setAlarm(expiresAt + 100);
    }
 
    return { acquired };
  }
 
  async release(owner: string): Promise<{ released: boolean }> {
    return await this.ctx.storage.transaction(async () => {
      const existing = [...this.ctx.storage.sql.exec(
        "SELECT owner FROM lock_state LIMIT 1"
      )][0] as { owner: string } | undefined;
 
      if (!existing || existing.owner !== owner) {
        return { released: false };
      }
 
      this.ctx.storage.sql.exec("DELETE FROM lock_state");
      return { released: true };
    });
  }
 
  async renew(
    owner: string,
    ttlMs = DistributedLock.DEFAULT_TTL_MS
  ): Promise<{ renewed: boolean }> {
    const expiresAt = Date.now() + ttlMs;
    const result = [...this.ctx.storage.sql.exec(
      "UPDATE lock_state SET expires_at = ? WHERE owner = ? RETURNING owner",
      expiresAt,
      owner
    )];
 
    if (result.length > 0) {
      // Reset alarm to match the renewed expiry time
      await this.ctx.storage.setAlarm(expiresAt + 100);
      return { renewed: true };
    }
    return { renewed: false };
  }
 
  async alarm() {
    this.ctx.storage.sql.exec(
      "DELETE FROM lock_state WHERE expires_at <= ?",
      Date.now()
    );
  }
}

flowchart TD
    A[acquire request] --> B{Valid lock exists?}
    B -->|Yes| C[Return failure]
    B -->|No| D[DELETE then INSERT]
    D --> E[Set alarm]
    E --> F[Return success]
 
    G[Alarm fires] --> H[Delete expired lock]
 
    I[release request] --> J{Owner matches?}
    J -->|No| K[Return failure]
    J -->|Yes| L[Delete lock and return success]

// lock-service.ts — facade for RPC exposure
import { WorkerEntrypoint } from "cloudflare:workers";
 
interface Env {
  DISTRIBUTED_LOCK: DurableObjectNamespace<DistributedLock>;
}
 
export class LockService extends WorkerEntrypoint<Env> {
  async acquire(resource: string, owner: string, ttlMs?: number) {
    const stub = this.env.DISTRIBUTED_LOCK.get(
      this.env.DISTRIBUTED_LOCK.idFromName(resource)
    );
    return stub.acquire(owner, ttlMs);
  }
 
  async release(resource: string, owner: string) {
    const stub = this.env.DISTRIBUTED_LOCK.get(
      this.env.DISTRIBUTED_LOCK.idFromName(resource)
    );
    return stub.release(owner);
  }
 
  async renew(resource: string, owner: string, ttlMs?: number) {
    const stub = this.env.DISTRIBUTED_LOCK.get(
      this.env.DISTRIBUTED_LOCK.idFromName(resource)
    );
    return stub.renew(owner, ttlMs);
  }
}

// Calling Worker side
export default {
  async fetch(request: Request, env: Env) {
    // Type-safe call without HTTP serialization
    const { acquired } = await env.LOCK_SERVICE.acquire("order-42", "worker-abc");
    if (!acquired) {
      return new Response("Failed to acquire lock", { status: 409 });
    }
    // ... critical section processing ...
    await env.LOCK_SERVICE.release("order-42", "worker-abc");
    return new Response("Done");
  },
};

// All requests funnel into one instance — bottleneck
const id = env.CHAT_ROOM.idFromName("global-singleton");
 
// Distribute instances using entities as keys — do it this way
const id = env.CHAT_ROOM.idFromName(roomId);

// Use transaction() for storage atomicity
await this.ctx.storage.transaction(async () => {
  const row = [...this.ctx.storage.sql.exec("SELECT count FROM counters")][0];
  this.ctx.storage.sql.exec(
    "UPDATE counters SET count = ?",
    (row?.count as number ?? 0) + 1
  );
});
 
// Correct use of blockConcurrencyWhile — initialization involving external I/O
async initialize() {
  await this.ctx.blockConcurrencyWhile(async () => {
    // Block other requests from entering while fetching config from an external API
    const config = await fetch("https://config.example.com/settings").then(r => r.json());
    this.config = config;
  });
}