durable-objects ยท diff
git:20260809.e8d3666 to git:20260820.cd23820
26 added, 37 removed. Audit A to A.
---
name: durable-objects
- description: Create and review Cloudflare Durable Objects. Use when building stateful coordination, implementing RPC or HTTP interfaces, SQLite storage, alarms, WebSockets, bindings, migrations, or Durable Object tests.
+ description: Design, implement, debug, or test Cloudflare Durable Objects when the task specifically involves per-key coordination, strongly consistent object-owned state, RPC or HTTP interfaces, alarms, WebSocket hibernation, bindings, or class lifecycle. Do not trigger for ordinary stateless Workers or Cloudflare Agents SDK work already owned by the `agents-sdk` skill.
---
# Durable Objects
- Use Durable Objects for state that needs single-key coordination, strong
- consistency, persistent connections, or scheduled work. Keep the guidance
- proportional to the request: a narrow diagnosis does not require a redesign.
-
- ## Current documentation
-
- Retrieve current Cloudflare documentation when API, configuration, migration,
- or platform behavior matters:
-
- - [Documentation](https://developers.cloudflare.com/durable-objects/)
- - [API reference](https://developers.cloudflare.com/durable-objects/api/)
- - [Best practices](https://developers.cloudflare.com/durable-objects/best-practices/)
+ Use Durable Objects when one named object should serialize access to its own
+ state. Retrieve current Cloudflare documentation for APIs, bindings, storage,
+ class lifecycle, limits, and pricing.
- Load local references only when relevant:
+ Load only the relevant reference:
- - [rules.md](references/rules.md) for storage, concurrency, interfaces, and alarms.
- - [testing.md](references/testing.md) for Workers Vitest setup and alarm tests.
- - [workers.md](references/workers.md) for bindings, migrations, and observability.
+ - [rules.md](references/rules.md) for partitioning, storage, concurrency, RPC,
+ alarms, and WebSockets.
+ - [testing.md](references/testing.md) for Workers Vitest and alarm tests.
+ - [workers.md](references/workers.md) for bindings, lifecycle configuration,
+ generated types, and observability.
- ## Design checklist
+ ## Design contract
- 1. Name the coordination atom and choose a deterministic object ID. A global or
- environment-wide object is valid when deliberate low-volume serialization is
- the requirement; it is a problem only when unrelated high-volume work is
- forced through it.
- 2. Identify authoritative state and persist it before updating in-memory caches.
- Prefer SQLite for structured object-owned state; external stores remain
+ 1. Name the coordination key and deterministic object ID. Avoid a global object
+ unless deliberate low-volume global serialization is the requirement.
+ 2. Identify object-owned persistent state. Treat caches and external stores as
separate consistency boundaries.
- 3. Prefer typed RPC for new internal interfaces. Keep `fetch()` when HTTP
- semantics, headers, routing, or compatibility require it. Preserve live
- caller compatibility during interface migrations.
- 4. Keep state transitions small and deterministic. Fence or reconcile external
- I/O because it permits interleaving.
- 5. Use `blockConcurrencyWhile()` for initialization, not routine requests or
- external I/O.
- 6. Remember that each object has one alarm. Persist work and progress, make the
- handler idempotent, classify failures, and bound retries.
- 7. Verify the exact class export, binding, namespace, migration, and live path
- touched by the change. Test only the relevant lifecycle and failure cases.
+ 3. Prefer typed RPC for new internal interfaces; retain `fetch()` when HTTP
+ semantics or a live compatibility contract requires it.
+ 4. Keep state transitions deterministic. External I/O can interleave, so fence,
+ serialize, or reconcile the affected transition.
+ 5. Use `blockConcurrencyWhile()` for bounded initialization, not routine requests
+ or slow external work.
+ 6. Remember that one object has one alarm. Persist progress, make the handler
+ idempotent, and define bounded failure handling.
+ 7. Design for constructor reruns and eviction. In-memory state is not durable.
- Avoid Durable Objects for stateless work or high-fan-out independent requests
- that do not need serialization.
+ Verify the exact class export, binding target, lifecycle declaration, and live
+ path touched by the change. Test only the relevant concurrency, restart, alarm,
+ or WebSocket behavior.