Durable Object WebSocket Hibernation: Mental Model

Durable Objects are a natural fit for chat rooms, sessions, dashboards, game lobbies, and agent conversations because one DO can act as the live manager for one named room or session. The cost problem appears because WebSockets remain open for long periods even when nothing is happening.

Non-Hibernating Model

Client connects
DO accepts WebSocket
DO remains active while connection stays open

In the normal model, an accepted connection can keep the Durable Object awake in memory even during long periods of silence.

User is connected
  -> DO is awake
  -> duration billing continues

Hibernating Model

Client remains connected
DO can sleep when idle
DO wakes when message or event arrives

The important change is that the connection lifetime and the compute lifetime become separable.

User is connected
  -> DO can sleep
  -> no duration billing while hibernated
  -> event arrives
  -> DO wakes and handles it

Simple Analogy

Non-hibernating:
phone call is connected
person keeps holding phone in silence

Hibernating:
phone call is connected
person sleeps during silence
wakes when someone speaks

Why It Matters

WebSockets are long-lived. For chat apps, dashboards, collaborative tools, or multiplayer lobbies, the idle time can dominate the billing if compute stays awake the whole time.

What You Must Not Assume

With hibernation, in-memory JavaScript state is not reliable across idle periods.

Memory = temporary cache
Storage = durable source of truth
WebSocket attachments = recover connection metadata after wake

State Design Implication

A hibernating chat room should persist important room state and recover what it needs when it wakes again.

  • room metadata
  • user identity
  • permissions
  • sequence or progress metadata
  • presence metadata if needed

Code Shape Changes

The runtime model shifts from ordinary in-memory socket tracking to hibernation-aware APIs.

non-hibernating:
server.accept();
this.sockets.add(server);

hibernating:
this.ctx.acceptWebSocket(server);

Then the DO class handles `webSocketMessage()` and `webSocketClose()` instead of treating sockets only as normal memory-held event listeners.

Memory Line

WebSocket hibernation does not keep the DO awake for the whole connection. It keeps the connection alive while letting the DO sleep between events, which means your durable state design matters more than your in-memory state.

Part 1 of 2