feat(tooling): add standalone rendezvous test client (#25)

2026-07-16 11:05:56 +02:00
parent 94aba8a3bb
commit 7e3be2cad1
16 changed files with 2721 additions and 12 deletions
@@ -0,0 +1,56 @@
+# FinalFactory.Rendezvous.TestClient
+
+This is a diagnostic executable for exercising Rendezvous through the same public
+Client and Contracts API available to a game. It is not a production game client,
+server browser, dedicated server, relay, account system, or gameplay host.
+
+The executable has three explicit modes:
+
+- `host` publishes a session, maintains presence and its lease, accepts an
+authenticated direct peer, and answers a bounded ping/echo/ack/completion exchange;
+- `browse` prints compatible public listings; and
+- `join` selects or accepts a listing, drives traversal on its caller-owned
+  LiteNetLib socket, proves direct traffic, reports the typed outcome, and exits.
+
+Run `dotnet run --project src/FinalFactory.Rendezvous.TestClient -- --help` for
+the complete option reference. A typical script-mode invocation is:
+
+```bash
+export RENDEZVOUS_PUBLISHER_CREDENTIAL='<credential from the deployment boundary>'
+dotnet run --project src/FinalFactory.Rendezvous.TestClient -- \
+  host --service http://127.0.0.1:5000/ --mediator 127.0.0.1:9050 \
+  --game space-game --environment development --region local --protocol 1 \
+  --script --json --exit-after-echo
+```
+
+Publisher credentials are accepted only through a named environment variable.
+There is deliberately no command-line credential option because process command
+lines are routinely exposed to other local tools and diagnostics. Output uses an
+allowlisted event model and never includes lease tokens, punch capabilities,
+connection tickets, raw metadata, signing material, or reusable credentials.
+
+Script mode never prompts. Join mode selects the first compatible listing unless
+`--listing UUID` fixes the choice. `--json` emits one JSON object per line with
+`version: 1`; event names and the process exit codes below are stable automation
+contracts. A script-mode host without `--run-seconds` uses `--timeout-seconds` as
+its total runtime bound. New optional event properties may be added without changing
+the version. JSON help and usage failures are versioned events as well; informational
+events use stdout and failures use stderr.
+
+| Exit | Meaning |
+|---:|---|
+| `0` | Requested diagnostic flow completed successfully |
+| `2` | Invalid command or options |
+| `3` | Missing or invalid local configuration |
+| `10` | HTTP, registration, browser, lease, or socket failure |
+| `11` | No compatible session was available or selected |
+| `12` | Authorization or traversal reached a typed terminal failure |
+| `13` | A requested direct ping/echo proof did not complete |
+| `130` | Caller cancellation or Ctrl+C |
+
+The client prints the selected direct endpoint category (`loopback`, `private`, or
+`public`) but never the raw endpoint. A traversal failure reports whether an
+authoritative dedicated fallback is available; the diagnostic does not connect to
+that fallback automatically. A host may publish a policy-authorized endpoint with
+`--fallback IP:PORT`. See the repository integration guide for process
+orchestration and topology limitations.