For a Durable Object chat room holding 5,000 mostly idle clients, what changes in memory and billing between ws.accept() and ctx.acceptWebSocket()?
answer
- who holds the socket while idle
- eligible once handlers finish
- wall-clock GB-s at 128 MB
- messages billed twenty to one
- the constructor runs on every wake
basics
~20 sWith ws.accept() the object must stay in memory, billed for duration, as long as any socket is open. With ctx.acceptWebSocket() the runtime holds the sockets, so an idle object hibernates and accrues no duration charges until a message wakes it.
solid answer
~40 s`ws.accept()` is the standard API: the object's own event listeners hold the socket, so the object cannot hibernate, and it is billed for wall-clock duration at 128 MB for the entire time the socket is connected. `this.ctx.acceptWebSocket(ws)` is the Hibernation API: the runtime keeps the connection open, and once every handler has finished and nothing else holds the object, it becomes eligible to hibernate, and the runtime currently hibernates it after about 10 seconds idle. Eligible idle time is not billed for duration. Each incoming message wakes the object, its constructor runs again and then the handler runs, so duration follows handler time. Incoming messages are still billed as requests at a 20:1 ratio, and outgoing messages are free. For 5,000 idle chat clients, hibernation turns an always-on bill into one that follows traffic.
go deeper
Recall that ctx.acceptWebSocket() lets the object sleep with clients still connected, while ws.accept() keeps it awake and billed.
Explain eligibility (handlers finished, no timers, no pending I/O, no standard-API socket), the roughly 10-second idle period, eviction, and the constructor run on the next message.
Price it: duration is wall-clock GB-s at 128 MB, incoming messages are requests at 20:1, and one accept() socket keeps the whole object billable.
Frame it as a cost model the team can predict: hibernation makes duration follow handler time, so message rate, batching and per-message CPU become the levers.
## Two ways to accept a socket A Durable Object can serve WebSockets through either of two APIs, and the choice decides whether the object can leave memory while its clients stay connected. | | Standard API: `ws.accept()` | Hibernation API: `this.ctx.acceptWebSocket(ws)` | |---|---|---| | Who receives events | listeners added with `ws.addEventListener()` | class methods `webSocketMessage`, `webSocketClose`, `webSocketError` | | Object while clients are idle | stays in memory | eligible to hibernate | | Duration billing | the whole time the socket is connected | while handlers run, or while something else blocks hibernation | | Class fields | survive, because the instance survives | reset whenever the object hibernates | | Constructor | runs once per instance | runs again on every wake | The two cannot be combined on one socket. Calling `acceptWebSocket()` on a socket already passed to `accept()` throws `Cannot call acceptWebSocket() if the WebSocket was already accepted via accept()`. Mixing them across different sockets of one object is allowed but defeats the purpose, because a single standard-API socket keeps the whole object in memory. ## What hibernation actually does A Durable Object moves through a few lifecycle states, and the Hibernation API is what makes one of them reachable while clients are connected. - **Active**: a request or event is being handled. - **Idle, hibernateable**: nothing is running and nothing blocks hibernation. The runtime currently hibernates such an object after about 10 seconds. - **Hibernated**: the instance is removed from memory and its in-memory state is discarded, while its WebSocket clients stay connected to Cloudflare's network. - **Idle, non-hibernateable**: nothing is running, but a pending timer, unfinished I/O, an open outbound connection or a standard-API socket holds the object in memory. When a message reaches a hibernated object: 1. The runtime creates a new instance and runs the class `constructor`. 2. It calls `webSocketMessage(ws, message)` with the socket that received the message. 3. When the handler returns and nothing else is pending, the object is idle and eligible again. ## How the bill changes Two Durable Objects dimensions matter here: requests and compute duration. Prices below are the Workers Paid plan's. - **Duration** is wall-clock time in GB-seconds, always charged at the 128 MB a Durable Object is allocated, whatever it actually uses. Beyond the 400,000 GB-s included each month it costs $12.50 per million GB-s. - An object is billed for duration while it is actively running, or while it is idle but **not** eligible to hibernate. An idle object that is eligible is not billed, even before the runtime actually evicts it. - With `ws.accept()`, the object is billed for duration for the entire time the socket is connected. - **Requests**: opening each WebSocket costs one request. Incoming messages are counted at a 20:1 ratio, so 100 messages bill as 5 requests. Outgoing messages and incoming protocol pings are free. - Hibernation changes the duration line, not the request line. The pricing page's examples show the scale. 100 objects holding 50 standard-API sockets each, where every client sends a message a minute for eight hours a day, come to about $137.50 a month in duration. 100 objects holding 100 hibernatable sockets each, with a message per client per minute around the clock and 10 ms of handler time per message, come to about $12.50. ## The 5,000-client room For a room of 5,000 mostly idle clients, the standard API keeps the object in memory and billed every second of every day, even when nobody types. With the Hibernation API the bill follows activity: each message costs a twentieth of a request plus the milliseconds its handler runs. Five thousand is well under the ceiling of 32,768 hibernatable sockets per object, and a busy room is usually limited sooner by the CPU each message costs than by that number. The switch comes with three habits: - Keep the constructor light, because it runs on every wake. - Store per-socket data with the socket through `serializeAttachment()`, not in class fields, which vanish with the instance. - Find sockets through `this.ctx.getWebSockets()`, which the runtime maintains across hibernation, instead of an in-memory list. None of this changes what the client sees: it holds one open connection the whole time, and only the server side decides whether an instance sits in memory behind it.
- Does hibernation reduce the request part of the bill as well?No. Opening each WebSocket costs one request, and incoming messages are billed as requests at a 20:1 ratio whichever API accepted the socket; outgoing messages and incoming protocol pings are free. Hibernation removes duration charges for idle time, which is usually the larger cost when traffic is sparse.
- In a busy room where a message arrives every second, does hibernation still save money?Yes, on duration. An idle object that is eligible for hibernation is not billed for duration even before it is evicted, so billing still follows handler time. The object just stays in memory between frequent messages, so constructor runs are rare. What grows is CPU per message, which makes batching several logical messages into one frame worthwhile.
- Believes ws.accept() lets the object hibernate once its listeners go quiet.
- Thinks hibernation closes client connections and clients must reconnect on wake.
- Expects hibernation to make incoming WebSocket messages free of request charges.
- Calls ws.accept() first and then ctx.acceptWebSocket() on the same socket.
- Assumes class fields survive while the object is hibernated.