docs: record wgcloak v1 release state

This commit is contained in:
h3cx committed 2026-09-19 20:07:55 +02:00
1 parent 5767b9038f
commit ac197d1eca
2 files changed
+70 -72

No files matched your search

+42 -53
View File
@@ -1,9 +1,10 @@
# Development state
Checkpoint: 2026-09-19. Branch: `main`. HEAD: `49ec9d8`
(`docs: refresh development checkpoint`). The working tree is not clean: this
checkout contains concurrent implementation, documentation, benchmark, fuzz,
and integration-test changes. No commit was created for this checkpoint.
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
@@ -32,72 +33,60 @@ and integration-test changes. No commit was created for this checkpoint.
`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 server datagram
capability boundary.
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.
## Current worktree inventory
## Verification at 5767b90
Modified files include `Cargo.toml`, `Cargo.lock`, `README.md`,
`docs/OPERATIONS.md`, both advanced/minimal server examples, both systemd
templates, runtime/config/control/server/transport sources, and related tests.
Untracked assets include `benches/`, `fuzz/`, `docs/BENCHMARKS.md`,
`docs/FUZZING.md`, `tests/encrypted_runtime.rs`, and
`tests/server_capabilities.rs`. `docs/DEVELOPMENT_STATE.md` and
`docs/IMPLEMENTATION_CHECKLIST.md` are also modified by this reconciliation.
Treat these as shared worktree state; do not discard them with a cleanup
command.
## Verification performed in this worktree
The following checks passed:
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` — 95 tests passed
- `cargo bench --bench protocol_transports --no-run`
- `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 gates ran against the shared dirty
worktree, not a clean checkout.
benchmark compilation was checked. These are deferred optional release
artifacts, not hidden implementation failures.
## Remaining work
## Deferred optional work
Required before an unconditional release sign-off:
- 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.
1. Re-run the documented gates from the final clean checkout after concurrent
changes are integrated and reviewed.
2. Install/use `cargo-fuzz` and run bounded smoke sessions for each target;
retain the compile-only result as the current evidence until then.
3. Make and test a final practical datagram-size-cap decision. The benchmark
analysis recommends 1200 bytes, while configuration still permits the
larger protocol-bound ceiling.
## Optional follow-up tasks
Optional or explicitly out of scope for the current prototype:
- Config and certificate/key reload remain unsupported; the control command
reports this explicitly. Spec language makes certificate reload desirable
but optional and does not require full hot reload for the first milestone.
- A network benchmark remains opt-in work because its results depend on host
scheduling, kernel buffers, MTU, and runtime conditions. The deterministic
microbenchmarks are present and compile.
- A measured benchmark report and sanitizer fuzz report are release artifacts,
not evidence currently available from this host.
## First three recovery/release tasks
1. Review and commit the shared implementation/docs/bench/fuzz work as one
coherent checkpoint, then repeat the full gates from that clean checkout.
2. Run the four cargo-fuzz targets for bounded smoke sessions and record the
toolchain/host results in the fuzzing notes.
3. Decide whether to enforce the documented 1200-byte practical cap or retain
the protocol-bound configurable ceiling, then add the corresponding
boundary evidence and update the acceptance checklist.
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.