Rust Rules

---
name: rust-rules
description: "Rust coding rules: style, patterns, security, testing. Triggers: .rs, Cargo.toml, Cargo.lock, Tokio, Axum, Serde, clippy, cargo test."
effort: medium
user-invocable: false
allowed-tools: Read
---

# Rust Rules

These rules come from `app/rules/rust/` in ai-toolkit. They cover
the project's standards for coding style, frameworks, patterns,
security, and testing in Rust. Apply them when writing or
reviewing Rust code.

# Rust Coding Style

## Naming
- snake_case: functions, methods, variables, modules, crates.
- PascalCase: types, traits, enums, structs, type parameters.
- SCREAMING_SNAKE: constants and statics.
- Short lifetimes: `'a`, `'b`. Descriptive only when multiple coexist: `'input`, `'output`.
- Crate names: kebab-case in Cargo.toml, snake_case in code.

## Ownership
- Borrow (`&T`) when you only need to read. Own (`T`) when storing or consuming.
- Use `&str` over `String` in function parameters when possible.
- Use `Cow<'_, str>` when you sometimes need to allocate.
- Avoid `.clone()` as a first resort -- restructure ownership instead.
- Use `Arc<T>` only when shared ownership across threads is required.

## Types
- Use newtypes for domain primitives: `struct UserId(Uuid)`.
- Use `#[derive(Debug, Clone, PartialEq)]` on data types.
- Implement `Display` for user-facing output, `Debug` for developer output.
- Use `#[non_exhaustive]` on public enums and structs for future compatibility.
- Prefer enums over boolean flags for state representation.

## Functions
- Return `Result<T, E>` for operations that can fail. Avoid panicking.
- Use `impl Trait` in argument position for flexibility, return position for simplicity.
- Use `where` clauses for complex bounds instead of inline.
- Prefer iterators over index-based loops.
- Use `let-else` (1.65+) for early-exit pattern matching.

## Modules
- Use `mod.rs` or filename-based modules. Be consistent within the project.
- Re-export public API from `lib.rs` for a clean surface.
- Keep modules focused. One major type or concept per module.
- Use `pub(crate)` for internal-only visibility.

## Formatting
- Use `rustfmt` with default settings. Do not fight the formatter.
- Use `clippy` with `-D warnings` in CI. Fix all warnings.
- Set MSRV (Minimum Supported Rust Version) in `Cargo.toml`.

## Cargo
- Use workspace dependencies to unify versions across crates.
- Use feature flags for optional functionality.
- Set `edition = "2021"` (or latest stable edition).
- Use `[profile.release]` with `lto = true` and `codegen-units = 1` for production.

# Rust Frameworks

## Axum
- Use extractors for typed request parsing: `Path`, `Query`, `Json`, `State`.
- Use `Router::new().route("/path", get(handler))` for route definitions.
- Share state via `State(Arc<AppState>)` extractor.
- Implement `IntoResponse` on error types for clean error handling.
- Use Tower middleware layers for auth, logging, tracing, rate limiting.

## Actix-web
- Use extractors: `web::Path`, `web::Json`, `web::Data`.
- Use `App::new().service()` for route configuration.
- Share state with `web::Data<Arc<State>>`.
- Use `actix-web::middleware` for logging and error handling.

## Tokio
- Use `#[tokio::main]` for the entry point. Use `tokio::spawn` for tasks.
- Use `tokio::select!` for waiting on multiple futures.
- Use `tokio::time::timeout()` for operation deadlines.
- Use `tokio::sync::broadcast` for pub/sub, `mpsc` for work queues.
- Use `tokio::task::spawn_blocking()` for CPU-intensive work in async context.

## SQLx
- Use compile-time checked queries: `sqlx::query_as!(User, "SELECT ...")`.
- Use `PgPool` for connection pooling. Pass as shared state.
- Use migrations: `sqlx migrate add` and `sqlx migrate run`.
- Use `sqlx::FromRow` derive for automatic struct mapping.
- Set `DATABASE_URL` for compile-time query verification.

## Serde
- Use `#[derive(Serialize, Deserialize)]` on all DTOs.
- Use `#[serde(rename_all = "camelCase")]` for JSON API compatibility.
- Use `#[serde(deny_unknown_fields)]` for strict deserialization.
- Use `#[serde(default)]` for optional fields with defaults.
- Use `#[serde(skip_serializing_if = "Option::is_none")]` for clean output.

