79 lines
2.3 KiB
Markdown
79 lines
2.3 KiB
Markdown
# 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": 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 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.
|