rust-expert

author	luo-kai
name	rust-expert
description	Expert-level Rust programming. Use when writing Rust code, working with the borrow checker, lifetimes, ownership, traits, async Rust, error handling with Result/Option, cargo, crates, unsafe code, or systems-level Rust. Also use when the user mentions 'borrow checker', 'lifetime', 'ownership', 'cargo', 'trait', 'impl', 'clippy', 'unsafe', 'tokio', or 'Rust compile error'.
license	MIT
metadata	{"author":"luokai0","version":"1.0","category":"coding"}

Rust Expert

You are an expert Rust engineer with deep knowledge of ownership, the type system, async programming, and the Rust ecosystem.

Before Starting

1. Use case — systems programming, CLI, web server, embedded, WASM, library?
2. Async needed? — Tokio, async-std, or sync?
3. Error handling style — library (thiserror) or application (anyhow)?
4. Rust edition — 2021 (default), 2024?
5. Specific problem — borrow checker error, performance, API design?

---

Core Expertise Areas

• Ownership & borrowing: move semantics, borrow rules, lifetime annotations
• Type system: traits, generics, associated types, type inference, newtype pattern
• Error handling: Result, Option, ? operator, thiserror, anyhow, custom errors
• Async Rust: Tokio runtime, async/await, tasks, channels, select!, timeout
• Iterators: Iterator trait, adapters, collect, lazy evaluation, custom iterators
• Cargo: workspace, features, build scripts, profile optimization, publishing
• Unsafe Rust: when to use it, raw pointers, FFI, invariants
• Performance: zero-cost abstractions, profiling, SIMD, memory layout

---

Key Patterns & Code

Ownership & Borrowing Mental Model

// Rule 1: Each value has exactly one owner
let s1 = String::from("hello");
let s2 = s1;           // s1 is MOVED — ownership transferred
// println!("{}", s1); // compile error: s1 moved

// Rule 2: You can have multiple immutable borrows OR one mutable borrow
let mut s = String::from("hello");
let r1 = &s;           // immutable borrow OK
let r2 = &s;           // second immutable borrow OK
// let r3 = &mut s;    // compile error: cannot borrow as mutable while immutably borrowed
println!("{} {}", r1, r2);
let r3 = &mut s;       // OK now — r1 and r2 no longer used
r3.push_str(" world");

// Rule 3: References must be valid (no dangling references)
// Rust guarantees this at compile time via lifetimes

// Clone when you need a copy
let s1 = String::from("hello");
let s2 = s1.clone();   // deep copy — both valid
println!("{} {}", s1, s2);

// Copy types (stack-only types) are copied automatically
let x = 5;
let y = x;             // x is copied, not moved
println!("{} {}", x, y); // both valid

Lifetimes

// Lifetime annotations describe relationships between references
// They don't change how long values live — just tell the compiler

// Function returning reference must specify lifetime
fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() > y.len() { x } else { y }
}

// Struct holding a reference needs lifetime annotation
struct Important<'a> {
    content: &'a str,
}

impl<'a> Important<'a> {
    fn announce(&self, announcement: &str) -> &str {
        println!("Attention: {}", announcement);
        self.content
    }
}

// Lifetime elision rules (compiler infers these common cases)
// 1. Each reference parameter gets its own lifetime
// 2. If only one input lifetime, output gets that lifetime
// 3. If &self or &mut self, output gets self's lifetime
fn first_word(s: &str) -> &str {  // lifetime elided — compiler infers
    let bytes = s.as_bytes();
    for (i, &byte) in bytes.iter().enumerate() {
        if byte == b' ' { return &s[..i]; }
    }
    s
}

// Static lifetime — lives for entire program
const GREETING: &'static str = "Hello, world!";

Traits — The Core Abstraction

use std::fmt;

// Define a trait
trait Animal {
    fn name(&self) -> &str;
    fn sound(&self) -> &str;

    // Default implementation
    fn describe(&self) -> String {
        format!("{} says {}", self.name(), self.sound())
    }
}

// Implement trait
struct Dog { name: String }
struct Cat { name: String }

impl Animal for Dog {
    fn name(&self) -> &str { &self.name }
    fn sound(&self) -> &str { "woof" }
}

impl Animal for Cat {
    fn name(&self) -> &str { &self.name }
    fn sound(&self) -> &str { "meow" }
}

// Trait bounds — generic functions
fn print_animal(animal: &impl Animal) {
    println!("{}", animal.describe());
}

// Equivalent with where clause (cleaner for complex bounds)
fn compare_animals<T, U>(a: &T, b: &U) -> String
where
    T: Animal + fmt::Debug,
    U: Animal + fmt::Debug,
{
    format!("{} vs {}", a.name(), b.name())
}

// Dynamic dispatch with dyn Trait
fn make_sounds(animals: &[Box<dyn Animal>]) {
    for animal in animals {
        println!("{}", animal.sound());
    }
}

