---

name: rust-patterns description: Rust backend patterns including Axum, Tokio, error handling with anyhow/thiserror, and tracing. agents: [rex] triggers: [rust, axum, tokio, cargo, clippy]

Rust Backend Patterns

Production Rust patterns for backend services using Axum, Tokio, and the broader Rust ecosystem.

Core Stack

Context7 Library IDs

Query these libraries for current best practices:

• Tokio: /websites/rs_tokio_tokio
• Serde: /websites/serde_rs
• Anyhow: /dtolnay/anyhow
• Thiserror: /dtolnay/thiserror
• Tracing: /tokio-rs/tracing
• Clippy: /rust-lang/rust-clippy
• Axum: /tokio-rs/axum

Execution Rules

1. Clippy pedantic always. Run with -W clippy::pedantic
2. No unwrap in production. Use ? or proper error handling
3. Type safety. Leverage Rust's type system fully
4. Documentation. Doc comments on all public items
5. Tests. Unit tests alongside code, integration tests in tests/

Error Handling Patterns

Application Errors with anyhow

Copyuse anyhow::{Context, Result};

fn do_thing() -> Result<()> {
    let data = fetch_data()
        .context("failed to fetch data")?;
    process(data)
        .context("failed to process")?;
    Ok(())
}

Library Errors with thiserror

Copyuse thiserror::Error;

#[derive(Error, Debug)]
pub enum ServiceError {
    #[error("user not found: {id}")]
    UserNotFound { id: String },
    
    #[error("validation failed: {0}")]
    Validation(String),
    
    #[error(transparent)]
    Database(#[from] sqlx::Error),
}

Async Patterns with Tokio

Basic Async

Copyuse tokio::time::{sleep, Duration};

async fn poll_until_ready() -> Result<Data> {
    loop {
        if let Some(data) = check_status().await? {
            return Ok(data);
        }
        sleep(Duration::from_secs(1)).await;
    }
}

Concurrent Operations

Copyuse tokio::try_join;

async fn fetch_all() -> Result<(User, Posts)> {
    let (user, posts) = try_join!(
        fetch_user(),
        fetch_posts()
    )?;
    Ok((user, posts))
}

Channels for Coordination

Copyuse tokio::sync::mpsc;

async fn worker(mut rx: mpsc::Receiver<Job>) {
    while let Some(job) = rx.recv().await {
        process(job).await;
    }
}

Structured Logging with tracing

Copyuse tracing::{info, warn, instrument, span, Level};

#[instrument(skip(secret))]
fn process_request(id: &str, secret: &str) {
    info!(request_id = %id, "processing request");
}

// Manual spans
fn complex_operation() {
    let span = span!(Level::INFO, "complex_op");
    let _enter = span.enter();
    
    info!("starting operation");
    // ... work ...
    info!("completed operation");
}

Axum Web Framework

Basic Route Setup

Copyuse axum::{Router, routing::{get, post}, extract::State, Json};

async fn create_app(db: Database) -> Router {
    Router::new()
        .route("/health", get(health_check))
        .route("/users", post(create_user))
        .with_state(AppState { db })
}

async fn health_check() -> &'static str {
    "ok"
}

async fn create_user(
    State(state): State<AppState>,
    Json(req): Json<CreateUserRequest>,
) -> Result<Json<User>, AppError> {
    let user = state.db.create_user(req).await?;
    Ok(Json(user))
}

Custom Error Type for Axum

Copyuse axum::{response::IntoResponse, http::StatusCode};

struct AppError(anyhow::Error);

impl IntoResponse for AppError {
    fn into_response(self) -> axum::response::Response {
        (
            StatusCode::INTERNAL_SERVER_ERROR,
            format!("Something went wrong: {}", self.0),
        ).into_response()
    }
}

impl<E> From<E> for AppError where E: Into<anyhow::Error> {
    fn from(err: E) -> Self {
        Self(err.into())
    }
}

Validation Commands

Copycargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings -W clippy::pedantic
cargo test --workspace --all-features
cargo build --release

Guidelines

• Use tracing for logging, never println!
• Handle errors with anyhow context
• Keep functions small and focused
• Write doc comments on all public items
• Prefer ? over explicit match for error propagation
• Use #[must_use] on functions returning values