93 lines
5.0 KiB
Markdown
93 lines
5.0 KiB
Markdown
# 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.
|