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
- 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
- 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.
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
so later leave logs can identify a disconnected LAN gateway or client MAC when
that peer was known.
and from the initial welcome, so later leave logs can identify a disconnected
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>
```
Keep these values from the logs as you go:
```text
gateway peer id:
client peer id:
client virtual MAC:
Windows TAP IPv4:
```
## Machines
- 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.
Use the same room code everywhere, for example `ROOM1`.
Start order is relay first, gateway second, Windows client last.
## Build Prerequisites
@@ -162,6 +172,7 @@ Expected client output:
```text
prepared TAP adapter ... MAC ... configured and media disconnected before relay connect
lanparty-client-win connected as peer ...
relay event: LAN gateway connected as peer ...
relay route pinned before TAP ...
relay route verified after TAP activation ...
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.
## 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
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
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
interface into the LAN party switch, bring the interface up, and restart the
gateway.
@@ -344,3 +387,4 @@ For a useful test report, capture:
- ping result from `<tap-ip>` to a LAN host
- switch MAC-table entry for the Windows client MAC
- LAN game discovery or join result
- lifecycle sanity-check result