Code Style Guide¶

cargo +nightly fmt --all

use std::{
    hash::{DefaultHasher, Hash, Hasher},
    sync::{
        atomic::{AtomicU64, AtomicUsize, Ordering},
        Arc,
    },
};

use dashmap::DashMap;

use super::{get_healthy_worker_indices, LoadBalancingPolicy, SelectWorkerInfo};
use crate::worker::Worker;

cargo clippy --locked --all-targets --all-features -- -D warnings

#[expect(
    clippy::disallowed_methods,
    reason = "supervisor outlives the task it watches; it ends when that task ends"
)]
spawn(async move {
    // ...
});

Arc::new(RoundRobinPolicy::new())
Arc::new(CacheAwarePolicy::with_config(config))

let config = RouterConfig::builder()
    .policy(PolicyConfig::Random)
    .host("127.0.0.1")
    .port(3001)
    .request_timeout_secs(60)
    .build()?; // validates; build_unchecked() skips validation

// crates/tokenizer/src/factory.rs: a blocking function and its async twin
pub fn create_tokenizer(model_name_or_path: &str) -> Result<Arc<dyn traits::Tokenizer>> { ... }
pub async fn create_tokenizer_async(
    model_name_or_path: &str,
) -> Result<Arc<dyn traits::Tokenizer>> { ... }

// No blocking twin: no suffix
async fn fetch_models() -> Result<Vec<Model>> { ... }

// Avoid
async fn fetch_models_async() -> Result<Vec<Model>> { ... }

//! Round-robin load balancing policy

// 1. Imports, grouped by rustfmt (see Formatting)
use dashmap::DashMap;

use super::{get_healthy_worker_indices, LoadBalancingPolicy, SelectWorkerInfo};
use crate::worker::Worker;

// 2. Constants
const MAX_TRACKED_SETS: usize = 4096;

// 3. Types
#[derive(Debug, Default)]
pub struct RoundRobinPolicy {
    // ...
}

// 4. Inherent implementations
impl RoundRobinPolicy {
    pub fn new() -> Self {
        // ...
    }
}

// 5. Trait implementations
impl LoadBalancingPolicy for RoundRobinPolicy {
    // select_worker, name, reset, as_any
}

// 6. Tests
#[cfg(test)]
mod tests {
    use super::*;
    // ...
}

#[derive(Debug, thiserror::Error)]
pub enum ConfigError {
    #[error("Validation failed: {reason}")]
    ValidationFailed { reason: String },

    #[error("Invalid value for field '{field}': {value} - {reason}")]
    InvalidValue {
        field: String,
        value: String,
        reason: String,
    },

    #[error("Incompatible configuration: {reason}")]
    IncompatibleConfig { reason: String },

    #[error("Missing required field: {field}")]
    MissingRequired { field: String },
}

pub type ConfigResult<T> = Result<T, ConfigError>;

// Good
fn process() -> Result<Response> {
    let data = fetch_data()?;
    let result = transform(data)?;
    Ok(result)
}

// Avoid
fn process() -> Result<Response> {
    let data = match fetch_data() {
        Ok(d) => d,
        Err(e) => return Err(e),
    };
    // ...
}

let config: serde_json::Value = std::fs::read_to_string(&config_path)
    .with_context(|| format!("Failed to read config.json at {}", config_path.display()))
    .and_then(|s| {
        serde_json::from_str(&s).with_context(|| {
            format!("Failed to parse config.json at {}", config_path.display())
        })
    })?;

#[expect(
    clippy::expect_used,
    reason = "startup initialization — metrics exporter must be installed or the process cannot serve metrics"
)]
pub fn start_prometheus(config: PrometheusConfig) -> PrometheusHandle {

//! Liveness, readiness, and health endpoints: O(1) event-maintained readiness
//! state and an optional isolated probe listener. Not k8s-specific, though
//! Kubernetes is the motivating consumer.
//!
//! # Why this exists (#1694)
//!
//! `/readiness` used to scan the whole fleet on every probe ...

/// Select a single worker from the available workers
///
/// This is used for regular routing mode where requests go to a single worker.
///
/// # Arguments
/// * `workers` - Available workers to select from
/// * `info` - Additional information for routing decisions
fn select_worker(&self, workers: &[Arc<dyn Worker>], info: &SelectWorkerInfo) -> Option<usize>;

// Good: explains why, not what
// Use a longer timeout for large requests to avoid false positives
let timeout = if request.body_size() > LARGE_REQUEST_THRESHOLD {
    Duration::from_secs(60)
} else {
    Duration::from_secs(30)
};

// Bad: explains what (obvious from code)
// Set timeout to 30 seconds
let timeout = Duration::from_secs(30);

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

    /// Test that round robin distributes requests evenly across workers
    #[tokio::test]
    async fn test_round_robin_distribution() {
        // ...
    }

    /// Test round robin with one worker failing
    #[tokio::test]
    async fn test_round_robin_with_failing_worker() {
        // ...
    }
}

#[test]
fn test_one_instance_keeps_each_candidate_set_fair() {
    // ...
}

#[test]
fn test_past_the_cap_a_new_set_evicts_the_least_recently_used() {
    // ...
}

// Avoid
#[test]
fn test1() {}

// Good (model_gateway/tests/routing/load_balancing_test.rs)
assert_eq!(
    success_count, num_requests,
    "All requests should succeed with round robin"
);

// Avoid
assert!(success_count == num_requests);

// Good: reuse buffer
let mut buffer = Vec::with_capacity(1024);
for item in items {
    buffer.clear();
    serialize_into(&mut buffer, item)?;
    send(&buffer).await?;
}

// Bad: allocate each iteration
for item in items {
    let buffer = serialize(item)?;
    send(&buffer).await?;
}

// Good: HashMap for frequent lookups
let workers: HashMap<String, Worker> = ...;

// Bad: Vec for frequent lookups
let workers: Vec<Worker> = ...;
workers.iter().find(|w| w.url == url) // O(n) each time

// Good: concurrent operations
let (health1, health2) = tokio::join!(
    check_health(&worker1),
    check_health(&worker2),
);

// Bad: sequential when not needed
let health1 = check_health(&worker1).await;
let health2 = check_health(&worker2).await;

pub fn validate_worker_url(url: &str) -> ConfigResult<()> {
    // ...
    const ALLOWED_SCHEMES: &[&str] = &["http", "https", "grpc", "grpcs", "ipc"];
    let scheme = url.split_once("://").map_or("", |(s, _)| s);
    if !ALLOWED_SCHEMES.contains(&scheme) {
        return Err(ConfigError::InvalidValue {
            field: "worker_url".to_string(),
            value: url.to_string(),
            reason: "URL must start with a lowercase http://, https://, grpc://, grpcs://, or ipc:// scheme"
                .to_string(),
        });
    }
    // ...
}

impl std::fmt::Debug for TenantApiKeyEntry {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("TenantApiKeyEntry")
            .field("tenant_id", &self.tenant_id)
            .field("key", &"<redacted>")
            .finish()
    }
}

feat(routers): compile provider routers behind per-provider Cargo features

One Cargo feature per provider router, plus a `providers` umbrella in the
default set, so a self-hosted build can leave the provider routers out.

Signed-off-by: Your Name <your.email@example.com>