docs: refresh development checkpoint
This commit is contained in:
h3cx committed
1 parent
586ff8f223
commit
49ec9d8c33
1 file changed
+49
-91
+49
-91
@@ -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.
|
||||
Reference in new issue
Block a user