Yzavyas Claude 1337 Build Rust

Rust Production Patterns

Production-grade patterns that separate competent from exceptional Rust developers.

Philosophy

1. Make illegal states unrepresentable — use types to eliminate bugs (Minsky 2010)
2. Parse, don't validate — transform unstructured data into typed structures (King 2019)
3. Zero-cost abstractions — high-level code that compiles to optimal machine code (Stroustrup 2012)
4. Explicit over implicit — no hidden allocations, no surprise behavior (Rust design principle)
5. Design away lifetime complexity — if fighting the borrow checker, reconsider data model (community convention)
6. Clone consciously — every .clone() is a decision about allocation (community convention)
7. Trust but verify safety — Rust prevents data races, not deadlocks (language guarantee)

Decision Frameworks

String Ownership

Heuristic from Steve Klabnik (Rust core team, 12+ years experience): "Following this rule will get you through 95% of situations."

Trait Objects vs Generics

Rule: Default to generics. Use dyn for heterogeneous collections or plugin systems.

Error Handling Selection

Writing a library?
├── YES → thiserror (callers match on variants)
└── NO (application) → Need pretty diagnostics?
    ├── YES → color-eyre (CLI) or miette (source snippets)
    └── NO → anyhow

Async vs Threads

Guideline: Keep work between .await points brief (microseconds to tens of milliseconds). Tokio uses cooperative scheduling with budget-based yielding since v0.2.14 — tasks that exceed budget get nudged to yield, but long-running sync work still starves the runtime (tokio preemption blog).

Production Gotchas

Well-established patterns from tokio documentation and production experience.

Blocking in Async

• Trap: Sync operations inside async tasks starve runtime (tokio shared-state tutorial)
• Detection: tokio-console shows tasks not yielding (see "task liveliness" metrics)
• Fix: spawn_blocking() for CPU work; async alternatives for I/O

// Wrong
async fn bad() {
    std::thread::sleep(Duration::from_secs(2)); // Blocks worker
}

// Correct
async fn good() {
    tokio::task::spawn_blocking(|| heavy_computation()).await.unwrap();
}

Mutex Across Await

• Trap: std::sync::Mutex guard held across .await deadlocks (tokio shared-state tutorial)
• Detection: Deadlock under load; compiles fine (Clippy lint await_holding_lock catches this)
• Fix: Drop guard before await, or tokio::sync::Mutex

// Deadlock risk
async fn bad(mutex: Arc<std::sync::Mutex<i32>>) {
    let guard = mutex.lock().unwrap();
    some_async_op().await; // Guard held!
}

// Safe: explicit drop
async fn good(mutex: Arc<std::sync::Mutex<i32>>) {
    {
        let mut guard = mutex.lock().unwrap();
        *guard += 1;
    } // Dropped before await
    some_async_op().await;
}

Cancellation Safety

• Trap: Futures dropped mid-operation leave invalid state (tokio docs: cancel-safety)
• Detection: Check API docs for "Cancel safety" section; read is safe, read_line is NOT
• Fix: Don't hold invalid state across await; use CancellationToken (tokio-util)
• Checkpoint: Before using select! or timeout, verify each branch's cancellation safety in docs

Feature Flag Unification

• Trap: Cargo unifies features globally; non-additive features break (Cargo reference: features)
• Detection: cargo tree --edges features (Cargo book)
• Fix: Features must be additive; use default-features = false
• Checkpoint: Before adding feature-gated dependencies, run cargo tree -e features -i <crate> to check resolution

Hidden Allocations

• Trap: clone(), to_string(), format!(), Vec growth (community pattern)
• Detection: DHAT, cargo-flamegraph, Clippy perf lints
• Fix: with_capacity(), SmallVec, Cow, shrink_to_fit()

Reference Cycles

• Trap: Rc<RefCell<T>> cycles leak memory (Rust Book ch15)
• Fix: Weak<T> for back-edges; consider arenas

Obsolete Patterns

Note: async-trait still needed for dyn Trait with async methods.

Type Design Patterns

Newtype Pattern

Compile-time type safety for IDs:

struct UserId(u64);
struct OrderId(u64);

fn process_user(id: UserId) { /* ... */ }
// process_user(OrderId(1)); // Won't compile!

Builder Pattern

struct ConfigBuilder {
    required_field: Option<String>,
    optional_field: Option<i32>,
}

impl ConfigBuilder {
    fn required_field(mut self, val: String) -> Self {
        self.required_field = Some(val);
        self
    }

    fn build(self) -> Result<Config, BuilderError> {
        Ok(Config {
            required_field: self.required_field.ok_or(BuilderError::MissingField)?,
            optional_field: self.optional_field.unwrap_or_default(),
        })
    }
}

Use typed-builder crate in production.

Typestate Pattern

Compile-time state machine enforcement:

struct Connection<State> { /* ... */ _state: PhantomData<State> }
struct Disconnected;
struct Connected;
struct Authenticated;

impl Connection<Disconnected> {
    fn connect(self) -> Connection<Connected> { /* ... */ }
}

impl Connection<Connected> {
    fn authenticate(self, creds: &str) -> Connection<Authenticated> { /* ... */ }
}

impl Connection<Authenticated> {
    fn query(&self, sql: &str) -> Result<Data, Error> { /* ... */ }
}
// Can't call query() on unauthenticated connection - won't compile

When to use: Required state transitions, protocol implementations.

Enums Over Booleans

// Bad
fn validate(data: &str, strict: bool) { /* ... */ }

// Good
enum Validation { Strict, Lenient }
fn validate(data: &str, mode: Validation) { /* ... */ }

Error Handling

Library Errors — thiserror

#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error("invalid input: {0}")]
    InvalidInput(String),
    #[error("network error")]
    Network(#[from] std::io::Error),
    #[error(transparent)]
    Other(#[from] anyhow::Error),
}

pub type Result<T> = std::result::Result<T, Error>;

Application Errors — anyhow

use anyhow::{Context, Result, bail, ensure};

fn process() -> Result<()> {
    let data = read_file()
        .with_context(|| format!("failed to read config"))?;

    ensure!(!data.is_empty(), "config file is empty");

    if invalid(&data) {
        bail!("invalid configuration format");
    }
    Ok(())
}

Rules:

• Never .unwrap() in library code
• Never .expect() without useful message

Production Patterns

Defensive Slice Matching

// Anti-pattern: decoupled check
if !users.is_empty() { let user = users[0]; }

// Better: coupled via match
match users.as_slice() {
    [] => handle_empty(),
    [single] => handle_one(single),
    [first, ..] => handle_multiple(first),
}

Simplify Lifetimes Through Architecture

Insight: "Data lives forever or for duration of event loop."

• Use Copy IDs instead of references
• Pass references top-down each frame
• Trade-off: Lookup indirection vs lifetime elimination

Temporary Mutability Scoping

let sorted = {
    let mut temp = get_data();
    temp.sort();
    temp  // Immutable from here
};

Extension Traits

• Suffix with Ext (RFC 445)
• Export in prelude for glob import

Specialized Domains

Load reference based on project context:

Anti-Patterns

Quick Reference

Commands

cargo clippy -- -W clippy::pedantic  # Lints
cargo nextest run   # Faster tests    |  cargo deny check    # Deps
cargo tree --edges features          # Feature resolution
cargo bloat --release                # Binary size

Common Crates

Converted and distributed by TomeVault — claim your Tome and manage your conversions.