Four phases
| Phase | |
|---|---|
open | Created, waiting for the roster to fill |
active | The roster is full and play is underway |
resolved | Terminal. A terminal position was reached and the server computed a result |
abandoned | Terminal. The action deadline passed with the game unfinished, or a management client closed the session |
resolved and abandoned never transition again. Every field is in the reference.
Two modes
Both are created and driven through the same routes.
match — the default. Fill the roster, play one game, end.
table — long-lived. Active from creation, players join and leave between rounds, the model settles each round, and the table stays open until it is closed or empties. Closing a table settles every seat out first, as each player leaving would, so a bet still open on it is released rather than held.
The config is snapshotted at creation
The session resolves against that snapshot and never reads live app config again — including what each player is allowed to see, which your model decides per viewer.
So a later config edit cannot change a session already in flight. Change your rules and games in progress finish under the rules they started with.
The snapshot carries the game key, the model kind, the mode, the roster size, the turn deadline, the leaderboard target, and the model-specific rules block — kept opaque to the session infrastructure, which treats every game the same.
Membership binds to the authenticated user
members: string[] // authenticated user ids, in join order. Never client-asserted.Join order is also turn order for a sequential game.
Every route requires authentication, and membership comes from core’s auth seam — never a client-supplied id.
Who reads a session
A session reads only for the people in it. The session itself judges membership, and anyone it does not admit gets a 403: multiplayer/not_a_member on every route, a plain 403 on the socket upgrade.
| Route | Who it answers |
|---|---|
GET /multiplayer/sessions/:id, the socket, an action, a close | Current members only |
GET /multiplayer/sessions/:id/result | Anyone who ever joined, a player who left the table included |
POST /multiplayer/sessions/:id/leave | Anyone who ever joined |
Leaving closes the player’s sockets. No state frame reaches a socket whose player is no longer a member. A repeated leave is not an error, and its view shows nothing live.
This gates reading, not joining. Whoever holds an open session’s id may still join it, by design.
The Durable Object holds nothing important in memory
Metadata is read fresh on each request, from the object’s own storage.
That is not fastidiousness — it is the whole cost model. A Durable Object that holds state in memory cannot hibernate, and a session that cannot hibernate bills duration continuously while a player thinks about their move.
Game-specific state lives separately under the model’s own storage key, Zod-validated on every read — defense in depth against a corrupt blob.
The deadline is an alarm, never a timer
deadline: number | null // absolute ms-epoch, or null to wait indefinitelyEnforced by a Durable Object alarm.
A passed deadline moves the session to abandoned.
A management client can see and end a session
A session is a Durable Object addressed by its id, so nothing could list the live ones. Multiplayer keeps an index: each session writes a row to pithy_multiplayer_sessions when it opens, rewrites it as its roster and phase move, and deletes it when it ends. With the control plane composed, a management client lists the sessions in flight from it, reads one from its Durable Object, and closes a stuck one.
A close ends the session with no result. It turns abandoned, every member gets a last state frame carrying the operator’s reason in outcome.closedReason, and their sockets close. A session read never carries the game’s state. The reference has the routes, and how a result is voided.
The result is durable, and it is in your D1
The session lives in a Durable Object; the result is a single row in your own app database, joinable beside your own tables.
The publish to a leaderboard is one-way. The session writes; it never reads a board back.
Play
POST /multiplayer/games/:game create a session — you are its first member
POST /multiplayer/sessions/:id/join another player joins
POST /multiplayer/sessions/:id/action take your action
POST /multiplayer/sessions/:id/leave leave a table seat (table mode)
POST /multiplayer/sessions/:id/close close a table (table mode)
GET /multiplayer/sessions/:id your redacted view
GET /multiplayer/sessions/:id/result the durable result, once terminal
GET /multiplayer/sessions/:id/socket live play over a hibernation-safe WebSocketAn action’s body is whatever the game’s model defines. When the model declares an action schema, the session checks every action against it before apply runs, after membership and phase are judged, and a malformed one is refused with validation/invalid_input. On the socket, the same action is the payload of an action frame; the socket contract has every frame.
What a session costs
A session waiting on a player’s turn hibernates and bills no duration.
Two platform facts shape the rest — WebSocket messages bill at 20:1, and duration bills the full 128 MB regardless of how little the session uses. Both are documented, dated as of 2026-07-16, and Cloudflare’s pricing page is the authority.
Cheap idle sessions are a Durable Object property, not a Pithy feature. Anyone building on a DO gets them. What this adds is the wiring and the authority on top.