Roadmap: ship the Rendezvous connection control plane #1

New Issue

2026-07-15T09:55:21+02:00

Kyuubi commented

2026-07-15 09:55:21 +02:00

Product outcome

Give SpaceGame, Unscouted, and future Final Factory multiplayer games one reusable connection control plane that can publish and browse compatible sessions, authorize a join, introduce peers through NAT, and return a typed outcome without owning gameplay or carrying normal gameplay traffic.

The service is intentionally narrower than a general game-services platform and broader than a bare server list plus NAT helper. It owns the connection lifecycle through an authenticated direct-connect attempt, then exits the gameplay path.

Product boundaries

Rendezvous owns:

game/environment policy and compatibility;
session listings, renewable leases, and host UDP presence;
bounded browser metadata and cursor-based discovery;
short-lived join attempts, punch capabilities, and connection tickets;
LiteNetLib endpoint introduction from observed UDP endpoints;
typed timeout/failure results;
security controls, observability, administration, deployment, and SDK delivery.

Each game owns:

player identity and accounts;
authoritative match admission and capacity;
simulation, replication, persistence, and gameplay traffic;
presentation of the server browser;
the final fallback decision after direct connectivity fails.

Gameplay hosting, social/chat, skill matchmaking, and relaying remain out of the initial runtime.

Recommended architecture

One deployable ASP.NET Core service with separable modules:

FinalFactory.Rendezvous.Server: directory, join authorization, endpoint registry, NAT mediator, and operations.
FinalFactory.Rendezvous.Contracts: transport-neutral IDs, requests, responses, errors, limits, and version rules.
FinalFactory.Rendezvous.Client: publisher, browser, join client, and caller-driven LiteNetLib coordinator.
FinalFactory.Rendezvous.Tests: unit, contract, security, adverse-network, lifecycle, and three-party integration tests.
FinalFactory.Rendezvous.TestClient: thin interactive/scriptable host, browser, and join diagnostic using only public SDK contracts.

The server targets the current .NET LTS. Client/contracts remain compatible with the .NET runtime used by the Godot consumers. LiteNetLib is pinned to a stable 2.x release.

Initial ephemeral state is single-instance/in-memory behind explicit store interfaces. Shared state and deterministic mediator routing are required before horizontal scaling.

Core domain

SessionListing: bounded public discovery record.
Lease: renewable capability controlling listing lifetime.
HostPresence: fresh, authenticated local/public UDP observation.
JoinAttempt: short-lived authorization connecting one client to one session.
PunchCapability: opaque one-time credential scoped to attempt, role, game, environment, and expiry.
ConnectionTicket: compact signed credential presented during the direct LiteNetLib connection.

A listing is browser-visible only while both its HTTP lease and its authenticated UDP host presence are fresh. Raw endpoints, lease credentials, punch capabilities, and internal identifiers never appear in browser responses.

v1 connection flow

Host binds its gameplay LiteNetLib NetManager.
Host registers a session over HTTP and receives lease plus host-presence capabilities.
Host renews the lease over HTTP and refreshes presence through NatPunchModule using the same gameplay UDP socket.
Client browses compatible sessions and requests a join attempt.
Client binds its gameplay NetManager and sends the punch capability to the mediator.
Mediator validates both observed endpoints, active lease/presence, scope, expiry, and replay state.
Mediator calls NatIntroduce with internal/external endpoints and a compact connection ticket.
Client connects to the successful endpoint using the same manager.
Host validates and consumes the connection ticket before accepting.
SDK reports success only after the authenticated LiteNetLib peer connection, not merely after NAT introduction.
Timeout/failure returns a typed result so the game can choose its configured fallback.

Initial policy recommendations to ratify

Use SessionListing as the canonical public noun.
Support provisioned dedicated-server credentials plus explicitly lower-trust player-hosted listings; never treat a secret embedded in a game client as user authentication.
Require exact network-protocol compatibility in v1; retain build version for display and diagnostics.
Implement IPv4 NAT punching first while keeping contracts address-family aware for IPv6 direct connections.
Return typed failure plus an optional game-configured dedicated endpoint in v1; design relay as a separate future component.
Retain aggregate outcome metrics and only short-lived diagnostic attempt records; define IP-address retention before production.
Keep directory and mediator in one executable initially, with module boundaries that permit a later operational split.

