104 lines
5.3 KiB
Markdown
104 lines
5.3 KiB
Markdown
# 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.
|
||
|
||
## Implemented behavior
|
||
|
||
- The package provides a reusable Rust library and thin binary. Integration
|
||
tests use the library rather than path-including production modules.
|
||
- 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 backend-session activation.
|
||
- `auto` follows configured transport order, uses bounded probes/retries, stops
|
||
on authentication rejection, and reconnects with jittered 250 ms–30 s
|
||
backoff. Successful connections reset the backoff.
|
||
- Enabled server listeners run concurrently, reject incompatible UDP bind
|
||
conflicts, isolate backend UDP sockets per authenticated session, enforce
|
||
admission limits, and publish aggregate status/statistics.
|
||
- The Unix control socket uses a private runtime directory and `0600` socket
|
||
permissions. It refuses active sockets, removes only verified stale sockets,
|
||
parses/serializes newline-delimited JSON structurally, limits concurrent
|
||
clients, and bounds idle/oversized requests. `status`, `stats`, `shutdown`,
|
||
and client-only `reconnect` are supported. `reload` explicitly reports
|
||
unsupported.
|
||
- Secret-file loading opens one descriptor, uses Linux `O_NOFOLLOW` and
|
||
`O_NONBLOCK`, validates a regular file and permissions from that descriptor,
|
||
and reads the opened descriptor. Secret contents are not logged.
|
||
- Systemd templates run as an unprivileged user with hardening enabled;
|
||
`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.
|
||
- `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.
|
||
- 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.
|
||
|
||
## Current worktree inventory
|
||
|
||
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:
|
||
|
||
- `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 check --manifest-path fuzz/Cargo.toml`
|
||
|
||
`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.
|
||
|
||
## Remaining work
|
||
|
||
Required before an unconditional release sign-off:
|
||
|
||
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 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.
|