wgcloak/docs/DEVELOPMENT_STATE.md

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.

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 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.
• 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.

Verification checkpoint

Before the final config and client-ID edits, the full gates passed:

• 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.

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.

First recovery tasks

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