straywild-discovery-server/README.md

# 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

```bash
python3 -m straywild_discovery
```

The default listener is `127.0.0.1:7770`.

```bash
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:

```bash
python3 -m unittest discover -v
```

## Configuration

Environment variables are documented in
[`deploy/straywild-discovery.env.example`](deploy/straywild-discovery.env.example).

The intended public topology is:

```text
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`](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`](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.

## 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](LICENSE)).

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

Copyright © 2026 Woofmeow.