ddidderr
802fe3d082
Client relay I/O now shares atomic tunnel counters across cloned ClientRelayIo handles and the owning ClientSession. The counters cover successful Ethernet frame rx/tx, relay datagram rx/tx, and dropped or malformed frames so client diagnostics have the traffic totals called out in PLAN.md. The counters live in client-core because that crate owns relay datagram classification and Ethernet payload validation. The Windows TAP runner can later sample this snapshot without duplicating protocol decisions. Test Plan: - cargo fmt --check - cargo test -p lanparty-client-core - cargo clippy -p lanparty-client-core --all-targets -- -D warnings - cargo test --workspace - cargo clippy --workspace --all-targets -- -D warnings - git diff --check Refs: PLAN.md
157 lines
6.3 KiB
Markdown
157 lines
6.3 KiB
Markdown
# softlan-vpn
|
|
|
|
Monorepo for a Layer 2 over QUIC LAN party bridge.
|
|
|
|
## Workspace crates
|
|
|
|
- `lanparty-proto`: shared frame format, MAC validation, MTU helpers.
|
|
- `lanparty-ctrl`: control-plane messages (join/hello/role/version).
|
|
- `lanparty-obs`: shared diagnostics/logging event models.
|
|
- `lanparty-client-core`: platform-agnostic client session state.
|
|
- `lanparty-client-route`: Windows relay-route inspection.
|
|
- `lanparty-client-tap`: TAP-Windows6 adapter discovery and frame I/O.
|
|
- `lanparty-client-win`: Windows TAP + route/metric handling binary.
|
|
- `lanparty-gateway`: Linux AF_PACKET gateway binary.
|
|
- `lanparty-relay`: public QUIC relay binary.
|
|
|
|
### `lanparty-proto`
|
|
|
|
Transport-agnostic tunnel contract shared by all binaries:
|
|
|
|
- overlay datagram header encoding and decoding
|
|
- Ethernet frame header parsing
|
|
- MAC address parsing and identity validation
|
|
- QUIC datagram to TAP MTU budget helpers
|
|
|
|
### `lanparty-ctrl`
|
|
|
|
Reliable control-plane schema shared by the QUIC stream handlers:
|
|
|
|
- endpoint hello messages with role, room, MAC, and datagram budget
|
|
- server welcome, reject, peer lifecycle, stats, and disconnect messages
|
|
- room-code, role/MAC, peer-id, and effective-MTU validation
|
|
- length-prefixed JSON control frames for reliable QUIC streams
|
|
|
|
### `lanparty-obs`
|
|
|
|
Shared diagnostics and structured logging vocabulary:
|
|
|
|
- gateway/relay frame logs with MACs, ethertype, length, peer, and action
|
|
- tunnel counters shared by control messages and runtime diagnostics
|
|
- client connectivity/TAP diagnostics and user-facing status messages
|
|
|
|
### `lanparty-client-core`
|
|
|
|
Platform-neutral remote client relay session:
|
|
|
|
- relay QUIC connection with pinned relay certificate trust
|
|
- client hello with room, virtual MAC, and datagram budget
|
|
- welcome/reject handling with assigned peer id and effective TAP MTU
|
|
- Ethernet frame send/receive helpers over QUIC DATAGRAM
|
|
- client tunnel statistics for frame/datagram rx/tx and drops
|
|
|
|
### `lanparty-client-route`
|
|
|
|
Windows route-table boundary:
|
|
|
|
- read-only best-route lookup for a relay destination IP
|
|
- selected source address, next hop, interface index/LUID, prefix, and metric
|
|
- interface index/LUID lookup from Windows network adapter GUIDs
|
|
- scoped IP interface MTU overrides with restore-on-drop behavior
|
|
- scoped IP interface metric overrides with restore-on-drop behavior
|
|
- scoped default-route suppression with restore-on-drop behavior
|
|
- scoped host-route pinning for the relay IP on the pre-TAP interface
|
|
- non-Windows builds return a clear unsupported-platform error
|
|
|
|
### `lanparty-client-tap`
|
|
|
|
Windows TAP adapter boundary:
|
|
|
|
- TAP-Windows6 adapter discovery from the Windows network adapter registry
|
|
- `\\.\Global\{NetCfgInstanceId}.tap` device path construction
|
|
- blocking Ethernet frame reads/writes through the TAP device handle
|
|
- TAP driver IOCTL helpers for media status, adapter MAC, and MTU
|
|
|
|
### `lanparty-relay`
|
|
|
|
Public relay binary and relay-owned room state:
|
|
|
|
- QUIC endpoint binding and first-stream hello/welcome admission
|
|
- room admission for clients and gateways
|
|
- one gateway per room, duplicate client MAC rejection, and room limits
|
|
- stable effective room MTU chosen before Ethernet datagrams flow
|
|
- live Ethernet datagram forwarding with no ingress reflection
|
|
- L2 safety filters for jumbo, switch-control, DHCP-server, and IPv6-RA frames
|
|
- client broadcast/multicast, unknown-unicast, and total bandwidth limiting
|
|
- malformed peer datagram disconnect threshold
|
|
- peer leave cleanup for room membership and MAC indexes
|
|
|
|
## Build
|
|
|
|
```bash
|
|
cargo check --workspace
|
|
```
|
|
|
|
## Relay
|
|
|
|
```bash
|
|
cargo run -p lanparty-relay -- --listen 443/udp --dev-cert-der-out relay-cert.der
|
|
```
|
|
|
|
`--listen` accepts either a socket address or a UDP port shorthand such as
|
|
`443/udp`. The relay binds a QUIC endpoint, accepts a control-stream `hello`,
|
|
replies with `welcome` or `reject`, and forwards live Ethernet QUIC datagrams
|
|
between accepted peers in the same room. It currently uses a generated
|
|
self-signed development certificate; `--dev-cert-der-out` writes that
|
|
certificate so the gateway and client can pin it in development. Production
|
|
certificate handling remains future work. Ethernet forwarding decisions are
|
|
logged with room, peer, MAC, ethertype, action, drop reason, and target count.
|
|
Unknown unicast from a client is forwarded only to the gateway port; unknown
|
|
unicast from the gateway is dropped instead of flooded to every remote client.
|
|
|
|
## Gateway
|
|
|
|
```bash
|
|
cargo run -p lanparty-gateway -- \
|
|
--relay 203.0.113.10:443 \
|
|
--server-name lanparty-relay.local \
|
|
--relay-ca-cert relay-cert.der \
|
|
--room ROOM1 \
|
|
--interface eth0
|
|
```
|
|
|
|
The gateway connects to the relay as `role = gateway`, completes the
|
|
control-stream hello/welcome handshake, opens an AF_PACKET socket on the LAN
|
|
interface with promiscuous packet membership, and bridges Ethernet frames
|
|
between the relay and wired LAN until shutdown. It tracks remote-client source
|
|
MACs seen from relay traffic and periodically emits small CAM refresh frames so
|
|
the physical switch keeps those MACs associated with the gateway port. Gateway
|
|
frame logs include direction, peer id when present, MACs, ethertype/length,
|
|
frame length, action, and drop reason.
|
|
|
|
## Windows Client
|
|
|
|
```bash
|
|
cargo run -p lanparty-client-win -- \
|
|
--relay 203.0.113.10:443 \
|
|
--server-name lanparty-relay.local \
|
|
--relay-ca-cert relay-cert.der \
|
|
--room ROOM1
|
|
```
|
|
|
|
The Windows client binary currently connects to the relay as `role = client`
|
|
with a generated locally administered virtual MAC persisted in
|
|
`lanparty-client-identity.json`, completes the control-stream hello/welcome
|
|
handshake, pins a host route for the relay IP on the current pre-TAP interface,
|
|
verifies that the relay route still uses that pinned host route after TAP
|
|
activation, and then bridges Ethernet frames between the relay and the first
|
|
TAP-Windows6 adapter until shutdown.
|
|
`--virtual-mac` can still override the stored identity for manual testing. On
|
|
Windows it sets the TAP IP interface MTU to the relay-selected MTU, marks the
|
|
TAP media connected, and reports the driver MAC/MTU before forwarding frames,
|
|
along with the TAP interface index/LUID. The client applies a scoped TAP
|
|
interface metric and disables TAP default routes while it runs, periodically
|
|
rechecks that the relay route remains pinned, then restores the previous route
|
|
policy on exit. Until automatic TAP MAC configuration is wired, startup fails
|
|
before bridging if the driver-reported MAC does not match the tunnel identity.
|