Rust Development Guidelines - OpenEV Data API¶

// Each struct has a single responsibility
pub struct VehicleReader {
    // Only reads vehicle files
}

pub struct VehicleValidator {
    // Only validates vehicle data
}

pub struct VehicleRepository {
    // Only handles vehicle persistence
}

// This struct does too many things
pub struct VehicleManager {
    // Reads, validates, transforms, saves, queries...
}

// Define behavior through traits
pub trait OutputGenerator {
    fn generate(&self, vehicles: &[Vehicle]) -> Result<Vec<u8>>;
}

// Easy to add new formats without modifying existing code
pub struct JsonGenerator;
impl OutputGenerator for JsonGenerator { /* ... */ }

pub struct SqliteGenerator;
impl OutputGenerator for SqliteGenerator { /* ... */ }

pub trait VehicleStore {
    fn save(&mut self, vehicle: Vehicle) -> Result<()>;
    fn find(&self, id: &str) -> Result<Option<Vehicle>>;
}

// Both implementations respect the contract
impl VehicleStore for SqliteStore { /* ... */ }
impl VehicleStore for PostgresStore { /* ... */ }

// Segregated traits
pub trait Readable {
    fn read(&self, id: &str) -> Result<Vehicle>;
}

pub trait Writable {
    fn write(&mut self, vehicle: Vehicle) -> Result<()>;
}

// Implement only what you need
impl Readable for ReadOnlyStore { /* ... */ }
impl Readable + Writable for FullStore { /* ... */ }

// Fat trait forcing unnecessary implementations
pub trait Repository {
    fn read(&self, id: &str) -> Result<Vehicle>;
    fn write(&mut self, vehicle: Vehicle) -> Result<()>;
    fn delete(&mut self, id: &str) -> Result<()>;
    fn update(&mut self, vehicle: Vehicle) -> Result<()>;
}

// Depend on trait, not concrete type
pub struct EtlPipeline<G: OutputGenerator> {
    generator: G,
}

impl<G: OutputGenerator> EtlPipeline<G> {
    pub fn new(generator: G) -> Self {
        Self { generator }
    }
}

// Hardcoded dependency on concrete type
pub struct EtlPipeline {
    generator: JsonGenerator, // Tightly coupled
}

// Impossible to have a vehicle without required fields
pub struct Vehicle {
    pub make: SlugName,          // Cannot be empty
    pub model: SlugName,
    pub year: Year,              // Validated range (1900-2100)
    pub battery: BatterySpecs,   // At least one capacity required
}

// Year is constrained
pub struct Year(u16);

impl Year {
    pub fn new(value: u16) -> Result<Self, ValidationError> {
        if (1900..=2100).contains(&value) {
            Ok(Year(value))
        } else {
            Err(ValidationError::InvalidYear(value))
        }
    }
}

// Many ways to be invalid
pub struct Vehicle {
    pub make: Option<String>,      // Could be None
    pub model: Option<String>,
    pub year: i32,                 // Could be negative or 9999
    pub battery: Option<Battery>,  // Could be None
}

// lib.rs or main.rs - Define public API
pub mod domain;
pub mod validation;

pub use domain::{Vehicle, Battery};  // Re-export public types
pub use validation::Validator;

// Private modules
mod internal;

// Good - Clear intent
pub struct VehicleRepository;
pub struct JsonSerializer;
pub struct ValidationError;

// Bad - Vague or generic
pub struct Manager;
pub struct Handler;
pub struct Data;

// Good
fn load_dataset() -> Result<Dataset>;
fn validate_vehicle(v: &Vehicle) -> Result<()>;
fn merge_json_files(files: &[File]) -> Json;

// Bad
fn dataset() -> Result<Dataset>;
fn vehicle(v: &Vehicle) -> Result<()>;

// Good
http_client, database_url, repository

// Acceptable
url, json, xml, html, api

// Bad
veh, db_repo, usr

// Good - Type-safe and self-documenting
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct VehicleId(String);

impl VehicleId {
    pub fn new(value: String) -> Result<Self, ValidationError> {
        if value.is_empty() {
            return Err(ValidationError::EmptyId);
        }
        Ok(VehicleId(value))
    }
}

