client/matchmaking-api/README.md

# Spacewar Matchmaking API

FastAPI service for matchmaking, stats, and ranks (chat planned — see below).
One process, one Postgres database, no Redis: matchmaking tickets live
in-memory in the API process, which is enough at this scale — add Redis
later only if the API needs to run as more than one instance.

## Run it

```
cp .env.example .env   # already done for local dev; edit if needed
docker compose up -d
```

API is at `http://localhost:8100`, interactive docs at `/docs`. Postgres is
exposed on host port `5433` (mapped from its usual `5432`, to avoid clashing
with any other local Postgres) for local inspection.

```
docker compose down          # stop
docker compose down -v       # stop + wipe the postgres volume
```

Code in `app/` is bind-mounted with `--reload`, so edits take effect without
rebuilding the image. Rebuild (`docker compose up -d --build`) only when
`requirements.txt` changes.

## How matchmaking works right now

- `POST /matchmaking/queue/join` `{callsign, mode}` — creates the
  player row if it doesn't exist yet, returns a `ticket_id`.
- `GET /matchmaking/queue/status/{ticket_id}` — poll this; once matched it
  returns the assigned server's `server_ip`/`server_port`/`team`.
- `POST /matchmaking/queue/leave?ticket_id=...` — cancel a queued ticket.

A background loop (`app/queue_manager.py`) runs every 2s and forms a match
once enough players are queued for casual, then splits them into two teams
and assigns the first available `GameServer`. Casual has bot fill
(`spacewar/bots/bot_manager.gd` pads both teams up to
`GameConfig.bot_min_team_size` in-game), so 1 queued player is enough to
form a match — `CASUAL_TEAM_SIZE` just caps how many real players can group
into one match, it no longer gates formation. Ranked mode has been removed
entirely (was never implemented past matchmaking-queue scaffolding) — the
`Mode` enum only has `casual` now.

Real servers self-register: `spacewar/autoload/network_manager.gd`'s
`host_server()` calls `POST /servers/register` once on boot and then every
`HEARTBEAT_INTERVAL` (8s) as a heartbeat, reporting live player count. The
endpoint upserts on `(ip, port, mode)` — an unrecognized combo creates a
row, a recognized one just refreshes it — and now also computes `status`
from `player_count` vs `max_players` (`full` once at capacity) instead of
always writing `available`. A background loop (`sweep_stale_servers` in
`app/routers/servers.py`, run every 5s from `main.py`'s lifespan) marks a
server `offline` once its `last_heartbeat` is older than
`server_stale_seconds` (20s default) — catches a server that crashed or was
`kill -9`'d instead of shutting down cleanly, so it doesn't sit in the list
looking joinable forever.

Three demo `GameServer` rows are still auto-seeded on API startup
(`_seed_demo_servers` in `main.py`) at `127.0.0.1:7777/7778/7779` with
`player_count` 40/20/10 out of `max_players` 50, so `menu/server_select.gd`
has something to list even with no real server running — and since
registration is a plain upsert, running a real Godot server on one of those
same `(ip, port)` pairs (`godot4 --headless --path spacewar -- --server`)
just takes that row over with live data, no special-casing needed. A demo
row with nothing real backing it goes stale and flips to `offline` within
`server_stale_seconds` of API startup, same as any other server. `--server-ip=`
(new `network_manager.gd` cmdline arg) controls what IP a hosted server
advertises — defaults to loopback for local dev. That IP is handed straight
to game clients to connect to, so it must be reachable from wherever the
*client* runs, not the API container — `host.docker.internal` would resolve
inside the api container but not on the client's machine, which is why this
isn't a docker-internal address (same constraint `DEV_SEED_SERVER_IP` has).
`player_count`/`max_players` from `GET /servers` are just this DB-stored
value; `menu/server_select.gd` also queries each server directly over UDP
(`network_manager.gd`'s ping responder) for a live, pre-connect number and
RTT, overriding the DB value in the UI once that probe answers.

## Client integration

The Godot client is wired up (`spacewar/autoload/matchmaking_client.gd`):
QUICK PLAY on the main menu calls `POST /matchmaking/queue/join`, polls
`GET /matchmaking/queue/status/{ticket_id}` every 1.5s, and once `matched`
connects `NetworkManager` directly to the returned `server_ip`/`server_port`.
Point it at a non-default API with `godot4 ... -- --matchmaking-api=http://host:port`.

## Adding a new domain (stats/ranks did this; chat will too)

1. Add/extend a model in `app/models.py` if it needs its own table.
2. Add request/response shapes to `app/schemas.py`.
3. Add a router file under `app/routers/`, `include_router()` it in
   `app/main.py`.

Chat isn't scaffolded yet (no data model or requirements decided), but it
fits the same shape — likely a WebSocket router using FastAPI's native
support, in this same service.

## Not set up yet, on purpose

- **Migrations**: tables are created via `Base.metadata.create_all()` on
  startup. Fine while the schema is still moving; switch to Alembic before
  this holds real data.
- **Auth**: `callsign` is the only player identity, matching the game
  client's current state (no accounts yet). Real identity arrives with the
  GodotSteam auth checklist item in `overview/tech.md`.
- **Bot-fill timeouts**: current matching is a simple threshold (enough
  players queued → form a match). Refine once there's real queue volume to
  tune against.