/rust

name: rust
description: Use when writing Rust or resolving borrow-checker, lifetime, and trait errors. Covers ownership models, error handling with thiserror and anyhow, async with Tokio, and safe abstractions over unsafe code.
metadata:
  category: languages
  version: 1.0.0
  tags: [rust, ownership, lifetimes, tokio, error-handling]

Rust

Purpose

Write Rust that satisfies the borrow checker by design rather than by fighting it. Ownership is a modeling decision made before the code is written, not a compiler obstacle discovered afterward.

When to Use

• Building Rust libraries, services, or CLI tools.
• Resolving lifetime, borrow, or trait-bound errors.
• Designing error types for a library versus an application.
• Writing async Rust with Tokio.
• Auditing or minimizing `unsafe` blocks.

Capabilities

• Ownership and borrowing design: when to clone, when to borrow, when to use `Rc`/`Arc`.
• Error modeling: `thiserror` for libraries, `anyhow` for binaries.
• Trait design, generic bounds, and trait objects.
• Async runtimes, `Send`/`Sync` bounds, and cancellation semantics.
• Safe encapsulation of `unsafe`, with documented invariants.

Inputs

• Crate or module source.
• Edition and MSRV.
• Whether the artifact is a library (stable public API) or a binary.

Outputs

• Code that compiles with zero warnings under `clippy::pedantic` (or a documented allow-list).
• Explicit error enums with `#[from]` conversions.
• Tests including compile-fail tests for API misuse where warranted.

Workflow

1. **Model ownership first** — Decide who owns each value and how long it lives before writing the signature. 2. **Design the error type** — A library's error enum is public API. Enumerate failure modes explicitly. 3. **Implement** — Start with owned values and clones. Optimize to borrows only where profiling or ergonomics justify it. 4. **Constrain generics late** — Write it concrete, then generalize if a second caller appears. 5. **Gate** — `cargo clippy -- -D warnings`, `cargo fmt --check`, `cargo test`, `cargo deny check`.

Best Practices

• A `clone()` in non-hot-path code is not a defect. Premature borrow optimization produces unreadable lifetimes.
• Libraries return concrete error enums; binaries use `anyhow::Result` and add context at each layer.
• Never `unwrap()` outside tests and `main`. Use `expect("invariant: ...")` where the invariant is genuinely proven.
• Prefer `impl Trait` in argument position for simple bounds; use named generics when the caller must choose the type.
• Every `unsafe` block gets a `// SAFETY:` comment stating the invariant that makes it sound.
• Use `#[non_exhaustive]` on public enums you may extend.

Examples

**Library error type:**

use thiserror::Error;

#[derive(Debug, Error)]
#[non_exhaustive]
pub enum StoreError {
    #[error("key not found: {0}")]
    NotFound(String),

    #[error("storage backend unavailable")]
    Unavailable(#[source] std::io::Error),

    #[error("value for {key} exceeds {limit} bytes")]
    TooLarge { key: String, limit: usize },
}

pub fn get(key: &str) -> Result<Vec<u8>, StoreError> {
    std::fs::read(key).map_err(|e| match e.kind() {
        std::io::ErrorKind::NotFound => StoreError::NotFound(key.to_owned()),
        _ => StoreError::Unavailable(e),
    })
}

**Async with timeout and cancellation:**

use tokio::time::{timeout, Duration};

pub async fn fetch_with_deadline(url: &str) -> anyhow::Result<String> {
    let body = timeout(Duration::from_secs(5), reqwest::get(url))
        .await
        .context("request timed out after 5s")?
        .context("request failed")?
        .text()
        .await?;
    Ok(body)
}

Notes

• Borrow-checker errors are usually design feedback. If a lifetime is hard to name, the ownership model is probably wrong.
• `Arc<Mutex<T>>` is a legitimate answer, not a failure. Contention, not the type, is what costs you.
• Async traits are stable as of Rust 1.75 for non-object-safe use; `async-trait` is still needed for trait objects.