# Discovery API v1

The API stores public room advertisements as short-lived leases. It does not proxy or relay game
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 and the number of active, unexpired room leases.

## `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": 1,
  "max_players": 8,
  "game_version": "0.6.4-alpha",
  "protocol_version": 3
}
```

The `201` response includes the public `room` and a secret `lease_token`. The host retains that
token only for the current hosting session.

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.

## Error shape

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

## Trust boundary

- The observed source IP is authoritative for a room's public address.
- `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.