3.8 KiB
Benchmarking
wgcloak has a deterministic Criterion target for protocol and transport
building blocks. It does not open sockets, require certificates, or depend on
network timing. Because the target is declared with harness = false,
cargo test --all-targets executes it as a smoke check; that run is not a
measured benchmark report.
Run it
# Compile the benchmark without running it.
cargo bench --bench protocol_transports --no-run
# Run the complete local benchmark and write Criterion reports under target/.
cargo bench --bench protocol_transports
# Run one group while iterating.
cargo bench --bench protocol_transports -- direct_protocol
The target measures:
- direct authenticated DATA packet encode, bounded parse, and MAC verification for 64, 512, and 1200-byte opaque payloads;
- TLS/TCP frame encoding plus incremental split-input and coalesced-input decoding;
- HTTP/3 HTTP Datagram context encoding/decoding, capsule encoding/decoding, and CONNECT-UDP challenge-response verification;
- replay-window sequential acceptance and duplicate rejection.
The benchmark input and cryptographic keys are fixed, non-secret test values. They are not production credentials. Criterion's default warm-up, sample, and measurement settings are suitable for a first comparison; keep those settings stable when comparing commits.
Environment report
Record at least the following with published results:
date/time (UTC):
commit:
host/CPU:
RAM:
OS/kernel:
rustc --version:
cargo --version:
governor/power profile:
command and Criterion filter:
notes (background load, thermal state, VM/container):
Do not compare values from different CPU governors, virtualized hosts, or substantially different Rust/dependency lockfiles without noting the change. Criterion reports are local artifacts and are not committed by default.
Network benchmark status
No loopback UDP relay benchmark is enabled yet. A socket benchmark would be
environment-sensitive: scheduler load, kernel socket buffers, loopback queueing,
and task runtime configuration can dominate the result. Add it as an explicit
opt-in benchmark (or a separate executable) only when it reports packet loss,
latency percentiles, CPU context, socket buffer settings, and a bounded run
duration. It must not run as part of cargo test or the deterministic Criterion
group.
Datagram-size analysis and recommendation
The configured default application payload is 1200 bytes. The project-wide configurable safety ceiling is 16,384 bytes; transport framing and path capabilities may produce a lower effective session maximum. The wire overheads are:
| Path | Per-datagram overhead relevant to the configured payload |
|---|---|
| Direct UDP | 32-byte authenticated DATA header; the u16 packet limit is theoretical, not an MTU guarantee |
| TLS/TCP | 2-byte big-endian frame length; TCP preserves framing but does not provide an MTU bound |
| HTTP/3 CONNECT-UDP | HTTP Datagram context varint plus h3-quinn's quarter-stream varint; the implementation subtracts both before accepting payload |
| QUIC DATAGRAM | QUIC/path framing and UDP/IP headers are path-dependent; the peer's negotiated maximum is authoritative |
Recommendation: retain 1200 bytes as the practical default for ordinary Internet paths. Users may configure larger values up to 16,384 bytes for jumbo/custom paths, subject to each transport's negotiated/path-specific effective maximum. Boundary tests should cover each transport, including HTTP/3 stream/context overhead at both one-byte and multi-byte varint widths.
The direct protocol and TLS framing have larger u16 wire limits, but those limits are not safe project configuration values. The 16,384-byte ceiling keeps parser/session allocations bounded. HTTP/3 and QUIC limits remain negotiated/path-dependent and are bounded further before allocation and send.