Durable Objects

무엇인가

Durable Object는 Cloudflare가 정확히 한 곳에만 존재함을 보장하는 작고 상태를 가진 서버다. 각 객체는 고유한 ID와 자체 영속 스토리지를 갖고, 요청을 한 번에 하나씩 처리하므로 조정(coordination)을 위한 자연스러운 거처가 된다 — 카운터, 락, 게임 룸, 채팅 세션. Worker가 상태 없이 어디서나 실행된다면, Durable Object는 상태를 갖고 단일하게 존재한다.

강점

• 단일 인스턴스 보장 — 복제본 간 경쟁 상태(race condition)가 없다.
• 객체와 같은 위치에 있는 내장 영속 스토리지(이제 SQLite 기반).
• 실시간 앱에 이상적: WebSockets, 프레즌스, 라이브 협업.
• 강한 일관성: 한 객체 안에서 쓰기 직후 읽기(read-after-write)가 즉시 반영된다.
• 알람(alarm)으로 객체가 자신의 미래 작업을 스케줄링할 수 있다.

트레이드오프

• 객체당 단일 스레드 — 뜨거운 객체는 병목이 될 수 있으니 키로 샤딩하라.
• 일반 Worker보다 따져야 할 것이 많다. 객체 경계를 직접 설계해야 한다.
• 객체당 스토리지는 제한적이다. 대규모에서 D1이나 R2를 대체하지 못한다.
• 상태 없는 요청 처리에는 과하다.

언제 쓰나

조정이나 엔티티별 상태가 필요할 때 Durable Objects에 손을 뻗어라: 채팅 룸, 멀티플레이어 게임 상태, 레이트 리미터, 리더 선출, 또는 여러 클라이언트가 동시에 편집하는 라이브 문서.

바이브 코딩 적합성

Durable Objects는 그렇지 않으면 만들기 까다로운 실시간 기능에서 빛나며, 에이전트가 클래스·바인딩·WebSocket 처리를 스캐폴딩할 수 있다. 어떻게 샤딩할지 — 보통 룸·사용자·문서당 하나의 객체 — 를 알려 주어 단일 객체가 모든 트래픽을 직렬화하지 않도록 하라. 아래 설정은 마이그레이션과 함께 Durable Object 클래스를 선언한다.

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

[[migrations]]
tag = "v1"
new_sqlite_classes = ["ChatRoom"]

npx wrangler deploy