From ab8bda4bdf135eb6e75a66964e86a916da06859a Mon Sep 17 00:00:00 2001 From: ddidderr Date: Fri, 22 May 2026 06:26:27 +0200 Subject: [PATCH] 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 --- TESTING.md | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/TESTING.md b/TESTING.md index 06eef28..5c7ee52 100644 --- a/TESTING.md +++ b/TESTING.md @@ -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: +``` + ## 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 `` 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