Delivery phases

Phase 0 — decisions and foundation

Ratify the ADR/threat model, bootstrap the solution and CI, then freeze v1 contracts and compatibility rules.

Phase 1 — minimum useful control plane

Implement game policy, listings/leases, browsing, publisher/browser SDKs, join authorization, LiteNetLib mediation, direct-connect coordination, a thin test client, and a deterministic three-party test.

Phase 2 — production hardening

Add malformed/replay/amplification defenses, rate limits, fuzz/load/soak tests, health/metrics/audit/admin controls, deployment artifacts, package/release automation, and failure/fallback examples.

Phase 3 — consumers and scale

Integrate SpaceGame and Unscouted independently, prove production run shapes, then add shared ephemeral state and mediator routing only when multiple service instances are required.

Future — relay

Specify and implement an optional relay only after direct-punch failure data justifies its cost. Relay remains isolated from directory/mediator state and is not a prerequisite for the direct-connect MVP.

Release gates

Contract and golden-vector compatibility tests pass.
The thin TestClient can publish, browse, join, establish an authenticated direct LiteNetLib connection, and exchange ping/echo traffic from the introduced endpoint in interactive and scripted modes.
Same-LAN, external-endpoint, timeout, rejection, cancellation, stale-host, and incompatible-version paths are deterministic.
No UDP response is sent to an unverified HTTP-supplied endpoint; amplification factor and packet sizes are bounded.
Expired/replayed/mismatched capabilities and tickets are rejected.
Listing metadata is bounded, validated, and safe to display as data.
A Linux container boots, exposes HTTP and UDP, reports liveness/readiness, drains gracefully, and emits no secrets.
Client and contracts packages are versioned and consumable by both games.
Supported and capacity profiles are measured and documented before production.

Tracking

This roadmap is complete when the implementation, hardening, adoption, and readiness issues below are closed. Individual issues remain unassigned until someone starts them.

Implementation backlog

Phase 0 — decisions and foundation

#2 — Architecture, trust, and privacy threat model
#3 — .NET solution and continuous quality gates
#4 — Versioned HTTP/UDP contracts and compatibility

Phase 1 — minimum useful control plane

#5 — Game/environment principals and key lifecycle
#6 — Atomic ephemeral state and availability semantics
#7 — Presence-gated session leases
#8 — Compatible-session browsing
#9 — Publisher/browser SDK
#10 — Join attempts, punch capabilities, and connection tickets
#11 — Authenticated presence and LiteNetLib NAT mediator
#12 — Caller-owned LiteNetLib SDK coordinator
#13 — Typed outcomes and fallback handoff
#25 — Thin interactive/scriptable TestClient
#14 — Three-party and NAT-topology integration harness

Phase 2 — public-Internet hardening and operations

#15 — Tenant isolation, abuse controls, parser/replay hardening
#16 — Observability, health, audit, privacy, and operator controls
#17 — Secure Linux container/deployment
#18 — Capacity, soak, resilience, and availability gates
#19 — Package and server artifact releases
#20 — Samples, integration documentation, and runbooks

Phase 3 — consumer adoption and production readiness

#21 — SpaceGame pilot
#22 — Unscouted pilot
#23 — Real-network canary and v1 production-readiness gate

Optional enhancements

#26 — Live session-list updates over SSE with polling fallback
#27 — Read-only diagnostic and Grafana dashboards

Evidence-driven future scope

#24 — Decide optional relay fallback from measured failures

