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

Refactor acceptance and architecture handoff

Browse Source
This commit is contained in:
sasa
2026-10-30 23:30:16 +02:00
parent 7123197ec4
commit 4c86472740
11 changed files with 314 additions and 164 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/PROJECT_LAYOUT.md
+87 -59
View File
@@ -1,19 +1,13 @@
# Project Layout
Read this document when creating or reorganizing modules. The layout below
reflects the current package; sections marked planned describe later test and
integration work only.
This is the integrated package layout after M26. Paths below exist in the
repository; scenario descriptions name current owners. Add modules when a
cohesive responsibility needs them, not as placeholders.
## Target project layout
The repository has one Cargo package with a binary (`src/main.rs`) and a
library (`src/lib.rs`). Startup and process exit remain in `main.rs`; testable
application logic and the management TUI are library modules. A library target
does not require publishing a separate library package. Introduce a workspace
only when independently reusable or separately built components justify it.
Implemented modules include the following. Add modules as implementation
requires them; do not generate empty scaffolding for future integration work.
The repository has one Cargo package with a binary (`src/main.rs`) and a library
(`src/lib.rs`). Startup and process exit remain in `main.rs`; testable
application logic and the TUI are library modules. The library target is not a
separately published package.
```text
Cargo.toml
@@ -23,64 +17,98 @@ AGENTS.md
CONTEXT.md
PLANS.md
README.md
.gitignore
src/
main.rs # Startup, arguments, process exit
lib.rs # Module declarations and application API
config.rs # Application settings and path resolution
domain.rs # Clients, identities, address allocation/reservations, change states
app.rs # Application operations and orchestration
lib.rs # Library modules; test-only container driver gate
startup.rs # Root boundary, settings/store loading, session entry
config.rs # Settings validation and executable-relative paths
domain.rs # Client projection, address allocation/reservations, apply knowledge
app.rs # Application facade, session, and public operation types
app/
draft.rs # Coordinated in-memory document, client-state, and vault drafts
first_delivery.rs # Session-local first-issue authorization and retry state
first_file.rs # Password-free first-file and optional QR scenario
draft.rs # Coordinated document/client/vault draft replacements
first_delivery.rs # Session-local one-use capability and retry state
first_file.rs # First-delivery file and optional QR scenario
reissue.rs # Password-per-action saved-client reissue
read_model.rs # Secret-free application facts and per-action eligibility
reissue.rs # Per-action vault authentication and saved-client delivery
commit.rs # Prepare, backup, install, and publish saved-state Commit
restore.rs # Bound preview and confirmed saved-state replacement
backups.rs # Manual/pre-operation backup and archive-list scenarios
restart.rs # Bound restart preview, backup, job, verification, and publication scenario
commit.rs # Backup, saved install, and Commit publication
restore.rs # Preview, reservation rebuild, and confirmed saved replacement
backups.rs # Manual/pre-operation backup and archive listing
restart.rs # Restart preview, backup/job/verify/publication sequence
wireguard.rs # Server configuration module boundary
wireguard/
document.rs # Parsing and edits preserving original text
metadata.rs # Managed client comment blocks
vault.rs # Encryption, import, secret retrieval
backup.rs # Backup archives and restoration
runtime.rs # Running WireGuard interface and statistics
service.rs # Systemd operations and restart verification
delivery.rs # Client configuration files and QR generation
tui.rs # Terminal UI entry point
document.rs # Lossless parse, peer inspection and document authority
edit.rs # Byte-preserving peer and metadata edits
metadata.rs # Managed comment grammar and metadata validation
vault.rs # Vault format, encryption, key matching and retrieval
vault/
source.rs # Read-only configured client-source access
import.rs # Client-file reconciliation and encrypted import
persistence.rs # Saved-file installation, recovery and state codec
backup.rs # Versioned archive encoding, parsing and preview
runtime.rs # Runtime observations, peer projections and comparison
runtime/
netlink.rs # Bounded Generic Netlink WireGuard reader
transport.rs # Read-only runtime transport
service.rs # Systemd request and job completion adapter
service/
dbus.rs # D-Bus systemd implementation
delivery.rs # Client configuration rendering and adapter boundary
delivery/
files.rs # Secure client file publication
qr.rs # Terminal QR generation
tui.rs # TUI entry and session lifecycle
tui/
state.rs # Screen state and navigation
events.rs # Commands, worker lifecycle, and background events
state.rs # Screens, selection, UI generations and navigation
events.rs # Typed commands, worker queue and lifecycle
events/
executor.rs # Application command adaptation and prepared contexts
forms.rs # Short-lived forms and secret owners
render.rs # Rendering
terminal.rs # Terminal setup and cleanup
executor.rs # Application command adaptation and prepared contexts
forms.rs # Short-lived form inputs and sensitive commands
render.rs # Visual strings, styles, wrapping and layout
terminal.rs # Terminal setup, event loop and cleanup
container_driver.rs # Test-only Alpine scenario driver (`cfg(test)`)
tests/
config_preservation.rs # Untouched server configuration remains identical
commit_restore.rs # Persistence, backups, restore, runtime isolation
client_delivery.rs # Client file delivery and lifecycle workflows
vault_import.rs # Existing-client import and reconciliation workflows
tui_workflow.rs # Synthetic worker-level TUI workflows
fixtures/ # Synthetic configuration and archive inputs
support/
mod.rs # Shared test adapters and helpers
config_preservation.rs # Synthetic byte-preservation behavior
commit_restore.rs # Persistence, backups, restore and runtime isolation
client_delivery.rs # First delivery, retry, reissue and lifecycle behavior
runtime_restart.rs # Restart scenario behavior using controlled adapters
vault_import.rs # Import and reconciliation behavior
tui_workflow.rs # Worker-level TUI workflows and synthetic PTY checks
testcontainers_wireguard.rs # Explicitly selected, ignored Alpine integration suite
support/ # Shared fixtures, adapters and container harness
fixtures/wireguard/ # Synthetic server configuration
containers/alpine/ # Pinned Alpine runtime image and readiness support
vm/ # Guarded disposable-VM preparation/test scripts
config/
wireguard-admin.example.toml # Safe example; settings format chosen at implementation
wireguard-admin.example.toml # Safe distributable example settings
docs/
SPEC.md
IMPLEMENTATION.md
PROJECT_LAYOUT.md
architecture/domain-refactoring.md
adr/
target/ # Cargo output; never commit
target/ # Cargo output; never commit
```
- Use modules named for their responsibility. Avoid catch-all `utils`, `helpers`, or `common` modules; place supporting code with its owner.
- Begin with a single module file and split into child modules when needed. Prefer `name.rs` with `name/child.rs` for production modules; `tests/support/mod.rs` keeps test helpers from becoming a separate integration test target.
- Declare application modules once in the library, rather than duplicating them in both `main.rs` and `lib.rs`. Keep internals private or `pub(crate)`; expose only the library API needed by the binary and behavioral integration tests.
- Keep focused unit tests beside their modules under `#[cfg(test)]`; put cross-module behavioral tests in `tests/`. Use `tests/support/` for test-only adapters rather than exporting test infrastructure from the production library.
- The `config/` directory contains distributable examples, not live settings. The example filename above is illustrative and does not settle the settings format. Actual settings remain alongside the deployed executable as specified.
- Keep live server configurations, private keys, delivered client files, and runtime `Backup/` data out of the source tree and version control. Ignore generated build output and local deployment data without hiding synthetic fixtures.
- Add `examples/` only for runnable Rust examples and `benches/` only when benchmarks are needed. Do not add empty directories or scripts that duplicate Cargo commands.
- Keep the layout aligned with actual module responsibilities as the code grows. Update this section when files move; do not preserve obsolete paths merely to match the initial tree.
## Ownership rules
- `Application` is the public facade. Scenario ordering belongs in `src/app/`
owners; the facade delegates without transferring authority to the TUI.
- The server `ConfigDocument` is authoritative for peers and metadata.
`ClientStates` is only the manageable-client projection. Editing preserves
unowned bytes and comments.
- Domain logic does not perform file, crypto, runtime, service, or rendering
work. Persistence owns installed state; backup owns archive encoding;
runtime owns observations/comparison; service owns systemd calls.
- `app/read_model.rs` supplies secret-free facts and action eligibility.
TUI state owns selection/navigation/generation; the executor binds prepared
continuations and calls application operations; renderers own presentation.
- Keep module internals private or `pub(crate)` where possible. Public facade
APIs retained for integration fixture setup are documented with their caller
audit in [the architecture map](architecture/domain-refactoring.md).
- Keep focused unit tests beside their modules and cross-module behavior in
`tests/`. `src/container_driver.rs` is included only in the library test
harness. Its opt-in Alpine application fixture is not systemd acceptance.
- `config/` holds safe examples, not live settings. Runtime data and archives
remain outside the source tree. Do not commit live configuration, keys,
delivered client files, or generated `Backup/` data.
- Keep this map aligned with actual files and responsibility. Do not add empty
directories or speculative traits/modules.