// Important standard traits to implement
#[derive(Debug, Clone, PartialEq)]
struct Point {
    x: f64,
    y: f64,
}

impl fmt::Display for Point {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "({}, {})", self.x, self.y)
    }
}

impl std::ops::Add for Point {
    type Output = Point;
    fn add(self, other: Point) -> Point {
        Point { x: self.x + other.x, y: self.y + other.y }
    }
}

Error Handling

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

// Library errors — use thiserror for precise, typed errors
#[derive(Debug, Error)]
pub enum AppError {
    #[error("User {id} not found")]
    NotFound { id: u64 },

    #[error("Invalid email: {email}")]
    InvalidEmail { email: String },

    #[error("Database error: {0}")]
    Database(#[from] sqlx::Error),

    #[error("Network error: {0}")]
    Network(#[from] reqwest::Error),

    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),
}

// Application code — use anyhow for ergonomic error propagation
fn load_config(path: &str) -> Result<Config> {
    let content = std::fs::read_to_string(path)
        .with_context(|| format!("Failed to read config file: {path}"))?;

    let config: Config = serde_json::from_str(&content)
        .context("Failed to parse config as JSON")?;

    ensure!(config.port > 0, "Port must be positive, got {}", config.port);

    Ok(config)
}

// The ? operator — propagates errors up
async fn get_user(id: u64, db: &Pool) -> Result<User, AppError> {
    let user = sqlx::query_as::<_, User>("SELECT * FROM users WHERE id = $1")
        .bind(id as i64)
        .fetch_optional(db)
        .await?;                        // propagates sqlx::Error → AppError::Database

    user.ok_or(AppError::NotFound { id })
}

// Handling errors at call site
fn process() {
    match get_user(42, &db).await {
        Ok(user) => println!("Found: {}", user.name),
        Err(AppError::NotFound { id }) => eprintln!("User {} not found", id),
        Err(AppError::Database(e)) => eprintln!("DB error: {}", e),
        Err(e) => eprintln!("Unexpected error: {}", e),
    }
}

Iterators — Functional Style

let numbers = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

// Chained iterator adapters — lazy, no intermediate allocations
let result: Vec<i32> = numbers
    .iter()
    .filter(|&&x| x % 2 == 0)   // keep even numbers
    .map(|&x| x * x)             // square them
    .take(3)                     // first 3 only
    .collect();                  // materialize into Vec

println!("{:?}", result);  // [4, 16, 36]

// fold (reduce)
let sum: i32 = numbers.iter().sum();
let product: i32 = numbers.iter().product();
let max = numbers.iter().max().unwrap();

// Custom iterator
struct Counter {
    count: u32,
    max: u32,
}

impl Counter {
    fn new(max: u32) -> Counter { Counter { count: 0, max } }
}

impl Iterator for Counter {
    type Item = u32;

    fn next(&mut self) -> Option<u32> {
        if self.count < self.max {
            self.count += 1;
            Some(self.count)
        } else {
            None
        }
    }
}

// Use all iterator adapters on custom iterator
let sum_of_squares: u32 = Counter::new(5)
    .zip(Counter::new(5).skip(1))
    .map(|(a, b)| a * b)
    .filter(|x| x % 3 == 0)
    .sum();

Async Rust with Tokio

use tokio::{
    time::{timeout, Duration, sleep},
    sync::{mpsc, broadcast, Mutex},
    task,
    select,
};
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Spawn concurrent tasks
    let handle1 = task::spawn(async { fetch_data("url1").await });
    let handle2 = task::spawn(async { fetch_data("url2").await });

    let (result1, result2) = tokio::join!(handle1, handle2);

    // Timeout
    match timeout(Duration::from_secs(5), slow_operation()).await {
        Ok(result) => println!("Got result: {:?}", result),
        Err(_) => println!("Timed out after 5s"),
    }

    // Channel communication
    let (tx, mut rx) = mpsc::channel::<String>(32);

    let producer = task::spawn(async move {
        for i in 0..10 {
            tx.send(format!("message {}", i)).await.unwrap();
            sleep(Duration::from_millis(100)).await;
        }
    });

    let consumer = task::spawn(async move {
        while let Some(msg) = rx.recv().await {
            println!("Received: {}", msg);
        }
    });

    tokio::try_join!(producer, consumer)?;

    Ok(())
}

// select! — wait for multiple async operations
async fn race_operations() {
    let mut interval = tokio::time::interval(Duration::from_secs(1));
    let (tx, mut rx) = mpsc::channel::<()>(1);

    loop {
        select! {
            _ = interval.tick() => {
                println!("Tick");
            }
            Some(_) = rx.recv() => {
                println!("Received signal, stopping");
                break;
            }
        }
    }
}

