libreqos-rust-workflow

name	libreqos-rust-workflow
description	Shared LibreQoS Rust workflow for repo contributors. Use when changing Rust under src/rust, validating Rust crates, deciding between workspace commands and --manifest-path, or applying LibreQoS-specific Rust conventions and verification steps.

LibreQoS Rust Workflow

Use this skill for Rust work in this repo.

Scope

• Rust sources live under src/rust/.
• src/rust/Cargo.toml is the source of truth for current workspace members.
• Some crates exist in-tree but are not current workspace members. If a crate is outside [workspace].members, use cargo --manifest-path path/to/Cargo.toml.

Workflow

1. Read AGENTS.md first for current repo rules and crate descriptions.
2. Identify whether the touched crate is a workspace member.
3. Validate the touched crate with cargo check -p <crate> when possible.
4. Run relevant tests:
   • Unit tests MUST pass.
   • Before any git commit that includes Rust logic changes, you MUST run cargo test -p <crate> (or the smallest equivalent scope) and confirm it compiles and succeeds.
   • Do not add tests just to “have tests”. Tests must validate functionality (avoid assert!(true)-style tests or “tests” that only prove the compiler accepts code).
   • Check for test functions that look like tests but are missing #[test] (functions in #[cfg(test)] modules that are never executed should be treated as a bug unless they are explicitly helper functions).
5. Run cargo clippy -p <crate> -- -D warnings and fix actionable issues.
   • If you decide to suppress a lint/warning anyway, you MUST include a justification and tell the user: I'M SORRY, MASTER. I HAVE FAILED YOU. I HAVE SUPPRESSED A WARNING WHEN I SHOULD HAVE WRITTEN GOOD CODE. I AM FOREVER IN YOUR DEBT.
6. After any repo change, invoke heckler via $libreqos-review-subagents-workflow before returning to the user.
7. After each source-code implementation batch, also invoke reaper via $libreqos-review-subagents-workflow.
8. During large sessions, invoke $libreqos-review-subagents-workflow (and helen if UI changed).
9. If dependencies changed, also run:
   • cargo machete
   • cargo audit
   • cargo tree
10. If the change adds, renames, moves, or newly depends on runtime files, static assets, helper scripts, service files, templates, or install-time artifacts, review and update src/build_dpkg.sh in the same change.
11. Use workspace-wide commands only for cross-cutting changes or shared dependency changes.

Architecture And Structure Rules

• Do not create additional binaries unless specifically instructed.
  • Long-running services that can be part of lqosd should be part of lqosd.
• Do not create large library source files; prefer breaking code into clean modules.
• Avoid huge functions; prefer small functions.
  • Rule of thumb: anything that won’t fit on a terminal screen is probably too big.

Documentation Requirements

• Every module must have a doc header describing what it does (//! ... at the top of the module).
• Every public function and struct must have full RustDoc (examples are optional).
• Functions must document any side effects (file I/O, network I/O, spawning threads/tasks, touching TC/XDP state, global state, etc.).

Correctness And Error-Handling Requirements

• If a function has arguments with invariants, check the invariants first and fail fast.
• Use thiserror for new error types, defined at (or very near) the failure source.
  • Document every failure path; avoid collapsing everything into a single FooError.
• Avoid anyhow and other Box<dyn Error> patterns in new reusable code.
• Avoid pub static whenever possible; actor-owned state with clean boundaries is preferred.
  • If a static is unavoidable, guard it behind accessor functions so misuse of the lock is impossible.

Preferred Rust Direction

• Prefer parking_lot for new Mutex and RwLock usage.
• Prefer crossbeam_channel for new MPSC/MPMC channels.
• Prefer thiserror for structured errors.
• Prefer let else and early returns over deeply nested if let.
• Avoid introducing new pub static values with locks when helper functions or actors are better.
• Avoid introducing new #[inline(always)]; prefer #[inline].
• Keep RustDoc current for changed public items and note side effects for non-pure functions.
• Avoid allocation in hot paths.

Async And Tokio

• Treat async code as latency-sensitive shared execution. Do not add blocking work to a Tokio task without checking the impact on the runtime.
• Review every synchronous call made from an async context for blocking potential, including filesystem I/O, process spawning, DNS/network clients, compression, parsing of large inputs, CPU-heavy loops, mutex contention, and sleep/wait calls.
• Use async APIs when they exist and fit the surrounding code.
• Use tokio::task::spawn_blocking for unavoidable blocking or CPU-heavy work called from async code, and keep the closure narrow so ownership, cancellation behavior, and error handling stay obvious.
• Do not hold async locks, runtime handles, or request-scoped borrows across spawn_blocking boundaries unless the ownership and lifetime implications are explicit and safe.
• Prefer tokio::sync primitives inside async tasks. Use blocking locks only when there is a clear reason and no .await can occur while the guard is held.

Notes

• Existing code does not fully match all preferred conventions yet. Treat these as direction for new and touched code, not as a reason to perform unrelated cleanup.
• Build/package scripts live under src/, not repo root.
• src/build_dpkg.sh is a functional packaging manifest for shipped installs. Forgetting to update it is a common failure mode; treat package-content drift as a bug.
• Treat protocol and identity surfaces as compatibility boundaries:
  • Prefer additive-only changes (new optional fields, #[serde(default)] where applicable).
  • Assume rolling upgrades where old/new binaries may coexist unless a coordinated restart is explicitly planned.
  • Do not rename fields, change types, or change semantics without explicit versioning and a coordinated rollout plan.
  • Keep compatibility shims at the boundary, make them explicit, and test them; avoid “fallbacks everywhere”.
  • Avoid per-request info! logging in hot paths; prefer debug!, sampling, or aggregate counters.