rust-core

name	rust-core
description	Shared reference for the Rust cluster: the library-vs-application error strategy (thiserror vs anyhow) that everything turns on, type-driven design conventions, the cargo tooling matrix, and the shared guardrails both spokes obey. USE WHEN choosing a Rust error type, shaping a public API, or wiring the cargo/CI toolchain — the decisions both patterns and testing depend on.
cluster	rust
version	1.0.0

Rust Core

Shared model for the rust cluster. Both spokes — rust-patterns (write) and rust-testing (verify) — depend on these conventions; keep them consistent here so the two never contradict each other (e.g. an error type designed in code and asserted in a test).

1. The decision this cluster turns on: error strategy

Rust's error story splits on who consumes the error, and that single choice ripples into the API, the call sites, and every test:

Library / reusable crate ──> thiserror  (typed enum, #[from], stable variants — callers MATCH on it)
Application / binary ───────> anyhow     (dynamic Result + .context() — callers REPORT it)

• thiserror — derive a structured #[derive(Error)] enum at every library boundary. Callers (and tests) pattern-match exact variants: assert!(matches!(err, StorageError::NotFound { .. })). Use #[from] to absorb upstream errors without losing type. → rust-patterns
• anyhow — in binaries and glue code, return anyhow::Result<T> and attach .context(...) /.with_context(...) at each ?. Use bail!/ensure! for early exits. The trace, not the type, is the product. → rust-patterns
• Never Box<dyn Error> in a library, and never unwrap()/expect() on a recoverable error in production. ? is the default; expect("…") is allowed only for genuinely-unreachable invariants (poisoned mutex, joined thread) with a message that states the invariant.

Rule: decide lib-vs-app first; it fixes whether downstream code and tests match on variants or just propagate context. Treat a change of error strategy (enum → dynamic, or vice versa) as a public-API change.

2. Type-driven design conventions

The shared stance both spokes assume:

• Make illegal states unrepresentable — model variants as enums; match exhaustively, no catch-all _ for business logic (a new variant should force a compile error). → rust-patterns
• Parse, don't validate — convert unstructured input to typed structs at the boundary; wrap primitives in newtypes (UserId(u64)) so arguments can't be swapped. → rust-patterns
• Borrow, don't clone — pass &T/&[T]/&str; reach for Cow when ownership is conditional.
• Accept generics, return concrete types; trait objects (Box<dyn _>) only for heterogeneous collections / plugins. → rust-patterns
• Minimal pub surface — pub(crate) for internal sharing; re-export the public API from lib.rs. Organize modules by domain, not by type.
• unsafe is a last resort: every block carries a # Safety / // SAFETY: note proving its invariants; never used to dodge the borrow checker.

3. Concurrency baseline

• Shared mutable state → Arc<Mutex<T>> (treat lock() poisoning as an invariant via expect).
• Prefer message passing — mpsc/sync_channel with bounded backpressure; drop(tx) to end an rx iterator.
• Async on Tokio; never block the executor (std::thread::sleep → tokio::time::sleep, blocking I/O → spawn_blocking). Tests of async code use #[tokio::test]. → rust-patterns, rust-testing

4. Cargo / tooling matrix

Concern	Tool / command	Spoke
Type-check (fast)	cargo check	rust-patterns
Lints	cargo clippy -- -D warnings	rust-patterns
Format	cargo fmt --check	rust-patterns
Security audit	cargo audit	rust-patterns
Unit / integration / doc tests	cargo test (--lib / --test <name> / --doc)	rust-testing
Parameterized tests	rstest	rust-testing
Property tests	proptest	rust-testing
Mocking	mockall (#[automock])	rust-testing
Benchmarks	criterion (harness = false)	rust-testing
Coverage gate	cargo llvm-cov --fail-under-lines 80	rust-testing

CI runs them in order: fmt --check → clippy -D warnings → cargo test → coverage gate.

5. Version / conventions

• Target a current stable toolchain (dtolnay/rust-toolchain@stable) with clippy + rustfmt components; unsafe examples assume Rust 2024+ edition semantics.
• Pin dev-tooling versions in CI via taiki-e/install-action (e.g. cargo-llvm-cov).
• Coverage targets: critical business logic 100%, public API 90%+, general code 80%+, generated/FFI excluded.

6. Shared guardrails

• ? over unwrap() in all library/production code; expect("invariant") only for the truly unreachable.
• Library → thiserror, application → anyhow; never Box<dyn Error> in a library; state any change to the error strategy.
• Make illegal states unrepresentable; match exhaustively; newtype your primitives.
• Keep unsafe minimal and documented with a # Safety comment.
• Expose the narrowest pub surface; organize by domain.
• TDD: write the failing test first; tests are independent, never sleep(), and assert on typed error variants (matches!) rather than panic strings wherever a Result is returned.
• Gate merges on fmt --check, clippy -D warnings, cargo test, and the coverage threshold.