Rust Domain Skill

Purpose

Provide expert-level guidance on Rust development, including the ownership system, async programming with Tokio, web framework patterns (Axum, Actix), error handling with thiserror/anyhow, and production-grade systems programming.

Key Patterns

1. Ownership and Borrowing

// Ownership rules:
// 1. Each value has exactly one owner
// 2. When the owner goes out of scope, the value is dropped
// 3. You can have EITHER one mutable reference OR any number of immutable references

// Prefer borrowing over cloning
fn process_name(name: &str) -> String {
    // Takes a reference -- no ownership transfer
    name.to_uppercase()
}

// Use lifetimes when the compiler needs help
struct Config<'a> {
    database_url: &'a str,
    app_name: &'a str,
}

impl<'a> Config<'a> {
    fn connection_string(&self) -> String {
        format!("{}?app={}", self.database_url, self.app_name)
    }
}

// Interior mutability for shared mutable state
use std::sync::{Arc, RwLock};

#[derive(Clone)]
struct AppState {
    cache: Arc<RwLock<HashMap<String, CachedItem>>>,
    db: Arc<Pool<Postgres>>,
}

impl AppState {
    fn get_cached(&self, key: &str) -> Option<CachedItem> {
        self.cache.read().unwrap().get(key).cloned()
    }

    fn set_cached(&self, key: String, item: CachedItem) {
        self.cache.write().unwrap().insert(key, item);
    }
}

2. Error Handling

use thiserror::Error;

// Domain-specific errors with thiserror
#[derive(Error, Debug)]
pub enum AppError {
    #[error("resource not found: {resource} with id {id}")]
    NotFound { resource: String, id: String },

    #[error("unauthorized: {0}")]
    Unauthorized(String),

    #[error("validation failed: {0}")]
    Validation(String),

    #[error("database error")]
    Database(#[from] sqlx::Error),

    #[error("external service error")]
    ExternalService(#[from] reqwest::Error),

    #[error(transparent)]
    Internal(#[from] anyhow::Error),
}

// Map to HTTP responses (Axum)
impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, code, message) = match &self {
            AppError::NotFound { .. } => (StatusCode::NOT_FOUND, "NOT_FOUND", self.to_string()),
            AppError::Unauthorized(msg) => (StatusCode::UNAUTHORIZED, "UNAUTHORIZED", msg.clone()),
            AppError::Validation(msg) => (StatusCode::UNPROCESSABLE_ENTITY, "VALIDATION", msg.clone()),
            AppError::Database(_) => {
                tracing::error!(error = ?self, "database error");
                (StatusCode::INTERNAL_SERVER_ERROR, "INTERNAL", "internal error".into())
            }
            AppError::ExternalService(_) => {
                tracing::error!(error = ?self, "external service error");
                (StatusCode::BAD_GATEWAY, "BAD_GATEWAY", "upstream error".into())
            }
            AppError::Internal(_) => {
                tracing::error!(error = ?self, "internal error");
                (StatusCode::INTERNAL_SERVER_ERROR, "INTERNAL", "internal error".into())
            }
        };

        (status, Json(json!({ "error": { "code": code, "message": message } }))).into_response()
    }
}

// Use Result<T, AppError> throughout
type AppResult<T> = Result<T, AppError>;

3. Axum Web Framework

use axum::{
    extract::{Path, Query, State, Json},
    http::StatusCode,
    middleware,
    routing::{get, post, delete},
    Router,
};
use tower::ServiceBuilder;
use tower_http::{
    cors::CorsLayer,
    trace::TraceLayer,
    compression::CompressionLayer,
    timeout::TimeoutLayer,
};

pub fn create_router(state: AppState) -> Router {
    let api = Router::new()
        .route("/users", get(list_users).post(create_user))
        .route("/users/{id}", get(get_user).delete(delete_user))
        .layer(middleware::from_fn_with_state(state.clone(), auth_middleware));

    Router::new()
        .nest("/api/v1", api)
        .route("/health", get(health_check))
        .layer(
            ServiceBuilder::new()
                .layer(TraceLayer::new_for_http())
                .layer(CompressionLayer::new())
                .layer(TimeoutLayer::new(Duration::from_secs(30)))
                .layer(CorsLayer::permissive()),
        )
        .with_state(state)
}

// Handler with extractors
async fn list_users(
    State(state): State<AppState>,
    Query(params): Query<ListUsersParams>,
) -> AppResult<Json<PaginatedResponse<UserResponse>>> {
    let users = state.user_service.list(params.into()).await?;
    Ok(Json(users))
}

async fn create_user(
    State(state): State<AppState>,
    Json(body): Json<CreateUserRequest>,
) -> AppResult<(StatusCode, Json<UserResponse>)> {
    let user = state.user_service.create(body).await?;
    Ok((StatusCode::CREATED, Json(user)))
}

