From 49ec9d8c33c4720bfde0f93d43ab81b182e83705 Mon Sep 17 00:00:00 2001 From: Hector van der Aa Date: Tue, 15 Sep 2026 11:00:03 +0200 Subject: [PATCH] docs: refresh development checkpoint --- docs/DEVELOPMENT_STATE.md | 140 +++++++++++++------------------------- 1 file changed, 49 insertions(+), 91 deletions(-) diff --git a/docs/DEVELOPMENT_STATE.md b/docs/DEVELOPMENT_STATE.md index 7bae75b..73e028a 100644 --- a/docs/DEVELOPMENT_STATE.md +++ b/docs/DEVELOPMENT_STATE.md @@ -1,113 +1,71 @@ # Development state -End-of-day checkpoint: 2026-09-15. Branch: `main`. Baseline commit: -`313ab00` (`checkpoint: implement wgcloak v1 foundations`). Work after that -checkpoint remains uncommitted in the shared worktree. Several agents have -edited files in parallel; use the inventory below and review the complete diff -before committing. +Checkpoint: 2026-09-15 end of day. Branch: `main`. Latest commit: +`586ff8f` (`checkpoint: integrate authenticated transports`). The working tree +is clean. Config and client-ID changes are included in this commit. The +resumed recovery-only assignments after this commit made no edits. ## Implemented behavior -- The package now has a reusable Rust library (`src/lib.rs`) and a thin binary - (`src/main.rs`). Integration tests import `wgcloak` instead of compiling - production modules through `#[path]`; module unit tests run once in the - library test target. -- Client and server runtime paths 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. For encrypted transports, shared-secret authentication occurs - before server backend-session activation. -- Client `auto` uses its configured transport order and bounded connection - probes, stops on authentication rejection, and reconnects with jittered - exponential backoff from 250 ms through 30 s. Successful connections reset - the backoff. The client control `reconnect` command forces another attempt. +- The package has a reusable Rust library and a thin binary. Integration tests + import the library; module unit tests run once in the library test target. +- 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 server backend-session + activation. +- Client `auto` follows configured order and bounded probes, stops on + authentication rejection, and reconnects with jittered 250 ms–30 s backoff. + Successful connections reset the backoff. Client control supports explicit + reconnect. - The server runs enabled listeners concurrently, rejects incompatible UDP - listener port conflicts, and aggregates listener/session statistics. Sessions - are isolated and use per-session backend UDP sockets. Admission limits cover - active sessions, per-IP sessions, pending handshakes, and authentication - attempts. + listener port conflicts, aggregates listener/session statistics, and gives + sessions isolated backend UDP sockets. Admission limits cover sessions, + per-IP sessions, pending handshakes, and authentication attempts. - The Unix control socket uses a private runtime directory and mode `0600`, refuses an active socket, and removes only a verified stale socket. `status`, `stats`, and `shutdown` are supported; `reconnect` is client-only. Config and - certificate/key reload are not implemented. The CLI/control reload request - returns an explicit unsupported response. -- The local client UDP listener currently tracks one most-recent application - peer; concurrent local source peers can replace the return target. -- Direct UDP keepalives are one-way. Silent peer loss may not be detected - immediately; a local transport error or explicit client reconnect is the - recovery path covered by tests. + certificate/key reload remain unsupported. +- A client currently tracks one most-recent local UDP application peer, so + concurrent local sources can replace the return target. Direct UDP + keepalives are one-way; silent peer loss may require explicit reconnect or a + local transport error to be noticed. -## Verification checkpoint +## Verification -Before the final config and client-ID edits, the full gates passed: +The latest full gates passed on commit `586ff8f`, including the config and +client-ID changes: - `cargo fmt --all -- --check` - `cargo check --all-targets` - `cargo clippy --all-targets -- -D warnings` - `cargo test --all-targets --quiet` — 76 tests passed. -After those edits, the config-focused suite passed 12/12, the client-ID focused -transport tests passed, and the current `cargo check` passes. Rerun the full -gates after these edits before treating the tree as audited. The broader -encrypted daemon-runtime end-to-end proof described below is not yet created or -complete; focused transport and HTTP/3 runtime tests do not replace it. +The tree was clean at this checkpoint. No uncommitted file inventory applies. ## Remaining work, prioritized -1. Add and complete encrypted daemon-runtime end-to-end proof: local UDP - application traffic through client runtime, encrypted transport, server - runtime, and UDP echo backend, including auth rejection, session isolation, - status/stats, and bounded shutdown. Exercise each encrypted mode where - practical; do not mistake lower-level transport tests for daemon proof. -2. Rerun formatting, all-target check, strict all-target Clippy, and the full - suite after the final config/client-ID edits; then review the complete diff - and reconcile acceptance evidence with `docs/IMPLEMENTATION_CHECKLIST.md`. -3. Add fuzz and benchmark targets for parsers, framing, protocol/auth paths, - and transport overhead; record the environment and baseline. -4. Decide and document a practical maximum datagram-size cap, with config and - boundary tests tied to transport overhead and MTU constraints. -5. Confirm whether configuration and certificate/key reload are required by - the spec/product scope. Until implemented and tested, they remain explicitly - unsupported; do not imply hot reload in CLI or deployment docs. +1. Add `tests/encrypted_runtime.rs` for daemon-level QUIC and TLS proof through + the client runtime, encrypted transport, server runtime, and UDP echo + backend. Cover auth rejection, session independence, control status/stats, + and bounded shutdown. Lower-level transport tests are not a substitute. +2. Start fuzzing: `fuzz/**` and `docs/FUZZING.md` are unstarted. Cover packet + parsers, authentication/framing boundaries, and malformed transport input. +3. Add benchmarks; benchmark targets and baselines are unstarted. +4. Decide a practical maximum datagram-size cap and justify it against transport + overhead and MTU constraints; add boundary/config tests. +5. Decide whether config and certificate/key reload are optional or required by + the spec/product scope. They are currently unsupported. Finish a final + spec-to-implementation audit and update the acceptance checklist with + evidence; do not claim unsupported behavior. -## First recovery tasks +## First tasks for tomorrow -1. Inspect current client/server orchestration and transport test APIs, then - create the encrypted daemon-runtime echo test without duplicating transport - internals. -2. Re-run the four full gates above against the current tree; resolve any - compile, lint, or test regressions before adding further features. -3. Review spec milestones and the 17 completion criteria, and record evidence - for each criterion in the coordinator checklist. Keep fuzzing, benchmarks, - datagram-cap decision, and reload scope visible as open items. - -## Current worktree inventory - -Captured with `git status --short` for this checkpoint. These are shared-tree -changes; ownership is not implied by this list. - -Modified files: - -- `Cargo.lock`, `Cargo.toml` -- `README.md` -- `docs/ARCHITECTURE.md`, `docs/DEVELOPMENT_STATE.md`, - `docs/IMPLEMENTATION_CHECKLIST.md`, `docs/OPERATIONS.md`, `docs/PROTOCOL.md`, - `docs/TROUBLESHOOTING.md` -- `examples/client.advanced.toml`, `examples/server.advanced.toml`, - `examples/server.minimal.toml` -- `packaging/systemd/wgcloak-client.service`, - `packaging/systemd/wgcloak-server.service` -- `src/cli.rs`, `src/client/mod.rs`, `src/client/supervisor.rs`, `src/config.rs`, - `src/control.rs`, `src/main.rs`, `src/protocol/auth.rs`, - `src/protocol/direct.rs`, `src/server/mod.rs`, `src/stats.rs`, - `src/transport/direct_udp.rs`, `src/transport/http3.rs`, - `src/transport/mod.rs`, `src/transport/quic.rs` -- `tests/control.rs`, `tests/direct_udp.rs`, `tests/http3.rs`, - `tests/integration_transports.rs`, `tests/quic.rs`, `tests/supervisor.rs`, - `tests/tls_tcp.rs` - -Untracked files: - -- `src/lib.rs`, `src/server/limits.rs` -- `tests/http3_integration.rs`, `tests/http3_runtime.rs`, `tests/limits.rs`, - `tests/reconnect.rs`, `tests/runtime_lifecycle.rs` +1. Implement the focused daemon-level QUIC/TLS test in `tests/encrypted_runtime.rs`, + then run `cargo test --test encrypted_runtime -- --nocapture`. +2. Run the full gate sequence after the test lands: + `cargo fmt --all -- --check`, `cargo check --all-targets`, + `cargo clippy --all-targets -- -D warnings`, and + `cargo test --all-targets --quiet`. +3. Review the spec checklist, decide the datagram cap and reload scope, and + record acceptance evidence plus the unstarted fuzz/benchmark work.