# 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.