ddidderr
4fa1c1cabb
Add the first route-table mutation API to `lanparty-client-route`. Given the pre-TAP best-route snapshot, the crate can now create a host route for the relay IP on that same interface and return an RAII guard that deletes the route when it is dropped. The route row is initialized with `InitializeIpForwardEntry`, uses a /32 or /128 destination prefix for the relay IP, preserves the pre-TAP interface index/LUID, and uses the remembered next hop or an on-link unspecified next hop when Windows reported no gateway. The guard tracks whether creation actually succeeded so pure row-construction tests and failed creates do not try to delete routes they did not install. This remains a crate-level boundary only. The Windows client still reports the pre-TAP route but does not yet hold a pin across TAP activation; that is the next integration slice. Test Plan: - cargo fmt --check - cargo test -p lanparty-client-route - cargo clippy -p lanparty-client-route --all-targets -- -D warnings - cargo check -p lanparty-client-route --target x86_64-pc-windows-msvc - cargo clippy -p lanparty-client-route --target x86_64-pc-windows-msvc --all-targets -- -D warnings - cargo test --workspace - cargo clippy --workspace --all-targets -- -D warnings - git diff --check Refs: PLAN.md Refs: https://learn.microsoft.com/en-us/windows-hardware/drivers/network/createipforwardentry2 Refs: https://learn.microsoft.com/en-us/windows-hardware/drivers/network/initializeipforwardentry
140 lines
5.1 KiB
Markdown
140 lines
5.1 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
|
|
|
|
### `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
|
|
- 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
|
|
- 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.
|
|
|
|
## 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, 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.
|
|
|
|
## 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, snapshots the current relay route, 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 marks the TAP media connected and reports the driver MAC/MTU before
|
|
forwarding frames. Route pinning and automatic TAP MAC/MTU configuration are
|
|
not wired yet.
|