ia-rust-systems

---
name: ia-rust-systems
slug: compound-eng-rust-systems
class: language
description: >-
  Rust patterns for CLI tools, backend services, and general application code.
  Use when working with Rust, Cargo workspaces, axum/tokio services, clap CLIs,
  async concurrency, or configuring clippy, rustfmt, cargo-nextest, or Cargo.toml.
paths: "**/*.rs,**/Cargo.toml"
original_author: iliaal
source: clawhub
---

# Rust Systems & Services

Modern application-layer Rust (edition 2024) covering CLIs, web services, and libraries. Not `no_std`/embedded.

## intent

This skill documents production Rust patterns for CLI tools, backend services, and application libraries. Use it when building or maintaining Rust projects with Cargo workspaces, async services (axum, tokio), command-line tools (clap), or configuring the compiler toolchain (clippy, rustfmt, cargo-nextest). Follow these patterns to keep code simple, maintainable, and resilient in production.

## inputs

### Rust Toolchain

- `rust-toolchain.toml` pinned per repo so all contributors and CI use the same compiler version
- `Cargo.toml` and `Cargo.lock` (lock file goes in version control for reproducibility, both binaries and libraries)

### External Tools (optional but recommended)

| Tool | Purpose | Setup |
|------|---------|-------|
| `clippy` | Lint pass | Built-in; run `cargo clippy --workspace --all-targets -- -D warnings` |
| `rustfmt` | Code formatter | Built-in; run `cargo fmt --all` |
| `cargo-nextest` | Fast test runner | `cargo install cargo-nextest`; faster isolation than `cargo test` |
| `cargo-deny` | License/advisory/duplicate checks | `cargo install cargo-deny` |
| `cargo-machete` | Find unused deps | `cargo install cargo-machete` |
| `cargo-llvm-cov` | Coverage reports | `cargo install cargo-llvm-cov` |
| `miri` | UB detector for unsafe code | `cargo +nightly miri test` |

### Project Structure

- Monorepo using Cargo workspaces with layered crates (protocol/shared types → storage → service → CLI binaries)
- Centralized dependency versions in `[workspace.dependencies]`
- Centralized lints in `[workspace.lints.*]` inherited by all member crates

## procedure

### 1. Workspace Setup (Multi-Crate Projects)

**Input:** decision to structure as a monorepo or single crate.

**Steps:**
1. Create root `Cargo.toml` with `[workspace]` section listing all member crates.
2. Define `[workspace.dependencies]` once at the root with pinned versions.
3. Create subdirectory structure under `crates/`:
   - `crates/protocol/` ,  shared types, zero dependencies on other workspace crates
   - `crates/storage/` ,  persistence layer, depends only on `protocol`
   - `crates/service/` ,  business logic, depends on `protocol` + `storage`
   - `crates/cli/` ,  binary entrypoint, depends on everything
4. In each member's `Cargo.toml`, reference workspace versions: `tokio = { workspace = true }`.
5. Define `[workspace.lints.*]` at root with `rust` and `clippy` rule sets; each member opts in with `[lints] workspace = true`.
6. Verify no cycles: leaf crates (protocol) have no intra-workspace deps; each higher layer depends only on lower layers.

**Output:** Multi-crate workspace compiling with `cargo build --workspace`, all members sharing versions and lints.

### 2. Error Handling Strategy

**Input:** crate's role (library, binary, service layer).

