docs: expand MVP test guide

Refresh the manual MVP test guide around the current relay, gateway, and
Windows client behavior. The guide now calls out the values to record during a
run, the exact process order, expected gateway lifecycle signals, and a short
gateway restart sanity check.

Also update the README component notes so the control plane and Windows client
docs mention the gateway peer id carried in welcomes.

Test Plan:
- git diff --check
- git diff --cached --check

Refs: MVP manual validation
This commit is contained in:
2026-05-22 07:24:07 +02:00
parent d15031c9d1
commit 8deb7d1d60
2 changed files with 47 additions and 3 deletions
+3 -3
View File
@@ -33,7 +33,7 @@ Reliable control-plane schema shared by the QUIC stream handlers:
- endpoint hello messages with role, room, MAC, and datagram budget - endpoint hello messages with role, room, MAC, and datagram budget
- server welcome mode, reject, peer lifecycle, stats, and disconnect messages - server welcome mode, reject, peer lifecycle, stats, and disconnect messages
- initial room gateway-presence status in server welcomes - initial room gateway-presence status and gateway peer id in server welcomes
- room-code, role/MAC, peer-id, and effective-MTU validation - room-code, role/MAC, peer-id, and effective-MTU validation
- length-prefixed JSON control frames for reliable QUIC streams - length-prefixed JSON control frames for reliable QUIC streams
@@ -290,5 +290,5 @@ with direction, peer id, MACs, ethertype/length, frame length, action, and drop
reason. TAP device read/write errors still stop the bridge. reason. TAP device read/write errors still stop the bridge.
Relay lifecycle events are logged as they arrive, including gateway joins and Relay lifecycle events are logged as they arrive, including gateway joins and
peer leaves. The client remembers peer identities from join and catch-up events peer leaves. The client remembers peer identities from join and catch-up events
so later leave logs can identify a disconnected LAN gateway or client MAC when and from the initial welcome, so later leave logs can identify a disconnected
that peer was known. LAN gateway or client MAC when that peer was known.
+44
View File
@@ -30,6 +30,15 @@ gateway iface: eth0
LAN test host: <lan-host-ip> LAN test host: <lan-host-ip>
``` ```
Keep these values from the logs as you go:
```text
gateway peer id:
client peer id:
client virtual MAC:
Windows TAP IPv4:
```
## Machines ## Machines
- Relay: public Linux host reachable over UDP. - Relay: public Linux host reachable over UDP.
@@ -37,6 +46,7 @@ LAN test host: <lan-host-ip>
- Client: Windows 11 machine with TAP-Windows6 installed. - Client: Windows 11 machine with TAP-Windows6 installed.
Use the same room code everywhere, for example `ROOM1`. Use the same room code everywhere, for example `ROOM1`.
Start order is relay first, gateway second, Windows client last.
## Build Prerequisites ## Build Prerequisites
@@ -162,6 +172,7 @@ Expected client output:
```text ```text
prepared TAP adapter ... MAC ... configured and media disconnected before relay connect prepared TAP adapter ... MAC ... configured and media disconnected before relay connect
lanparty-client-win connected as peer ... lanparty-client-win connected as peer ...
relay event: LAN gateway connected as peer ...
relay route pinned before TAP ... relay route pinned before TAP ...
relay route verified after TAP activation ... relay route verified after TAP activation ...
TAP driver reports MAC ... and MTU ... TAP driver reports MAC ... and MTU ...
@@ -223,6 +234,34 @@ client. It should appear on the physical port connected to the Linux gateway.
This is the practical MVP acceptance test. This is the practical MVP acceptance test.
## Lifecycle Sanity Check
Run this after the basic tunnel works. It verifies that the room lifecycle is
visible to the Windows client and that a gateway restart does not leave stale
status behind.
1. Stop the gateway with Ctrl-C while the relay and client keep running.
Expected client output:
```text
relay event: LAN gateway disconnected (peer ..., Normal)
gateway connected no
Waiting for LAN gateway
```
2. Start the gateway again with the same relay, room, cert, and interface.
Expected client output:
```text
relay event: LAN gateway connected as peer ...
gateway connected yes
Connected to LAN gateway
```
After the reconnect, repeat one quick `ping -S <tap-ip> <lan-host-ip>`.
## Useful Log Signals ## Useful Log Signals
Relay frame forwarding: Relay frame forwarding:
@@ -290,6 +329,10 @@ check relay lifecycle logs and duplicate-MAC rejection first.
If the client says `Waiting for LAN gateway`, check that the gateway uses the If the client says `Waiting for LAN gateway`, check that the gateway uses the
same room code and is connected to the same relay. same room code and is connected to the same relay.
If the client stays on `gateway connected yes` after the gateway has stopped,
capture the relay and client lifecycle logs. The client should clear this state
from the gateway peer id it received during welcome or peer-join catch-up.
If the gateway fails with `reports no carrier`, plug the selected Ethernet If the gateway fails with `reports no carrier`, plug the selected Ethernet
interface into the LAN party switch, bring the interface up, and restart the interface into the LAN party switch, bring the interface up, and restart the
gateway. gateway.
@@ -344,3 +387,4 @@ For a useful test report, capture:
- ping result from `<tap-ip>` to a LAN host - ping result from `<tap-ip>` to a LAN host
- switch MAC-table entry for the Windows client MAC - switch MAC-table entry for the Windows client MAC
- LAN game discovery or join result - LAN game discovery or join result
- lifecycle sanity-check result