docs: clarify MVP test guide

Add the concrete pass conditions for the manual MVP proof and a small fill-in
block for relay, room, gateway interface, and LAN host values. This makes the
operator flow easier to follow before starting the relay, gateway, and Windows
client.

The guide also calls out the gateway lifecycle and CAM-refresh log lines that
matter for switch MAC learning, plus the non-link-local TAP IPv4 address to use
for ping tests.

Test Plan:
- cargo fmt --check
- cargo test --workspace
- cargo clippy --workspace --all-targets -- -D warnings
- git diff --check
- git diff --cached --check

Refs: PLAN.md MVP manual end-to-end proof
This commit is contained in:
2026-05-22 06:26:27 +02:00
parent c44dc98b22
commit ab8bda4bdf
+32 -1
View File
@@ -9,6 +9,27 @@ Windows TAP client -> public QUIC relay -> Linux AF_PACKET gateway -> LAN
The MVP is intentionally manual. It does not include an installer, GUI,
production certificates, auth, or end-to-end payload encryption.
## MVP Pass Conditions
The MVP proof is successful when all of these are true:
- Relay shows one gateway peer and one Windows client peer in the same room.
- Windows client reports `gateway connected yes`.
- Windows TAP adapter gets a real LAN DHCP address, not only `169.254.x.x`.
- A LAN host can be reached from the TAP address with `ping -S`.
- The physical switch learns the Windows client MAC on the Linux gateway port.
- A LAN game can discover or join a server through the TAP adapter.
Fill these in before starting so the commands below are just copy/edit/run:
```text
relay host: relay.example.net
relay UDP port: 8443
room code: ROOM1
gateway iface: eth0
LAN test host: <lan-host-ip>
```
## Machines
- Relay: public Linux host reachable over UDP.
@@ -90,6 +111,8 @@ Expected relay output:
accepted Gateway peer ... in room ROOM1 ...
```
Leave this running before starting the Windows client.
## Start The Windows Client
In an Administrator terminal on Windows:
@@ -141,7 +164,7 @@ DHCP received: 10.x.x.x
If Windows reports both a `169.254.x.x` TAP address and a real LAN IPv4
address, the client diagnostics should prefer the real LAN address.
## What To Verify
## Verify The Tunnel
1. Relay sees both peers:
@@ -163,6 +186,8 @@ Connected to LAN gateway
Get-NetIPAddress | ? InterfaceAlias -like "*TAP*"
```
Use the non-link-local IPv4 address as `<tap-ip>` in the next step.
4. ARP and ping work from the TAP-side address:
```powershell
@@ -191,6 +216,7 @@ relay frame room=ROOM1 ... action=Forwarded drop_reason=- targets=1
Gateway LAN traffic:
```text
gateway control event: client peer ... joined with MAC ...
gateway frame interface=eth0 direction=LanToRemote ... action=Forwarded
gateway frame interface=eth0 direction=RemoteToLan ... action=Forwarded
gateway CAM refresh interface=eth0 peer_id=... mac=... reason=peer_joined
@@ -265,6 +291,11 @@ If ping fails but DHCP worked, check Windows firewall, the target LAN host
firewall, and whether the LAN subnet conflicts with the client's home LAN.
Uncommon LAN subnets such as `10.73.42.0/24` are safer than `192.168.0.0/24`.
If switch MAC learning does not show the Windows client MAC on the gateway
port, look for `gateway CAM refresh ... reason=peer_joined`. If that line is
present but the switch still does not learn it, check the selected gateway
interface and switch port first.
## Cleanup
Stop client, gateway, and relay with Ctrl-C. The Windows client removes the