Architecting Rust Services

use std::fmt;

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub struct Money {
    cents: u64,
}

impl Money {
    pub fn from_cents(cents: u64) -> Self {
        Money { cents }
    }
    pub fn cents(self) -> u64 {
        self.cents
    }
}

impl fmt::Display for Money {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "{}.{:02}", self.cents / 100, self.cents % 100)
    }
}

#[derive(Debug, Clone, PartialEq)]
pub struct Sku(String);

impl Sku {
    pub fn parse(s: &str) -> Result<Self, DomainError> {
        let valid = s.len() == 8 && s.as_bytes()[3] == b'-' && s[..3].chars().all(|c| c.is_ascii_uppercase()) && s[4..].chars().all(|c| c.is_ascii_digit());
        if valid { Ok(Sku(s.to_string())) } else { Err(DomainError::InvalidSku(s.to_string())) }
    }
}

#[derive(Debug, PartialEq)]
pub enum DomainError {
    InvalidSku(String),
    EmptyOrder,
    TooManyItems { max: usize },
}

#[derive(Debug)]
pub struct OrderLine {
    pub sku: Sku,
    pub quantity: u32,
    pub unit_price: Money,
}

#[derive(Debug)]
pub struct Order {
    lines: Vec<OrderLine>, // private: only valid orders can be built
}

impl Order {
    pub const MAX_LINES: usize = 50;

    pub fn new(lines: Vec<OrderLine>) -> Result<Self, DomainError> {
        if lines.is_empty() {
            return Err(DomainError::EmptyOrder);
        }
        if lines.len() > Self::MAX_LINES {
            return Err(DomainError::TooManyItems { max: Self::MAX_LINES });
        }
        Ok(Order { lines })
    }

    pub fn total(&self) -> Money {
        Money::from_cents(self.lines.iter().map(|l| l.unit_price.cents() * l.quantity as u64).sum())
    }
}

fn main() {
    let line = |sku: &str, q, c| Ok::<_, DomainError>(OrderLine { sku: Sku::parse(sku)?, quantity: q, unit_price: Money::from_cents(c) });
    let order = Order::new(vec![line("ABC-1234", 2, 1999).unwrap(), line("XYZ-0001", 1, 500).unwrap()]).unwrap();
    println!("total: {}", order.total());
    println!("{:?}", Sku::parse("abc-12"));
    println!("{:?}", Order::new(vec![]).map(|o| o.total()));
}

use std::collections::HashMap;
use std::sync::Mutex;

#[derive(Debug, Clone, PartialEq)]
pub struct OrderId(pub u64);

#[derive(Debug, Clone)]
pub struct StoredOrder {
    pub id: OrderId,
    pub customer: String,
    pub total_cents: u64,
    pub placed_at: u64,
}

#[derive(Debug)]
pub enum RepoError {
    Unavailable(String),
}

// Ports, defined by the application layer.
pub trait OrderRepository {
    async fn save(&self, customer: &str, total_cents: u64, placed_at: u64) -> Result<OrderId, RepoError>;
    async fn by_customer(&self, customer: &str) -> Result<Vec<StoredOrder>, RepoError>;
}

pub trait Clock {
    fn now_unix(&self) -> u64;
}

// The use case depends on the ports, not on Postgres or the system clock.
pub struct PlaceOrder<R, C> {
    pub repo: R,
    pub clock: C,
    pub max_orders_per_customer: usize,
}

#[derive(Debug)]
pub enum PlaceOrderError {
    LimitReached,
    Storage(RepoError),
}

impl<R: OrderRepository, C: Clock> PlaceOrder<R, C> {
    pub async fn execute(&self, customer: &str, total_cents: u64) -> Result<OrderId, PlaceOrderError> {
        let existing = self.repo.by_customer(customer).await.map_err(PlaceOrderError::Storage)?;
        if existing.len() >= self.max_orders_per_customer {
            return Err(PlaceOrderError::LimitReached);
        }
        self.repo.save(customer, total_cents, self.clock.now_unix()).await.map_err(PlaceOrderError::Storage)
    }
}

// Adapters for tests: an in-memory repository and a fixed clock.
#[derive(Default)]
pub struct InMemoryOrders {
    orders: Mutex<HashMap<u64, StoredOrder>>,
}

impl OrderRepository for InMemoryOrders {
    async fn save(&self, customer: &str, total_cents: u64, placed_at: u64) -> Result<OrderId, RepoError> {
        let mut orders = self.orders.lock().unwrap();
        let id = orders.len() as u64 + 1;
        orders.insert(id, StoredOrder { id: OrderId(id), customer: customer.to_string(), total_cents, placed_at });
        Ok(OrderId(id))
    }
    async fn by_customer(&self, customer: &str) -> Result<Vec<StoredOrder>, RepoError> {
        Ok(self.orders.lock().unwrap().values().filter(|o| o.customer == customer).cloned().collect())
    }
}

pub struct FixedClock(pub u64);

impl Clock for FixedClock {
    fn now_unix(&self) -> u64 {
        self.0
    }
}

