Add NETfishing discovery service

README.md

@@ -0,0 +1,77 @@
+# NETfishing Discovery Server
+
+An ephemeral public-room directory for NETfishing. It complements the game's existing direct ENet
+transport: hosts advertise a room through HTTPS, browsers retrieve compatible rooms, and joining
+still uses the authoritative host's UDP endpoint.
+
+This first phase intentionally does not use coturn. TURN relays WebRTC traffic; NETfishing currently
+uses ENet/UDP, so NAT traversal and relay transport are a separate future phase.
+
+## Requirements
+
+- Python 3.11 or newer
+- A TLS reverse proxy for public deployment
+
+There are no runtime Python package dependencies.
+
+## Run locally
+
+```bash
+python3 -m netfishing_discovery
+```
+
+The default listener is `127.0.0.1:7770`.
+
+```bash
+curl http://127.0.0.1:7770/health
+```
+
+Run the focused tests with:
+
+```bash
+python3 -m unittest discover -v
+```
+
+## Configuration
+
+Environment variables are documented in
+[`deploy/netfishing-discovery.env.example`](deploy/netfishing-discovery.env.example).
+
+The intended public topology is:
+
+```text
+NETfishing client -> HTTPS reverse proxy -> 127.0.0.1:7770 discovery service
+NETfishing client -----------------------> advertised ENet/UDP host:port
+```
+
+Configure the Godot client with the reverse proxy's HTTPS origin through
+`network/discovery/base_url` in `project.godot`. For local development, the
+same value can be overridden without modifying the project by setting
+`NETFISHING_DISCOVERY_URL` before launching the game.
+
+The reverse proxy must preserve the client address in `X-Forwarded-For`, and
+its own address must be listed in `NETFISHING_DISCOVERY_TRUSTED_PROXY_CIDRS`.
+Apply ordinary request-rate limits to the write endpoints at the proxy. Do not
+expose the Python listener directly to the public Internet.
+
+Use the sample systemd unit in [`deploy/netfishing-discovery.service`](deploy/netfishing-discovery.service)
+as a deployment starting point. The service keeps only active leases in memory, so it requires no
+database, backups, or schema migrations.
+
+## Connectivity boundary
+
+Discovery makes a room findable; it does not make an unreachable ENet host
+reachable. A host still needs its advertised UDP port forwarded/reachable from
+the Internet. The existing coturn service cannot relay ENet packets because
+TURN is a WebRTC transport component. NAT traversal or relay support therefore
+remains a separate transport project and is not hidden inside the directory.
+
+## API
+
+See [`docs/API.md`](docs/API.md) for the versioned HTTP contract.
+
+## Repository relationship
+
+This is deliberately a separate repository from the Godot game. The game and service can version,
+deploy, and roll back independently. The discovery API version is independent from NETfishing's
+save schema and gameplay network protocol.