bstein/lesavka
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

nextcloud: integration with mailu

Browse Source
This commit is contained in:
Brad Stein 2025-12-14 14:20:56 -03:00
parent 2e5f162d2c
commit 953f29dec7
1 changed files with 20 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
AGENTS.md
View File

@ -1,38 +1,31 @@
# Repository Guidelines
## Project Structure & Module Organization
Rust is split into three crates: `server/` (gRPC relay and device control with async tests in `server/tests`), `client/` (GTK + GStreamer desktop agent; `src/input/` and `src/output/` hold HID and media pipelines), and `common/` (shared protobuf schema in `common/proto/lesavka.proto`, compiled via `build.rs`). `scripts/install/*.sh` provision Arch-based hosts, `scripts/manual/*.sh` run hardware diagnostics, and `scripts/daemon/lesavka-core.sh` handles USB gadget bring-up.
- `common/`: tonic/prost definitions; edit `proto/lesavka.proto` and let `build.rs` regenerate bindings.
- `server/`: gRPC relay and media handling; entrypoint `src/main.rs`; integration tests in `server/tests`.
- `client/`: GTK + GStreamer desktop agent; input adapters live in `src/input`, UVC output in `src/output`, helpers/tests in `src/tests`.
- `scripts/`: `install/` provisioning for Arch-based hosts, `daemon/lesavka-core.sh` systemd entrypoint, `manual/` diagnostics (VPN, USB reset, media capture).
## Build, Test, and Development Commands
- `cargo fmt --all` — run rustfmt across every crate before committing.
- `cargo clippy --workspace --all-targets -D warnings` — enforce lint cleanliness against desktop, server, and shared code.
- `cargo build --workspace --all-targets` — compile every binary/lib in debug mode; prefer `--release` for deployment artifacts referenced by install scripts.
- `cargo test --workspace` — executes unit tests plus async scenarios such as `server/tests/hid.rs`.
- `cargo run -p lesavka_server` / `cargo run -p lesavka_client` — start each side locally; set `LESAVKA_SERVER_ADDR` in the environment when pointing the client at a remote relay.
- Formatting: `cargo fmt --all --manifest-path client/Cargo.toml` (repeat for `server`/`common`).
- Linting: `cargo clippy --all-targets --manifest-path server/Cargo.toml -D warnings` (run for client too).
- Build: `cargo build --all-targets --manifest-path server/Cargo.toml` and `cargo build --all-targets --manifest-path client/Cargo.toml`; building either pulls `common`.
- Tests: `cargo test --manifest-path server/Cargo.toml` runs async RPC tests; `cargo test --manifest-path client/Cargo.toml` covers keymap/unit cases.
- Runtime: `cargo run --manifest-path server/Cargo.toml` to start the relay; `LESAVKA_SERVER_ADDR=<host:port> cargo run --manifest-path client/Cargo.toml` to point the client at a server.
- Provisioning: `scripts/install/server.sh` and `scripts/install/client.sh` install dependencies and systemd units; rerun after changing installers or binary names.
## Coding Style & Naming Conventions
Follow Rust 2024 idioms: four-space indentation, `snake_case` for modules/functions, and `CamelCase` for types and protobuf messages. Keep gRPC traits in `common` authoritative and prefer `tonic` streams over manual channels. Never hand-edit generated files in `target/` or the `OUT_DIR`; update `.proto` files and rebuild instead. Document hardware constants inline.
- Rust 2024 with four-space indentation; `snake_case` for functions/modules, `CamelCase` for types and Protobuf messages.
- Keep RPC shapes defined in `common/proto/lesavka.proto`; never hand-edit generated code in `target/` or `OUT_DIR`.
- Prefer tonic streaming APIs over manual channels; keep GStreamer/GTK wiring in small helpers to avoid sprawling `main.rs`.
- Use `tracing` consistently; default `RUST_LOG=info,lesavka=debug` for local runs.
## Testing Guidelines
Async tests should use `#[tokio::test(flavor = "multi_thread")]` when they spawn background servers, mirroring `hid_roundtrip`. Give tests descriptive names and keep them near the code they exercise (`client/src/tests/`, `server/tests/`). Cover new RPCs end-to-end by instantiating the tonic server in-process and asserting on gRPC clients.
- Async integration tests mirror `server/tests/hid.rs` using `#[tokio::test]` and an in-process tonic server/client pair.
- Place client unit tests next to modules (`client/src/tests`); name cases after behavior (`keycode_to_usage_maps_letters`, `hid_roundtrip`).
- For new RPCs, add end-to-end assertions for request/response, stream termination, and error paths; prefer deterministic timeouts over sleeps.
## Commit & Pull Request Guidelines
Recent history favors terse, imperative summaries (“usb fix”), so keep titles under ~50 characters and describe the subsystem. Commits should stay focused (proto update plus regeneration in one commit, client UI tweaks in another). Pull requests must include context, manual verification steps (`cargo test --workspace`, notable hardware checks), relevant logs or screenshots, and linked issues. Call out script or deployment changes so operators know when to re-run `scripts/install/server.sh` or update systemd units.
## Deployment Notes
For reproducible installs, prefer `scripts/install/server.sh --ref <branch>` to provision capture nodes (udev rules, GStreamer stack) and drop `lesavka-core.service`, while `scripts/install/client.sh` handles desktop prerequisites and systemd activation. When editing these scripts, test on an Arch VM. Keep secret material (VPN credentials, Tailscale auth) out of git and load them via environment variables or systemd drop-ins.
Install scripts must stay idempotent and self-contained: add any new runtime dependencies (e.g., audio/ALSA tools needed for mic bring-up) to the respective install script so a rerun on an arbitrary server/client brings the box to a ready state.
## Current Setup
- Server runs on Raspberry Pi 5 host `titan-jh` (ssh alias configured) and is already provisioned; client setup happens on this machine.
- HDMI capture uses two USB AVerMedia/GC311 devices with power/data split; AC relays on GPIO keep them off unless needed (control scripts already on the Pi).
- USB gadget exposes HID/UAC/UVC; webcam feed is expected from the client into the gadget UVC node (default `LESAVKA_UVC_DEV=/dev/video4`).
- Client ↔ server address: `http://38.28.125.112:50051` (was `64.25.10.31`).
- Webcam uplink is the remaining piece to confirm end-to-end after client install; server-side audio/video capture is in place.
## Session Notes (Dec 1, 2025)
- Server change pending deployment: `server/src/main.rs` now auto-picks UVC sink via `LESAVKA_UVC_DEV` or first `:video_output:` node (titan-jh gadget is `/dev/video0`); errors if none. `stream_microphone` honors `LESAVKA_UAC_DEV`.
- Client change: mic capture falls back to first non-`.monitor` Pulse source if `LESAVKA_MIC_SOURCE` missing/not found.
- Action: rerun `scripts/install/server.sh --ref feature/webcam-caps` on titan-jh (optionally set `LESAVKA_UVC_DEV=/dev/video0`, `LESAVKA_UAC_DEV=plughw:UAC2Gadget,0`), then restart service. Check `/tmp/lesavka-server.log` for “stream_camera using UVC sink”.
- Tethys display: SDDM running but greeter not; capture shows black+cursor. Need greeter/desktop on HDMI head (GC311 input) once display/cable is correct; investigate sddm greeter crash after reboot.
- Git history favors short, imperative subjects (`"install mic deps"`, `"client: improve mic defaults"`); keep each commit focused.
- Before opening a PR, run fmt, clippy, and tests for client and server; note any manual steps or env vars used (`LESAVKA_SERVER_ADDR`, `LESAVKA_UVC_DEV`, `LESAVKA_UAC_DEV`).
- PR descriptions should summarize intent, attach logs/screenshots when touching media paths, and flag installer/systemd changes so operators can re-run the relevant scripts.