celld: Durable Objects on Your Own Storage Chapter 2 · The cell model

Chapter 2celld: Durable Objects on Your Own Storage

The cell model

Part II · How celld worksEdition celld v0.6.0Length 431 words · 2 min

A cell is the Durable Object: a small server with a name and a private SQLite database. You make one cell for each user, each document, each chat room, or each AI agent. A cell serves HTTP, holds WebSocket connections, sets alarms, and makes outbound connections. Two properties make the model safe without distributed locking:

  • One thread per cell. Two requests to the same cell never run at the same instant. A second request can interleave only while the first awaits, and storage operations are synchronous, so a storage operation never interleaves at all. The data in a cell stays consistent by construction. Lab 1, Part 2 shows it live: with a timer awaited between read and write, ten concurrent increments all return 1; wrapped in blockConcurrencyWhile(), they return 1 through 10.
  • No shared database. Cells share nothing; the application divides into cells from the start. The contention of one shared database never appears, because no shared database exists.
§01

Cell states

A cell has the same states as a Durable Object:

  • Resident: in memory. A resident cell is active while it does work and idle while it waits.
  • Hibernated: evicted from memory. Its hibernatable WebSocket clients stay connected and it stays on its node.
  • Inactive: no node holds it. It is only an object in the bucket, at essentially zero cost.

Every cell starts inactive. One 8 GB node holds ~1,000 resident cells, which prices a resident cell at roughly $0.05/month. Idle eviction is opt-in: CELLD_IDLE_EVICT_S sets how many seconds without work send an idle resident cell to hibernation, and when it is unset only memory pressure or the residency cap removes one. That matters for balancing (Chapter 5), which moves only hibernated cells. Lab 3, Part 2 watches a chat room hibernate while both of its sockets stay open, then wake on the next message with its constructor running again.

Fig. 1
Cell lifecycle states A cell starts inactive—only an object in the bucket. Activation restores it into memory as resident, where it is active while it works and idle while it waits. celld evicts an idle cell to hibernated, which keeps its WebSocket clients connected and keeps it on the same node; a message wakes it back to resident and the constructor runs again. Releasing ownership, or losing the node, returns a cell from either resident or hibernated to inactive. INACTIVE only an object in the bucket no node holds it ≈ zero cost every cell starts here RESIDENT in memory, one thread ACTIVE serving work IDLE waiting ~1,000 per 8 GB node ≈ $0.05/month each HIBERNATED evicted, but still placed WS clients stay connected stays on its node the only two differences activation restore from bucket constructor runs evict idle memory freed a message wakes it constructor runs again ownership released, or the node is lost—from either state the cell is back to an object in the bucket memory holds nothing across any of these transitions, so the constructor runs again on the next event
The cell lifecycle. Only two things separate a hibernated cell from a cold one: its WebSocket clients are still connected, and it is still on its node. Everything else about a wake is a cold start, which is why the constructor has to stay light and state has to be restored inside the handler.

Two practical consequences follow. First, keep the constructor light. It runs on every wake, including every message to a hibernated cell, so restore state from SQLite storage inside the handler, not in the constructor. Second, idle cost is near zero: an agent fleet whose cells hibernate between events costs almost nothing to hold, which is exactly the economics the model is designed for.

Warning
Sources

This chapter draws on: celld: documentation at v0.6.0 (9 entries) · celld: release notes (5 entries) · Cloudflare documentation (4 entries). The full entries are in the Bibliography.