Add NETfishing discovery service

docs/API.md

@@ -0,0 +1,76 @@
+# 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.