#[tokio::main]
async fn main() {
    let use_case = PlaceOrder { repo: InMemoryOrders::default(), clock: FixedClock(1_790_000_000), max_orders_per_customer: 2 };
    for _ in 0..3 {
        println!("{:?}", use_case.execute("ana", 4_498).await);
    }
    let stored = use_case.repo.by_customer("ana").await.unwrap();
    println!("stored {} orders, placed at {}", stored.len(), stored[0].placed_at);
}

use async_trait::async_trait;
use std::sync::Arc;

#[async_trait]
pub trait PaymentGateway: Send + Sync {
    async fn charge(&self, customer: &str, cents: u64) -> Result<String, String>;
}

pub struct StripeGateway;
pub struct FakeGateway;

#[async_trait]
impl PaymentGateway for StripeGateway {
    async fn charge(&self, customer: &str, cents: u64) -> Result<String, String> {
        Ok(format!("stripe charge for {customer}: {cents}"))
    }
}

#[async_trait]
impl PaymentGateway for FakeGateway {
    async fn charge(&self, _customer: &str, cents: u64) -> Result<String, String> {
        if cents > 100_000 { Err("declined".into()) } else { Ok("fake-charge-1".into()) }
    }
}

fn gateway_from_config(name: &str) -> Arc<dyn PaymentGateway> {
    match name {
        "stripe" => Arc::new(StripeGateway),
        _ => Arc::new(FakeGateway), // chosen at runtime from configuration
    }
}

#[tokio::main]
async fn main() {
    for name in ["stripe", "fake"] {
        let gateway = gateway_from_config(name);
        println!("{name}: {:?}", gateway.charge("ana", 4_498).await);
    }
    println!("fake, big amount: {:?}", gateway_from_config("fake").charge("bo", 500_000).await);
}

use std::sync::Arc;

// Ports (simplified to synchronous for brevity).
trait Clock: Send + Sync {
    fn now(&self) -> u64;
}
trait Notifier: Send + Sync {
    fn notify(&self, msg: &str) -> String;
}

// Adapters.
struct SystemClock;
impl Clock for SystemClock {
    fn now(&self) -> u64 {
        1_790_000_000 // stands in for SystemTime::now()
    }
}
struct EmailNotifier {
    smtp_host: String,
}
impl Notifier for EmailNotifier {
    fn notify(&self, msg: &str) -> String {
        format!("email via {}: {msg}", self.smtp_host)
    }
}

// Use cases hold what they need.
struct ShipOrder {
    clock: Arc<dyn Clock>,
    notifier: Arc<dyn Notifier>,
}
impl ShipOrder {
    fn execute(&self, order_id: u64) -> String {
        self.notifier.notify(&format!("order {order_id} shipped at {}", self.clock.now()))
    }
}

// Application state handed to HTTP handlers: cheap to clone.
#[derive(Clone)]
struct AppState {
    ship_order: Arc<ShipOrder>,
}

struct Config {
    smtp_host: String,
}

// The composition root.
fn build_app(config: &Config) -> AppState {
    let clock: Arc<dyn Clock> = Arc::new(SystemClock);
    let notifier: Arc<dyn Notifier> = Arc::new(EmailNotifier { smtp_host: config.smtp_host.clone() });
    AppState { ship_order: Arc::new(ShipOrder { clock, notifier }) }
}

fn main() {
    let config = Config { smtp_host: "smtp.internal:587".into() };
    let state = build_app(&config);
    println!("{}", state.ship_order.execute(1001));
}

use axum::{Json, Router, extract::Path, http::StatusCode, response::{IntoResponse, Response}, routing::get};
use serde_json::json;
use tower::ServiceExt;

// Application-layer error: what can go wrong, in business terms.
#[derive(Debug, thiserror::Error)]
enum AppError {
    #[error("order {0} not found")]
    NotFound(u64),
    #[error("order {0} was already shipped")]
    AlreadyShipped(u64),
    #[error("storage unavailable")]
    Storage(#[source] std::io::Error),
}

// The single place where errors become HTTP responses.
impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, code) = match &self {
            AppError::NotFound(_) => (StatusCode::NOT_FOUND, "order_not_found"),
            AppError::AlreadyShipped(_) => (StatusCode::CONFLICT, "order_already_shipped"),
            AppError::Storage(e) => {
                tracing::error!(error = %e, "storage failure"); // log details, don't leak them
                (StatusCode::SERVICE_UNAVAILABLE, "temporarily_unavailable")
            }
        };
        let message = if status.is_server_error() { "please retry later".to_string() } else { self.to_string() };
        (status, Json(json!({ "error": code, "message": message }))).into_response()
    }
}

async fn ship(Path(id): Path<u64>) -> Result<Json<serde_json::Value>, AppError> {
    match id {
        1 => Ok(Json(json!({ "order": 1, "status": "shipped" }))),
        2 => Err(AppError::AlreadyShipped(2)),
        3 => Err(AppError::Storage(std::io::Error::other("connection refused"))),
        other => Err(AppError::NotFound(other)),
    }
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/orders/{id}/ship", get(ship));
    for id in [1, 2, 3, 9] {
        let req = axum::http::Request::get(format!("/orders/{id}/ship")).body(axum::body::Body::empty()).unwrap();
        let res = app.clone().oneshot(req).await.unwrap();
        let status = res.status().as_u16();
        let body = axum::body::to_bytes(res.into_body(), 1024).await.unwrap();
        println!("{id}: {status} {}", String::from_utf8_lossy(&body));
    }
}