## Product outcome Give SpaceGame, Unscouted, and future Final Factory multiplayer games one reusable connection control plane that can publish and browse compatible sessions, authorize a join, introduce peers through NAT, and return a typed outcome without owning gameplay or carrying normal gameplay traffic. The service is intentionally narrower than a general game-services platform and broader than a bare server list plus NAT helper. It owns the connection lifecycle through an authenticated direct-connect attempt, then exits the gameplay path. ## Product boundaries Rendezvous owns: - game/environment policy and compatibility; - session listings, renewable leases, and host UDP presence; - bounded browser metadata and cursor-based discovery; - short-lived join attempts, punch capabilities, and connection tickets; - LiteNetLib endpoint introduction from observed UDP endpoints; - typed timeout/failure results; - security controls, observability, administration, deployment, and SDK delivery. Each game owns: - player identity and accounts; - authoritative match admission and capacity; - simulation, replication, persistence, and gameplay traffic; - presentation of the server browser; - the final fallback decision after direct connectivity fails. Gameplay hosting, social/chat, skill matchmaking, and relaying remain out of the initial runtime. ## Recommended architecture One deployable ASP.NET Core service with separable modules: - `FinalFactory.Rendezvous.Server`: directory, join authorization, endpoint registry, NAT mediator, and operations. - `FinalFactory.Rendezvous.Contracts`: transport-neutral IDs, requests, responses, errors, limits, and version rules. - `FinalFactory.Rendezvous.Client`: publisher, browser, join client, and caller-driven LiteNetLib coordinator. - `FinalFactory.Rendezvous.Tests`: unit, contract, security, adverse-network, lifecycle, and three-party integration tests. - `FinalFactory.Rendezvous.TestClient`: thin interactive/scriptable host, browser, and join diagnostic using only public SDK contracts. The server targets the current .NET LTS. Client/contracts remain compatible with the .NET runtime used by the Godot consumers. LiteNetLib is pinned to a stable 2.x release. Initial ephemeral state is single-instance/in-memory behind explicit store interfaces. Shared state and deterministic mediator routing are required before horizontal scaling. ## Core domain - `SessionListing`: bounded public discovery record. - `Lease`: renewable capability controlling listing lifetime. - `HostPresence`: fresh, authenticated local/public UDP observation. - `JoinAttempt`: short-lived authorization connecting one client to one session. - `PunchCapability`: opaque one-time credential scoped to attempt, role, game, environment, and expiry. - `ConnectionTicket`: compact signed credential presented during the direct LiteNetLib connection. A listing is browser-visible only while both its HTTP lease and its authenticated UDP host presence are fresh. Raw endpoints, lease credentials, punch capabilities, and internal identifiers never appear in browser responses. ## v1 connection flow 1. Host binds its gameplay LiteNetLib `NetManager`. 2. Host registers a session over HTTP and receives lease plus host-presence capabilities. 3. Host renews the lease over HTTP and refreshes presence through `NatPunchModule` using the same gameplay UDP socket. 4. Client browses compatible sessions and requests a join attempt. 5. Client binds its gameplay `NetManager` and sends the punch capability to the mediator. 6. Mediator validates both observed endpoints, active lease/presence, scope, expiry, and replay state. 7. Mediator calls `NatIntroduce` with internal/external endpoints and a compact connection ticket. 8. Client connects to the successful endpoint using the same manager. 9. Host validates and consumes the connection ticket before accepting. 10. SDK reports success only after the authenticated LiteNetLib peer connection, not merely after NAT introduction. 11. Timeout/failure returns a typed result so the game can choose its configured fallback. ## Initial policy recommendations to ratify - Use `SessionListing` as the canonical public noun. - Support provisioned dedicated-server credentials plus explicitly lower-trust player-hosted listings; never treat a secret embedded in a game client as user authentication. - Require exact network-protocol compatibility in v1; retain build version for display and diagnostics. - Implement IPv4 NAT punching first while keeping contracts address-family aware for IPv6 direct connections. - Return typed failure plus an optional game-configured dedicated endpoint in v1; design relay as a separate future component. - Retain aggregate outcome metrics and only short-lived diagnostic attempt records; define IP-address retention before production. - Keep directory and mediator in one executable initially, with module boundaries that permit a later operational split. ## Delivery phases ### Phase 0 — decisions and foundation Ratify the ADR/threat model, bootstrap the solution and CI, then freeze v1 contracts and compatibility rules. ### Phase 1 — minimum useful control plane Implement game policy, listings/leases, browsing, publisher/browser SDKs, join authorization, LiteNetLib mediation, direct-connect coordination, a thin test client, and a deterministic three-party test. ### Phase 2 — production hardening Add malformed/replay/amplification defenses, rate limits, fuzz/load/soak tests, health/metrics/audit/admin controls, deployment artifacts, package/release automation, and failure/fallback examples. ### Phase 3 — consumers and scale Integrate SpaceGame and Unscouted independently, prove production run shapes, then add shared ephemeral state and mediator routing only when multiple service instances are required. ### Future — relay Specify and implement an optional relay only after direct-punch failure data justifies its cost. Relay remains isolated from directory/mediator state and is not a prerequisite for the direct-connect MVP. ## Release gates - Contract and golden-vector compatibility tests pass. - The thin TestClient can publish, browse, join, establish an authenticated direct LiteNetLib connection, and exchange ping/echo traffic from the introduced endpoint in interactive and scripted modes. - Same-LAN, external-endpoint, timeout, rejection, cancellation, stale-host, and incompatible-version paths are deterministic. - No UDP response is sent to an unverified HTTP-supplied endpoint; amplification factor and packet sizes are bounded. - Expired/replayed/mismatched capabilities and tickets are rejected. - Listing metadata is bounded, validated, and safe to display as data. - A Linux container boots, exposes HTTP and UDP, reports liveness/readiness, drains gracefully, and emits no secrets. - Client and contracts packages are versioned and consumable by both games. - Supported and capacity profiles are measured and documented before production. ## Tracking This roadmap is complete when the implementation, hardening, adoption, and readiness issues below are closed. Individual issues remain unassigned until someone starts them. ## Implementation backlog ### Phase 0 — decisions and foundation - [ ] #2 — Architecture, trust, and privacy threat model - [ ] #3 — .NET solution and continuous quality gates - [ ] #4 — Versioned HTTP/UDP contracts and compatibility ### Phase 1 — minimum useful control plane - [ ] #5 — Game/environment principals and key lifecycle - [ ] #6 — Atomic ephemeral state and availability semantics - [ ] #7 — Presence-gated session leases - [ ] #8 — Compatible-session browsing - [ ] #9 — Publisher/browser SDK - [ ] #10 — Join attempts, punch capabilities, and connection tickets - [ ] #11 — Authenticated presence and LiteNetLib NAT mediator - [ ] #12 — Caller-owned LiteNetLib SDK coordinator - [ ] #13 — Typed outcomes and fallback handoff - [ ] #25 — Thin interactive/scriptable TestClient - [ ] #14 — Three-party and NAT-topology integration harness ### Phase 2 — public-Internet hardening and operations - [ ] #15 — Tenant isolation, abuse controls, parser/replay hardening - [ ] #16 — Observability, health, audit, privacy, and operator controls - [ ] #17 — Secure Linux container/deployment - [ ] #18 — Capacity, soak, resilience, and availability gates - [ ] #19 — Package and server artifact releases - [ ] #20 — Samples, integration documentation, and runbooks ### Phase 3 — consumer adoption and production readiness - [ ] #21 — SpaceGame pilot - [ ] #22 — Unscouted pilot - [ ] #23 — Real-network canary and v1 production-readiness gate ### Optional enhancements - [ ] #26 — Live session-list updates over SSE with polling fallback - [ ] #27 — Read-only diagnostic and Grafana dashboards ### Evidence-driven future scope - [ ] #24 — Decide optional relay fallback from measured failures

