ddidderr
cd8a536771
The Windows TAP pump used the same send helper as direct callers, so malformed, jumbo, or over-budget TAP frames were reported as errors that stopped the bridge. That is too brittle for the no-fragmentation MVP: local frames that cannot fit the tunnel should be counted and dropped, while real QUIC send failures should still surface as fatal. Add a client send outcome that reports whether a frame was sent or locally dropped. The existing send_ethernet API still returns an error for direct callers when the outcome is a local drop. The live TAP pump uses the outcome API so it can log the drop reason and keep forwarding later frames. Document the new client behavior in the README. Test Plan: - cargo fmt --check - git diff --check - cargo test -p lanparty-client-core - cargo test -p lanparty-client-win - cargo test --workspace - cargo clippy --workspace --all-targets -- -D warnings Attempted: - cargo check -p lanparty-client-win --target x86_64-pc-windows-msvc (blocked by missing MSVC lib.exe on this Linux host) Refs: PLAN.md
234 lines
11 KiB
Markdown
234 lines
11 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-net`: shared relay endpoint parsing and resolution.
|
|
- `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
|
|
- negotiated QUIC datagram budget validation before send
|
|
- 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 mode, reject, peer lifecycle, stats, and disconnect messages
|
|
- initial room gateway-presence status in server welcomes
|
|
- 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-net`
|
|
|
|
Shared network address handling for tunnel binaries:
|
|
|
|
- relay DNS name, IP literal, and socket-address parsing
|
|
- UDP/443 default for bare relay hosts
|
|
- relay address resolution before tunnel interface activation
|
|
|
|
### `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
|
|
- QUIC DATAGRAM support and negotiated datagram budget diagnostics
|
|
- reliable relay control-event reads for peer lifecycle messages
|
|
- Ethernet frame send/receive helpers over QUIC DATAGRAM with budget checks and
|
|
local drop outcomes for malformed or oversized sends
|
|
- client tunnel statistics for frame/datagram rx/tx and drops
|
|
- reliable client stats snapshot sends for relay diagnostics
|
|
- best-effort graceful disconnect messages before QUIC close
|
|
|
|
### `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
|
|
- unicast IP address snapshots for TAP diagnostics
|
|
- 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
|
|
- TAP `NetworkAddress` registry configuration for the tunnel MAC identity
|
|
- `\\.\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
|
|
- per-peer egress budget checks against the negotiated datagram size
|
|
- reliable `PeerJoined`/`PeerLeft` notifications to existing room peers
|
|
- L2 safety filters for invalid-source, jumbo, switch-control, DHCP-server,
|
|
and IPv6-RA frames
|
|
- client broadcast/multicast, unknown-unicast, and total bandwidth limiting
|
|
- malformed peer datagram disconnect threshold
|
|
- peer stats control events retained for relay diagnostics
|
|
- graceful disconnect control events propagated as peer-leave reasons
|
|
- per-peer last-seen timestamps in relay room snapshots
|
|
- 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.
|
|
Safety-policy rejects use the `filtered` action so they are distinguishable
|
|
from malformed/unknown-destination drops and rate limits.
|
|
Malformed peer datagrams log their per-peer count before the relay disconnects
|
|
peers that cross the malformed-datagram threshold.
|
|
Relay egress skips caused by a target peer's smaller datagram budget are logged
|
|
with the ingress peer, target peer, encoded length, and target budget.
|
|
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.
|
|
When a peer joins or leaves, the relay sends a reliable lifecycle control event
|
|
to peers that are still present in the room. Newly joined peers also receive
|
|
`PeerJoined` events for peers that were already present.
|
|
|
|
### MVP Trust Model
|
|
|
|
The MVP relay terminates QUIC for every client and gateway connection. QUIC
|
|
protects traffic on the public network path, but the relay process sees
|
|
plaintext Ethernet frames while forwarding them between peers in a room. That is
|
|
acceptable for the first LAN-party proof, where the relay is an operator-trusted
|
|
component, but it is not end-to-end encrypted.
|
|
|
|
Future room-key payload encryption should keep the relay-visible routing header
|
|
small and leave only Ethernet payload bytes encrypted end-to-end between clients
|
|
and the LAN gateway.
|
|
|
|
## Gateway
|
|
|
|
```bash
|
|
cargo run -p lanparty-gateway -- \
|
|
--relay lanparty-relay.local \
|
|
--server-name lanparty-relay.local \
|
|
--relay-ca-cert relay-cert.der \
|
|
--room ROOM1 \
|
|
--iface 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 captures whole LAN frames up
|
|
to the overlay payload-length ceiling before deciding whether they fit the
|
|
tunnel. It never fragments Ethernet frames; LAN frames whose encoded datagrams
|
|
exceed the negotiated QUIC budget are counted, dropped, and logged instead of
|
|
stopping the bridge.
|
|
`--relay` accepts a DNS name or socket address; bare hosts default to UDP/443.
|
|
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. The gateway also tracks frame/datagram
|
|
counters and periodically sends stats snapshots to the relay. Relay lifecycle
|
|
events seed and retire remote-client MACs for CAM refresh even before that
|
|
client sends traffic. On shutdown, the gateway sends a best-effort disconnect
|
|
control message before closing QUIC so the relay can report the intended reason.
|
|
|
|
## Windows Client
|
|
|
|
```bash
|
|
cargo run -p lanparty-client-win -- \
|
|
--relay lanparty-relay.local \
|
|
--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`, resolves the relay DNS name before TAP
|
|
activation, completes the control-stream hello/welcome handshake, pins a host
|
|
route for the resolved 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. `--relay` accepts a DNS name or socket address; bare hosts
|
|
default to UDP/443. Before opening the adapter, it writes the
|
|
generated tunnel MAC to the TAP driver's `NetworkAddress` registry setting.
|
|
The startup status reports whether the relay already has a LAN gateway for the
|
|
room.
|
|
`--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. Startup prints a warning when TAP default routes were enabled
|
|
before the scoped protection was applied. Startup still fails before bridging
|
|
if the driver-reported MAC does not match the tunnel identity, because an
|
|
already-initialized Windows TAP adapter may need to be disabled/enabled or
|
|
reinstalled before it reloads the configured `NetworkAddress`.
|
|
It prints and reports client diagnostics snapshots with relay reachability,
|
|
LAN-gateway presence, route-pinning, QUIC datagram budget, TAP status/IP,
|
|
broadcast frame flow, frame/datagram counters, and drops. The periodic
|
|
diagnostics refresh the TAP unicast IP so DHCP results that arrive after
|
|
bridging starts become visible in later status lines. Each snapshot also emits
|
|
short user-facing lines such as relay/gateway connection status, relay-route
|
|
and TAP readiness warnings, DHCP address presence, and broadcast-flow
|
|
confirmation when those signals are observed. Malformed TAP frames, jumbo
|
|
frames, and TAP frames whose encoded datagrams exceed the negotiated QUIC budget
|
|
are counted and dropped before relay send without stopping 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.
|