use std::collections::HashMap;
use std::time::Duration;

#[derive(Debug)]
struct Config {
    port: u16,
    database_url: String,
    db_pool_size: u32,
    request_timeout: Duration,
    payment_provider: PaymentProvider,
}

#[derive(Debug)]
enum PaymentProvider {
    Stripe { api_key_set: bool },
    Fake,
}

fn load(env: &HashMap<&str, &str>) -> Result<Config, Vec<String>> {
    let mut errors = Vec::new();
    let get = |key: &str| env.get(key).copied();

    let port = get("PORT").unwrap_or("8080").parse::<u16>().map_err(|e| errors.push(format!("PORT: {e}"))).unwrap_or(0);
    let database_url = get("DATABASE_URL").map(str::to_string).unwrap_or_else(|| {
        errors.push("DATABASE_URL: required".into());
        String::new()
    });
    let db_pool_size = match get("DB_POOL_SIZE").unwrap_or("10").parse::<u32>() {
        Ok(n) if (1..=100).contains(&n) => n,
        Ok(n) => {
            errors.push(format!("DB_POOL_SIZE: {n} is outside 1..=100"));
            0
        }
        Err(e) => {
            errors.push(format!("DB_POOL_SIZE: {e}"));
            0
        }
    };
    let request_timeout = Duration::from_millis(get("REQUEST_TIMEOUT_MS").unwrap_or("5000").parse().unwrap_or_else(|_| {
        errors.push("REQUEST_TIMEOUT_MS: not a number".into());
        0
    }));
    let payment_provider = match get("PAYMENT_PROVIDER").unwrap_or("fake") {
        "stripe" => PaymentProvider::Stripe { api_key_set: get("STRIPE_API_KEY").is_some() },
        "fake" => PaymentProvider::Fake,
        other => {
            errors.push(format!("PAYMENT_PROVIDER: unknown value {other:?}"));
            PaymentProvider::Fake
        }
    };
    if let PaymentProvider::Stripe { api_key_set: false } = payment_provider {
        errors.push("STRIPE_API_KEY: required when PAYMENT_PROVIDER=stripe".into());
    }

    if errors.is_empty() { Ok(Config { port, database_url, db_pool_size, request_timeout, payment_provider }) } else { Err(errors) }
}

fn main() {
    let good = HashMap::from([("DATABASE_URL", "postgres://db/orders"), ("PAYMENT_PROVIDER", "stripe"), ("STRIPE_API_KEY", "sk_live_...")]);
    println!("{:#?}", load(&good).unwrap());

    let bad = HashMap::from([("PORT", "80800"), ("DB_POOL_SIZE", "500"), ("PAYMENT_PROVIDER", "stripe")]);
    match load(&bad) {
        Ok(_) => println!("unexpected"),
        Err(errors) => {
            println!("invalid configuration:");
            for e in errors {
                println!("  - {e}");
            }
        }
    }
}

use std::collections::HashMap;
use std::sync::{Arc, RwLock};
use std::sync::atomic::{AtomicU64, Ordering};

/// A component with its own synchronization, exposing only safe operations.
#[derive(Default)]
struct PriceCache {
    prices: RwLock<HashMap<String, u64>>,
    hits: AtomicU64,
    misses: AtomicU64,
}

impl PriceCache {
    fn get_or_load(&self, sku: &str, load: impl FnOnce() -> u64) -> u64 {
        if let Some(p) = self.prices.read().unwrap().get(sku) {
            self.hits.fetch_add(1, Ordering::Relaxed);
            return *p;
        }
        self.misses.fetch_add(1, Ordering::Relaxed);
        let price = load(); // not holding the lock while loading
        self.prices.write().unwrap().insert(sku.to_string(), price);
        price
    }
}

#[derive(Clone)]
struct AppState {
    prices: Arc<PriceCache>,
    service_name: Arc<str>, // immutable config: no lock needed
}

fn handle(state: &AppState, sku: &str) -> String {
    let price = state.prices.get_or_load(sku, || 1999);
    format!("[{}] {sku} costs {price}", state.service_name)
}

fn main() {
    let state = AppState { prices: Arc::new(PriceCache::default()), service_name: Arc::from("catalog") };
    let handles: Vec<_> = (0..4)
        .map(|i| {
            let state = state.clone(); // cheap: two Arc clones
            std::thread::spawn(move || handle(&state, if i % 2 == 0 { "ABC-1234" } else { "XYZ-0001" }))
        })
        .collect();
    for h in handles {
        let _ = h.join().unwrap();
    }
    println!("{}", handle(&state, "ABC-1234"));
    let (hits, misses) = (state.prices.hits.load(Ordering::Relaxed), state.prices.misses.load(Ordering::Relaxed));
    println!("lookups: {}, misses at least 2: {}", hits + misses, misses >= 2);
}