docs: describe Rendezvous service (#3)

2026-07-15 10:10:40 +02:00
commit 2959c7e845
1 changed files with 78 additions and 0 deletions
@@ -0,0 +1,78 @@
+# Rendezvous
+
+Rendezvous is shared discovery and connection-coordination infrastructure for Final Factory multiplayer games. It gives games such as **SpaceGame** and **Unscouted** a common way to publish available servers, browse sessions, authorize joins, and establish direct peer-to-peer UDP connections through NAT where possible.
+
+Rendezvous is not a game server. It does not simulate gameplay, own match state, or carry normal gameplay traffic. Once two peers establish a direct connection, the service leaves the gameplay path.
+
+## Responsibilities
+
+Rendezvous is intended to provide:
+
+- Server registration with renewable heartbeat leases.
+- Server and session browsing with bounded, game-specific metadata.
+- Public endpoint observation for hosts and clients.
+- LiteNetLib NAT introduction and UDP hole punching.
+- Short-lived, authenticated join and punch tokens.
+- Clear timeouts and failure results when a direct connection cannot be established.
+- Isolation by game, environment, protocol version, and region.
+- Operational health, metrics, logging, administration, and rate limiting.
+
+UDP hole punching cannot guarantee a direct connection through every network. Symmetric NAT, carrier-grade NAT, restrictive firewalls, and platform policies can prevent it. Consumers must therefore support a defined fallback, such as a dedicated server or a future relay service.
+
+## Connection flow
+
+1. A host registers a server or session and renews its lease with heartbeats.
+2. A client queries Rendezvous and selects a compatible session.
+3. Rendezvous validates the join request and issues short-lived credentials.
+4. The host and client contact the mediator from their gameplay UDP sockets.
+5. The mediator introduces their observed public and reported local endpoints.
+6. Both peers attempt LiteNetLib UDP hole punching.
+7. On success, they establish a direct authenticated connection.
+8. On timeout or failure, the game selects or reports its configured fallback.
+
+## Planned components
+
+- `FinalFactory.Rendezvous.Server` — deployable service hosting the server directory, HTTP API, and UDP NAT mediator.
+- `FinalFactory.Rendezvous.Contracts` — versioned wire contracts and shared protocol definitions.
+- `FinalFactory.Rendezvous.Client` — .NET client library used by participating games.
+- `FinalFactory.Rendezvous.TestClient` — thin interactive and scriptable host/browser/join diagnostic built only on the public SDK.
+- `FinalFactory.Rendezvous.Tests` — unit, integration, security, and connection-lifecycle tests.
+
+The server directory and NAT mediator begin as separate modules in one deployable service because they share session, lease, authorization, and endpoint state. Their internal boundary should allow independent deployment later if scale, availability, or security requirements diverge.
+
+## Service boundaries
+
+Rendezvous must remain independent of game simulation and transport payloads. Each game supplies only the information required for discovery and compatibility, including:
+
+- A stable game identifier and environment.
+- Build and network-protocol compatibility versions.
+- Region and capacity information.
+- A bounded, validated metadata document for browser presentation.
+
+Canonical player, world, inventory, combat, and persistence state remains owned by each game's authoritative server. Rendezvous identifiers must never become canonical entity or player identities.
+
+## Security model
+
+The service is designed as public Internet infrastructure. Implementations should assume all registrations, searches, metadata, and UDP packets are hostile. At minimum, the production service will require:
+
+- Per-game credentials and signing keys.
+- Short-lived, single-purpose tokens resistant to replay.
+- Strict payload, metadata, and token size limits.
+- Registration, query, and introduction rate limits.
+- Lease expiry so abandoned or crashed servers disappear automatically.
+- Validation of game, environment, room, and protocol-version boundaries.
+- Structured audit events without logging secrets or reusable credentials.
+
+## Non-goals
+
+The initial service does not provide:
+
+- Gameplay hosting or authoritative simulation.
+- General-purpose user accounts, social features, or chat.
+- Skill-based matchmaking.
+- Guaranteed traversal through every NAT or firewall.
+- Gameplay relaying; a relay may be designed as a separate future component.
+
+## Project status
+
+Rendezvous is currently in its initial design and bootstrap stage. The first implementation should establish the contracts, directory leases, LiteNetLib mediator, client SDK, thin test client, and a three-party integration test before either game depends on it for production connectivity.