netfishing-discovery-server/README.md

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

python3 -m netfishing_discovery

The default listener is 127.0.0.1:7770.

curl http://127.0.0.1:7770/health

Run the focused tests with:

python3 -m unittest discover -v

Configuration

Environment variables are documented in deploy/netfishing-discovery.env.example.

The intended public topology is:

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 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 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.