92 lines
3.8 KiB
Markdown
92 lines
3.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```text
|
|
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.
|