Kyuubi referenced this issue

2026-07-15 10:04:12 +02:00

Ratify the v1 architecture, trust model, and privacy threat model #2

Kyuubi commented

2026-07-16 04:53:07 +02:00

Roadmap progress: issue #4 (versioned v1 HTTP/UDP/error/compatibility contracts) is implemented and pushed as 69c8b2d on codex/issue-4-v1-contracts. Locked restore, Release build, formatter, generated-OpenAPI drift check, real-process HTTP/UDP smoke, and all 36 tests pass. The stacked issue branch is not merged yet.

Roadmap progress: issue #4 (versioned v1 HTTP/UDP/error/compatibility contracts) is implemented and pushed as `69c8b2d` on `codex/issue-4-v1-contracts`. Locked restore, Release build, formatter, generated-OpenAPI drift check, real-process HTTP/UDP smoke, and all 36 tests pass. The stacked issue branch is not merged yet.

Kyuubi commented

2026-07-16 05:14:05 +02:00

Roadmap progress: issue #5 (game/environment provisioning, typed principals, and tenant-scoped signing-key lifecycle) is implemented and pushed as 47382dd on codex/issue-5-provisioning. Locked restore, formatter, Release build, OpenAPI drift check, real Development readiness, explicit Production fail-closed startup, and all 56 tests pass. The stacked branch is not merged yet.

