recflare/apps/match/README.md

# match

Matchmaking Worker served on the `match` subdomain (`match.recflare.net`) — a Hono app
that handles player presence and places players into room instances. Rooms, room
instances and presence all live in the shared `recflare` D1 database.

## Routes

| Method | Path                                 | Auth | Description                                           |
| ------ | ------------------------------------ | ---- | ----------------------------------------------------- |
| POST   | `/player/login`                      |      | Login ack (no-op; must not touch presence)            |
| POST   | `/player/exclusivelogin`             |      | Exclusive-login ack (no-op) → `{ errorCode: 0 }`      |
| POST   | `/player/logout`                     | ✓\*  | Clear presence (except the Orientation seed)          |
| POST   | `/player/notifydisconnect`           |      | Disconnect notification (no-op ack)                   |
| GET    | `/player?id=1&id=2,3`                |      | Batch player presence lookup                          |
| POST   | `/player/heartbeat`                  | ✓    | Presence heartbeat (JSON body)                        |
| PUT    | `/player/statusvisibility`           | ✓\*  | Set status visibility                                 |
| GET    | `/player/avoidjuniors`               | ✓    | The player's "avoid juniors" setting → `true`/`false` |
| PUT    | `/player/avoidjuniors`               | ✓    | Set it (`avoidJuniors=True`) → the resulting value    |
| POST   | `/goto/room/:room`                   | ✓    | Go to a room (`dormroom` → personal dorm)             |
| POST   | `/matchmake/none`                    |      | Preserve current instance, else dorm                  |
| POST   | `/matchmake/room/:roomId/:subRoomId` | ✓    | Matchmake into a specific subroom                     |
| POST   | `/matchmake/room/:roomId`            | ✓    | Matchmake into a room (default subroom)               |
| POST   | `/matchmake/:room`                   | ✓    | Matchmake by id or name (`dorm` → personal dorm)      |
| POST   | `/goto/none`                         |      | Go to the dorm                                        |
| PUT    | `/player/photonregionpings`          |      | Region ping report (no-op ack)                        |
| PUT    | `/player/gameserverregionpings`      |      | Region ping report (no-op ack)                        |
| POST   | `/roominstance/:id/reportjoinresult` |      | Report join result (no-op ack)                        |
| PUT    | `/roominstance/:id/inprogress`       | ✓    | Set the instance's in-progress flag                   |
| GET    | `/room/:roomId/instances`            | ✓    | A room's live instances (owner/co-owner only)         |
| GET    | `/rooms/requiring/developer`         |      | Rooms requiring a developer → `[]`                    |
| GET    | `/rooms/requiring/rrplus`            |      | Rooms requiring RR+ → `[]`                            |
| GET    | `/openapi.json`                      |      | Generated OpenAPI 3.1 spec (see below)                |

\* `logout` and `statusvisibility` read the token when present but never 401 — an
unauthenticated call is a no-op ack. The other ✓ routes return an empty-body 401 when
the Bearer JWT (issued by the `auth` worker) is missing or invalid.

## API documentation

`GET /openapi.json` serves a spec generated from `describeRoute` blocks that sit
alongside each handler, with the schemas in `src/openapi.ts`.

**The spec is descriptive, not enforced** — same rationale as the `auth`/`accounts`
workers: a reverse-engineered protocol, lenient handlers, no runtime validation. A test
asserts every route appears in the spec, so adding one without documenting it fails.

## Presence

Presence is a per-player row in the shared `presence` table recording the room instance
that player is currently in, plus status fields (visibility, device class, VR movement
mode, platform, app version). It's written by matchmake/goto and refreshed by the
heartbeat, and read by the heartbeat and the batch `GET /player`.

- **`isOnline` means "has a live presence row"**, not "is in a room". Rows expire on a
  TTL, so a player who stops heartbeating drops offline; a player can be online in the
  lobby with `roomInstance` null.
- **The heartbeat is write-thrifty.** An unchanged heartbeat re-writes the row (to
  extend its TTL) only once the TTL is within `PRESENCE_REFRESH_THRESHOLD` seconds of
  lapsing — a still player is refreshed periodically rather than on every beat.
