straywild Discovery Server

An ephemeral public-room directory for straywild. 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.

Friend presence and live room invitations use the same service as short-lived capability channels. There are no discovery accounts, durable friend records, or offline messages; friendship state stays on each player's device.

Requirements

• Python 3.11 or newer
• A TLS reverse proxy for public deployment

There are no runtime Python package dependencies.

Run locally

python3 -m straywild_discovery

The default listener is 127.0.0.1:7770.

curl http://127.0.0.1:7770/health

Set straywild_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/straywild-discovery.env.example.

The intended public topology is:

straywild client -> HTTPS reverse proxy -> 127.0.0.1:7770 discovery service
straywild client -----------------------> public UDP rendezvous:7771
straywild 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 straywild_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 straywild_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/straywild-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 straywild 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 straywild'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.

Existing NETfishing installations can be upgraded in place. The legacy netfishing_discovery module, command name, and NETFISHING_DISCOVERY_* environment variables remain accepted, while new installations should use the Straywild names shown above. When both forms of an environment setting exist, the Straywild value takes precedence.

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

straywild and Woofmeow branding is not granted under the GPL; see TRADEMARKS.md. Unsolicited contributions are not accepted; see CONTRIBUTING.md. Historical and expressly invited work is governed by CONTRIBUTOR-TERMS.md.

Copyright © 2026 Woofmeow.