97 lines
3.4 KiB
Markdown
97 lines
3.4 KiB
Markdown
# 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. The package version follows the coordinated NETfishing release tag.
|
|
|
|
## `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.7.1-alpha",
|
|
"protocol_version": 4
|
|
}
|
|
```
|
|
|
|
`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.
|
|
|
|
The discovery release accepts room advertisements only from the matching NETfishing game release.
|
|
A mismatched `game_version` returns `409 game_version_mismatch` with `required_game_version`; the
|
|
room is not created or updated.
|
|
|
|
## `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.
|