sasa/wireguard-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Implement adaptive client list

Browse Source
This commit is contained in:
sasa
2026-10-28 23:12:22 +02:00
parent d49721ff8e
commit 4960c65f65
8 changed files with 1794 additions and 256 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PLANS.md
+101 -25
View File
@@ -108,24 +108,25 @@ Actual systemd/D-Bus acceptance runs in a disposable VM. Never use production to
Each row is a delivery milestone, not a completion claim. Expand its record before execution; retain its original ID and acceptance scope.
| ID | Milestone | Prerequisites | State |
| --- | -------------------------------------------------------- | ----------------------------------------- | ----------- |
| 1 | Rust foundation, settings, and domain states | None | accepted |
| 2 | Server configuration editing with byte preservation | 1 | accepted |
| 3 | Client keys, encrypted vault, and existing-client import | 2 | accepted |
| 4 | Backups, safe Commit, and full restoration | 3 | accepted |
| 5 | Runtime observation and systemd restart adapter | 4 | accepted |
| 6 | Client configuration delivery and reissue lifecycle | 5 | accepted |
| 7 | Complete terminal management workflow | 6 | accepted |
| 8 | Alpine Testcontainers integration | 7; suitable disposable Docker environment | accepted |
| 9 | Real systemd acceptance and release readiness | 8; disposable systemd VM | retired |
| 10 | Visible styled keyboard quick reference in bottom panel | 8; existing M7 TUI | accepted |
| 11 | Valid subnet routes shown as a capability limitation | 10 | accepted |
| 12 | Aligned, responsive client table | 11 | accepted |
| 13 | Compact terminal QR disclosure | 12 | accepted |
| 14 | Restart verification for valid legacy peers | 13 | accepted |
| 15 | Diagnosable systemd restart and unloaded-unit resolution | 14 | accepted |
| 16 | Root systemd private peer restart transport | 15 | blocked |
| ID | Milestone | Prerequisites | State |
| --- | --------------------------------------------------------- | ----------------------------------------- | -------- |
| 1 | Rust foundation, settings, and domain states | None | accepted |
| 2 | Server configuration editing with byte preservation | 1 | accepted |
| 3 | Client keys, encrypted vault, and existing-client import | 2 | accepted |
| 4 | Backups, safe Commit, and full restoration | 3 | accepted |
| 5 | Runtime observation and systemd restart adapter | 4 | accepted |
| 6 | Client configuration delivery and reissue lifecycle | 5 | accepted |
| 7 | Complete terminal management workflow | 6 | accepted |
| 8 | Alpine Testcontainers integration | 7; suitable disposable Docker environment | accepted |
| 9 | Real systemd acceptance and release readiness | 8; disposable systemd VM | retired |
| 10 | Visible styled keyboard quick reference in bottom panel | 8; existing M7 TUI | accepted |
| 11 | Valid subnet routes shown as a capability limitation | 10 | accepted |
| 12 | Aligned, responsive client table | 11 | accepted |
| 13 | Compact terminal QR disclosure | 12 | accepted |
| 14 | Restart verification for valid legacy peers | 13 | accepted |
| 15 | Diagnosable systemd restart and unloaded-unit resolution | 14 | accepted |
| 16 | Root systemd private peer restart transport | 15 | accepted |
| 17 | Adaptive client list, persistent details and clear states | 16 accepted; existing M7/M12 TUI | accepted |
### Milestone 1 — Rust foundation, settings, and domain states
@@ -3676,7 +3677,7 @@ Accepted for the synthetic adapter and application scope after R1 (owner-change
### Milestone 16 — Root systemd private peer restart transport
Status: blocked (2026-10-27T22:42:48+02:00) on end-to-end private-peer and disposable-VM systemd checks. M15 is accepted for synthetic behavior; M9 disposable-VM systemd acceptance remains retired and unaccepted.
Status: accepted by explicit user direction (2026-10-28) following a reported successful manual check. The manual environment, commands and transport coverage were not supplied; the previously recorded disposable-VM evidence gap remains a validation limitation, not a claimed passing VM run. M9 remains retired and unaccepted.
#### Outcome and scope
@@ -3688,19 +3689,19 @@ Support explicit restart on a root-managed systemd host without a system bus by
| --- | --- | --- | --- |
| M16.1 | explorer | complete | Pinned zbus 5.19.0 source and official systemd private-socket protocol findings |
| M16.2 | implementer | complete for implementation scope | Transport implementation, zbus feature/docs and 16 focused synthetic tests |
| M16.3 | independent reviewer; repairer | blocked | R1 private permission category closed on re-review; R2 private-path behavioral evidence remains unavailable |
| M16.3 | independent reviewer; repairer | user-directed close with evidence gap | R1 closed on re-review; R2 private-path behavioral evidence remains unavailable and was not independently closed |
| M16.4 | coordinator | complete for available checks | Integrated source, pinned Rust gates and [M16 evidence](docs/evidence/milestone-16.md); VM unavailable |
- [ ] M16-A1: root-only private peer connection and system-bus path work against real systemd with correct method destination and job signal tracking. Source audit and synthetic selection checks pass; real transport checks remain unavailable.
- [x] M16-A2: source and synthetic checks preserve subscribe-before-request, canonical alias ID, bounded deadline, disconnect/uncertainty behavior, and no retry after possible submission.
- [ ] M16-A3: synthetic selection/failure and existing job-tracker tests pass, but the private `SystemdBus` branch was not exercised end to end because local peer credential access returned sandbox `EPERM`.
- [ ] M16-A4: R1 was closed, but R2 remains open; pinned Rust gates pass. Disposable-VM private and system-bus acceptance is unavailable.
- [ ] M16-A4: R1 was closed; R2 lacks independent behavioral closure. Pinned Rust gates passed, but disposable-VM private and system-bus acceptance is unavailable. User-directed milestone acceptance waives this outstanding evidence rather than proving the criterion.
Available checks: focused service/application tests, `cargo fmt --all -- --check`, `cargo clippy --locked --all-targets -- -D warnings`, `cargo test --locked`, `cargo build --locked --release`, `git diff --check` all passed on repaired inputs. Synthetic checks used no production socket or keys. [M16 evidence](docs/evidence/milestone-16.md) records exact results and identities. Disposable-VM checks were not run.
#### Outcome and handoff
Official systemd source confirms root `systemctl` connects to `/run/systemd/private` directly when PID 1 is systemd; official `systemd(1)` docs caution this socket is private to systemd. Pinned zbus 5.19.0 exposes peer mode behind its approved crate's `p2p` feature. The implementation uses destination-free peer calls and local signal matching without bus owner monitoring; the bus path remains available. M16-R1 (P2, private permission category) was repaired and independently closed. M16-R2 (P2, private-branch behavioral evidence) remains open: local zbus peer credential access returned sandbox `EPERM`, and the prior disposable Debian VM has no installed/verified guest. No production or host socket was touched. The next action is a disposable-VM run with synthetic configuration covering both transports; until then M16 cannot be accepted.
Official systemd source confirms root `systemctl` connects to `/run/systemd/private` directly when PID 1 is systemd; official `systemd(1)` docs caution this socket is private to systemd. Pinned zbus 5.19.0 exposes peer mode behind its approved crate's `p2p` feature. The implementation uses destination-free peer calls and local signal matching without bus owner monitoring; the bus path remains available. M16-R1 (P2, private permission category) was repaired and independently closed. M16-R2 (P2, private-branch behavioral evidence) remains unverified by the recorded automated evidence: local zbus peer credential access returned sandbox `EPERM`, and the prior disposable Debian VM has no installed/verified guest. The user reported a successful manual check and directed that M16 be considered done; its details and transport scope are unavailable. This user-directed acceptance does not convert the missing disposable-VM checks into passing evidence. No production or host socket was touched by this execution.
### Bounded TUI maintenance TUI-FL-001 — Stable keyboard footer
@@ -3722,10 +3723,85 @@ Checks: focused `tui::render::tests` and TUI workflow tests, `cargo fmt --all --
First independent review found TUI-FL-001.2-R1 (P2, omission marker overflow) and R2 (P2, nine-row terminals lose client-list interior). A separate repairer fixed both and independent re-review closed them. That re-review found R3 (P3, unconditional marker reserve omits an action at width 102–103 even when all fit); the two-pass packing repair and regression were independently re-reviewed and closed. Final pinned Rust gates passed. [Evidence](docs/evidence/tui-footer-layout.md) separates synthetic render checks from any physical terminal verification.
### Milestone 17 — Adaptive client list, persistent details and clear states
Status: accepted (2026-10-28T23:09:37+02:00) after independent review, R1/R2 repair and re-review, and pinned Rust gates. Evidence: [M17](docs/evidence/milestone-17.md).
Prerequisites: M16 accepted under the sequential execution policy; pinned Rust toolchain and existing TUI fixture environment; actual GPT-6-Sol/medium coordinator and GPT-6-Luna/high roles. M16 was accepted by explicit user direction after a reported successful manual check; its details remain unavailable and are not M17 test evidence. The user confirmed this session's active coordinator model and effort; project TOML and the configured subagent roles specify GPT-6-Luna/high.
#### Outcome and scope
Make the client list use terminal space effectively: adaptive columns, an always-present selected-client detail pane when dimensions permit, and explicit Draft / Saved / Applied presentation. Governed by [SPEC](docs/SPEC.md) sections Data sources, Operations and states, and Client screen and statistics, all three [ADRs](docs/adr/), and [DEVELOPMENT](docs/DEVELOPMENT.md). All product text and identifiers remain English.
Scope is presentation and secret-free view/navigation support. Preserve the two-row standard footer delivered by TUI-FL-001, action authorization, keyboard shortcuts, confirmations, QR disclosure and full-screen forms. No search, sorting controls, new telemetry collection, dependency changes, persistence schema, runtime/service behavior, configuration writes, terminal-theme overhaul or inferred online status. Handshake and current counters reuse existing observations in details; new table statistic columns are deferred.
#### Context and implementation steps
Repository inspection found `src/tui/render.rs::client_table_columns` fixes Name at 13 cells on wide screens and gives remaining width to combined Allowed IPs. `render_list` repeats supported/inspection-only Mode and derives row state from the narrower `client_states` map; peers outside that map must not be presumed absent from saved files. `render_details` and `detail_lines` already expose full public data, routes, limitations and observations, but only on a separate screen. `state_summary` counts managed saved clients and document issues, not all visible peers or peer issues. `SessionView.applied` is global; periodic statistics explicitly do not mark state applied. The proposed work must preserve these distinctions rather than relabel unknown facts as verified.
Read before dispatch: AGENTS.md, SPEC.md, CONTEXT.md, all three ADRs, docs/IMPLEMENTATION.md, docs/EXECUTION_RECORDS.md, docs/PROJECT_LAYOUT.md, docs/DEVELOPMENT.md, docs/DEPENDENCIES.md, docs/ENVIRONMENT.md, docs/TESTING.md and docs/CODEX.md. Coordinator owns PLANS.md and acceptance; one implementation writer at a time. Use actual configured GPT-6-Luna/high implementer, separate reviewer and repairer roles after verifying the coordinator/model prerequisites. Do not silently substitute models.
| Task | Owner | State | Files and deliverable |
| --- | --- | --- | --- |
| M17.1 | implementer | complete for implementation scope | `src/tui/render.rs`: adaptive wide/medium/compact columns, growing Name, host address columns and route/inspection markers; focused checks passed |
| M17.2 | implementer | complete for implementation scope | `src/tui/render.rs`, `src/tui/state.rs`, `src/tui/terminal.rs`: dimension-only panes, shared visible-row/selection resolver, draft removal and duplicate-key navigation; focused checks passed |
| M17.3 | implementer | complete for implementation scope | Explicit Draft/Saved/Applied and scoped issue/count/detail text in TUI, saved peer count from installed bytes, README help and synthetic legacy workflow; focused checks passed |
| M17.4 | independent reviewer; repairer | complete | R1 loading-state and R2 Clippy findings repaired by separate repairer and independently closed |
| M17.5 | coordinator | complete | Integrated gates passed on fingerprinted inputs; [M17 evidence](docs/evidence/milestone-17.md), acceptance and resume update |
1. Establish one deterministic layout policy based on terminal dimensions, not selected content. Wide mode (initial target at least 140 columns and 20 rows) places the list left and details right, with a useful detail minimum of 48 interior columns and the remaining width assigned to the list. Normal narrower mode (at least 80 columns and 24 rows) places a fixed-height detail pane below the list, reserving at least five visible client rows. At smaller sizes prioritize a usable list, show a concise selected-client summary where it fits, and retain Enter for full details. Keep the existing 34 x 8 minimum guard and very-short behavior. Final breakpoint constants may be adjusted during implementation only to meet measured cell budgets; record them and their boundary tests. Pane heights must not change with label, issue or route length.
2. Allocate table widths from the list pane's actual inner width, reserving borders, selection marker and gaps. Prioritize Name and change state, keep shortened public identity visible where feasible, and use separate IPv4/IPv6 columns when they fit. Give Name a growing share instead of a fixed 13-cell cap. Remove the repetitive Mode column; retain an explicit text marker for inspection-only peers. At constrained widths progressively compact/hide address and key columns with full values available in details. Truncate by display cells with an ellipsis; escape control text. Never treat a subnet as a client's host address; list a route summary/marker and preserve all routes in details.
3. Reuse a shared selected-record resolver and detail content for the persistent pane and Enter screen. Highlight and pane must refer to the same first row even before navigation. Up/Down continue selecting clients; Enter opens scrollable full details, Esc returns with selection retained. Preserve identity across accepted refreshes, handle disappearance and empty views, and inspect ambiguous/malformed rows by document position without enabling mutation. Include draft removals in the unified visible-row model so a row and its details remain reachable. Document issue rows must never be treated as client action targets. Persistent details show full label/key, all routes, draft/saved facts, global apply verification, available handshake/counters, and specific management limitations. Long content uses a visible continuation instruction to Enter; no new focus shortcut is required.
4. Replace Debug-style global state text with explicit labels: Draft: no changes / pending; Saved: clearly defined peer and managed-client counts; Applied: verified / not verified / observation unavailable according to existing state. Clarify that global verification refers to saved configuration, not a current draft. Use stable text markers for draft added/changed/removed and inspection limitations, with colors supplementary. A saved row is not proof of applied access; handshake presence is not apply verification. Unknown must not be displayed as pending restart unless saved-versus-applied divergence is known. Metadata/vault-only drafts must still appear pending even if semantic client-change count is zero. If necessary, add a minimal public projection of existing facts; do not infer saved membership from the draft document or add a new durable model.
5. Define count labels and issue accounting explicitly: distinguish visible/draft peers, saved peers where known, managed clients, document/peer problems and capability limitations. Count each chosen category consistently; do not report a capability limitation as corruption. If existing projections cannot supply a count correctly, use an accurately scoped label instead of inventing a total. Explain inspection-only reasons in details using current capability rules.
#### Acceptance and validation
- [x] M17-A1: wide buffers use extra width for names; long Latin/Cyrillic/wide-character labels remain aligned, with full identity and values accessible in details. Address columns and route markers are accurate for dual-stack, IPv4-only and subnet-route peers.
- [x] M17-A2: persistent side/bottom details update with the highlighted row; empty/loading, first render, duplicate aliases/keys, malformed peers, document-only issues, draft removals and refresh/removal do not select or authorize the wrong client.
- [x] M17-A3: at fixed terminal dimensions, selection, long notices/routes, action availability and periodic statistics do not change pane or footer geometry. Resizing between wide/stacked/compact modes keeps selection, navigation and content reachable without overlap, wrapping table rows or out-of-bounds rendering.
- [x] M17-A4: tests distinguish no draft, added/renamed/deleted drafts, metadata/vault-only draft, saved-but-unverified state, known unapplied changes if available, verified saved state with a new draft, unavailable observations and refresh without apply verification. No saved/handshake/inspection marker falsely claims active access or saved absence.
- [x] M17-A5: full details explain capability limits separately from actual document/peer errors, display all routes and existing handshake/RX/TX observations, preserve secret-free escaping, and use consistent scoped counts including nonmanaged peers.
- [x] M17-A6: Enter/Esc and existing actions/forms/QR retain behavior; standard footer remains two hint rows plus borders. Independent review findings are repaired and rechecked, and all focused and Rust gates pass on integrated inputs.
Planned synthetic buffer matrix: 34x8, 40x9, 60x16, 80x24, 100x30, 139x40, 140x40, 180x50 and 220x50, plus final breakpoint minus/exact/plus dimensions. Use representative secret-free fixtures for state combinations and long content; assert visible semantics, selection and geometry rather than snapshots containing payloads. Add a synthetic workflow/PTY resize scenario only where buffer tests cannot verify navigation or terminal lifecycle.
Validation: pinned Rust/Cargo 1.97.1, rustfmt 1.9.0 and Clippy 0.1.97; `cargo fmt --all -- --check`, `cargo clippy --locked --all-targets -- -D warnings`, `cargo test --locked`, `cargo build --locked --release` and `git diff --check` all exited 0 on the repaired inputs. Focused `cargo test --locked tui::` passed 71 tests; `cargo test --locked --test tui_workflow` passed 8. Full test suite passed 384 with 3 explicitly ignored. Exact source/artifact identities and synthetic/PTY limits are in [M17 evidence](docs/evidence/milestone-17.md). No production, Docker or VM checks were run for this presentation scope.
#### Progress
- [x] M17.1: adaptive table implementation and focused synthetic checks complete; coordinator inspected the actual `src/tui/render.rs` diff.
- [x] M17.2: persistent pane and shared navigation implementation plus focused synthetic checks complete; coordinator inspected the actual state/terminal diff.
- [x] M17.3: explicit state/count/detail implementation and focused synthetic checks complete; coordinator inspected the actual state/README/workflow diff.
- [x] M17.4: independent review found R1; separate repairer fixed it and independent re-review closed it with 39 render tests and fmt/diff checks passing.
- [x] M17.4: integrated Clippy reported R2 at two renderer closures; targeted repair and independent re-review closed it. Exact Clippy gate now passes.
- [x] M17.5: integrated pinned Rust gates and release build passed; source/binary identities and limitations recorded in [M17 evidence](docs/evidence/milestone-17.md). Milestone accepted.
- [x] User confirmed the active GPT-6-Sol/medium coordinator; configured GPT-6-Luna/high roles handled implementation, review and repairs in sequence.
#### Review and repair
| Finding | Iteration | Location and impact | Owner | Resolution and evidence | State |
| --- | --- | --- | --- | --- | --- |
| M17-R1 (P2) | R1 | `src/tui/render.rs`: loading list conflicted with persistent empty-detail message | repairer | Early loading branch plus 140×20/80×24 buffer regression; independent re-review closed, 39 render tests passed | closed |
| M17-R2 (P2) | gate | `src/tui/render.rs:914,1141`: redundant closures failed `cargo clippy --locked --all-targets -- -D warnings` | repairer | Function items preserve semantics; exact Clippy gate passed and independent re-review closed | closed |
#### Evidence and handoff
Current evidence: [M17 evidence](docs/evidence/milestone-17.md) records fingerprinted source/release binary, 71 focused TUI tests, 8 workflow tests, 384 full-suite passes with 3 ignored, all pinned Rust gates and R1/R2 independent closure. Synthetic PTY coverage is distinct from manual terminal-emulator or real-system acceptance.
#### Decisions and discoveries
The user's requested subset is adaptive columns, persistent details and clear states. Existing detail observations can be reused without adding collection. A dedicated full-details screen remains necessary for long routes and small terminals. A global AppliedState cannot safely become an independent verified flag on every draft row. M16's user-directed acceptance is separate from M17 fixture evidence; no dependency or specification change is planned.
#### Outcome
Accepted for the presentation and synthetic fixture scope after independent review, R1/R2 closure and pinned Rust gates. No real WireGuard/systemd, Alpine, disposable-VM or manual terminal-emulator behavior is claimed. Stop after M17; do not commit, deploy, resume retired M9 VM work or access production.
## Current progress and resume point
- TUI-FL-001 is complete (2026-10-27): fixed-height two-row keyboard footer, narrow Help/overflow behavior and compact nine-row handling passed synthetic rendering tests, independent R1–R3 closure and pinned Rust gates. [Footer evidence](docs/evidence/tui-footer-layout.md) identifies source/artifact inputs. M16 remains blocked and unaffected.
- Milestone 16 is blocked after implementation, independent review/repair and passing pinned Rust gates: synthetic tests cover selection/failures, but private-peer behavior and both real systemd transports lack disposable-VM evidence. [M16 evidence](docs/evidence/milestone-16.md) records the source and artifact. No production result is claimed.
- M17 is accepted (2026-10-28): adaptive columns, persistent selected-client details and explicit state/count presentation passed independent R1/R2 closure, synthetic/PTY checks and pinned Rust completion gates. [M17 evidence](docs/evidence/milestone-17.md) records final inputs and limits. Stop here; no next milestone is started.
- TUI-FL-001 is complete (2026-10-27): fixed-height two-row keyboard footer, narrow Help/overflow behavior and compact nine-row handling passed synthetic rendering tests, independent R1–R3 closure and pinned Rust gates. [Footer evidence](docs/evidence/tui-footer-layout.md) identifies source/artifact inputs.
- Milestone 16 is accepted by explicit user direction following a reported successful manual check. Earlier independent review/repair and pinned Rust gates passed; private-peer and both real transport paths still lack recorded disposable-VM evidence. [M16 evidence](docs/evidence/milestone-16.md) records the source and artifact. No production result is claimed by this execution.
- Milestone 15 is accepted (2026-10-27) for synthetic service-adapter and application behavior: typed failure/phase/unit reporting, documented `LoadUnit` resolution, conservative uncertainty, independent R1/R2 closure and pinned Rust gates. [M15 evidence](docs/evidence/milestone-15.md) records source/artifact identity. Disposable-VM systemd acceptance remains incomplete and unclaimed.
- Milestone 14 is accepted (2026-10-27) for fixture restart orchestration: complete saved-peer projection, legacy/IPv4-only/broader-route eligibility, safe blockers and durable verified history passed independent review and pinned Rust gates. [M14 evidence](docs/evidence/milestone-14.md) records source/artifact identity. No disposable-VM systemd acceptance or production result is claimed.
- Milestone 13 is accepted (2026-10-27): compact, explicitly colored QR disclosure, complete quiet zone and dimensioned fallback passed synthetic rendering tests, independent R5 closure and pinned Rust gates. [M13 evidence](docs/evidence/milestone-13.md) records the reviewed source and release artifact. No manual scan, Alpine rerun, VM or production validation is claimed.
@@ -3747,7 +3823,7 @@ First independent review found TUI-FL-001.2-R1 (P2, omission marker overflow) an
- Milestone 8 delivered reviewed opt-in Alpine Testcontainers coverage for real IPv4 WireGuard peers, application lifecycle, saved/runtime separation, restoration, import/reissue, backup failures and the real Rustix reader. Host gates and three fresh real-container runs passed on one stable source fingerprint; M8-A1–A10 accepted. Real IPv6 behavior is unverified by user-authorized scope.
- Milestone 9 is retired and unaccepted: the reviewed disposable VM preparation and guarded first start did not establish Debian/systemd acceptance. The exact VM was powered off after the user stopped work. M9.2–M9.3 were not started; M9-A1–A9 are unchecked.
- Next action: M16 separately requires disposable-VM private-peer and system-bus acceptance. Do not access production, commit, or deploy.
- Next action: none for M17. Stop after acceptance. Keep the undocumented M16 manual check and absent disposable-VM evidence separate from M17 fixture evidence. Do not access production, commit, or deploy.
## Plan maintenance