// Bad - Easy to confuse different strings
fn get_vehicle(id: String) -> Vehicle;
fn get_make(make: String) -> Vec<Vehicle>;
// Which string is which?

#[derive(Debug)]
pub struct VehicleBuilder {
    make: Option<SlugName>,
    model: Option<SlugName>,
    year: Option<Year>,
    battery: Option<BatterySpecs>,
}

impl VehicleBuilder {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn make(mut self, make: SlugName) -> Self {
        self.make = Some(make);
        self
    }

    pub fn build(self) -> Result<Vehicle, BuilderError> {
        Ok(Vehicle {
            make: self.make.ok_or(BuilderError::MissingMake)?,
            model: self.model.ok_or(BuilderError::MissingModel)?,
            year: self.year.ok_or(BuilderError::MissingYear)?,
            battery: self.battery.ok_or(BuilderError::MissingBattery)?,
        })
    }
}

// Good - Clear states
#[derive(Debug, Clone, PartialEq)]
pub enum VehicleAvailability {
    Production { start_year: u16 },
    Discontinued { end_year: u16 },
    Concept,
    Announced { expected_year: u16 },
}

// Bad - Multiple booleans
pub struct VehicleAvailability {
    pub is_production: bool,
    pub is_discontinued: bool,
    pub is_concept: bool,
    // Unclear which combination is valid
}

#[derive(Debug, Clone, PartialEq, Eq, Hash)]          // For most types
#[derive(Debug, Clone, PartialEq)]                    // For types with floats
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]   // For small copyable types

#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]

use thiserror::Error;

#[derive(Debug, Error)]
pub enum ValidationError {
    #[error("Missing required field: {field}")]
    MissingField { field: String },

    #[error("Invalid year: {0}. Must be between 1900 and 2100")]
    InvalidYear(u16),

    #[error("At least one battery capacity (gross or net) is required")]
    MissingBatteryCapacity,

    #[error("Schema validation failed: {0}")]
    SchemaError(String),
}

use anyhow::{Context, Result};

pub fn load_dataset(path: &Path) -> Result<Dataset> {
    let file = File::open(path)
        .context(format!("Failed to open dataset file: {:?}", path))?;

    let dataset = serde_json::from_reader(file)
        .context("Failed to parse JSON")?;

    Ok(dataset)
}

// Good
pub fn validate_vehicle(vehicle: &Vehicle) -> Result<(), ValidationError>;
pub fn save_to_db(&self, vehicle: Vehicle) -> Result<VehicleId>;

// Bad - panicking in library code
pub fn validate_vehicle(vehicle: &Vehicle) {
    assert!(!vehicle.make.is_empty());  // NO!
}

// Bad - hiding errors
pub fn save_to_db(&self, vehicle: Vehicle) -> Option<VehicleId>;

pub fn process_vehicle(path: &Path) -> Result<Vehicle> {
    let raw_json = std::fs::read_to_string(path)?;
    let vehicle: Vehicle = serde_json::from_str(&raw_json)?;
    vehicle.validate()?;
    Ok(vehicle)
}

// Library code - NO PANIC
pub fn parse_year(s: &str) -> Result<Year, ParseError> {
    let value: u16 = s.parse()
        .map_err(|_| ParseError::InvalidFormat)?;
    Year::new(value)
}

// Application code - panic is acceptable for truly unrecoverable errors
pub fn main() {
    let config = load_config()
        .expect("Configuration file is required");
}

// Port - abstract interface
pub trait VehicleRepository {
    fn find_by_id(&self, id: &VehicleId) -> Result<Option<Vehicle>>;
    fn save(&mut self, vehicle: Vehicle) -> Result<VehicleId>;
    fn list_all(&self) -> Result<Vec<Vehicle>>;
}

// Adapter - concrete implementation
pub struct SqliteVehicleRepository {
    connection: rusqlite::Connection,
}

impl VehicleRepository for SqliteVehicleRepository {
    fn find_by_id(&self, id: &VehicleId) -> Result<Option<Vehicle>> {
        // SQLite-specific implementation
    }