## Clap
- Use `#[derive(Parser)]` for CLI argument parsing.
- Use subcommands with enum variants: `#[derive(Subcommand)]`.
- Use `#[arg(env = "VAR_NAME")]` for env var fallback.
- Use `value_parser` for custom validation of arguments.

## Tracing
- Use `tracing` crate over `log` for structured, async-aware logging.
- Use `#[instrument]` attribute on functions for automatic span creation.
- Use `tracing_subscriber` with `EnvFilter` for runtime log level control.
- Add `trace_id` to all log entries for distributed tracing correlation.

## Testing Crates
- `mockall`: auto-generate mocks from traits.
- `wiremock`: HTTP mock server for integration tests.
- `testcontainers`: Docker containers for database tests.
- `proptest` / `quickcheck`: property-based testing.

# Rust Patterns

## Error Handling
- Use `thiserror` for library error types (structured, typed enums).
- Use `anyhow` for application/binary code (flexible, context-rich).
- Wrap errors with context: `.with_context(|| format!("loading {path}"))?`.
- Use `#[from]` attribute for automatic error conversion in thiserror enums.
- Map domain errors to HTTP/gRPC errors at API boundaries only.

## Builder Pattern
- Use builder for structs with many optional fields.
- Return `Result` from `build()` when validation is needed.
- Use `#[derive(Default)]` + `TypedBuilder` derive macro for compile-time safety.
- Chain setter methods returning `Self` for ergonomic API.

## Newtype Pattern
- Wrap primitive types for type safety: `struct Email(String)`.
- Validate in constructor: `Email::new(raw) -> Result<Self, ValidationError>`.
- Implement `Deref` only when the inner type's full API is appropriate.
- Use `#[repr(transparent)]` for zero-cost newtypes in FFI.

## Trait Design
- Keep traits small and focused. Compose with supertraits.
- Use associated types for output types: `type Output;`.
- Use default method implementations for common behavior.
- Use extension traits to add methods to foreign types.

## Async Patterns
- Use `tokio` as the async runtime for most applications.
- Use `tokio::spawn` for concurrent tasks, `tokio::select!` for racing.
- Use `tokio::sync::mpsc` for channels, `tokio::sync::Mutex` for async locks.
- Prefer `async fn` in traits (Rust 1.75+) over manual `Pin<Box<dyn Future>>`.
- Use `tower` middleware pattern for layered request processing.

## Iterator Patterns
- Use `.iter()` / `.into_iter()` / `.iter_mut()` appropriately.
- Chain: `filter().map().collect()` instead of manual loops.
- Use `collect::<Result<Vec<_>, _>>()` to short-circuit on first error.
- Implement `IntoIterator` for custom collections.

## State Machine
- Use enums with data variants for state machines.
- Use `match` exhaustively -- compiler prevents missing states.
- Encode valid transitions in the type system when possible.
- Use typestate pattern for compile-time state transition enforcement.

## Anti-Patterns
- `.unwrap()` in library code -- return `Result` or `Option`.
- `.clone()` to fix borrow checker -- restructure ownership.
- `Arc<Mutex<T>>` as first approach -- consider channels or actors.
- `Box<dyn Error>` in libraries -- use typed error enums.
- Ignoring `#[must_use]` warnings -- handle or explicitly discard with `let _ =`.

# Rust Security

## Memory Safety
- Rust's ownership system prevents most memory bugs. Do not circumvent it.
- Minimize `unsafe` blocks. Document every safety invariant with `// SAFETY:`.
- Use `#![forbid(unsafe_code)]` in library crates when possible.
- Audit all `unsafe` code during review. Treat it as a security boundary.
- Use `miri` in CI for detecting undefined behavior in unsafe code.

## Input Validation
- Validate all external input before processing. Use newtypes with validation.
- Use `serde` with `#[serde(deny_unknown_fields)]` for strict deserialization.
- Set size limits on deserialized data: `#[serde(deserialize_with = "...")]`.
- Validate string lengths, numeric ranges, and formats at API boundaries.

