ia-rust-systems
Rust patterns for CLI tools, backend services, and general application code. Use when working with Rust, Cargo workspaces, axum/tokio services, clap CLIs, async concurrency, or configuring clippy, rustfmt, cargo-nextest, or Cargo.toml.
Rust Systems & Services
Covers modern application-layer Rust (edition 2024): CLIs, web services, libraries. Not no_std/embedded.
Working rules
- Preserve error variants in libraries and add operational context at application boundaries.
- Distinguish missing configuration from unreadable or invalid files before writing replacements.
- Keep blocking work off async workers, bound queues and spawned work, and define shutdown behavior.
- Trace exported interfaces before treating a change as internal; verify installed runtime capabilities.
- Do not mutate process-wide state in concurrent tests; exercise the real binary and relevant feature combinations.
Unsafe Discipline
- Default: no
unsafe. If clippy flags it, don't#[allow]it; refactor. The#[expect]escape hatch below does not apply here; unsafe findings get fixed, not annotated. - Every
unsafeblock gets a// SAFETY:comment naming the operation, the contract clause it discharges, and the code (types, bounds, a dominating check) that enforces each premise. Review the code first and the comment second: a comment asserting a property of a caller-supplied argument that no code checks makes the enclosing safe function unsound. - Unsafe code never relies for memory safety on caller-supplied safe code:
len()/size_hint(),Ord,Eq,Hash,Clone,Deref,Drop, closures, and callbacks may return any type-correct value, panic, or reenter. Check capacity and bounds before each write, callset_lenonly for elements actually initialized, and restore invariants (or hold a guard) before any call into caller code. - Keep
unsafeblocks minimal: wrap in a safe abstraction at module boundary, mark the modulepub(crate). - Run
miri(cargo +nightly miri test) on any crate containingunsafeor raw pointer arithmetic; a clean run is evidence for the paths the tests execute, not a proof premise. - Prefer
bytemuck,zerocopy,bytesover hand-rolled transmutes for zero-copy patterns. - Env-var writes are
unsafein edition 2024. Write them only inmain, before the runtime starts or any thread spawns. Concurrentgetenvis UB;OnceLockdoes not make it safe. Watch for lazyLD_LIBRARY_PATH-style writes on first use; hoist them to startup. - For reviewing or writing
unsafe(raw parts to references,transmute, sealed-trait reliance, FFI), read unsafe-review.md and give every unsafe site a recorded disposition before concluding.
Discipline
- Simplicity first: every change as simple as possible, impact minimal code.
- Only touch what's necessary; avoid unrelated changes in a PR.
- No
#[allow(clippy::...)]as a shortcut; fix the underlying issue. When a suppression is genuinely warranted, write#[expect(clippy::lint_name, reason = "...")]instead:expectwarns once the lint stops firing, so a suppression that has outlived its cause reports itself, whereallowrots silently forever. (expectneeds Rust 1.81+; edition 2024 clears that floor.) - Before adding a trait or generic, verify it's used in 3+ places. Otherwise a concrete type is clearer.
bool::then_some(x)takesxby value: the argument is computed before the bool is consulted, so a guard written as a condition plus a fixed-width slice panics on exactly the inputs the condition was checking for:(b.len() >= 19 && b[4] == b'-').then_some(&v[..19])panics on any shorter value, exiting 101 inside the one function written to report the case as undetermined. Usethen(|| …), which is lazy. Clippy does not flag the difference. Grepthen_some(for an argument that indexes, slices, unwraps, or allocates. Related: a fixed-width slice is not a parse.&v[..19]also panics mid-character on non-ASCII, and comparing two such prefixes lexicographically drops the timezone offset, so01:00+02:00sorts after00:00Zwhile being an hour earlier. Parse and normalize, or reject.
Verify
cargo fmt --all -- --checkpasses with zero diffscargo clippy --workspace --all-targets --all-features -- -D warningspassescargo nextest run --workspace(orcargo test --workspace) passes with zero failures- When using nextest,
cargo test --doc --workspacealso passes; nextest does not run doctests cargo deny checkpasses (licenses, advisories, duplicates) for any crate going to production- Every new
unsafehas each// SAFETY:premise enforced in code or by a caller# Safetycontract
Task-specific references
Read the relevant reference before implementing or reviewing the matching behavior:
- For
unsafeblocks, raw-parts references,transmute, sealed-trait reliance, or FFI wrappers: unsafe-review.md. - For Cargo setup, workspace changes, public API reachability, build profiles, or CI: toolchain-and-interfaces.md.
- For errors, ownership, parsing boundaries, Tokio, shutdown, or concurrency: ownership-and-execution.md.
- For CLI/service entrypoints, production resilience, telemetry, or tests: applications-and-testing.md.
Existing specialized references, when the corresponding topic applies:
Related skills
- Downloads
- 2.8kAll time
- Security audit
- Pass
- Last updated
- 11h ago
- Current version
- v5.1.7
- License
- MIT-0
