Cloudflare Durable Objects: Building a Stateful Game Server at the Edge

What Durable Objects Actually Are

A Durable Object is a single-threaded JavaScript/TypeScript object that lives at the edge. Think of it as one actor in the actor model, but the runtime handles all the hard parts: routing requests to the right instance, persisting state, and ensuring single-threaded access.

Each Durable Object has:

• A globally unique ID
• A single-threaded execution context (no concurrency bugs possible)
• A transactional key-value storage API (strongly consistent)
• The ability to accept WebSocket connections
• An alarm system for scheduled work

The critical property: only one instance of a given Durable Object exists anywhere in the world at any time. The platform guarantees this. If two requests for the same object arrive at different Cloudflare PoPs, one waits while the request is routed to wherever that object is currently running.

// wrangler.toml
[durable_objects]
bindings = [
 { name = "GAME_ROOMS", class_name = "GameRoom" }
]

[[migrations]]
tag = "v1"
new_classes = ["GameRoom"]

The Game Room: Actor Model in Practice

Here is the skeleton of a game server implementation. Each game room is one Durable Object:

export class GameRoom implements DurableObject {
 private state: DurableObjectState;
 private env: Env;
 private gameState: GameState | null = null;
 private sessions: Map<string, WebSocket> = new Map();

 constructor(state: DurableObjectState, env: Env) {
 this.state = state;
 this.env = env;

 // CRITICAL: Block all requests until state is loaded
 this.state.blockConcurrencyWhile(async () => {
 const stored = await this.state.storage.get<GameState>("gameState");
 this.gameState = stored ?? createEmptyGame();
 });
 }

 async fetch(request: Request): Promise<Response> {
 const url = new URL(request.url);

 if (url.pathname === "/ws") {
 return this.handleWebSocket(request);
 }

 if (url.pathname === "/state") {
 return Response.json(this.gameState);
 }

 return new Response("Not found", { status: 404 });
 }

 private handleWebSocket(request: Request): Response {
 const pair = new WebSocketPair();
 const [client, server] = Object.values(pair);

 const playerId = new URL(request.url).searchParams.get("playerId");
 if (!playerId) {
 return new Response("Missing playerId", { status: 400 });
 }

 this.state.acceptWebSocket(server, [playerId]);
 this.sessions.set(playerId, server);

 // Send current state to the new player
 server.send(JSON.stringify({
 type: "sync",
 state: this.gameState,
 yourId: playerId,
 }));

 this.broadcast({
 type: "player_joined",
 playerId,
 playerCount: this.sessions.size,
 }, playerId);

 return new Response(null, { status: 101, webSocket: client });
 }

 async webSocketMessage(ws: WebSocket, message: string) {
 const data = JSON.parse(message);
 const tags = this.state.getTags(ws);
 const playerId = tags[0];

 switch (data.type) {
 case "place_tile":
 this.handlePlaceTile(playerId, data);
 break;
 case "draw_tiles":
 this.handleDrawTiles(playerId);
 break;
 case "end_turn":
 this.handleEndTurn(playerId);
 break;
 }
 }

 async webSocketClose(ws: WebSocket) {
 const tags = this.state.getTags(ws);
 const playerId = tags[0];
 this.sessions.delete(playerId);

 this.broadcast({
 type: "player_left",
 playerId,
 playerCount: this.sessions.size,
 });

 // Set an alarm to clean up if everyone leaves
 if (this.sessions.size === 0) {
 await this.state.storage.setAlarm(Date.now() + 300_000); // 5 minutes
 }
 }

 async alarm() {
 if (this.sessions.size === 0) {
 // No one reconnected — clean up
 await this.state.storage.deleteAll();
 }
 }

 // ...
}

The beauty here is the absence of complexity. No mutex, no locks, no CAS loops, no optimistic concurrency control. The runtime guarantees that webSocketMessage calls are serialized. When Player A places a tile and Player B draws tiles simultaneously, they execute one after the other, never interleaved. The actor model gives you this for free.

The Routing Layer: Workers as Matchmakers

A Cloudflare Worker acts as the entry point, routing players to the right Durable Object:

export default {
 async fetch(request: Request, env: Env): Promise<Response> {
 const url = new URL(request.url);

 if (url.pathname.startsWith("/game/")) {
 const roomId = url.pathname.split("/")[2];

 // The ID is deterministic — same roomId always routes to the same DO
 const id = env.GAME_ROOMS.idFromName(roomId);
 const room = env.GAME_ROOMS.get(id);

 // This request is forwarded to wherever the DO is running
 return room.fetch(request);
 }

 if (url.pathname === "/matchmake") {
 return handleMatchmaking(request, env);
 }

 // Serve static assets from the edge (or proxy to Vercel)
 return env.ASSETS.fetch(request);
 }
};

async function handleMatchmaking(request: Request, env: Env): Promise<Response> {
 const { preferredLanguage, skillRating } = await request.json();

 // Check waiting rooms by language
 const waitingRoomId = env.GAME_ROOMS.idFromName(
 `waiting:${preferredLanguage}:${Math.floor(skillRating / 100) * 100}`
 );
 const waitingRoom = env.GAME_ROOMS.get(waitingRoomId);

 const response = await waitingRoom.fetch(new Request("https://internal/join", {
 method: "POST",
 body: JSON.stringify({ skillRating }),
 }));

 return response;
}

The key insight: idFromName() is a deterministic hash. The string "waiting:en:1200" always maps to the same Durable Object ID, so all English-speaking players with ~1200 rating end up in the same matchmaking room without any coordination layer.

State Management: Transactional Storage

The storage API is deceptively simple but remarkably powerful:

private async handlePlaceTile(playerId: string, data: PlaceTileAction) {
 if (this.gameState!.currentTurn !== playerId) {
 this.sendError(playerId, "Not your turn");
 return;
 }

 const { x, y, letter } = data;

 // Validate the move
 const validation = validatePlacement(this.gameState!, x, y, letter, playerId);
 if (!validation.valid) {
 this.sendError(playerId, validation.reason);
 return;
 }

 // Apply the move
 this.gameState!.board[y][x] = { letter, playerId, timestamp: Date.now() };
 this.gameState!.players[playerId].tiles = this.gameState!.players[playerId].tiles
 .filter(t => t !== letter);
 this.gameState!.moveHistory.push({ playerId, x, y, letter, timestamp: Date.now() });

 // Persist atomically — if this fails, in-memory state is stale
 // but the next request will reload from storage via blockConcurrencyWhile
 await this.state.storage.put("gameState", this.gameState);

 // Broadcast to all players
 this.broadcast({
 type: "tile_placed",
 playerId,
 x, y, letter,
 scores: this.calculateScores(),
 });
}

For more complex operations, you get transactions:

await this.state.storage.transaction(async (txn) => {
 const game = await txn.get<GameState>("gameState");
 const stats = await txn.get<PlayerStats>(`stats:${playerId}`);

 game!.currentTurn = nextPlayer(game!);
 stats!.movesPlayed += 1;
 stats!.lastActive = Date.now();

 await txn.put("gameState", game);
 await txn.put(`stats:${playerId}`, stats);
});

This is ACID within a single Durable Object. The writes either all commit or all roll back. No partial updates. No torn reads. In a traditional distributed system, getting this guarantee across multiple keys requires a consensus protocol. Here, it's a one-liner because the single-threaded model makes serializable isolation trivial.

Performance: What I Actually Measured

A load test with 500 simulated players across 50 game rooms yields these results:

| Metric | Value | |--------|-------| | WebSocket message latency (same region) | 8-15ms | | WebSocket message latency (cross-continent) | 40-90ms | | State persistence latency | 2-5ms | | Cold start (new DO) | 15-25ms | | Warm message processing | <1ms | | Max concurrent WebSockets per DO | ~32,000 (tested) | | Storage reads | <1ms (cached in-memory after first read) |

The cross-continent latency deserves explanation. When a player in Tokyo connects to a room that was created by a player in Berlin, the Durable Object is running near Berlin. The Tokyo player's messages route through Cloudflare's backbone to Berlin, get processed, and the response routes back. That's ~80ms round trip. Not instant, but better than a server in us-east-1 for both players.

For a word game, 80ms is fine — it's a turn-based game, not a twitch shooter. For real-time games like .io games, you'd want to use the location hints API to spawn the DO near the majority of players:

const id = env.GAME_ROOMS.newUniqueId({
 jurisdiction: "eu" // Optional: restrict to EU for GDPR
});