Roadmap progress: issue #5 (game/environment provisioning, typed principals, and tenant-scoped signing-key lifecycle) is implemented and pushed as `47382dd` on `codex/issue-5-provisioning`. Locked restore, formatter, Release build, OpenAPI drift check, real Development readiness, explicit Production fail-closed startup, and all 56 tests pass. The stacked branch is not merged yet.

Kyuubi commented

2026-07-16 05:33:11 +02:00

Roadmap progress: issue #6 (bounded atomic ephemeral state and single-active availability semantics) is implemented and pushed as 02ca502 on codex/issue-6-atomic-state. Locked restore, formatter, Release build, generated-contract drift, real Development readiness, and all 78 tests pass. The stacked branch is not merged yet.

Roadmap progress: issue #6 (bounded atomic ephemeral state and single-active availability semantics) is implemented and pushed as `02ca502` on `codex/issue-6-atomic-state`. Locked restore, formatter, Release build, generated-contract drift, real Development readiness, and all 78 tests pass. The stacked branch is not merged yet.

Kyuubi commented

2026-07-16 05:59:15 +02:00

Roadmap progress: issue #7 (authenticated session registration, UDP-presence-gated leases, ownership, and expiry) is implemented and pushed as 49564c7 on codex/issue-7-session-leases. Locked restore, formatter, Release build, OpenAPI drift, real HTTP/UDP smoke, and all 94 tests pass. The stacked branch is not merged yet.

Roadmap progress: issue #7 (authenticated session registration, UDP-presence-gated leases, ownership, and expiry) is implemented and pushed as `49564c7` on `codex/issue-7-session-leases`. Locked restore, formatter, Release build, OpenAPI drift, real HTTP/UDP smoke, and all 94 tests pass. The stacked branch is not merged yet.

Kyuubi commented

2026-07-16 06:06:54 +02:00

Roadmap progress: issue #8 (bounded compatible-session browsing and listing visibility) is implemented and pushed as a9a2b3d on codex/issue-8-session-browser. Locked restore, formatter, Release build, OpenAPI drift, real HTTP browsing, and all 100 tests pass. The stacked branch is not merged yet.

Roadmap progress: issue #8 (bounded compatible-session browsing and listing visibility) is implemented and pushed as `a9a2b3d` on `codex/issue-8-session-browser`. Locked restore, formatter, Release build, OpenAPI drift, real HTTP browsing, and all 100 tests pass. The stacked branch is not merged yet.

Kyuubi commented

2026-07-16 06:28:11 +02:00

Roadmap progress: issue #9 (publisher and session-browser .NET client SDK) is implemented and pushed at 06c3973 on codex/issue-9-client-sdk.

The SDK now covers typed publishing, renewal/update/deregistration, bounded browsing/paging, explicit lease maintenance, stable failures/retries, test injection seams, package guidance, API compatibility, and real-server integration. Final gates: Release build clean, package clean, 110/110 tests passing. Next dependency-ready item is #10.

Roadmap progress: issue #9 (publisher and session-browser .NET client SDK) is implemented and pushed at `06c3973` on `codex/issue-9-client-sdk`. The SDK now covers typed publishing, renewal/update/deregistration, bounded browsing/paging, explicit lease maintenance, stable failures/retries, test injection seams, package guidance, API compatibility, and real-server integration. Final gates: Release build clean, package clean, 110/110 tests passing. Next dependency-ready item is #10.

Kyuubi referenced this issue

2026-07-16 06:28:27 +02:00

Implement short-lived join attempts, punch capabilities, and connection tickets #10

Kyuubi commented

2026-07-16 06:56:58 +02:00

Roadmap update: issue #10 is implemented and verified on codex/issue-10-join-attempts at 1baa105 (126/126 tests passing). Moving next to #11, the authenticated host-presence and amplification-safe LiteNetLib NAT mediator.

Roadmap update: issue #10 is implemented and verified on `codex/issue-10-join-attempts` at `1baa105` (126/126 tests passing). Moving next to #11, the authenticated host-presence and amplification-safe LiteNetLib NAT mediator.

