rust

Rust Patterns

Reference for Rust-specific patterns, ownership model, and type-driven design.

Iron Law

MAKE ILLEGAL STATES UNREPRESENTABLE [15][2, C-VALIDATE]

Encode invariants in the type system. If a function can fail, return Result. If a value might be absent, return Option. If a state transition is invalid, make it uncompilable. Runtime checks are a fallback, not a strategy.

When This Skill Activates

• Working with Rust codebases
• Designing type-safe APIs
• Managing ownership and borrowing
• Implementing error handling
• Writing concurrent code

---

Ownership & Borrowing [1, Ch.4][11]

Prefer borrowing over cloning — accept &str not String, &[T] not &Vec<T> [2, C-BORROW]. The borrow checker enforces the Stacked Borrows aliasing model at compile time [6][11]. Lifetime annotations required when elision rules can't resolve ambiguity [1, Ch.10].

// BAD: fn process(data: String) — takes ownership unnecessarily
fn process(data: &str) -> usize { data.len() } // GOOD: borrow [2, C-BORROW]

See references/ownership.md for elision rules, interior mutability, Cow, and Pin.

---

Error Handling [8][9][16]

Use thiserror for libraries (typed, matchable variants); anyhow for applications (ergonomic propagation). Never use Box<dyn Error> in library APIs [8][16].

#[derive(thiserror::Error, Debug)]
pub enum AppError {
    #[error("IO error reading {path}")]
    Io { path: String, #[source] source: io::Error },
    #[error("{entity} with id {id} not found")]
    NotFound { entity: String, id: String },
}
// ? operator propagates with source context [1, Ch.9]
fn read_config(path: &str) -> Result<Config, AppError> {
    let raw = fs::read_to_string(path).map_err(|e| AppError::Io { path: path.into(), source: e })?;
    toml::from_str(&raw).map_err(|e| AppError::Parse { source: e })
}

---

Type System

Newtype Pattern [2, C-NEWTYPE][15]

struct UserId(String);   struct OrderId(String);
// Can't accidentally swap — compiler enforces [15]
fn get_order(user_id: &UserId, order_id: &OrderId) -> Result<Order, AppError> { todo!() }