Toolchains Rust Core

Rust Core Toolchain Conventions

Edition and Toolchain

• Target Rust 2024 edition. MSRV is set by the most-constrained transitive dependency, not the edition floor — pin it explicitly in Cargo.toml (rust-version = "...").
• Gate every change on cargo fmt --check, cargo clippy -- -D warnings, and cargo test.
• Prefer cargo nextest run for faster, isolated test execution when available.

Ownership and Borrowing

• Borrow by default, own only when necessary. Accept &str / &[T] in function signatures, not String / Vec<T>, unless the function must take ownership.
• Return owned values; let callers borrow. Avoid returning references tied to locals.
• Reach for Cow<'_, str> when a value is usually borrowed but occasionally owned.
• Use Rc/Arc only for genuine shared ownership; prefer passing references first.
• Interior mutability: Cell/RefCell for single-threaded, Mutex/RwLock (under Arc) for shared-state concurrency. Never hold a lock across an .await.

Error Handling

• Never unwrap()/expect()/panic! in library code. Return Result<T, E>.
• Libraries: define a typed error enum with thiserror. Applications: anyhow::Result with .context(...) to add provenance at each boundary.
• Use the ? operator for propagation; convert errors with From/#[from].
• Reserve panic! for truly unreachable invariants, and document why.

Async with tokio

• Use #[tokio::main] (or an explicit runtime) and async/.await for I/O-bound work.
• Spawn concurrent work with tokio::spawn; join with tokio::join! or try_join!.
• Apply explicit timeouts via tokio::time::timeout on all external calls.
• Offload CPU-bound work with tokio::task::spawn_blocking — never block the runtime.
• Hold no std::sync lock across an .await; use tokio::sync primitives instead.

Project Structure and Idioms

• One responsibility per module; expose a curated public API via pub in lib.rs.
• Derive Debug, and Clone/PartialEq/Eq where cheap and meaningful.
• Model state with enums + exhaustive match; avoid boolean-flag soup.
• Prefer iterator chains over manual index loops; they are clearer and often faster.
• Use newtypes (struct UserId(u64)) to make illegal states unrepresentable.
• Write doctests for public functions; they double as runnable documentation.