Kyuubi commented

2026-07-16 07:37:33 +02:00

Roadmap update: issue #11 is implemented, adversarially audited, and verified on codex/issue-11-nat-mediator at 6d076c2 (145/145 tests passing). Moving next to #12, the caller-owned LiteNetLib connection coordinator.

Roadmap update: issue #11 is implemented, adversarially audited, and verified on `codex/issue-11-nat-mediator` at `6d076c2` (145/145 tests passing). Moving next to #12, the caller-owned LiteNetLib connection coordinator.

Kyuubi referenced this issue

2026-07-16 22:17:17 +02:00

Design shared state and deterministic routing for HA and multi-region #28

Kyuubi referenced this issue

2026-07-16 22:17:18 +02:00

Scale beyond the measured single-active v1 capacity envelope #29

Kyuubi referenced this issue

2026-07-16 22:17:19 +02:00

Add platform authentication adapters without making Rendezvous an identity provider #30

Kyuubi commented

2026-07-17 00:25:10 +02:00

Consolidated roadmap reconciliation checkpoint after closing #27:

Current stacked delivery tip: 99885f8 on codex/issue-27-diagnostic-dashboards, pushed with a clean worktree.
Locally implementable roadmap scope #2–#20, #25, #26, and #27 is present in the stack and individually verified; #10, #26, and #27 are already closed. The older issues remain open only because their completion comments explicitly require the stack to land on main before closure.
Latest full gate: formatting clean, Debug/Release builds clean, 320/320 Release tests, dependency-free dashboard tests, clean merged Compose provisioning, rendered browser accessibility/security verification, real three-party TestClient scenario, and workload-backed Prometheus/Grafana evidence.
#21 and #22 remain correctly open for public immutable-package restore and representative external NAT/CGNAT/IPv6/multi-host evidence.
#23 remains correctly NOT READY/open for its 13 protected-credential, public-network, one-hour endurance, real-alert, independent-operator, and recovery evidence gates.
#24 remains dependency-blocked by measured production failure data from #23.
#28–#30 remain explicit post-v1, trigger-gated follow-ups; their HA/scale/platform conditions have not occurred and speculative implementation would violate their own issue classifications.

No production-ready claim is made. The next local reconciliation step is landing the verified stack on main and closing the completed implementation issues; that external branch mutation still requires explicit merge authorization.

Consolidated roadmap reconciliation checkpoint after closing #27: - Current stacked delivery tip: `99885f8` on `codex/issue-27-diagnostic-dashboards`, pushed with a clean worktree. - Locally implementable roadmap scope #2–#20, #25, #26, and #27 is present in the stack and individually verified; #10, #26, and #27 are already closed. The older issues remain open only because their completion comments explicitly require the stack to land on `main` before closure. - Latest full gate: formatting clean, Debug/Release builds clean, 320/320 Release tests, dependency-free dashboard tests, clean merged Compose provisioning, rendered browser accessibility/security verification, real three-party TestClient scenario, and workload-backed Prometheus/Grafana evidence. - #21 and #22 remain correctly open for public immutable-package restore and representative external NAT/CGNAT/IPv6/multi-host evidence. - #23 remains correctly NOT READY/open for its 13 protected-credential, public-network, one-hour endurance, real-alert, independent-operator, and recovery evidence gates. - #24 remains dependency-blocked by measured production failure data from #23. - #28–#30 remain explicit post-v1, trigger-gated follow-ups; their HA/scale/platform conditions have not occurred and speculative implementation would violate their own issue classifications. No production-ready claim is made. The next local reconciliation step is landing the verified stack on `main` and closing the completed implementation issues; that external branch mutation still requires explicit merge authorization.

Kyuubi self-assigned this 2026-07-17 00:26:48 +02:00

Kyuubi commented

2026-07-17 00:34:20 +02:00

Merge-gate checkpoint: the stacked roadmap branch is clean through Release build, 320/320 tests, 15/15 architecture/API/docs convention tests, formatting/analyzers, dashboard assets, compatibility/license checks, generated API verification, and the quick capacity/resilience gate. The gate exposed one full-suite-only SSE integration timeout; the test-only timing budget was stabilized and the complete suite is green again. This branch advances #1; external production/canary and public-package gates remain open.