From 8deb7d1d600fbff8035aceb938f68c9cf09544a2 Mon Sep 17 00:00:00 2001 From: ddidderr Date: Fri, 22 May 2026 07:24:07 +0200 Subject: [PATCH] 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 --- README.md | 6 +++--- TESTING.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7af6936..1f64a16 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/TESTING.md b/TESTING.md index 283cc4e..4e2cf25 100644 --- a/TESTING.md +++ b/TESTING.md @@ -30,6 +30,15 @@ gateway iface: eth0 LAN test host: ``` +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: - 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 `. + ## 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 `` to a LAN host - switch MAC-table entry for the Windows client MAC - LAN game discovery or join result +- lifecycle sanity-check result