# Rust Systems Programming Patterns

## Description

A comprehensive guide to production Rust patterns for 2026. Covers ownership and borrowing mental models, error handling with thiserror/anyhow, async concurrency with Tokio, web services with Axum, database access (SQLx, Diesel, SeaORM), CLI development, WebAssembly, and Python bindings via PyO3. Targets Rust Edition 2024 (1.85.0+).

## Usage

Install this skill to get production-ready Rust patterns including:
- Ownership, borrowing, and lifetime rules with concrete mental models
- thiserror vs anyhow selection guide for libraries vs applications
- Tokio runtime patterns: spawn, select!, streams
- Axum web server: routing, extractors, middleware, shared state
- Concurrency primitives: Arc, Mutex, RwLock, channels, Rayon

When working on Rust projects, this skill provides context for:
- Deciding when to clone vs borrow vs move
- Structuring async code to avoid blocking the event loop
- Choosing between database libraries based on project needs
- Building CLI tools with Clap v4 derive API
- Creating Python extension modules with PyO3

## Key Patterns

### Ownership Mental Model

Think of ownership like a title deed:
- Move (`let y = x`): You transfer the deed. `x` is no longer valid.
- Immutable borrow (`&T`): Multiple readers simultaneously, no modifications.
- Mutable borrow (`&mut T`): One exclusive borrower who can modify. No others inside.

```rust
// Quick pattern reference
fn risky() -> Result<T, E> {
    let x = operation()?;  // ? operator: early return on error
    Ok(x)
}

// Shared mutable state across threads
let data = Arc::new(Mutex::new(vec![]));
let clone = Arc::clone(&data);
tokio::spawn(async move { clone.lock().unwrap().push(1); });
```

### Error Handling: thiserror vs anyhow

Use `thiserror` for libraries (callers need matchable error variants):

```rust
use thiserror::Error;

#[derive(Error, Debug)]
pub enum MyError {
    #[error("file not found: {0}")]
    FileNotFound(String),
    #[error("io error: {0}")]
    IoError(#[from] io::Error),  // auto-converts from io::Error
}
```

Use `anyhow` for applications (add context to error chains):

```rust
use anyhow::{Result, Context};

fn main() -> Result<()> {
    let data = std::fs::read_to_string("user.json")
        .context("could not read user.json")?;
    Ok(())
}
```

### Tokio Async Patterns

```rust
// Multi-threaded runtime
#[tokio::main(flavor = "multi_thread", worker_threads = 4)]
async fn main() { ... }

// Race futures: select! picks the first to complete
let winner = tokio::select! {
    result = slow_future() => result,
    result = fast_future() => result,
    _ = tokio::time::sleep(Duration::from_secs(5)) => "timeout",
};

// Blocking code inside async: use spawn_blocking
let data = tokio::task::spawn_blocking(|| {
    std::fs::read_to_string("file.txt")
}).await.unwrap();
```

Anti-pattern: blocking sync I/O inside `async fn`. Use `tokio::fs` instead of `std::fs`.

### Axum Web Server

```rust
use axum::{Router, routing::{get, post}, Json, http::StatusCode};
use std::sync::Arc;

#[derive(Clone)]
struct AppState { db_url: String }

async fn create_user(Json(user): Json<User>) -> (StatusCode, Json<User>) {
    (StatusCode::CREATED, Json(user))
}

#[tokio::main]
async fn main() {
    let state = Arc::new(AppState { db_url: "postgres://...".into() });
    let app = Router::new()
        .route("/users", post(create_user))
        .with_state(state);
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}
```

### Concurrency Primitives

```rust
// Arc<Mutex<T>>: shared mutable state across threads
let counter = Arc::new(Mutex::new(0));
for _ in 0..10 {
    let c = Arc::clone(&counter);
    thread::spawn(move || { *c.lock().unwrap() += 1; });
}

// RwLock: multiple readers OR one writer
let data = Arc::new(RwLock::new(vec!["a", "b"]));
let read = data.read().unwrap();   // shared read
let write = data.write().unwrap(); // exclusive write

// Rayon: parallel iterators (automatic work-stealing)
use rayon::prelude::*;
let sum: u64 = (1..=1_000_000).collect::<Vec<_>>().par_iter().sum();
```

Prefer channels over Arc<Mutex> for message-passing patterns.

### SQLx: Compile-Time Checked SQL

```rust
use sqlx::PgPool;

let pool = PgPool::connect("postgres://user:pass@localhost/db").await?;
let users: Vec<(i32, String)> = sqlx::query_as(
    "SELECT id, name FROM users WHERE age > $1"
).bind(18).fetch_all(&pool).await?;
```

Database selection: `sqlx` for raw SQL with compile-time checks, `diesel` for type-safe query builder (sync), `sea-orm` for full async ORM.

### Clap v4 CLI (Derive API)

```rust
use clap::{Parser, Subcommand};

#[derive(Parser)]
#[command(name = "myapp", about = "My CLI tool")]
struct Cli {
    #[arg(short, long)] verbose: bool,
    #[command(subcommand)] command: Commands,
}

#[derive(Subcommand)]
enum Commands {
    Process { #[arg(short, long)] format: String },
    Download { url: String },
}
```

### PyO3: Python Bindings

```rust
use pyo3::prelude::*;

#[pymodule]
fn mymodule(py: Python, m: &PyModule) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(fast_compute, m)?)?;
    Ok(())
}

#[pyfunction]
fn fast_compute(data: Vec<f64>) -> f64 {
    data.iter().sum()
}
// Build with: maturin develop --release
// Use from Python: import mymodule; result = mymodule.fast_compute([1.0, 2.0])
```

### Rust 2024 Edition

```rust
// Async traits work natively (no async_trait crate needed)
pub trait Fetcher {
    async fn fetch(&self, url: &str) -> Result<String>;
}

// Let chains: cleaner nested conditions
if let Some(x) = get_value()
    && x > 0
    && let y = x * 2
    && y < 100
{
    println!("All conditions met: {}", y);
}
```

### Anti-Patterns to Avoid

| Anti-Pattern | Better Approach |
|---|---|
| Over-cloning to bypass borrow checker | Use references &T instead |
| Arc<Mutex<T>> everywhere | Single owner + mutable ref, or channels |
| .unwrap() in library code | Return Result<T, E> |
| Sync I/O in async functions | Use tokio::fs, spawn_blocking |

## Tools & References

- [The Rust Book](https://doc.rust-lang.org/book/)
- [Tokio Tutorial](https://tokio.rs/tokio/tutorial)
- [Axum Docs](https://docs.rs/axum/latest/axum/)
- [PyO3 Docs](https://pyo3.rs/)
- `cargo add tokio --features full` - async runtime
- `cargo add axum serde serde_json` - web + serialization
- `cargo add thiserror anyhow` - error handling

---
*Published by [MidOS](https://midos.dev) — MCP Community Library*