    fn save(&mut self, vehicle: Vehicle) -> Result<VehicleId> {
        // SQLite-specific implementation
    }

    fn list_all(&self) -> Result<Vec<Vehicle>> {
        // SQLite-specific implementation
    }
}

// Service depends on abstraction, not implementation
pub struct EtlPipeline<R, G>
where
    R: VehicleRepository,
    G: OutputGenerator,
{
    repository: R,
    generator: G,
}

impl<R, G> EtlPipeline<R, G>
where
    R: VehicleRepository,
    G: OutputGenerator,
{
    pub fn new(repository: R, generator: G) -> Self {
        Self { repository, generator }
    }

    pub fn process(&mut self, vehicles: Vec<Vehicle>) -> Result<Vec<u8>> {
        for vehicle in vehicles {
            self.repository.save(vehicle)?;
        }
        let all_vehicles = self.repository.list_all()?;
        self.generator.generate(&all_vehicles)
    }
}

pub trait MergeStrategy {
    fn merge(&self, base: &Json, overlay: &Json) -> Json;
}

pub struct DeepMergeStrategy;
impl MergeStrategy for DeepMergeStrategy {
    fn merge(&self, base: &Json, overlay: &Json) -> Json {
        // Deep merge implementation
    }
}

pub struct ShallowMergeStrategy;
impl MergeStrategy for ShallowMergeStrategy {
    fn merge(&self, base: &Json, overlay: &Json) -> Json {
        // Shallow merge implementation
    }
}

// Repository handles persistence
pub struct VehicleRepositoryImpl {
    db: Database,
}

impl VehicleRepositoryImpl {
    fn to_domain(&self, row: DbRow) -> Result<Vehicle> {
        // Map database row to domain entity
    }

    fn from_domain(&self, vehicle: &Vehicle) -> DbRow {
        // Map domain entity to database row
    }
}

use async_trait::async_trait;

#[async_trait]
pub trait AsyncVehicleRepository {
    async fn find_by_id(&self, id: &VehicleId) -> Result<Option<Vehicle>>;
    async fn save(&self, vehicle: Vehicle) -> Result<VehicleId>;
}

#[async_trait]
impl AsyncVehicleRepository for PostgresRepository {
    async fn find_by_id(&self, id: &VehicleId) -> Result<Option<Vehicle>> {
        // Async implementation
    }

    async fn save(&self, vehicle: Vehicle) -> Result<VehicleId> {
        // Async implementation
    }
}

use futures::future::join_all;

pub async fn load_multiple_vehicles(ids: Vec<VehicleId>) -> Result<Vec<Vehicle>> {
    let futures = ids
        .into_iter()
        .map(|id| async move {
            load_vehicle(&id).await
        });

    join_all(futures).await
        .into_iter()
        .collect::<Result<Vec<_>>>()
}

// For servers - multi-threaded runtime
#[tokio::main]
async fn main() -> Result<()> {
    // Server code
}

// For CLIs - current thread runtime (lighter)
#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<()> {
    // CLI code
}

pub struct Vehicle {
    // ...
}

impl Vehicle {
    pub fn is_available_in_year(&self, year: u16) -> bool {
        // implementation
    }
}

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

    #[test]
    fn test_vehicle_availability() {
        let vehicle = Vehicle::new(/* ... */);
        assert!(vehicle.is_available_in_year(2024));
        assert!(!vehicle.is_available_in_year(1999));
    }

    #[test]
    fn test_invalid_year_returns_error() {
        let result = Year::new(3000);
        assert!(result.is_err());
    }
}

// tests/etl_pipeline_test.rs
use ev_etl::EtlPipeline;
use ev_core::Vehicle;

#[test]
fn test_full_etl_pipeline() {
    let input_dir = "fixtures/sample_vehicles";
    let output_dir = temp_dir();

    let result = EtlPipeline::new()
        .input(input_dir)
        .output(output_dir)
        .formats(vec!["json", "sqlite"])
        .run();

    assert!(result.is_ok());
    assert!(output_dir.join("vehicles.json").exists());
    assert!(output_dir.join("vehicles.db").exists());
}

use proptest::prelude::*;

