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.

The service also runs a small UDP rendezvous. It observes packets sent from the exact ENet sockets used by hosts and joiners, then lets an authenticated room host retrieve pending endpoints and send hole-punch packets. Gameplay remains direct and never passes through this service.

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

Set NETFISHING_DISCOVERY_BUILD_REVISION to the deployed Git commit. The health response reports both the package version and that build revision, which makes production/source drift visible.

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 -----------------------> public UDP rendezvous:7771
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

The game first requests UPnP forwarding, then uses same-socket UDP rendezvous and hole punching. This covers common home NAT configurations without changing ENet gameplay authority. Symmetric NAT and some carrier-grade networks can still require a future ENet-compatible relay fallback. Expose the configured traversal port over UDP in both the host firewall and provider firewall. The rendezvous listener intentionally processes its small, bounded packets serially so arbitrary datagrams cannot create unbounded worker threads. Apply conservative edge rate limits as an additional deployment control.

API

See docs/API.md for the versioned HTTP contract.

Repository relationship

This is deliberately a separate repository from the Godot game so the service can deploy and roll back independently. Production tags follow the coordinated NETfishing release train: a vX.Y.Z-alpha tag identifies the discovery snapshot tested for the same game and dedicated-server release. The versioned HTTP contract remains independent from NETfishing's save schema and gameplay network protocol. Each tagged deployment accepts room advertisements only from its matching game release so incompatible rooms are never presented as publicly available.

Licensing

Project-owned source code is licensed under the GNU General Public License, version 3 or, at your option, any later version (GPL-3.0-or-later).

NETfishing and Woofmeow branding is not granted under the GPL; see TRADEMARKS.md. Contributions are accepted under CONTRIBUTING.md and CONTRIBUTOR-TERMS.md.

Copyright © 2026 Alexander Sellite and Rheannon Eisworth.