// Shared state with Arc<Mutex<T>>
async fn shared_counter() {
    let counter = Arc::new(Mutex::new(0u64));
    let mut handles = vec![];

    for _ in 0..10 {
        let counter = Arc::clone(&counter);
        handles.push(task::spawn(async move {
            let mut lock = counter.lock().await;
            *lock += 1;
        }));
    }

    for handle in handles {
        handle.await.unwrap();
    }

    println!("Final count: {}", *counter.lock().await);
}

Builder Pattern

#[derive(Debug)]
pub struct Request {
    url: String,
    method: String,
    headers: HashMap<String, String>,
    body: Option<Vec<u8>>,
    timeout: Duration,
}

pub struct RequestBuilder {
    url: String,
    method: String,
    headers: HashMap<String, String>,
    body: Option<Vec<u8>>,
    timeout: Duration,
}

#[derive(Debug, thiserror::Error)]
pub enum BuildError {
    #[error("URL is required")]
    MissingUrl,
    #[error("Invalid URL: {0}")]
    InvalidUrl(String),
}

impl RequestBuilder {
    pub fn new(url: impl Into<String>) -> Self {
        RequestBuilder {
            url: url.into(),
            method: "GET".to_string(),
            headers: HashMap::new(),
            body: None,
            timeout: Duration::from_secs(30),
        }
    }

    pub fn method(mut self, method: impl Into<String>) -> Self {
        self.method = method.into();
        self
    }

    pub fn header(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.headers.insert(key.into(), value.into());
        self
    }

    pub fn body(mut self, body: impl Into<Vec<u8>>) -> Self {
        self.body = Some(body.into());
        self
    }

    pub fn timeout(mut self, timeout: Duration) -> Self {
        self.timeout = timeout;
        self
    }

    pub fn build(self) -> Result<Request, BuildError> {
        if self.url.is_empty() {
            return Err(BuildError::MissingUrl);
        }
        Ok(Request {
            url: self.url,
            method: self.method,
            headers: self.headers,
            body: self.body,
            timeout: self.timeout,
        })
    }
}

// Usage — fluent API
let request = RequestBuilder::new("https://api.example.com/users")
    .method("POST")
    .header("Content-Type", "application/json")
    .header("Authorization", "Bearer token123")
    .body(serde_json::to_vec(&payload).unwrap())
    .timeout(Duration::from_secs(10))
    .build()?;

Cargo.toml Best Practices

[package]
name = "my-app"
version = "0.1.0"
edition = "2021"
description = "My awesome app"
license = "MIT"
repository = "https://github.com/user/my-app"

[dependencies]
# Async runtime
tokio = { version = "1", features = ["full"] }

# Error handling
thiserror = "1"
anyhow = "1"

# Serialization
serde = { version = "1", features = ["derive"] }
serde_json = "1"

# HTTP client
reqwest = { version = "0.12", features = ["json", "rustls-tls"], default-features = false }

# Database
sqlx = { version = "0.7", features = ["postgres", "runtime-tokio-rustls", "migrate"] }

# Logging
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

[dev-dependencies]
tokio-test = "0.4"
mockall = "0.12"

# Release profile — optimize for size and speed
[profile.release]
opt-level = 3
lto = true           # link-time optimization
codegen-units = 1    # single codegen unit for better optimization
strip = true         # strip debug symbols
panic = "abort"      # smaller binary, faster

---

Best Practices

• Run cargo clippy -- -D warnings — treat all clippy warnings as errors
• Run cargo fmt for consistent formatting
• Use thiserror for library errors, anyhow for application errors
• Prefer returning Result over panicking — use ? to propagate
• Use #[must_use] on Result-returning functions
• Prefer iterators over manual loops — they are often faster and clearer
• Use Arc<Mutex<T>> for shared mutable state across threads
• Always specify default-features = false for deps and opt-in to only what you need
• Write documentation tests — they serve as examples AND are verified by cargo test

---

Common Pitfalls

Pitfall	Problem	Fix
Fighting the borrow checker	Trying to hold refs across await points	Use owned types or Arc for async
Cloning everywhere	Performance regression	Profile first, use references where possible
unwrap() in production code	Panics on None or Err	Use ? operator or match
Blocking in async	Starves the Tokio executor	Use tokio::task::spawn_blocking
Ignoring clippy warnings	Misses idiomatic improvements	Run clippy --all-targets --all-features
Large futures	Stack overflow from deep async chains	Box large futures: Box::pin(async { ... })
String vs str confusion	Unnecessary allocations	Accept &str in functions, return String
Not using cargo workspaces	Duplicate dependencies across crates	Use workspaces for multi-crate projects

---

Related Skills

• wasm-expert: For compiling Rust to WebAssembly
• cli-tooling-expert: For building Rust CLIs
• embedded-expert: For Rust on embedded systems
• performance-optimization: For Rust performance tuning
• algorithms-expert: For implementing algorithms in Rust
• concurrency-expert: For advanced async and threading patterns