proptest! {
    #[test]
    fn test_year_roundtrip(year in 1900u16..=2100u16) {
        let y = Year::new(year).unwrap();
        let json = serde_json::to_string(&y).unwrap();
        let parsed: Year = serde_json::from_str(&json).unwrap();
        prop_assert_eq!(y, parsed);
    }
}

use mockall::{automock, predicate::*};

#[automock]
pub trait VehicleRepository {
    fn find_by_id(&self, id: &VehicleId) -> Result<Option<Vehicle>>;
}

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

    #[test]
    fn test_service_with_mock_repository() {
        let mut mock_repo = MockVehicleRepository::new();
        mock_repo
            .expect_find_by_id()
            .with(eq(VehicleId::new("test".to_string()).unwrap()))
            .times(1)
            .returning(|_| Ok(Some(create_test_vehicle())));

        let service = VehicleService::new(mock_repo);
        let result = service.get_vehicle_details(&VehicleId::new("test".to_string()).unwrap());
        assert!(result.is_ok());
    }
}

// tests/common/mod.rs
#![allow(dead_code)]

use ev_core::*;

pub fn create_test_vehicle() -> Vehicle {
    VehicleBuilder::new()
        .make(SlugName::new("test_make", "Test Make").unwrap())
        .model(SlugName::new("test_model", "Test Model").unwrap())
        .year(Year::new(2024).unwrap())
        .battery(create_test_battery())
        .build()
        .unwrap()
}

pub fn create_test_battery() -> BatterySpecs {
    BatterySpecs {
        pack_capacity_kwh_net: Some(60.0),
        thermal_management: Some(ThermalManagement::Liquid),
        ..Default::default()
    }
}

// tests/vehicle_test.rs
mod common;

#[test]
fn test_something() {
    let vehicle = common::create_test_vehicle();
    // ...
}

// Good - borrows instead of cloning
pub fn process_vehicles(vehicles: &[Vehicle]) -> Vec<String> {
    vehicles.iter()
        .map(|v| format_vehicle(v))
        .collect()
}

// Bad - unnecessary clone
pub fn process_vehicles(vehicles: &[Vehicle]) -> Vec<String> {
    vehicles.to_vec()  // Clones all vehicles!
        .iter()
        .map(|v| format_vehicle(v))
        .collect()
}

// Good - iterator chain
let total_capacity: f64 = vehicles
    .iter()
    .filter(|v| v.year == 2024)
    .filter_map(|v| v.battery.pack_capacity_kwh_net)
    .sum();

// Bad - manual loop
let mut total_capacity = 0.0;
for vehicle in vehicles {
    if vehicle.year == 2024 {
        if let Some(capacity) = vehicle.battery.pack_capacity_kwh_net {
            total_capacity += capacity;
        }
    }
}

// Good - accepts both String and &str
pub fn parse_vehicle_id(id: &str) -> Result<VehicleId> {
    VehicleId::new(id.to_string())
}

// Bad - forces caller to own a String
pub fn parse_vehicle_id(id: String) -> Result<VehicleId> {
    VehicleId::new(id)
}

use std::borrow::Cow;

pub fn normalize_slug(s: &str) -> Cow<str> {
    if s.chars().all(|c| c.is_ascii_lowercase() || c == '_') {
        Cow::Borrowed(s)  // No allocation needed
    } else {
        Cow::Owned(s.to_lowercase().replace('-', "_"))  // Allocate only if needed
    }
}

use rayon::prelude::*;

pub fn validate_all_vehicles(vehicles: Vec<Vehicle>) -> Vec<Result<(), ValidationError>> {
    vehicles
        .par_iter()  // Parallel iterator
        .map(|v| v.validate())
        .collect()
}

// benches/vehicle_benchmark.rs
use criterion::{black_box, criterion_group, criterion_main, Criterion};
use ev_core::Vehicle;

fn benchmark_vehicle_validation(c: &mut Criterion) {
    let vehicle = create_test_vehicle();

    c.bench_function("validate_vehicle", |b| {
        b.iter(|| {
            vehicle.validate()
        });
    });
}

criterion_group!(benches, benchmark_vehicle_validation);
criterion_main!(benches);

