h3cx/wgcloak
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refresh development checkpoint

Browse Source
This commit is contained in:
h3cx committed 2026-09-15 11:00:03 +02:00
1 parent 586ff8f223
commit 49ec9d8c33
1 file changed
+49 -91
Download Patch File Download Diff File Expand all files Collapse all files
docs/DEVELOPMENT_STATE.md
+49 -91
View File
@@ -1,113 +1,71 @@
# Development state # Development state
End-of-day checkpoint: 2026-09-15. Branch: `main`. Baseline commit: Checkpoint: 2026-09-15 end of day. Branch: `main`. Latest commit:
`313ab00` (`checkpoint: implement wgcloak v1 foundations`). Work after that `586ff8f` (`checkpoint: integrate authenticated transports`). The working tree
checkpoint remains uncommitted in the shared worktree. Several agents have is clean. Config and client-ID changes are included in this commit. The
edited files in parallel; use the inventory below and review the complete diff resumed recovery-only assignments after this commit made no edits.
before committing.
## Implemented behavior ## Implemented behavior
- The package now has a reusable Rust library (`src/lib.rs`) and a thin binary - The package has a reusable Rust library and a thin binary. Integration tests
(`src/main.rs`). Integration tests import `wgcloak` instead of compiling import the library; module unit tests run once in the library test target.
production modules through `#[path]`; module unit tests run once in the - Client and server runtimes support authenticated direct UDP, QUIC DATAGRAM,
library test target. HTTP/3 CONNECT-UDP with HTTP Datagrams, and TLS/TCP length-framed fallback.
- Client and server runtime paths support authenticated direct UDP, QUIC TLS client connections use normal certificate-chain and hostname verification.
DATAGRAM, HTTP/3 CONNECT-UDP with HTTP Datagrams, and TLS/TCP length-framed Shared-secret authentication precedes encrypted server backend-session
fallback. TLS client connections use normal certificate-chain and hostname activation.
verification. For encrypted transports, shared-secret authentication occurs - Client `auto` follows configured order and bounded probes, stops on
before server backend-session activation. authentication rejection, and reconnects with jittered 250 ms–30 s backoff.
- Client `auto` uses its configured transport order and bounded connection Successful connections reset the backoff. Client control supports explicit
probes, stops on authentication rejection, and reconnects with jittered reconnect.
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 - The server runs enabled listeners concurrently, rejects incompatible UDP
listener port conflicts, and aggregates listener/session statistics. Sessions listener port conflicts, aggregates listener/session statistics, and gives
are isolated and use per-session backend UDP sockets. Admission limits cover sessions isolated backend UDP sockets. Admission limits cover sessions,
active sessions, per-IP sessions, pending handshakes, and authentication per-IP sessions, pending handshakes, and authentication attempts.
attempts.
- The Unix control socket uses a private runtime directory and mode `0600`, - The Unix control socket uses a private runtime directory and mode `0600`,
refuses an active socket, and removes only a verified stale socket. `status`, refuses an active socket, and removes only a verified stale socket. `status`,
`stats`, and `shutdown` are supported; `reconnect` is client-only. Config and `stats`, and `shutdown` are supported; `reconnect` is client-only. Config and
certificate/key reload are not implemented. The CLI/control reload request certificate/key reload remain unsupported.
returns an explicit unsupported response. - A client currently tracks one most-recent local UDP application peer, so
- The local client UDP listener currently tracks one most-recent application concurrent local sources can replace the return target. Direct UDP
peer; concurrent local source peers can replace the return target. keepalives are one-way; silent peer loss may require explicit reconnect or a
- Direct UDP keepalives are one-way. Silent peer loss may not be detected local transport error to be noticed.
immediately; a local transport error or explicit client reconnect is the
recovery path covered by tests.
## 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 fmt --all -- --check`
- `cargo check --all-targets` - `cargo check --all-targets`
- `cargo clippy --all-targets -- -D warnings` - `cargo clippy --all-targets -- -D warnings`
- `cargo test --all-targets --quiet` — 76 tests passed. - `cargo test --all-targets --quiet` — 76 tests passed.
After those edits, the config-focused suite passed 12/12, the client-ID focused The tree was clean at this checkpoint. No uncommitted file inventory applies.
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 ## Remaining work, prioritized
1. Add and complete encrypted daemon-runtime end-to-end proof: local UDP 1. Add `tests/encrypted_runtime.rs` for daemon-level QUIC and TLS proof through
application traffic through client runtime, encrypted transport, server the client runtime, encrypted transport, server runtime, and UDP echo
runtime, and UDP echo backend, including auth rejection, session isolation, backend. Cover auth rejection, session independence, control status/stats,
status/stats, and bounded shutdown. Exercise each encrypted mode where and bounded shutdown. Lower-level transport tests are not a substitute.
practical; do not mistake lower-level transport tests for daemon proof. 2. Start fuzzing: `fuzz/**` and `docs/FUZZING.md` are unstarted. Cover packet
2. Rerun formatting, all-target check, strict all-target Clippy, and the full parsers, authentication/framing boundaries, and malformed transport input.
suite after the final config/client-ID edits; then review the complete diff 3. Add benchmarks; benchmark targets and baselines are unstarted.
and reconcile acceptance evidence with `docs/IMPLEMENTATION_CHECKLIST.md`. 4. Decide a practical maximum datagram-size cap and justify it against transport
3. Add fuzz and benchmark targets for parsers, framing, protocol/auth paths, overhead and MTU constraints; add boundary/config tests.
and transport overhead; record the environment and baseline. 5. Decide whether config and certificate/key reload are optional or required by
4. Decide and document a practical maximum datagram-size cap, with config and the spec/product scope. They are currently unsupported. Finish a final
boundary tests tied to transport overhead and MTU constraints. spec-to-implementation audit and update the acceptance checklist with
5. Confirm whether configuration and certificate/key reload are required by evidence; do not claim unsupported behavior.
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 ## First tasks for tomorrow
1. Inspect current client/server orchestration and transport test APIs, then 1. Implement the focused daemon-level QUIC/TLS test in `tests/encrypted_runtime.rs`,
create the encrypted daemon-runtime echo test without duplicating transport then run `cargo test --test encrypted_runtime -- --nocapture`.
internals. 2. Run the full gate sequence after the test lands:
2. Re-run the four full gates above against the current tree; resolve any `cargo fmt --all -- --check`, `cargo check --all-targets`,
compile, lint, or test regressions before adding further features. `cargo clippy --all-targets -- -D warnings`, and
3. Review spec milestones and the 17 completion criteria, and record evidence `cargo test --all-targets --quiet`.
for each criterion in the coordinator checklist. Keep fuzzing, benchmarks, 3. Review the spec checklist, decide the datagram cap and reload scope, and
datagram-cap decision, and reload scope visible as open items. record acceptance evidence plus the unstarted fuzz/benchmark work.
## 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`