Rust Quality

Goal

Write idiomatic, maintainable Rust code that follows the project's established patterns for error handling, type safety, cross-platform compatibility, and code organization.

When to use

• Writing new Rust modules or functions
• Refactoring existing Rust code
• Adding cross-platform support (iOS, Android, WASM)
• Implementing error types
• Creating newtypes or domain types
• Writing tests

When not to use

• Non-Rust codebases
• Simple documentation edits
• Configuration-only changes

Default workflow

1. Read existing code in the module/area being modified
2. Follow established patterns for imports, types, errors
3. Write implementation with proper feature gates
4. Add inline tests in #[cfg(test)] mod tests
5. Run just lint to verify formatting and clippy

Code Style

Imports (block style, grouped)

use {
    crate::{
        module_a::TypeA,
        module_b::{TypeB, TypeC},
    },
    external_crate::{ExternalType, AnotherType},
    std::collections::HashMap,
};

Error handling (thiserror + uniffi)

#[derive(Debug, thiserror::Error)]
#[cfg_attr(feature = "uniffi", derive(uniffi_macros::Error))]
pub enum MyError {
    #[error("Invalid input: {0}")]
    InvalidInput(String),

    #[error("Not found")]
    NotFound,

    #[error("Internal: {0}")]
    Internal(String),
}

Newtypes (full derive chain)

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, Default)]
pub struct MyId(u64);

impl MyId {
    pub fn new(id: u64) -> Self {
        Self(id)
    }
}

impl From<u64> for MyId {
    fn from(val: u64) -> Self {
        Self::new(val)
    }
}

impl std::fmt::Display for MyId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.0)
    }
}

Structs with FFI support

#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
#[cfg_attr(
    feature = "wasm",
    derive(tsify::Tsify),
    tsify(into_wasm_abi, from_wasm_abi)
)]
pub struct MyConfig {
    pub endpoint: String,
    pub timeout_ms: u64,
}

Feature-gated modules

// In lib.rs
#[cfg(feature = "my_feature")]
pub mod my_module;

#[cfg(any(feature = "feature_a", feature = "feature_b"))]
pub mod shared_module;

Async functions

pub async fn fetch_data(&self) -> eyre::Result<Data> {
    let response = self.client.get(&self.endpoint).await?;
    let data: Data = response.json().await?;
    Ok(data)
}

Inline tests

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_my_id_creation() -> eyre::Result<()> {
        let id = MyId::new(42);
        eyre::ensure!(id.0 == 42, "id should be 42");
        Ok(())
    }

    #[tokio::test]
    async fn test_async_fetch() {
        let result = fetch_data().await;
        assert!(result.is_ok());
    }
}

Impl block organization

impl MyClient {
    // 1. Constructor
    pub fn new(config: Config) -> Self {
        Self { config }
    }

    // 2. Getters
    pub fn config(&self) -> &Config {
        &self.config
    }

    // 3. Preparation (side-effect free)
    pub fn prepare_request(&self, input: Input) -> PreparedRequest {
        // ...
    }

    // 4. Async operations
    pub async fn execute(&self, request: PreparedRequest) -> eyre::Result<Output> {
        // ...
    }
}

Formatting rules

• Max line width: 80 characters
• Use cargo +nightly fmt --all for formatting
• Group imports with imports_granularity = "One"
• All clippy warnings are errors (-D warnings)

Validation checklist

• Imports use block style and are grouped (crate, external, std)
• Errors derive thiserror::Error with descriptive messages
• FFI types have #[cfg_attr(feature = "uniffi", ...)]
• Newtypes have From/Into impls and Display
• Tests are inline in #[cfg(test)] mod tests
• No clippy warnings
• Line width under 80 characters
• Feature gates for platform-specific code

Anti-patterns to avoid

• Stringly-typed APIs (use newtypes)
• unwrap() in library code (use ? with eyre::Result)
• Deeply nested imports (flatten to specific types)
• Missing feature gates for platform code
• Tests in separate files when inline suffices
• Verbose comments (code should be self-documenting)

Advanced Patterns

See REFERENCE.md for:

• Custom serde modules (duration_millis, etc.)
• UniFFI custom type mappings
• Platform-aware async spawning (native vs WASM)
• Async trait with WASM support (?Send)
• Thread-safe caching with Arc<RwLock<_>>
• Serde enum patterns (tagged unions, rename_all_fields)
• Feature flag organization in Cargo.toml
• Constants module pattern

Examples

Example 1: New error type

Input: "Add an error type for payment failures"

#[derive(Debug, thiserror::Error)]
#[cfg_attr(feature = "uniffi", derive(uniffi_macros::Error))]
pub enum PaymentError {
    #[error("Insufficient funds: required {required}, available {available}")]
    InsufficientFunds { required: u64, available: u64 },

    #[error("Invalid recipient: {0}")]
    InvalidRecipient(String),

    #[error("Network error: {0}")]
    Network(String),

    #[error("Timeout after {0}ms")]
    Timeout(u64),
}

Example 2: Cross-platform struct

Input: "Create a transaction request type for all platforms"

use {
    crate::chain::ChainId,
    alloy::primitives::{Address, U256},
    serde::{Deserialize, Serialize},
};

#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
#[cfg_attr(
    feature = "wasm",
    derive(tsify::Tsify),
    tsify(into_wasm_abi, from_wasm_abi)
)]
pub struct TransactionRequest {
    pub chain_id: ChainId,
    pub to: Address,
    pub value: U256,
    pub data: Vec<u8>,
}

impl TransactionRequest {
    pub fn new(chain_id: ChainId, to: Address, value: U256, data: Vec<u8>) -> Self {
        Self { chain_id, to, value, data }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_transaction_request_creation() {
        let req = TransactionRequest::new(
            ChainId::new_eip155(1),
            Address::ZERO,
            U256::ZERO,
            vec![],
        );
        assert_eq!(req.chain_id, ChainId::new_eip155(1));
    }
}