pub fn load_vehicle_from_file(path: &Path) -> Result<Vehicle> {
    // Validate path is within expected directory
    let canonical_path = path.canonicalize()?;
    if !canonical_path.starts_with("/allowed/directory") {
        return Err(SecurityError::InvalidPath.into());
    }

    // Limit file size
    let metadata = std::fs::metadata(&canonical_path)?;
    if metadata.len() > MAX_FILE_SIZE {
        return Err(SecurityError::FileTooLarge.into());
    }

    // Parse with size limits
    let content = std::fs::read_to_string(&canonical_path)?;
    serde_json::from_str(&content)
        .map_err(|e| e.into())
}

// Good - parameterized
pub fn find_vehicles_by_make(&self, make: &str) -> Result<Vec<Vehicle>> {
    let mut stmt = self.conn.prepare(
        "SELECT * FROM vehicles WHERE make_slug = ?1"
    )?;

    stmt.query_map([make], |row| {
        // Map row to Vehicle
    })
}

// Bad - string concatenation (SQL injection risk)
pub fn find_vehicles_by_make(&self, make: &str) -> Result<Vec<Vehicle>> {
    let query = format!("SELECT * FROM vehicles WHERE make_slug = '{}'", make);
    // NEVER DO THIS
}

// Good - environment variable
pub fn database_url() -> Result<String> {
    std::env::var("DATABASE_URL")
        .context("DATABASE_URL environment variable not set")
}

// Bad - hardcoded
pub fn database_url() -> String {
    "postgresql://user:password123@localhost/db".to_string()
}

//! Vehicle repository implementations.
//!
//! This module provides database access for vehicle entities through
//! implementations of the `VehicleRepository` trait.
//!
//! # Examples
//!
//! ```
//! use ev_core::{Vehicle, VehicleRepository};
//!
//! let repo = SqliteVehicleRepository::new("vehicles.db")?;
//! let vehicle = repo.find_by_id(&id)?;
//! ```

pub mod sqlite;
pub mod postgresql;

/// Represents an electric vehicle with complete specifications.
///
/// A `Vehicle` contains all the essential information about an EV including
/// manufacturer details, battery specifications, charging capabilities, and
/// performance metrics.
///
/// # Examples
///
/// ```
/// use ev_core::{Vehicle, VehicleBuilder};
///
/// let vehicle = VehicleBuilder::new()
///     .make("tesla", "Tesla")
///     .model("model_3", "Model 3")
///     .year(2024)
///     .build()?;
/// ```
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Vehicle {
    /// Vehicle manufacturer information
    pub make: SlugName,

    /// Vehicle model name and slug
    pub model: SlugName,

    /// Model year (1900-2100)
    pub year: Year,

    /// Battery specifications and capabilities
    pub battery: BatterySpecs,
}

/// Validates a vehicle against the JSON schema and business rules.
///
/// # Errors
///
/// Returns `ValidationError` if:
/// - Required fields are missing
/// - Values are out of valid range
/// - Business rules are violated
///
/// # Examples
///
/// ```
/// let vehicle = create_test_vehicle();
/// assert!(validate_vehicle(&vehicle).is_ok());
/// ```
pub fn validate_vehicle(vehicle: &Vehicle) -> Result<(), ValidationError> {
    // Implementation
}

/// Errors that can occur during vehicle validation.
#[derive(Debug, Error)]
pub enum ValidationError {
    /// A required field is missing from the vehicle data.
    ///
    /// This typically indicates incomplete input data.
    #[error("Missing required field: {field}")]
    MissingField {
        /// The name of the missing field
        field: String,
    },

    /// The year value is outside the valid range (1900-2100).
    #[error("Invalid year: {0}. Must be between 1900 and 2100")]
    InvalidYear(u16),
}

// At crate level for specific exceptions
#![allow(clippy::module_name_repetitions)]  // Vehicle in VehicleRepository

// At item level for specific cases
#[allow(clippy::too_many_arguments)]  // Rare, justified cases
pub fn complex_function(/* many params */) {}

use serde::Deserialize;

#[derive(Debug, Deserialize)]
pub struct Config {
    pub database_url: String,
    pub port: u16,
    #[serde(default = "default_log_level")]
    pub log_level: String,
}