- **A cron sweep** (`scheduled`) clears presence past its TTL and, crucially,
  recomputes the fullness of the instances those rows pointed at. Nothing else notices
  a player who crashed or hard-quit, so without the sweep their instance can stay
  flagged full — and unjoinable — with nobody in it.

The heartbeat also accepts a non-JSON (LoginLock form) body, which it reads and ignores;
only a JSON body carries status fields.

## Matchmaking and room instances

A matchmake resolves the room (by numeric id or name) from D1, then finds a joinable
public instance of the requested subroom or creates a new `room_instance`. The result
is persisted as the player's presence so the heartbeat can replay it — keeping the
client's local presence in sync. `errorCode` 0 with a `roomInstance` is success; an
unknown room returns `errorCode` 20 (NoSuchRoom) with `roomInstance: null`.

Several behaviours are load-bearing and reverse-engineered from the client:

- **Instance names are `^`-prefixed** so the client resolves the new scene; personal
  dorms are the exception (`@owner's Dorm`, no `^`). An empty `location` (the SubRoom's
  Unity scene id) makes the client reject the session.
- **Never re-place a player into their current instance.** The client keys the room
  transition off a _changing_ `roomInstanceId`; returning the same id hangs it mid-join,
  so the join search excludes the caller's current instance.
- **Subrooms are separate places.** Joining one must never land you in an instance of
  another, so instance reuse is scoped to the exact `(roomId, subRoomId)`.
- **The dorm is a single stable instance** with a constant Photon room id, returned
  identically by every dorm entry point and the heartbeat, so the client's whole-instance
  presence check never reads out-of-sync.
- **Two dorm keywords:** `goto/room/dormroom` and `matchmake/dorm` — different spellings
  the 2023 client uses for the same destination.
- **`matchmake/none` preserves existing presence** (it's how the client establishes the
  solo Orientation room) and only falls back to the dorm when the player has none.
  `goto/none` always goes to the dorm.

### Switching a room out (`ROOM_REDIRECTS`)

An operator can substitute one room for another at matchmake time — the way to replace a
stock RRO room, typically the Rec Center (room 2), with a room of their own without
touching the client. The knob is `RECFLARE_ROOM_REDIRECTS` in the root `.env` (see
`.env.example`), comma-separated `<fromRoomId>=<to>` pairs where `<to>` is a room id or
name: `2=MyHub`, or `2=100,3=MyHub`.

Substitution happens where a matchmake resolves a named room, so it covers every route
that names one — the two- and three-segment room matchmakes and a club's clubhouse — and
everything downstream (the ban check, presence, the visit count) sees only the room
actually entered. Matching is on the resolved room id, so asking by name (`RecCenter`)
substitutes the same as asking by id.

- **A requested subroom is dropped** when a substitution fires: the id addresses a subroom
  of the room the client asked for, so entry falls back to the substitute's default one.
- **One hop only** — `2=3,3=2` swaps the two rooms rather than looping.
- **An unresolvable target leaves the original room in place** (logged), so a typo doesn't
  make a room unreachable.
- **Following a friend and joining a specific instance are unaffected** — those enter a
  live instance, which is already in whichever room it was created in.

## Bindings

| Binding                    | Type          | Notes                                                        |
| -------------------------- | ------------- | ------------------------------------------------------------ |
| `DB`                       | D1            | Shared `recflare` database — rooms, room instances, presence |
| `JWT_SECRET`               | Secrets Store | Shared HS256 signing key (see the `auth` README)             |
| `RECFLARE_PLAYER_SETTINGS` | KV            | The `playersettings` map — `/player/avoidjuniors`            |

The `presence` and `room_instance` tables are owned/migrated by the `rooms` worker. This
worker owns one table of its own, `room_invite` (`migrations/0001_room_invite.sql`, applied
under its own `d1_migrations_match` table so it doesn't clash with the other workers
sharing the database): a row per game invite `POST /invite` sends, which is what gives the
invite the `RoomInviteId` the response carries. Its `created_at` is epoch seconds, so old
invites can be swept later.

The settings KV is owned by the `playersettings` worker; this worker touches exactly one
key in it, the "avoid juniors" preference, and its write merges (as that worker's own PUT
does) so the rest of the player's settings survive.

## Known gaps

- `/rooms/requiring/developer` and `/rooms/requiring/rrplus` always return `[]` — no
  such gating queue exists yet.