// Or use locationHint for latency optimization
const id = env.GAME_ROOMS.idFromName(roomId);
const room = env.GAME_ROOMS.get(id, { locationHint: "enam" }); // Eastern North America

Operational Considerations and Limitations

Memory limits. Each Durable Object gets 128 MB of memory. That sounds like a lot until you're holding 1000 WebSocket connections with per-player state. A typical game state serializes to ~2 KB per player, allowing ~500 players per room comfortably. For more, you need to shard rooms.

No inter-DO communication primitives. If Room A needs to know about Room B (e.g., for a tournament bracket), you have to go through a Worker fetch. There's no built-in pub/sub between Durable Objects. A simple relay pattern addresses this:

// Tournament coordinator DO
async notifyRooms(roomIds: string[], event: TournamentEvent) {
 const promises = roomIds.map(async (roomId) => {
 const id = this.env.GAME_ROOMS.idFromName(roomId);
 const room = this.env.GAME_ROOMS.get(id);
 return room.fetch(new Request("https://internal/tournament-event", {
 method: "POST",
 body: JSON.stringify(event),
 }));
 });

 await Promise.allSettled(promises);
}

Hibernation and cost. Durable Objects with WebSocket Hibernation are billed only when actively processing messages, not while idle. But every storage operation costs money. Persisting state on every single move can result in $12/day in storage writes during testing. Batching writes to every 500ms cuts that to $0.80/day:

private pendingWrite = false;

private async scheduleWrite() {
 if (this.pendingWrite) return;
 this.pendingWrite = true;

 // Coalesce writes — multiple moves within 500ms become one storage write
 setTimeout(async () => {
 await this.state.storage.put("gameState", this.gameState);
 this.pendingWrite = false;
 }, 500);
}

Debugging is rough. wrangler dev gives you local Durable Objects, but the behavior differs from production in subtle ways. Storage operations are synchronous locally but asynchronous in production. A common bug is storage.put() followed by storage.get() returning stale data in production because the put was not awaited. This works perfectly locally, making it difficult to catch.

Architecture Pattern: Durable Objects + Vercel

The final architecture looks like this:

[Players] → [Cloudflare Worker (routing)] → [Durable Objects (game state)]
 ↓
[Vercel (Next.js)] ← [Cloudflare Worker (static proxy)]
 ↓
[Vercel API Routes (user accounts, leaderboards)]

Vercel handles the Next.js frontend and the non-realtime API (user profiles, leaderboards, game history). Cloudflare handles the real-time game play. The separation is clean: anything that needs strong consistency and real-time updates goes to Durable Objects; anything that's eventually consistent and request/response goes to Vercel.

The frontend connects to both:

// Vercel API for account data
const profile = await fetch("/api/profile").then(r => r.json());

// Cloudflare Worker for game WebSocket
const ws = new WebSocket(
 `wss://game.example.com/game/${roomId}/ws?playerId=${profile.id}`
);

When Not to Use Durable Objects

They're not a general-purpose backend. Specific anti-patterns to avoid:

• CRUD APIs: Use a normal database. Durable Objects add latency for simple read/write patterns.
• Heavy computation: 128 MB memory, 30-second CPU time limit. Don't try to run ML inference.
• Global aggregation: If you need to count all active players across all rooms, you need a separate system. Each DO is isolated.
• Relational data: No joins, no indexes, no queries. The storage API is a key-value store.

They shine for: real-time collaboration, multiplayer games, chat rooms, IoT device coordination, rate limiting, and any scenario where a small group of clients need strongly consistent shared state with low latency.

The Verdict

After three months in production with ~2000 daily active players, this type of game server costs roughly $34/month on Cloudflare (Workers + Durable Objects + storage). The equivalent on AWS would be at least two EC2 instances plus an Application Load Balancer plus ElastiCache for session state — probably $150+/month for worse latency outside us-east-1.

More importantly, zero infrastructure updates are needed. No patching, no scaling configuration, no health checks, no auto-scaling groups. The platform handles all of it. When a game room is active, it runs. When it's idle, it hibernates. When players are on three continents, it still feels responsive.

Durable Objects aren't the answer to everything. But for the specific problem of "small groups need real-time shared state with strong consistency" — which describes a surprising number of applications — they represent one of the strongest solutions available.