wgcloak/docs/DEVELOPMENT_STATE.md

Development state

Release checkpoint: 2026-09-19. Branch: main. The implementation and license baseline is commit 5767b90 (release: finalize wgcloak v1 under GPLv3). The final documentation closeout is the only work that follows that baseline and is intended to be committed separately; no implementation claim below depends on an uncommitted code change.

Implemented behavior

• The package provides a reusable Rust library and thin binary. Integration tests use the library rather than path-including production modules.
• Client and server runtimes support authenticated direct UDP, QUIC DATAGRAM, HTTP/3 CONNECT-UDP with HTTP Datagrams, and TLS/TCP length-framed fallback. TLS client connections use normal certificate-chain and hostname verification. Shared-secret authentication precedes encrypted backend-session activation.
• auto follows configured transport order, uses bounded probes/retries, stops on authentication rejection, and reconnects with jittered 250 ms–30 s backoff. Successful connections reset the backoff.
• Enabled server listeners run concurrently, reject incompatible UDP bind conflicts, isolate backend UDP sockets per authenticated session, enforce admission limits, and publish aggregate status/statistics.
• The Unix control socket uses a private runtime directory and 0600 socket permissions. It refuses active sockets, removes only verified stale sockets, parses/serializes newline-delimited JSON structurally, limits concurrent clients, and bounds idle/oversized requests. status, stats, shutdown, and client-only reconnect are supported. reload explicitly reports unsupported.
• Secret-file loading opens one descriptor, uses Linux O_NOFOLLOW and O_NONBLOCK, validates a regular file and permissions from that descriptor, and reads the opened descriptor. Secret contents are not logged.
• Systemd templates run as an unprivileged user with hardening enabled; CAP_NET_BIND_SERVICE is documented as an optional, narrowly scoped aid for ports below 1024. No WireGuard, TUN/TAP, routing, or firewall management is implemented.
• The configured default application datagram is 1,200 bytes and the project safety ceiling is 16,384 bytes. Transport negotiation and framing may lower the effective per-session maximum; boundary coverage exists in config and server-capability tests.
• Oversized-datagram accounting is preserved in aggregate status/statistics across the direct, QUIC, HTTP/3, and TLS/TCP paths; the latest boundary and metrics repair is implemented by src/server/mod.rs::record_transport_drop and covered by its oversized_transport_error_is_counted_once test.
• tests/encrypted_runtime.rs covers daemon-level QUIC/TLS forwarding, authentication rejection, cancellation, session identity, and QUIC restart reconnect. tests/server_capabilities.rs covers the datagram capability boundary.
• A deterministic Criterion target exists in benches/protocol_transports.rs for protocol/framing/HTTP Datagram/replay microbenchmarks. The repository also contains four isolated cargo-fuzz targets under fuzz/ for direct packets, TLS frames, HTTP/3 parsing, and TOML parsing.
• Package metadata declares SPDX GPL-3.0-only, and LICENSE contains the complete GNU GPL version 3 text.

Verification at 5767b90

The final release gates passed against the committed 5767b90 implementation baseline before this documentation closeout:

• cargo fmt --all -- --check
• cargo check --all-targets
• cargo clippy --all-targets -- -D warnings
• cargo test --tests -- --test-threads=1 — 100 tests passed
• cargo check --manifest-path fuzz/Cargo.toml
• cargo bench --bench protocol_transports --no-run

cargo-fuzz is not installed on this host, so no fuzzing session or sanitizer run is claimed. No network/loopback benchmark was run; only deterministic benchmark compilation was checked. These are deferred optional release artifacts, not hidden implementation failures.

Deferred optional work

• Run bounded cargo-fuzz smoke sessions and sanitizer checks when the cargo-fuzz tool is available. The targets compile and have seed corpora.
• Run an explicitly opt-in network/loopback benchmark only when its host, kernel, MTU, scheduler, loss, latency, and duration controls are recorded.
• Config and certificate/key reload remain unsupported. The control command reports this explicitly; the specification makes certificate reload desirable but optional and does not require full hot reload for the first prototype.
• Produce measured benchmark and fuzz reports if a release process requires them; the deterministic benchmark and compile-only fuzz evidence are already part of the committed release.

Optional follow-up tasks

1. Install cargo-fuzz and run the four documented bounded smoke sessions.
2. Capture a reproducible deterministic benchmark report, then separately decide whether an environment-sensitive network benchmark is useful.
3. Revisit reload scope only if the product promotes the optional configuration/certificate reload behavior into a required feature.