netfishing-discovery-server/docs/API.md

# Discovery API v1

The API stores public room advertisements as short-lived leases and coordinates direct UDP hole
punching. It does not proxy or relay gameplay traffic. NETfishing continues to connect to the
returned host and UDP port through ENet.

All request and response bodies use `application/json`. Production clients must use HTTPS.

## `GET /health`

Returns service status, package version, configured build revision, and the number of active,
unexpired room leases. Deployments should set `NETFISHING_DISCOVERY_BUILD_REVISION` to the exact
Git commit they are running.

## `GET /v1/rooms`

Lists active rooms. Optional exact-match filters:

- `game_version`
- `protocol_version`

The response contains `rooms` and the server's `ttl_seconds`.

## `POST /v1/rooms`

Creates a room lease. The service derives the advertised address from the connection rather than
trusting an address supplied by the game client.

```json
{
  "room_name": "Pond Friends",
  "port": 7777,
  "current_players": 0,
  "max_players": 8,
  "game_version": "0.6.4-alpha",
  "protocol_version": 3
}
```

`current_players` may be zero for an empty dedicated server. A player-hosted
room normally includes its host in this count.

The `201` response includes the room, a secret `lease_token`, and an endpoint verification token.
The host sends the verification token to the UDP rendezvous from its bound ENet socket. Rooms are
excluded from public listings until the service observes that endpoint.

The service applies configured global and per-observed-address active-room limits. Exceeding one
returns `429 room_limit`; expired leases stop counting automatically.

## `PUT /v1/rooms/{room_id}`

Renews and updates a room lease. Send the complete room payload and:

```text
Authorization: Bearer <lease_token>
```

Hosts should heartbeat well before the configured TTL, initially every 15 seconds for a 45-second
lease. A missing heartbeat causes automatic removal without requiring a disconnect callback.

## `DELETE /v1/rooms/{room_id}`

Removes a room immediately. Requires the same bearer token. A clean host shutdown should call this,
but TTL expiry remains authoritative for crashes and lost connectivity.

## `POST /v1/rooms/{room_id}/join-attempts`

Creates a short-lived traversal token for a public room. The joining game sends that token to the
UDP rendezvous from the same ENet socket used for the gameplay connection.

## `GET /v1/rooms/{room_id}/join-attempts`

Requires the room lease bearer token. It consumes observed joining endpoints so the host can send
same-socket UDP punch packets before ENet retries its connection.

## Error shape

```json
{
  "error": {
    "code": "invalid_room",
    "message": "port must be between 1 and 65535"
  }
}
```

## Trust boundary

- The UDP rendezvous observation is authoritative for a room's public address and port.
- `X-Forwarded-For` is honored only when the immediate peer belongs to an explicitly configured
  trusted proxy CIDR.
- Lease tokens authorize update and deletion but are never included in public listings.
- The service is an ephemeral directory, not a source of gameplay authority.