**Steps:**
1. For library crates, define typed errors using `thiserror`:
   ```rust
   #[derive(Debug, thiserror::Error)]
   pub enum Error {
       #[error("validation failed: {0}")]
       Validation(String),
       #[error("io: {0}")]
       Io(#[from] std::io::Error),
   }

2. For binaries and app-layer code, use anyhow::Result<T> with .context("what was attempted") for error chains.
3. In function signatures, return Result<T, E> , never Box<dyn Error> from public APIs.
4. Use ? to propagate. Never call .unwrap() or .expect() outside tests and main.
5. If you write .expect("reason...") in app code, the message must explain why the invariant is provably upheld.
6. At crate boundaries, convert errors: use #[from] on thiserror variants for auto-conversion, or .map_err(MyError::from) when explicit.
7. In application code, use bail!("message") and ensure!(condition, "message") for early exits.
8. Annotate fallible APIs (returning Result) with #[must_use] so let _ = validate(x); fails at compile time.
9. For mandatory call sequences, encode state as part of the type: Client<Uninitialized> → Client<Connected>, making illegal calls unrepresentable at the type level rather than runtime errors.

Output: Typed, composable error handling; application code uses anyhow, library code uses thiserror.

3. Async Runtime Setup (Tokio)

Input: crate type (app, library) and workload (independent tasks, data parallelism, I/O concurrency).

Steps:

1. For applications, use #[tokio::main] with features = ["full"].
2. For libraries, add features = ["rt", "macros", "sync"] to stay slim.
3. Use tokio::spawn for independent tasks; wrap groups in JoinSet for coordinated cancellation.
4. Use tokio::select! to race futures (timeouts, cancellation, first-to-complete).
5. Never block the async runtime: call tokio::task::spawn_blocking for sync CPU work or blocking I/O library calls.
6. For shared state:
   • tokio::sync::Mutex only when the guard must be held across .await.
   • std::sync::Mutex (faster) when contention is low and the lock is released before any .await.
   • tokio::sync::RwLock when reads dominate writes (many readers, few writers). For hot caches with rare updates, use arc-swap::ArcSwap instead.
7. Propagate shutdown via CancellationToken (from tokio-util); long-running tasks check it.
8. Use bounded mpsc channels to apply backpressure; avoid unbounded channels (they hide memory leaks until OOM).
9. For hard concurrency limits not fitting a channel model, use Semaphore: let _permit = sem.acquire().await?; inside the spawned task; dropping the permit releases the slot.
10. Never mix async runtimes , pick tokio and commit to it; async-std and smol don't interop cleanly.

Output: Async code structured with tokio primitives, no blocking calls on the runtime, proper backpressure and cancellation.

4. CLI Tools (clap)

Input: requirement for a command-line interface.

Steps:

1. Use the derive API: #[derive(Parser)] + #[derive(Subcommand)] for less boilerplate.
2. Create one enum Commands variant per subcommand.
3. Flatten shared flags into a #[command(flatten)] struct CommonArgs.
4. Add --json flag on query commands for agent/pipe consumption; emit output via serde_json::to_string(&value)?.
5. Define exit codes: 0 for success, 1 for errors, 2 for argparse (clap handles this automatically), 3+ for domain-specific meanings documented in --help.
6. Ensure --version is provided automatically via #[command(version)].

Output: Single-file CLI with typed subcommands, help text derived from struct fields, --json support.

5. HTTP Services (axum)

Input: need to build a web service.

Steps:

1. Choose axum as the framework (tokio-native, tower middleware, extractor-based handlers).
2. Structure handlers to return Result<impl IntoResponse, AppError>.
3. Implement IntoResponse for your AppError to centralize error → HTTP status mapping.
4. At the boundary, validate input: axum::extract::Json<T> where T: Deserialize + Validate (use the validator crate). Internal code trusts input was validated.
5. Share application state via State<Arc<AppState>> , no globals or lazy_static.
6. Layer middleware via tower::ServiceBuilder: tracing → timeout → auth → CORS → handler (order matters).
7. For outbound HTTP clients and shared services, build a resilience stack:

   ServiceBuilder::new()
     .layer(TimeoutLayer)
     .layer(RateLimitLayer)
     .layer(ConcurrencyLimitLayer)
     .layer(LoadShedLayer)
     .layer(RetryLayer)
     .service(client)
   

   LoadShedLayer sheds excess load, ConcurrencyLimitLayer caps in-flight requests, RateLimitLayer bounds request rate, RetryLayer retries transient errors. Together, they produce backpressure instead of unbounded queueing.

Output: Production axum service with middleware stack, centralized error handling, and resilience layers.

6. Ownership and Allocation Discipline

Input: function signatures, hot paths, and shared ownership needs.

Steps:

1. Prefer &str over &String, &[T] over &Vec<T> in signatures , they accept more call sites without conversion.
2. Return owned types (String, Vec<T>) from constructors and public APIs; borrow in hot paths where lifetimes are obvious.
3. Use Arc<T> only for cross-thread sharing; single-threaded sharing uses Rc<T> or references.
4. Use Cow<'_, str> when a function sometimes allocates and sometimes borrows (e.g. normalization).
5. Let lifetime elision handle 90% of cases; if you're writing 'a in multiple signatures, consider making the type own its data instead.
6. For zero-copy slicing of shared immutable buffers (network parsers, frame decoders), use bytes::Bytes instead of Arc<Vec<u8>>. Use BytesMut to build buffers that split into Bytes without reallocation.
7. For hot-path allocations with small, predictable sizes:
   • smallvec::SmallVec<[T; N]> , inline for ≤N items, spills to heap beyond (good for "usually 1-8 items" like tag lists or lookup keys).
   • arrayvec::ArrayVec<T, CAP> , fixed capacity, never allocates, returns error when full (good for bounded buffers, per-request scratch space).
   • String interning for repeatedly-seen strings (config values, tenant IDs, route keys): use dashmap::DashMap<String, &'static str> with Box::leak on miss to get &'static str comparisons without per-call allocations.
8. Profile before optimizing , Vec/String on a cold path is not the bottleneck.

Output: Functions accept borrowed generic types, hot paths minimize allocations, shared state uses appropriate sync/arc patterns.

7. Testing

Input: application code ready for testing.

Steps:

1. Use #[test] (built-in); run with cargo nextest run --workspace instead of cargo test for parallel isolation.
2. Place unit tests in a mod tests { ... } block at the file's end for access to private items.
3. Place integration tests in a tests/ directory, one file per public API surface.
4. For async tests, use #[tokio::test]; add flavor = "multi_thread" when the code under test spawns tasks.
5. Use rstest for parametrized tests and fixtures; proptest or quickcheck for property-based testing on pure logic.
6. Use insta for snapshot testing (CLI output, serialization, large structs); review diffs with cargo insta review.
7. For CLI integration tests, use assert_cmd + predicates (invokes the binary, asserts on stdout/stderr/exit codes).
8. Assert on error kinds with matches!: assert!(matches!(result.unwrap_err(), MyError::Validation(_))) instead of match arms. Cleaner and won't break when unrelated variants are added.
9. Run coverage with cargo llvm-cov --workspace --html; target 70%+ on application code, higher on libraries.
10. For parsers and any code handling untrusted input, fuzz with cargo fuzz + libfuzzer-sys. A short nightly run surfaces panics and UB that unit tests miss.

Output: Comprehensive test suite covering happy paths, error cases, and edge cases. Coverage report generated.

8. Unsafe Code Discipline

Input: when unsafe is considered for zero-copy, transmute, or FFI patterns.

Steps:

1. Default: no unsafe. If clippy flags it, refactor instead of allowing.
2. Every unsafe block gets a // SAFETY: comment above it explaining why each invariant holds. No comment = code review rejection.
3. Keep unsafe blocks minimal and wrap them in a safe module-level abstraction, marked pub(crate).
4. Run cargo +nightly miri test on any crate containing unsafe or raw pointer arithmetic to catch UB.
5. Prefer bytemuck, zerocopy, or bytes over hand-rolled transmutes for zero-copy patterns.
6. Note: std::env::set_var and remove_var are unsafe under edition 2024 because concurrent getenv from another thread is UB at the libc level. Pin every env-var write to single-threaded startup, before tokio::main or any std::thread::spawn. Common offender: native library discovery paths (LD_LIBRARY_PATH, ORT_DYLIB_PATH, LIBTORCH) set lazily , compute and set them in main before the runtime starts.

Output: No unsafe code except where provably necessary; all unsafe blocks documented and verified with miri.

9. Compiler and Linting Configuration

Input: workspace root Cargo.toml.

Steps:

1. Define [workspace.lints.rust] and [workspace.lints.clippy] once at the root:

   [workspace.lints.rust]
   unsafe_code = "warn"
   missing_docs = "warn"
   
   [workspace.lints.clippy]
   all = { level = "warn", priority = -1 }
   pedantic = { level = "warn", priority = -1 }
   nursery = { level = "warn", priority = -1 }
   module_name_repetitions = "allow"
   must_use_candidate = "allow"
   

2. Each member crate opts in with [lints] workspace = true in its own Cargo.toml.
3. Run cargo fmt --all -- --check before commit.
4. Run cargo clippy --workspace --all-targets --all-features -- -D warnings and fix all warnings.
5. For any lint exception, document the rationale in a comment; never use #[allow(...)] as a shortcut.
6. Before adding a trait or generic, verify it's used in 3+ places; otherwise a concrete type is clearer.

Output: All crates use the same lint configuration. Zero warnings on clippy and fmt checks.

10. Verification (Pre-Commit Checklist)

Input: code ready for commit or PR.

Steps:

1. cargo fmt --all -- --check passes with zero diffs.
2. cargo clippy --workspace --all-targets --all-features -- -D warnings passes with zero warnings.
3. cargo nextest run --workspace (or cargo test --workspace) passes with zero failures.
4. For any crate going to production, cargo deny check passes (licenses, advisories, duplicates).
5. Every new unsafe block has a // SAFETY: comment.
6. No new #[allow(...)] lint exceptions without documented rationale.

Output: Code ready to merge; all checks green.

decision_points

Workspace vs. Single Crate

Decision: Use a workspace if the project has 2+ crates with interdependencies (e.g. shared types, pluggable layers). For a single-purpose library or binary, a single crate is simpler.

If workspace: follow the layered dependency model (protocol → storage → service → CLI). Define [workspace.dependencies] and [workspace.lints.*] at the root.

If single crate: still define [workspace.lints.*] for consistency; no [workspace.dependencies] needed.

Error Handling: thiserror vs. anyhow

Decision: Use thiserror in libraries (typed errors, pattern-matchable variants). Use anyhow in binaries and app-layer code (human-readable error chains, less boilerplate).

If library: consumers must see error variants and decide how to handle them. thiserror enables that.

If binary: convert library errors to anyhow::Result at the boundary with .context("what was being attempted"). Log or display the chain to the user.

Tokio vs. async-std / smol

Decision: Always pick tokio. Don't mix runtimes.

If starting fresh: use tokio. It has the largest ecosystem (axum, tonic, sqlx, etc.) and best stability.

If forced to interop: stick with tokio and drive everything through it; don't run two