Using Matchmaking

Open a room and share a code

POST /matchmaking/games/duel/rooms

A session is minted with the host already in it, and a code is returned. This is one of four ways in.

POST /matchmaking/rooms/WXYZ-1234/join

Join tolerates lowercase, whitespace and a missing dash. The code’s alphabet already excludes I, O, 0 and 1.

Invite somebody directly

POST /matchmaking/games/duel/invites
{ "email": "ada@example.com" }

Or a screen name — best-effort, because auth exposes no unique one. A name matching zero users or several is refused rather than guessed.

Route
GET /matchmaking/invitesPending, for the caller
POST /matchmaking/invites/:id/acceptMints the session and seats both
POST /matchmaking/invites/:id/decline

Exactly two players. A game with a larger roster is refused here and told to use a code or the queue. An invite is answered once: accepting or declining one that is already accepted, declined or canceled is matchmaking/invite_not_found, and nothing is minted for it.

Friends

The fourth way in is the waiting queue, which needs provisioning before it will pair anybody.

Route
GET /matchmaking/friends
POST /matchmaking/friends/:userId/request
POST /matchmaking/friends/:userId/acceptMutual accept forms the edge
POST /matchmaking/friends/:userId/decline
DELETE /matchmaking/friends/:userId

The routes mount only when friends is on — that flag, and every other, is in the reference.

Queue

POST   /matchmaking/games/duel/queue
GET    /matchmaking/games/duel/queue
DELETE /matchmaking/games/duel/queue

A player learns they matched through presence, not by polling.

Presence

GET /matchmaking/presence      (WebSocket)

On connect: pending invites, and which friends are online now.

Then events as they happen — match_found, invite, friend_request, and, when a management client acts, invite_canceled and queue_dropped. Offer pithy.presence.v1 in Sec-WebSocket-Protocol, and a frame the socket cannot accept is answered with an error frame rather than ignored. The keepalive is a plain-text ping, answered with pong. The socket contract has every frame.

The identity is a server-set header from the authenticated handler, stashed so it survives eviction. The object never trusts a client-supplied user id.

Call it from a client

A web app the Worker serves calls these routes through @pithy-sh/matchmaking/src/client/api — createRoom, joinRoom, sendInvite, listInvites, acceptInvite, declineInvite, the friend calls, and joinQueue, readQueue and leaveQueue. presencePath gives it the presence socket’s path, and MATCHMAKING_PRESENCE_PROTOCOL the subprotocol to offer. It is same-origin by construction, and no call throws; each returns a result to render.

A mobile app or a game engine generates its HTTP client from the Worker’s openapi.json and reads the presence socket against its asyncapi.json, both written by pithy contract. The frames are Zod schemas in @pithy-sh/matchmaking/src/presence/frames.

Watch it from a dashboard

With the control plane composed, a management client reads who is waiting and acts on it. matchmaking:queues:read lists the configured games, each with the key the per-game routes take, and reads a game’s queue, from its queue object, its open rooms, and every pending invite. matchmaking:queues:moderate cancels a pending invite or drops a player from a queue, each with an idempotency key and a required reason. A cancel tells both players, and a drop tells the player why, over presence. Each act writes one audit event, and nothing here touches the friend graph. The reference has the routes.

Nothing here is a hard dependency

Each peer is reached through a seam, and its absence degrades one thing rather than breaking the composition:

AbsentWhat happens
AuthEvery route denies. The right failure — a pairing layer with no identity has nothing to pair
RatingThe queue buckets by region only. No skill matching, everything else unchanged
MultiplayerEvery pairing path still runs, and none of them can mint the session it exists to produce

Install them and it lights up, with no wiring.

Mount it elsewhere

basePath moves the whole surface. The friend routes follow it.

What it stores

pithy_matchmaking_invitesDirect invites, indexed by invitee, carrying the session id once accepted
pithy_matchmaking_friendsOne row per pair, indexed both ways
KV, matchmaking:<code>Room codes

Room codes belong in KV rather than D1 because a room code is a short-lived pointer with a TTL and a use counter — which is exactly what KV is, and nothing else here is.

Queue state lives in the queue object’s own storage, and presence is the live socket set. Neither is a row you keep.

ESC