// Middleware
async fn auth_middleware(
    State(state): State<AppState>,
    mut req: Request,
    next: Next,
) -> Result<Response, AppError> {
    let token = req
        .headers()
        .get("Authorization")
        .and_then(|h| h.to_str().ok())
        .and_then(|h| h.strip_prefix("Bearer "))
        .ok_or_else(|| AppError::Unauthorized("missing token".into()))?;

    let claims = state.auth_service.verify(token).await?;
    req.extensions_mut().insert(claims);
    Ok(next.run(req).await)
}

4. Async with Tokio

use tokio::sync::{mpsc, Semaphore};
use tokio::time::{timeout, Duration};

// Bounded channel for backpressure
async fn process_events(mut rx: mpsc::Receiver<Event>) {
    while let Some(event) = rx.recv().await {
        if let Err(e) = handle_event(&event).await {
            tracing::error!(error = ?e, event = ?event, "failed to handle event");
        }
    }
}

// Semaphore for concurrency limiting
async fn fetch_all(urls: Vec<String>, max_concurrent: usize) -> Vec<Result<String, reqwest::Error>> {
    let semaphore = Arc::new(Semaphore::new(max_concurrent));
    let client = reqwest::Client::new();

    let tasks: Vec<_> = urls
        .into_iter()
        .map(|url| {
            let sem = semaphore.clone();
            let client = client.clone();
            tokio::spawn(async move {
                let _permit = sem.acquire().await.unwrap();
                client.get(&url).send().await?.text().await
            })
        })
        .collect();

    let mut results = Vec::with_capacity(tasks.len());
    for task in tasks {
        results.push(task.await.unwrap());
    }
    results
}

// Graceful shutdown
async fn run_server(listener: TcpListener, app: Router) {
    let (shutdown_tx, shutdown_rx) = tokio::sync::oneshot::channel::<()>();

    tokio::spawn(async move {
        let mut sigterm = tokio::signal::unix::signal(SignalKind::terminate()).unwrap();
        tokio::select! {
            _ = tokio::signal::ctrl_c() => {}
            _ = sigterm.recv() => {}
        }
        let _ = shutdown_tx.send(());
    });

    axum::serve(listener, app)
        .with_graceful_shutdown(async { shutdown_rx.await.ok(); })
        .await
        .unwrap();
}

5. Database with SQLx

use sqlx::{PgPool, FromRow, query_as};

#[derive(FromRow)]
struct User {
    id: Uuid,
    email: String,
    name: String,
    created_at: chrono::DateTime<chrono::Utc>,
}

// Compile-time checked queries
async fn get_user(pool: &PgPool, id: Uuid) -> AppResult<User> {
    sqlx::query_as!(
        User,
        r#"SELECT id, email, name, created_at FROM users WHERE id = $1"#,
        id
    )
    .fetch_optional(pool)
    .await?
    .ok_or_else(|| AppError::NotFound {
        resource: "user".into(),
        id: id.to_string(),
    })
}

// Transactions
async fn transfer_credits(pool: &PgPool, from: Uuid, to: Uuid, amount: i64) -> AppResult<()> {
    let mut tx = pool.begin().await?;

    sqlx::query!("UPDATE accounts SET balance = balance - $1 WHERE id = $2 AND balance >= $1", amount, from)
        .execute(&mut *tx)
        .await?;

    sqlx::query!("UPDATE accounts SET balance = balance + $1 WHERE id = $2", amount, to)
        .execute(&mut *tx)
        .await?;

    tx.commit().await?;
    Ok(())
}

Best Practices

1. Use clippy with #![deny(clippy::all)] in CI
2. Prefer &str over String in function parameters
3. Use thiserror for library errors, anyhow for application errors
4. Use tracing instead of log for structured, async-aware logging
5. Prefer Arc<T> over Rc<T> unless single-threaded is guaranteed
6. Use tokio::spawn for CPU-bound work in spawn_blocking
7. Prefer iterators over manual loops -- they often optimize better
8. Use #[derive] macros extensively: Debug, Clone, PartialEq, Serialize, Deserialize
9. Test with #[tokio::test] for async tests
10. Use cargo deny to audit dependencies for vulnerabilities

Common Pitfalls

Pitfall	Impact	Fix
Holding MutexGuard across .await	Deadlock	Scope the lock, clone data out
unwrap() in production code	Panics	Use ? operator, expect() with context
Cloning everything to satisfy borrow checker	Performance degradation	Restructure code, use Arc, references
Blocking the Tokio runtime	Async task starvation	Use tokio::task::spawn_blocking
Not setting #[tokio::main(flavor = "multi_thread")]	Single-threaded runtime	Explicitly configure runtime
Unbounded channels	Memory exhaustion	Use mpsc::channel(capacity)