feat: complete wgcloak v1 transports

docs/BENCHMARKS.md

@@ -0,0 +1,91 @@
+# 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.