diff --git a/docs/DEVELOPMENT_STATE.md b/docs/DEVELOPMENT_STATE.md index 09b3170..9ae7824 100644 --- a/docs/DEVELOPMENT_STATE.md +++ b/docs/DEVELOPMENT_STATE.md @@ -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. diff --git a/docs/IMPLEMENTATION_CHECKLIST.md b/docs/IMPLEMENTATION_CHECKLIST.md index 2c64ec2..95e57e2 100644 --- a/docs/IMPLEMENTATION_CHECKLIST.md +++ b/docs/IMPLEMENTATION_CHECKLIST.md @@ -1,9 +1,11 @@ # Implementation and acceptance checklist -This is an evidence-based coordinator checklist. A checked item identifies -current code and tests; it is not a claim that the dirty worktree is an -unconditionally released artifact. The latest evidence was collected on -2026-09-19 with serial integration tests. +This evidence-based checklist records the implementation and license baseline +at commit `5767b90` (`release: finalize wgcloak v1 under GPLv3`). The final +documentation closeout is the only work that follows that baseline; the gates +below were run against the committed implementation. Package metadata and +`LICENSE` use SPDX `GPL-3.0-only`. Optional deferred work is called out +explicitly and is not treated as an unimplemented v1 transport. ## Milestones 1–6 @@ -31,12 +33,18 @@ unconditionally released artifact. The latest evidence was collected on `tests/tls_tcp.rs`, `tests/integration_transports.rs`, and TLS cases in `tests/encrypted_runtime.rs`; the TLS/TCP head-of-line tradeoff is documented in `docs/PROTOCOL.md`. -- [ ] **6 — operational polish:** Control, validation, hardened systemd units, - capability guidance, deterministic benchmark assets, and fuzz targets are - present (`src/control.rs`, `tests/control.rs`, `packaging/systemd/`, - `benches/`, `fuzz/`). Leave this milestone open until final clean-checkout - gates, bounded cargo-fuzz runs, and the practical datagram cap decision are - recorded. Config/certificate reload remains explicitly unsupported. +- [x] **6 — operational polish:** Control, validation, hardened systemd units, + capability guidance, deterministic benchmark assets, fuzz targets, and + installation documentation are present (`src/control.rs`, `tests/control.rs`, + `packaging/systemd/`, `benches/`, `fuzz/`, `README.md`). The configured + default is 1,200 bytes and the validated project ceiling is 16,384 bytes. + Oversized-datagram metrics remain visible in aggregate status/statistics; + `src/server/mod.rs::record_transport_drop` and + `oversized_transport_error_is_counted_once` cover the latest repaired + boundary accounting. + Config/certificate reload remains explicitly unsupported; cargo-fuzz smoke + execution and environment-sensitive network benchmarking are optional + deferred validation artifacts. ## v1 completion criteria (spec §89) @@ -73,8 +81,8 @@ unconditionally released artifact. The latest evidence was collected on capability — `User=wgcloak`, hardening, and commented narrow `CAP_NET_BIND_SERVICE` guidance in both `packaging/systemd/*.service` files. - [x] 14. TOML configuration is clearly validated — `src/config.rs` tests and - `tests/server_capabilities.rs` cover role, transport, listener, and datagram - boundaries. + `tests/server_capabilities.rs` cover role, transport, listener, and the + 1,200-default/16,384-ceiling datagram boundaries. - [x] 15. Meaningful status and statistics are available — `src/control.rs`, `tests/control.rs`, `tests/runtime_lifecycle.rs`, and aggregate-stat tests in `tests/http3_runtime.rs`. @@ -95,14 +103,15 @@ unconditionally released artifact. The latest evidence was collected on - [x] Fuzz targets exist for direct packets, TLS frames, HTTP/3 parsing, and TOML parsing, and `cargo check --manifest-path fuzz/Cargo.toml` passes. No fuzzing execution or sanitizer result is claimed because `cargo-fuzz` is - not installed on the current host. -- [ ] `cargo test`, formatting, linting, and documented integration/bench - commands pass from a clean checkout. Current dirty-worktree evidence is: - `cargo fmt --all -- --check`, `cargo check --all-targets`, strict all-target - Clippy, serial `cargo test --tests -- --test-threads=1` (95 passed), and + not installed on the current host; this is optional deferred validation. +- [x] Release gates passed against the committed `5767b90` implementation + baseline before this documentation closeout: `cargo fmt --all + -- --check`, `cargo check --all-targets`, strict all-target Clippy, + `cargo test --tests -- --test-threads=1` (100 passed), + `cargo check --manifest-path fuzz/Cargo.toml`, and `cargo bench --bench protocol_transports --no-run`. - [x] Review confirms no payload/secret logging, no unsafe privilege grant, and no accidental WireGuard/routing/firewall coupling. Evidence: `docs/SECURITY.md`, hardened systemd templates, source audit, and the - authentication/control/secret-file tests. This review does not waive the - clean-checkout and fuzz-execution items above. + authentication/control/secret-file tests. Config/certificate reload remains + an explicit unsupported optional feature.