Durable Objects provide stateful coordination in both control planes and data planes. Applications scale best by distributing independent work across many objects, rather than requiring every request to pass through one object.
Use this page for guidance on how to choose coordination boundaries, size workloads, route requests, and plan for growth. For worked designs that apply these decisions, refer to Architecture examples.
Use this common pattern as a starting point for applications with shared account configuration and many independent resources. It shows how Durable Objects work with other Cloudflare developer platform services, keeping administrative coordination separate from live resource traffic.
Diagram as text
CONTROL PLANE
Account administrators → Config API → one Durable Object per account ID
Account objects own authoritative configuration and resource lifecycle state.
PROPAGATION
Account objects → KV Instant: small configuration and hostname-to-account mapping
Account objects → KV / R2: larger blobs, with optional Workers Cache
DATA PLANE
End users → stateless Workers: authentication, routing, transforms
End users → stateful Durable Objects: one room / document / session per object
KV Instant → stateless Workers: read configuration
KV / R2 → stateful Durable Objects: get blobs
The two groups are separate responsibilities, not a mandatory sequential chain.
No direct calls or writes go from the data plane to the control plane in this pattern.
ANALYTICS
Data-plane usage events → Pipelines → R2 / Basin → scheduled job
Scheduled job → Config API: reads summaries and decides on configuration changes
Analytics queries and feedback are not on the user request path.- Control plane: Account-scoped Durable Objects coordinate configuration and resource lifecycle changes through an administrative API.
- Propagation: Publish small configuration through KV and larger blobs through KV or R2, so readers do not need to query the account's control object for every request.
- Data plane: Workers handle stateless authentication, routing, and transforms. Separate Durable Objects coordinate each room, document, or session and own its application state.
- Analytics: Export usage events through Pipelines to R2 and Basin. A scheduled job can read summaries and propose configuration changes through the administrative API, outside the resource request path.
The recommendation is to separate responsibilities, not to reserve Durable Objects for only one plane. Adapt the services and coordination boundaries to your workload; not every application needs every component shown.
The arrows show logical responsibilities, not separate public endpoints or required Worker deployments. Durable Objects receive requests through Workers or other Durable Objects, not directly from the Internet. Keeping routine data-plane traffic out of the control plane is the design choice illustrated here, not a platform restriction.
For a worked design that follows the administrative, resource, and analytics flows, refer to Account control and resource traffic.
- Separate control-plane changes from data-plane traffic. Durable Objects can serve either role. Publish configuration outward so routine application requests do not depend on a control-plane object.
- Choose an atom of coordination. Use one object for a room, session, document, account, or other unit whose state must change together.
- Measure each object's capacity. Load-test the expected workload, allow headroom, and shard when one object cannot meet your targets.
- Route with deterministic names built from the resource key, using
getByName(). - Use complementary services. Distribute configuration with KV, store large objects in R2, and send analytical events to Basin Pipelines instead of collecting them in one global object.
- Plan for hot Durable Objects. Identify the limiting resource, then add shards or layers that preserve the coordination your application needs.
- Avoid routing unrelated, high-volume application requests through the same object just to discover their destination or update shared configuration.
- Avoid making each data-plane request write control-plane state or wait for a control-plane decision that could be published in advance.
- Avoid waking many objects to list, search, or aggregate when an index or analytics service can answer the query.
- Avoid creating one object per row, message, tool call, or agent turn when those operations need shared state.
- Avoid splitting a hot Durable Object without considering upstream connections, hot keys, or cross-object transactions.
- Avoid changing shard assignments without a plan for existing state and in-flight requests.
- Avoid letting independent timer owners overwrite the same object's alarm.
| Term | Meaning |
|---|---|
| Atom | The unit whose state needs coordinated updates, such as one document or one account's configuration. |
| Control plane | Administrative operations that create resources and manage their configuration, policies, or placement. |
| Data plane | Operations that deliver the application's primary function, such as editing a document or sending a message. Request routing and enforcement of published policies are part of this path. |
| Propagation layer | Published configuration or snapshots that let the data plane operate without querying its authoritative control-plane object for each request. |
| Analytics | Event collection and queries used to observe the application, separate from its authoritative operational state. |
| Shard | One of several objects that divide a workload by a stable key, region, or time period. |
| Hub, relay, leaf | Broadcast roles: a hub receives an upstream stream, a relay forwards updates, and leaves hold client connections. |
| Bounded parent | An object that coordinates a defined set of children, such as one account's resources. Its role depends on the operations it owns. |
Control plane and data plane describe responsibilities, not products. A Worker can expose administrative APIs or serve user traffic. A Durable Object can coordinate account configuration or own a live document. Using a Durable Object for the control plane is not itself an anti-pattern.
Cloudflare's control and data plane reference architecture uses Durable Objects in both planes. The important property is that high-volume resource requests reach their data-plane objects directly, rather than passing through a shared control-plane object.
Diagram as text
Coupled request path:
User requests → Worker → account control Durable Object → selected document object
Separate document Durable Objects: doc:1, doc:2, doc:3.
Data-plane throughput depends on the control object.
Separated request paths:
Administrative requests → config API Worker → account control Durable Object
Account control Durable Object → published configuration in KV / R2
User requests → request Worker → selected document Durable Object (doc:1, doc:2, or doc:3)
Request Worker reads published configuration, not the control object.For a high-volume data plane, use these two design rules:
- Do not make routine data-plane operations write back to control-plane state. Keep messages, edits, and session activity in the resource objects that own them. Send observations to a separate analytics path.
- Propagate control-plane changes outward. Publish configuration for request-serving Workers and Durable Objects to consume. Avoid a synchronous call to the control-plane object on every resource request.
Administrative changes still go through the control API. A background process can also propose changes through that API after analyzing usage. This is different from requiring every user request to update the control plane.
A direct call to a control-plane object can be a reasonable trade-off for a small workload or an operation that requires an immediate, authoritative decision. Measure that dependency and its failure behavior rather than treating all cross-plane calls as forbidden.
| Responsibility | Options | Design consideration |
|---|---|---|
| Authoritative account configuration or resource lifecycle | Scoped Durable Objects | Use Durable Objects when changes need per-account or per-resource coordination. Choose the scope from measured load. |
| Administrative API | Worker calling the appropriate control-plane object or store | Authenticate administrative changes separately from routine resource traffic. |
| Configuration distribution | KV; R2 for larger snapshots | Publish read-oriented copies. Define how consumers handle stale or missing configuration. |
| Request authentication, authorization, and routing | Worker; resource-specific checks in a Durable Object | Enforcing a policy is data-plane work. Changing that policy is control-plane work. |
| Resource state, ordering, and live connections | Durable Objects | Keep each object's responsibility and load bounded. |
| Searchable resource index | A scoped Durable Object | Listing a tenant's resources can query an index without waking every child. |
| Large payloads and archived state | R2 | Keep references or coordination state in the object rather than all payloads. |
| Analytical event ingestion and queries | Basin Pipelines, R2, Basin SQL, or Analytics Engine | Use an analytics service for cross-resource observations. Add a coordinating object only when the workload needs it. |
| Background delivery or multi-step execution | Queues or Workflows | Choose delivery and retry semantics separately from the coordination boundary. |
Classic Workers KV is eventually consistent. Publishing a change does not make it visible immediately to every reader. KV Instant is a separate, private-beta mode for small, infrequently updated configurations that are proactively propagated. Choose the mode for the workload and check its limits; do not assume a new routing map or permission policy takes effect everywhere at once.
Version configuration and plan for readers using the previous version. Retain old shard layouts during transitions, define behavior for missing configuration, and retry failed publication. R2 can hold larger versioned snapshots; caching still needs an explicit refresh policy.
If an operation requires immediate revocation or a strongly consistent read, choose a path that provides that guarantee. A synchronous check with a scoped Durable Object may be appropriate, with its capacity and latency included in the design.
An account object can own configuration changes and resource creation, while document or session objects handle independent user activity. A parent that creates and lists children acts as their control plane. A session coordinating its active participants acts as a data-plane coordinator.
Scope each coordinator by the work it owns, not by a rule that all control-plane state must live outside Durable Objects. A low-volume global administrative object may be sufficient; split it by account, resource type, or region when measurements require it.
For a worked topology with configuration propagation and analytics, refer to Separate account control from resource traffic.
The most important design decision is choosing what each Durable Object represents. Create one Durable Object per logical unit that needs coordination: a chat room, a game session, a document, a user's data, or a tenant's workspace.
This is the key insight that makes Durable Objects powerful. Instead of a shared database with locks, each "atom" of your application gets its own single-threaded execution environment with private storage.
import { DurableObject } from "cloudflare:workers";
// Each chat room is its own Durable Object instance
export class ChatRoom extends DurableObject {
async sendMessage(userId, message) {
// All messages to this room are processed sequentially by this single instance.
// No race conditions, no distributed locks needed.
this.ctx.storage.sql.exec(
"INSERT INTO messages (user_id, content, created_at) VALUES (?, ?, ?)",
userId,
message,
Date.now(),
);
}
}
export default {
async fetch(request, env) {
const url = new URL(request.url);
const roomId = url.searchParams.get("room") ?? "lobby";
// Each room ID maps to exactly one Durable Object instance globally
const stub = env.CHAT_ROOM.getByName(`room:${roomId}`);
await stub.sendMessage("user-123", "Hello, room!");
return new Response("Message sent");
},
};import { DurableObject } from "cloudflare:workers";
export interface Env {
CHAT_ROOM: DurableObjectNamespace<ChatRoom>;
}
// Each chat room is its own Durable Object instance
export class ChatRoom extends DurableObject<Env> {
async sendMessage(userId: string, message: string) {
// All messages to this room are processed sequentially by this single instance.
// No race conditions, no distributed locks needed.
this.ctx.storage.sql.exec(
"INSERT INTO messages (user_id, content, created_at) VALUES (?, ?, ?)",
userId,
message,
Date.now(),
);
}
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const url = new URL(request.url);
const roomId = url.searchParams.get("room") ?? "lobby";
// Each room ID maps to exactly one Durable Object instance globally
const stub = env.CHAT_ROOM.getByName(`room:${roomId}`);
await stub.sendMessage("user-123", "Hello, room!");
return new Response("Message sent");
},
};Use one test to pick your atom: the atom is the largest unit you need to update atomically, and the smallest unit you can serve on its own. Most applications land on a room, session, document, or match. Tenants and users make good parents and per-entity databases.
Diagram as text
Granularity ladder, coarse to fine:
Global ...................... TOO COARSE: every request queues on one thread; one failure affects everyone
Tenant or workspace ......... OK as a bounded parent or per-tenant database; too coarse if one tenant is busy
User ........................ OK for per-user state, settings, inbox
Room, session, document ..... SWEET SPOT: largest unit updated atomically, smallest unit served on its own
Row, message, tool call, agent turn ... TOO FINE when each operation needs shared state from other objectsSigns your atom is too coarse
- Unrelated requests queue behind each other.
- Peak requests per second for one object approach its limit.
- Storage grows without bound as the product grows.
- One customer's spike slows down other customers.
Signs your atom is too fine
- You need a transaction that spans several objects.
- One user action fans out to many objects.
- Every read reassembles state from several objects.
- You have one object per row, message, tool call, or agent turn, but each operation needs shared conversation or run state.
One application can, and often should, use several Durable Object classes at different rungs. For example, a consumer AI app might use one object per user profile, one per conversation, and one per agent run. Refer to Per-user constellation.
Avoid routing all rooms through one "global" object. This is a workload boundary problem, not a restriction on administrative objects. Name each room object after the coordination unit instead:
// 🔴 Bad: every room shares one global instance (one thread for the whole app)
const globalStub = env.CHAT_ROOM.getByName("global");
await globalStub.sendMessage(roomId, userId, message);
// ✅ Good: one instance per room
const roomStub = env.CHAT_ROOM.getByName(`room:${roomId}`);
await roomStub.sendMessage(userId, message);// 🔴 Bad: every room shares one global instance (one thread for the whole app)
const globalStub = env.CHAT_ROOM.getByName("global");
await globalStub.sendMessage(roomId, userId, message);
// ✅ Good: one instance per room
const roomStub = env.CHAT_ROOM.getByName(`room:${roomId}`);
await roomStub.sendMessage(userId, message);Diagram as text
WRONG: all clients → ChatRoom "global" (every room, one thread)
result: queues grow; one failure affects everyone
RIGHT: clients → room:lobby | room:42 | room:dev (one object per room)
result: rooms run in parallel; failures are isolatedThe Limits page is the source of truth for platform limits. Note the scope of each limit:
| Resource and scope | Value |
|---|---|
| Requests per second, per object | Soft limit of 1,000; not guaranteed throughput |
| SQLite-backed storage, per object on Workers Paid | 10 GB; refer to Limits for Workers Free per-object and account limits |
| CPU per request | 30 seconds by default, configurable up to 5 minutes |
| Alarm handler wall time | 15 minutes |
| Key and value size, per entry in the key-value storage API | 2 MB combined |
| Bound parameters per SQL query | 100 |
| Simultaneous outgoing connections, per request | 6 |
The documented 1,000 requests per second per object is a soft limit, not a throughput benchmark. The rate an object sustains depends on its CPU work, storage operations, payload sizes, and other work performed for each request. Do not assign fixed capacities to categories such as JSON validation or storage writes.
Load-test the operations your application performs, including expected bursts. Measure latency, CPU usage, storage work, and overload errors. Choose a target rate below both the documented soft limit and the rate your workload sustains, with headroom for bursts and variation.
For writes that can be partitioned independently, estimate an initial shard count from that measured target, then load-test the sharded design:
Required shards = ceil(Peak requests/second for one atom / Target requests/second per shard)WebSocket fan-out needs its own load test. Incoming requests per second and outbound messages per second measure different work: one incoming update can produce many outgoing messages. Measure broadcast latency at the expected subscriber count rather than deriving fan-out capacity from the request soft limit.
These hypothetical workloads show how to choose a boundary. They are not customer measurements or throughput guarantees.
| Workload | What to measure for one atom | Decision |
|---|---|---|
| Collaborative editing session | Event processing and broadcast latency with the expected viewers | Start with one object per session; split responsibilities if measurements require it |
| Chat room | Message rate, storage work, and subscriber count | Start with one object per room and test busy rooms separately |
| Coordinated work intake | Burst write rate and time to drain the backlog | Add hash shards when one buffer cannot meet the target |
| Live status feed | Time to deliver an update to the expected subscribers | Keep a regional hub as the atom and add a fan-out tree when broadcasts fall behind |
Use getByName() with meaningful, deterministic strings for consistent routing. The same input always produces the same Durable Object ID, ensuring requests for the same logical entity always reach the same instance.
import { DurableObject } from "cloudflare:workers";
export class GameSession extends DurableObject {
async join(playerId) {
// Game logic here
}
}
export default {
async fetch(request, env) {
const url = new URL(request.url);
const gameId = url.searchParams.get("game");
if (!gameId) {
return new Response("Missing game ID", { status: 400 });
}
// ✅ Good: Deterministic ID from a meaningful string
// All requests for "game-abc123" go to the same Durable Object
const stub = env.GAME_SESSION.getByName(gameId);
await stub.join("player-xyz");
return new Response("Joined game");
},
};import { DurableObject } from "cloudflare:workers";
export interface Env {
GAME_SESSION: DurableObjectNamespace<GameSession>;
}
export class GameSession extends DurableObject<Env> {
async join(playerId: string) {
// Game logic here
}
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const url = new URL(request.url);
const gameId = url.searchParams.get("game");
if (!gameId) {
return new Response("Missing game ID", { status: 400 });
}
// ✅ Good: Deterministic ID from a meaningful string
// All requests for "game-abc123" go to the same Durable Object
const stub = env.GAME_SESSION.getByName(gameId);
await stub.join("player-xyz");
return new Response("Joined game");
},
};Creating a stub does not instantiate or wake up the Durable Object. The Durable Object is only activated when you call a method on the stub.
Use newUniqueId() only when you need a new, random instance and will store the mapping externally:
export default {
async fetch(request, env) {
// newUniqueId() creates a random ID - useful when creating new instances
const id = env.GAME_SESSION.newUniqueId();
const stub = env.GAME_SESSION.get(id);
return Response.json({ gameId: id.toString() });
},
};export default {
async fetch(request: Request, env: Env): Promise<Response> {
// newUniqueId() creates a random ID - useful when creating new instances
const id = env.GAME_SESSION.newUniqueId();
const stub = env.GAME_SESSION.get(id);
return Response.json({ gameId: id.toString() });
},
};When an atom has a scale-out dimension, such as a region or a shard, consider this naming pattern: {class}:{atomId}[:{dimension}:{value}]. A consistent scheme lets any Worker compute the right object without a lookup.
Diagram as text
Name: stream:7:v2:shard:5
stream = class or type prefix
7 = atom ID
v2 = layout version (bump it before changing the shard count)
shard:5 = scale-out dimension (shard or region), always last- Start with a type prefix (
room:,session:,stream:) so that names stay readable in logs and never collide across uses. - Put the scale-out dimension last. Everything before it identifies the atom.
- Derive shards from a stable key. Hash a user ID, an event ID, or a connection ID. Never use a random number per request, or the same key lands on different objects.
- Version the layout before you change the shard count. Otherwise the same key maps to a different object mid-flight.
// Stable 32-bit FNV-1a hash: the same key maps to the same shard within a layout
function shardFor(key, shardCount) {
let hash = 0x811c9dc5;
for (let index = 0; index < key.length; index++) {
hash ^= key.charCodeAt(index);
hash = Math.imul(hash, 0x01000193);
}
return (hash >>> 0) % shardCount;
}
export default {
async fetch(request, env) {
const { streamId, eventId, payload } = await request.json();
// Per-stream settings are read-heavy config: keep them in KV
const config = await env.CONFIG.get(`stream:${streamId}`, "json");
if (!config) return new Response("Unknown stream", { status: 404 });
// The layout version is part of the name, so changing the shard
// count starts a new set of shards
const shard = shardFor(eventId, config.shardCount);
const stub = env.INGEST_SHARD.getByName(
`stream:${streamId}:v${config.layout}:shard:${shard}`,
);
const accepted = await stub.record(eventId, payload);
return new Response(null, { status: accepted ? 202 : 409 });
},
};// Stable 32-bit FNV-1a hash: the same key maps to the same shard within a layout
function shardFor(key: string, shardCount: number): number {
let hash = 0x811c9dc5;
for (let index = 0; index < key.length; index++) {
hash ^= key.charCodeAt(index);
hash = Math.imul(hash, 0x01000193);
}
return (hash >>> 0) % shardCount;
}
type StreamConfig = { shardCount: number; layout: number };
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const { streamId, eventId, payload } = await request.json<{
streamId: string;
eventId: string;
payload: string;
}>();
// Per-stream settings are read-heavy config: keep them in KV
const config = await env.CONFIG.get<StreamConfig>(
`stream:${streamId}`,
"json",
);
if (!config) return new Response("Unknown stream", { status: 404 });
// The layout version is part of the name, so changing the shard
// count starts a new set of shards
const shard = shardFor(eventId, config.shardCount);
const stub = env.INGEST_SHARD.getByName(
`stream:${streamId}:v${config.layout}:shard:${shard}`,
);
const accepted = await stub.record(eventId, payload);
return new Response(null, { status: accepted ? 202 : 409 });
},
};This example routes new events using the current layout. If an event can be retried after a layout change, retain its original layout version and shard count so that retries reach the original shard.
Do not put all your data in a single Durable Object. When you have hierarchical data (workspaces containing projects, game servers managing matches), create separate child Durable Objects for each entity. The parent coordinates and tracks children, while children handle their own state independently.
This enables parallelism: operations on different children can happen concurrently, while each child maintains its own single-threaded consistency.
import { DurableObject } from "cloudflare:workers";
// Parent: Coordinates matches, but doesn't store match data
export class GameServer extends DurableObject {
async createMatch(matchName) {
const matchId = crypto.randomUUID();
// Store reference to the child in parent's database
this.ctx.storage.sql.exec(
"INSERT INTO matches (id, name, created_at) VALUES (?, ?, ?)",
matchId,
matchName,
Date.now(),
);
// Initialize the child Durable Object
const childStub = this.env.GAME_MATCH.getByName(`match:${matchId}`);
await childStub.init(matchId, matchName);
return matchId;
}
async listMatches() {
// Parent knows about all matches without waking up each child
const cursor = this.ctx.storage.sql.exec(
"SELECT id, name FROM matches ORDER BY created_at DESC",
);
return cursor.toArray();
}
}
// Child: Handles its own game state independently
export class GameMatch extends DurableObject {
async init(matchId, matchName) {
await this.ctx.storage.put("matchId", matchId);
await this.ctx.storage.put("matchName", matchName);
this.ctx.storage.sql.exec(`
CREATE TABLE IF NOT EXISTS players (
id TEXT PRIMARY KEY,
name TEXT NOT NULL,
score INTEGER DEFAULT 0
)
`);
}
async addPlayer(playerId, playerName) {
this.ctx.storage.sql.exec(
"INSERT INTO players (id, name, score) VALUES (?, ?, 0)",
playerId,
playerName,
);
}
async updateScore(playerId, score) {
this.ctx.storage.sql.exec(
"UPDATE players SET score = ? WHERE id = ?",
score,
playerId,
);
}
}import { DurableObject } from "cloudflare:workers";
export interface Env {
GAME_SERVER: DurableObjectNamespace<GameServer>;
GAME_MATCH: DurableObjectNamespace<GameMatch>;
}
// Parent: Coordinates matches, but doesn't store match data
export class GameServer extends DurableObject<Env> {
async createMatch(matchName: string): Promise<string> {
const matchId = crypto.randomUUID();
// Store reference to the child in parent's database
this.ctx.storage.sql.exec(
"INSERT INTO matches (id, name, created_at) VALUES (?, ?, ?)",
matchId,
matchName,
Date.now(),
);
// Initialize the child Durable Object
const childStub = this.env.GAME_MATCH.getByName(`match:${matchId}`);
await childStub.init(matchId, matchName);
return matchId;
}
async listMatches(): Promise<{ id: string; name: string }[]> {
// Parent knows about all matches without waking up each child
const cursor = this.ctx.storage.sql.exec<{ id: string; name: string }>(
"SELECT id, name FROM matches ORDER BY created_at DESC",
);
return cursor.toArray();
}
}
// Child: Handles its own game state independently
export class GameMatch extends DurableObject<Env> {
async init(matchId: string, matchName: string) {
await this.ctx.storage.put("matchId", matchId);
await this.ctx.storage.put("matchName", matchName);
this.ctx.storage.sql.exec(`
CREATE TABLE IF NOT EXISTS players (
id TEXT PRIMARY KEY,
name TEXT NOT NULL,
score INTEGER DEFAULT 0
)
`);
}
async addPlayer(playerId: string, playerName: string) {
this.ctx.storage.sql.exec(
"INSERT INTO players (id, name, score) VALUES (?, ?, 0)",
playerId,
playerName,
);
}
async updateScore(playerId: string, score: number) {
this.ctx.storage.sql.exec(
"UPDATE players SET score = ? WHERE id = ?",
score,
playerId,
);
}
}With this pattern:
- Listing matches only queries the parent (children stay hibernated)
- Different matches process player actions in parallel
- Each match has its own SQLite database for player data
A parent can be an index and lifecycle manager for a set of children, such as one account's matches or one workspace's documents. In that role, it serves as their control plane. Keep routine child operations independent of it when those operations do not need parent coordination.
Diagram as text
Worker → tenant:acme (bounded parent, index of its children): create and list only (rare)
Worker → match:1 | match:2 | match:3: directly, for every player action (hot path)
tenant:acme → match:N: initialize resources through an explicit lifecycle operation
Player actions go directly to match objects; match activity does not update parent configuration.- Route independent resource operations straight to the child. Avoid consulting the parent for every player action or document edit.
- Keep administrative changes explicit. Create or delete resources through the lifecycle API. Publish operational events separately when listing or analytics needs them.
- Size the parent independently. Its administrative workload may be much smaller than the combined traffic of its children. Shard it only when its own measurements require that.
By default, a Durable Object is created near the location of the first request it receives. For most applications, this works well. However, you can provide a location hint to influence where the Durable Object is created. To pass a hint, create the ID with idFromName() and pass the option to get():
export default {
async fetch(request, env) {
const url = new URL(request.url);
const gameId = url.searchParams.get("game") ?? "default";
const regions = [
"wnam",
"enam",
"weur",
"eeur",
"apac",
"oc",
"afr",
"me",
"sam",
];
const region =
regions.find((hint) => hint === url.searchParams.get("region")) ?? "wnam";
// Provide a location hint for where this Durable Object should be created
const id = env.GAME_SESSION.idFromName(gameId);
const stub = env.GAME_SESSION.get(id, { locationHint: region });
await stub.join("player-xyz");
return new Response("Joined game");
},
};export default {
async fetch(request: Request, env: Env): Promise<Response> {
const url = new URL(request.url);
const gameId = url.searchParams.get("game") ?? "default";
const regions: DurableObjectLocationHint[] = [
"wnam",
"enam",
"weur",
"eeur",
"apac",
"oc",
"afr",
"me",
"sam",
];
const region =
regions.find((hint) => hint === url.searchParams.get("region")) ?? "wnam";
// Provide a location hint for where this Durable Object should be created
const id = env.GAME_SESSION.idFromName(gameId);
const stub = env.GAME_SESSION.get(id, { locationHint: region });
await stub.join("player-xyz");
return new Response("Joined game");
},
};Location hints are suggestions, not guarantees. Refer to Data location for available regions and details.
A Durable Object lives in one location. If one atom serves users on several continents (for example, a live feed), give it one instance per region. Put the region in the name and pass a matching location hint:
Diagram as text
Upstream source (one stream)
→ topic:42:sam (locationHint "sam") ← users in South America
→ topic:42:weur (locationHint "weur") ← users in Western Europe
→ topic:42:enam (locationHint "enam") ← users in Eastern North America
Regional instances do not share state; use them only for single-source data such as a feed.// Map the caller's continent to a Durable Objects location hint
const HINTS = {
NA: "enam",
SA: "sam",
EU: "weur",
AF: "afr",
AS: "apac",
OC: "oc",
};
export default {
async fetch(request, env) {
const topic = new URL(request.url).searchParams.get("topic");
if (!topic) return new Response("Missing topic", { status: 400 });
const hint = HINTS[String(request.cf?.continent)] ?? "enam";
// The region is part of the name: one instance per topic per region
const id = env.HUB.idFromName(`topic:${topic}:${hint}`);
return env.HUB.get(id, { locationHint: hint }).fetch(request);
},
};// Map the caller's continent to a Durable Objects location hint
const HINTS: Record<string, DurableObjectLocationHint> = {
NA: "enam",
SA: "sam",
EU: "weur",
AF: "afr",
AS: "apac",
OC: "oc",
};
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const topic = new URL(request.url).searchParams.get("topic");
if (!topic) return new Response("Missing topic", { status: 400 });
const hint = HINTS[String(request.cf?.continent)] ?? "enam";
// The region is part of the name: one instance per topic per region
const id = env.HUB.idFromName(`topic:${topic}:${hint}`);
return env.HUB.get(id, { locationHint: hint }).fetch(request);
},
};When a backend Worker first calls many objects (for example, a pool of executor shards), their default placement can concentrate them near that Worker. Use location hints to request placement across regions, while remembering that hints are not guarantees:
// Spread executor shards across regions so no single location carries them all
const REGIONS = ["wnam", "enam", "weur", "eeur", "apac"];
const EXECUTOR_SHARDS = 16;
function executorFor(env, instanceId) {
const shard = shardFor(instanceId, EXECUTOR_SHARDS);
const id = env.EXECUTOR.idFromName(`executor:${shard}`);
// A hint only applies when the object is first created,
// so keep the shard → region mapping stable
return env.EXECUTOR.get(id, {
locationHint: REGIONS[shard % REGIONS.length],
});
}// Spread executor shards across regions so no single location carries them all
const REGIONS: DurableObjectLocationHint[] = [
"wnam",
"enam",
"weur",
"eeur",
"apac",
];
const EXECUTOR_SHARDS = 16;
function executorFor(env: Env, instanceId: string) {
const shard = shardFor(instanceId, EXECUTOR_SHARDS);
const id = env.EXECUTOR.idFromName(`executor:${shard}`);
// A hint only applies when the object is first created,
// so keep the shard → region mapping stable
return env.EXECUTOR.get(id, {
locationHint: REGIONS[shard % REGIONS.length],
});
}Use Architecture examples to see how these decisions fit together. Each example identifies its coordination unit, request path, and limits. The examples are illustrative designs, not customer architectures or capacity guarantees.
| Requirement | Example | Apply this guidance |
|---|---|---|
| Administrative state changes less often than resource traffic | Account control and resource traffic | Separate the planes and plan for propagation. |
| One upstream stream serves many viewers | Fan out | Place regional instances and measure broadcast capacity. |
| Writes need application-specific coordination before backend processing | Fan in | Size each atom and use hash shards only when needed. |
| Several clients share one live session | Session per Durable Object | Choose the atom and split responsibilities if measured load requires it. |
| Conversations and agent runs have independent state | Per-user constellation | Choose granularity from state ownership, not from each tool call. |
| Many quiet entities share a changing, uneven workload | Shared shards placed by load | Version routing and plan a safe state handoff. |
| Customers deploy their own application code | Workers for Platforms | Separate deployment administration from runtime dispatch. |
When a Durable Object becomes hot, identify which resource or measured capacity its workload approaches. Then choose a scale-out technique that preserves the coordination your application needs. Smaller units can multiply upstream connections (one hub per sub-topic) or concentrate load on hot keys (one shard per event type). Consider adding shards or layers beneath the existing coordination boundary instead:
Diagram as text
Does one Durable Object approach a platform limit or miss its performance target?
no → stop: one object per atom
yes → which resource?
broadcast or socket count → fan-out tree
write rate → hash shards
storage growth → time buckets or child objects
mixed workloads → split by responsibility
Before choosing smaller units, consider upstream connections and hot keys.Trigger: one hub's broadcast latency exceeds your target at the expected subscriber count. Example: a live status feed gains subscribers faster than a regional hub can deliver updates.
Diagram as text
Origin → topic:feed:weur (relay; still exactly one upstream link per region)
→ topic:feed:weur:leaf:0 → capped share of client sockets
→ topic:feed:weur:leaf:1 → capped share of client sockets
→ topic:feed:weur:leaf:2 → capped share of client sockets
→ topic:feed:weur:leaf:3 → capped share of client sockets
Add leaves only for topics above a threshold.- The regional hub becomes a relay. It keeps the single upstream link and forwards each update to its leaves.
- Each leaf (
topic:{id}:{region}:leaf:{k}) holds a capped share of client sockets. The Worker assigns new sockets by hashing a connection ID across the current leaf count. - Enable leaves only for topics above a threshold. Most topics stay single-hub.
- Trade-off: one extra internal hop per update, plus some routing logic.
Trigger: peak writes for one atom exceed the target rate established by load-testing, or latency and overload errors show insufficient headroom. Example: an application work stream receives a burst that one ingestion buffer cannot absorb within the latency target.
Diagram as text
event A → Worker: shard = hash(eventId) % shardCount → shard:5 → accepted
event B → Worker → shard:6 → accepted
event A retry → Worker → shard:5 → duplicate detected by PRIMARY KEY (event_id)
Same key → same shard, every time: deduplication is a local SQLite constraint.- Choose the shard count from measured per-shard capacity and peak load, with headroom, and route by hash of the event ID. The diagram shows illustrative mappings, not a recommended shard count.
- The same event ID lands on the same shard within a layout, so a
UNIQUEorPRIMARY KEYconstraint detects retries locally. - Store the shard count in per-stream configuration and version it in the name. Preserve the original layout when retrying an event across a layout change.
- Trade-off: more shards can mean more, smaller batches for the backend to merge. Retention, replay, and recovery still need an end-to-end design.
Trigger: one atom's append-only data approaches its storage limit (10 GB per object on Workers Paid). Example: a tenant's audit log.
Diagram as text
Worker: bucket = yyyy-mm → audit:acme:2026-11 (hot, receives all new writes)
audit:acme:2026-10, audit:acme:2026-09 (cold, read-only, hibernated)
audit:acme:2026-08 (archived to R2, then deleted)
Monitor bucket size and roll over before reaching the applicable storage limit.Name buckets by period (audit:{tenantId}:{yyyy-mm}). Only the current bucket receives writes. Older buckets hibernate, serve occasional reads, and can be exported to R2 and deleted.
Trigger: one object is doing writes, read fan-out, and coordination at once. Example: an agent session serves read-only viewers while coordinating concurrent background runs.
Diagram as text
session:91 (source of truth, accepts all writes)
→ publish events → session:91:viewers (read-only fan-out) → viewers
→ spawn → run:a | run:b | run:… (one object per sub-agent, each ↔ its own sandbox)
⇠ each run reports its result on completion, not per token- The session object stays the source of truth and accepts all writes.
- A viewer relay (
session:{id}:viewers) serves read-only audiences, using a fan-out tree if needed. - Each sub-agent run is its own object. It reports back to the session on completion, not on every token.
- The atom is within its limits with headroom. Sharding speculatively adds hops and complexity for no benefit.
- The split would require a transaction across the new objects.
- The split adds one upstream connection, or one round trip, per new object.
- The new key is skewed. One event type or tenant would still get most of the traffic.
Deployment boundaries are separate from control-plane and data-plane roles. A small application can keep related classes in one Worker. Split class families when independent releases reduce the scope of disruptive updates.
A Worker that defines Durable Object classes is deployed together with them. By default, active Durable Objects defer code updates for up to 300 seconds while waiting to hibernate. WebSockets using the Hibernation API remain connected when an object adopts new code after hibernating. If the delay expires, or you select immediate mode, the object is reset, losing in-memory state and disconnecting WebSockets. Refer to Durable Objects code updates and Gradual deployments with Durable Objects. If one Worker defines every class, a deploy can affect objects across all of those classes, regardless of whether they serve control-plane or data-plane work.
Diagram as text
Worker logos identify deployment boundaries; Durable Objects icons identify DO classes.
Shared deployment: one Worker defines Run, Step, Shard, Timer, Account, and Index DO classes.
An immediate update can reset active objects across every class.
Separate deployments: Worker A (Run, Step), Worker B (Shard, Timer), Worker C (Account, Index).
Updating Worker B does not update objects defined in Workers A and C.
Default deferred updates can allow objects to adopt code after hibernation without a reset.- Group classes that change together (for example, runs and steps, or shards and timers) into their own Worker.
- Bind across Workers with
script_name, so the API Worker can call a class it does not deploy. - Keep RPC interfaces forwards and backwards compatible, because callers and objects now deploy independently.
- Use gradual deployments to spread resets over time within a family.
The diagram illustrates immediate updates. The default deferred code update strategy can postpone an object's update until it hibernates or reaches its configured max_delay. Deferral is best effort, so keep interfaces compatible across versions with either strategy.
{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "api",
"main": "src/index.ts",
// Set this to today's date
"compatibility_date": "2026-11-20",
"durable_objects": {
"bindings": [
{
"name": "ENGINE",
"class_name": "EngineShard",
"script_name": "engine"
}
]
}
}name = "api"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-11-20"
[[durable_objects.bindings]]
name = "ENGINE"
class_name = "EngineShard"
script_name = "engine"- Responsibilities: identify administrative operations, routine resource traffic, and analytics. Workers and Durable Objects can participate in either application plane.
- Propagation: data-plane traffic does not need to write control-plane state. Configuration has a version, a freshness policy, and a recovery path for failed publication.
- Coordination: each object owns a defined unit of state. Cross-object operations account for the absence of a shared transaction.
- Capacity: objects meet latency and throughput targets under load, with headroom for bursts and growth.
- Routing: names are deterministic, and layout changes preserve access to existing state and retries.
- Composition: resource requests bypass administrative parents when parent coordination is unnecessary.
- Placement: location hints match the workload and are treated as hints, not placement guarantees.
- Examples: the selected architecture example matches the workload and its trade-offs.
- Scale-out: you know which resource is limiting a hot object before adding shards or layers.
- Lifecycle: required state is durable, alarm ownership is explicit, and independently deployed interfaces remain compatible.