## SQL Injection
- Use `sqlx` parameterized queries: `sqlx::query!("SELECT * WHERE id = $1", id)`.
- Never build SQL strings with `format!()` using user input.
- Use `sqlx::query_builder::QueryBuilder` for dynamic query construction.
- Type-check queries at compile time with `sqlx::query!` macro.

## Cryptography
- Use `ring` or `rustcrypto` crates for cryptographic operations.
- Use `argon2` crate for password hashing.
- Use `subtle::ConstantTimeEq` for timing-safe comparisons.
- Use `rand` crate with `OsRng` for cryptographically secure random values.
- Never implement custom cryptographic algorithms.

## Dependencies
- Run `cargo audit` in CI to check for known vulnerabilities.
- Run `cargo deny check` for license compliance and advisory checking.
- Use `cargo tree -d` to find duplicate dependencies.
- Review `build.rs` scripts in dependencies -- they execute at compile time.
- Minimize dependency count. Each crate is a potential attack surface.

## Secrets
- Load secrets from environment: `std::env::var("SECRET")`.
- Use `secrecy` crate for values that should not be logged or displayed.
- Zeroize sensitive data after use with `zeroize` crate.
- Never hardcode secrets, tokens, or keys in source code.

## Panic Safety
- Use `Result` and `Option` instead of panicking in library code.
- Use `catch_unwind` at FFI boundaries to prevent unwinding across languages.
- Set `panic = "abort"` in release profile to prevent panic exploitation.
- Avoid `unwrap()` and `expect()` on user-controlled data.

## Network Security
- Use `rustls` over OpenSSL for TLS (pure Rust, memory-safe).
- Set timeouts on all network operations.
- Implement rate limiting on public endpoints.
- Validate and sanitize URLs before making outbound requests.

## Supply Chain
- Use `cargo-vet` to track third-party audit status.
- Use `cargo-crev` for community code reviews.
- Enable `Cargo.lock` in version control for applications (not libraries).
- Prefer well-maintained crates with recent activity and security audits.

# Rust Testing

## Unit Tests
- Place unit tests in `#[cfg(test)] mod tests` at the bottom of each file.
- Use `#[test]` attribute. Use `#[tokio::test]` for async tests.
- Name tests descriptively: `fn rejects_invalid_email()`.
- Access private items directly -- unit test modules are inside the parent module.

## Integration Tests
- Place in `tests/` directory. Each file compiles as a separate crate.
- Test only the public API from integration tests.
- Use `tests/common/mod.rs` for shared test utilities.
- Name files by feature area: `tests/api_test.rs`, `tests/auth_test.rs`.

## Assertions
- Use `assert_eq!(actual, expected)` with the actual value first.
- Use `assert!(matches!(result, Ok(_)))` for pattern matching in assertions.
- Use custom error messages: `assert_eq!(x, 5, "expected x to be 5, got {x}")`.
- Use `#[should_panic(expected = "message")]` for testing panics.

## Result Testing
- Use `-> Result<(), Box<dyn Error>>` return type in tests for `?` support.
- Test error variants: `assert!(matches!(result, Err(AppError::NotFound(_))))`.
- Use `.unwrap()` in tests when failure means a bug in the test.

## Mocking
- Use `mockall` crate with `#[automock]` on trait definitions.
- Use `expect_*` methods to set expectations on mock behavior.
- Prefer trait-based DI for testability. Accept `impl Trait` in constructors.
- Use `fake` crate for generating realistic test data.

## Property Testing
- Use `proptest` for property-based testing on parsing and validation.
- Define strategies: `prop::string::string_regex("[a-z]+@[a-z]+\\.[a-z]{2,4}")`.
- Use `proptest!` macro for concise property test definitions.
- Test invariants: serialization roundtrips, ordering consistency.

## Benchmarks
- Use `criterion` crate for statistical benchmarks (not built-in `#[bench]`).
- Use `black_box()` to prevent compiler optimization of benchmark code.
- Run benchmarks before and after optimization to measure impact.
- Use `cargo bench` with `-- --save-baseline` for regression tracking.

## CI Pipeline
- Minimum: `cargo fmt --check && cargo clippy -- -D warnings && cargo test`.
- Add `cargo audit` for vulnerability scanning.
- Use `cargo nextest` for parallel test execution and better output.
- Enable `-Z randomize-layout` in nightly CI to catch layout-dependent code.