rust-development
Rust development best practices for the Guts project - idiomatic code, error handling, async patterns, and commonware integration
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for Rust development within the Guts project, specifically tailored for decentralized infrastructure. It offers expert guidance on writing idiomatic code, implementing robust error handling using thiserror and anyhow, and mastering async patterns with Tokio. By integrating commonware primitives, it streamlines the creation of secure, high-performance P2P networking and consensus systems while ensuring strict adherence to memory safety and documentation standards.
Use Cases
- Architecting decentralized systems: Guidance on using commonware-p2p, cryptography, and consensus crates to build secure infrastructure.
- Standardizing error management: Implementing consistent error patterns across libraries and applications to improve maintainability and debugging.
- Developing high-concurrency services: Designing async services using structured concurrency, channels, and Tokio for efficient resource management.
- Enforcing code quality: Applying idiomatic Rust patterns, strict Clippy lints, and automated formatting to maintain a professional-grade codebase.
- Performance optimization: Utilizing zero-copy networking with Bytes and concurrent data structures like dashmap for high-throughput applications.
| name | rust-development |
|---|---|
| description | Rust development best practices for the Guts project - idiomatic code, error handling, async patterns, and commonware integration |
Rust Development Skill for Guts
You are developing a Rust project using commonware primitives for decentralized infrastructure.
Code Style Guidelines
General Principles
- Idiomatic Rust: Follow Rust idioms and conventions
- Memory Safety: Leverage the borrow checker, avoid unsafe unless absolutely necessary
- Error Handling: Use
thiserrorfor library errors,anyhowfor applications - Documentation: Every public item needs docs with examples
Formatting & Linting
# Always run before committing
cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
Error Handling Pattern
use thiserror::Error;
#[derive(Debug, Error)]
pub enum RepositoryError {
#[error("repository not found: {0}")]
NotFound(String),
#[error("permission denied for repository: {0}")]
PermissionDenied(String),
#[error("storage error: {0}")]
Storage(#[from] StorageError),
}
pub type Result<T> = std::result::Result<T, RepositoryError>;
Async Patterns
Use Tokio for async runtime with structured concurrency:
use tokio::sync::{mpsc, oneshot};
// Prefer channels over shared state
pub struct Service {
tx: mpsc::Sender<Command>,
}
impl Service {
pub async fn query(&self, request: Request) -> Result<Response> {
let (tx, rx) = oneshot::channel();
self.tx.send(Command::Query { request, reply: tx }).await?;
rx.await?
}
}
Module Structure
// lib.rs - re-export public API
pub mod error;
pub mod types;
pub mod service;
pub use error::{Error, Result};
pub use types::*;
pub use service::Service;
Testing
#[cfg(test)]
mod tests {
use super::*;
#[tokio::test]
async fn test_feature() {
// Arrange
let service = Service::new().await;
// Act
let result = service.do_something().await;
// Assert
assert!(result.is_ok());
}
}
Commonware Integration
Key Crates
commonware-cryptography: Use for Ed25519 signaturescommonware-p2p: Use for peer-to-peer networkingcommonware-consensus: Use for BFT consensuscommonware-storage: Use for persistent storagecommonware-codec: Use for serialization
Example: Using Cryptography
use commonware_cryptography::{Ed25519, Signer, Verifier};
pub struct Identity {
keypair: Ed25519,
}
impl Identity {
pub fn new() -> Self {
Self {
keypair: Ed25519::generate(),
}
}
pub fn sign(&self, message: &[u8]) -> Signature {
self.keypair.sign(message)
}
}
Cargo.toml Best Practices
[package]
name = "guts-core"
version = "0.1.0"
edition = "2021"
rust-version = "1.75"
license = "MIT OR Apache-2.0"
description = "Core types and traits for Guts"
repository = "https://github.com/AbdelStark/guts"
keywords = ["decentralized", "git", "p2p"]
categories = ["development-tools"]
[dependencies]
# Use workspace dependencies
thiserror = { workspace = true }
tokio = { workspace = true }
[dev-dependencies]
tokio-test = { workspace = true }
[lints.rust]
unsafe_code = "deny"
missing_docs = "warn"
[lints.clippy]
all = "warn"
pedantic = "warn"
nursery = "warn"
Performance Considerations
- Use
Arcfor shared ownership across async tasks - Prefer
bytes::Bytesfor zero-copy networking - Use
dashmapfor concurrent hash maps - Profile with
flamegraphbefore optimizing