woofmeow/netfishing-discovery-server
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: add UDP NAT rendezvous

Browse source
This commit is contained in:
Alexander Sellite 2026-08-10 19:49:47 -04:00
parent 6a7c7a676d
commit 804e19c51a
7 changed files with 370 additions and 27 deletions
Download patch file Download diff file Expand all files Collapse all files

22
docs/API.md
View file

@ -1,7 +1,8 @@
# 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.
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.
@ -37,8 +38,9 @@ trusting an address supplied by the game client.
`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 `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.
@ -59,6 +61,16 @@ lease. A missing heartbeat causes automatic removal without requiring a disconne
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
@ -72,7 +84,7 @@ but TTL expiry remains authoritative for crashes and lost connectivity.
## Trust boundary
- The observed source IP is authoritative for a room's public address.
- 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.