Rust Systems

---
name: Rust Systems
description: Use when building Rust systems with ownership models, lifetimes, async runtime, FFI, unsafe patterns, and performance.
category: Languages
version: 1.0.0
tools: []
---

# Rust Systems Engineering

Write safe, performant, and idiomatic Rust by mastering ownership, lifetimes, and the type system.

## Core Principles

- Correctness first, then performance; the compiler is an ally, not an obstacle
- Use `unsafe` only when strictly necessary with `// SAFETY:` comments documenting invariants
- Prefer zero-cost abstractions; reconsider if an abstraction adds runtime overhead
- Make illegal states unrepresentable using enums and the type system

## Ownership and Borrowing

- Default to owned types (`String`, `Vec<T>`, `PathBuf`); use references for read-only access
- Use `&str` and `&[T]` as function parameter types for maximum flexibility
- Use `Cow<'_, str>` when a function might or might not need to allocate
- Avoid `Clone` as a band-aid for borrow checker errors; restructure the code
- Use `Arc<T>` for shared ownership across threads; combine with `Mutex<T>` or `RwLock<T>` for interior mutability

## Lifetimes

- Elide lifetimes when the compiler can infer them; annotate only when required
- Name lifetimes descriptively: `'input`, `'conn`, `'query` instead of `'a`, `'b`, `'c`
- When a struct holds references, ensure referenced data outlives the struct; switch to owned data if complex
- Use `'static` only for truly static data or required by trait bounds (e.g., spawning tasks)

## Error Handling

- Define error enums with `thiserror` for libraries; use `anyhow` for applications
- Implement `From<SourceError>` for error conversions; use `?` operator for propagation
- Never use `.unwrap()` in library code; use `.expect("reason")` only when invariant is documented
- Return `Result<T, E>` from all fallible operations; use `Option<T>` only for genuinely optional values

## Async Runtime

- Use `tokio` as default async runtime; pin the version in `Cargo.toml`
- Use `tokio::spawn` for independent tasks; `tokio::join!` for all-complete requirements
- Use `tokio::select!` for racing futures with cancellation-safe branches
- Avoid blocking the runtime; use `tokio::task::spawn_blocking` for CPU-heavy or sync I/O
- Use channels for inter-task communication: `tokio::sync::mpsc`, `broadcast`, `watch`

## FFI and Unsafe

- Wrap FFI calls in safe Rust functions; unsafe boundary should be minimal
- Use `bindgen` for generating bindings from C headers
- Validate all pointers from foreign code before dereferencing
- Use `#[repr(C)]` for structs crossing the FFI boundary

## Performance

- Benchmark with `criterion`; profile with `perf`, `flamegraph`, or `samply`
- Prefer stack allocation over heap; use arrays and tuples for small fixed collections
- Use `SmallVec` or `ArrayVec` for collections usually small
- Avoid unnecessary allocations in hot paths; reuse buffers with `clear()`
- Prefer iterators over indexed loops; compiler optimizes iterator chains aggressively

## Project Structure & Testing

- Use workspace with multiple crates; separate library from binary
- Organize modules by domain: `auth/`, `storage/`, `api/` not by type
- Use `pub(crate)` for internal APIs; only `pub` for public contract
- Write unit tests in `#[cfg(test)] mod tests`; integration tests in `tests/` directory
- Use `proptest` or `quickcheck` for property-based testing

## Before Completing

- Run `cargo clippy -- -D warnings` with zero warnings
- Run `cargo test` to verify all tests pass
- Run `cargo fmt --check` to verify formatting
- Ensure all `unsafe` blocks have `// SAFETY:` comments