fn default_log_level() -> String {
    "info".to_string()
}

impl Config {
    pub fn from_env() -> Result<Self> {
        envy::from_env().context("Failed to load configuration from environment")
    }
}

use tracing::{info, warn, error, debug, instrument};

#[instrument(skip(repository))]
pub async fn load_vehicle(
    id: &VehicleId,
    repository: &impl VehicleRepository,
) -> Result<Vehicle> {
    debug!("Loading vehicle with id: {}", id);

    let vehicle = repository.find_by_id(id).await?;

    match vehicle {
        Some(v) => {
            info!("Successfully loaded vehicle: {} {}", v.make, v.model);
            Ok(v)
        }
        None => {
            warn!("Vehicle not found: {}", id);
            Err(VehicleError::NotFound)
        }
    }
}

// Extend external types with project-specific behavior
pub trait VehicleExt {
    fn display_name(&self) -> String;
    fn is_recent(&self) -> bool;
}

impl VehicleExt for Vehicle {
    fn display_name(&self) -> String {
        format!("{} {} {}", self.year, self.make.name, self.model.name)
    }

    fn is_recent(&self) -> bool {
        let current_year = chrono::Utc::now().year() as u16;
        self.year.0 >= current_year - 3
    }
}

// Different states represented by types
pub struct Unvalidated;
pub struct Validated;

pub struct Vehicle<S> {
    data: VehicleData,
    _state: PhantomData<S>,
}

impl Vehicle<Unvalidated> {
    pub fn new(data: VehicleData) -> Self {
        Self { data, _state: PhantomData }
    }

    pub fn validate(self) -> Result<Vehicle<Validated>, ValidationError> {
        // Validation logic
        Ok(Vehicle { data: self.data, _state: PhantomData })
    }
}

impl Vehicle<Validated> {
    // Only validated vehicles can be saved
    pub fn save(&self, repo: &mut impl VehicleRepository) -> Result<()> {
        repo.save(&self.data)
    }
}

// Bad - relying on strings
fn get_vehicle_field(vehicle: &Vehicle, field: &str) -> Option<String> {
    match field {
        "make" => Some(vehicle.make.clone()),
        "model" => Some(vehicle.model.clone()),
        _ => None,
    }
}

// Good - use enums
enum VehicleField {
    Make,
    Model,
    Year,
}

fn get_vehicle_field(vehicle: &Vehicle, field: VehicleField) -> String {
    match field {
        VehicleField::Make => vehicle.make.clone(),
        VehicleField::Model => vehicle.model.clone(),
        VehicleField::Year => vehicle.year.to_string(),
    }
}

// Bad - unnecessary clone
pub fn format_vehicles(vehicles: &[Vehicle]) -> Vec<String> {
    vehicles.iter()
        .map(|v| v.clone())  // Unnecessary!
        .map(|v| format!("{} {}", v.make, v.model))
        .collect()
}

// Good - just borrow
pub fn format_vehicles(vehicles: &[Vehicle]) -> Vec<String> {
    vehicles.iter()
        .map(|v| format!("{} {}", v.make, v.model))
        .collect()
}

// Bad - one type does everything
pub struct VehicleManager {
    pub data: Vehicle,
    pub db_connection: Connection,
    pub http_client: Client,
    pub cache: Cache,
    // ... more responsibilities
}

// Good - separate concerns
pub struct Vehicle { /* data only */ }
pub struct VehicleRepository { /* persistence */ }
pub struct VehicleService { /* business logic */ }
pub struct VehicleCache { /* caching */ }

// Bad - silently ignoring errors
let _ = vehicle.validate();  // Error ignored!

// Good - handle or propagate
vehicle.validate()?;

// Or explicitly acknowledge
let _ = vehicle.validate()
    .map_err(|e| eprintln!("Validation warning: {}", e));

// Bad - can panic
let vehicle = repository.find_by_id(&id).unwrap();

// Good - handle error
let vehicle = repository.find_by_id(&id)?;

// Or provide context
let vehicle = repository.find_by_id(&id)
    .expect("Vehicle must exist at this point");  // Only if truly infallible