Configuration

# config/default.toml
[server]
host = "127.0.0.1"
port = 3000

[database]
max_connections = 10
acquire_timeout_secs = 3

# config/production.toml
[server]
host = "0.0.0.0"

[database]
max_connections = 30

use std::fmt;

use config::{Config, Environment, File};
use serde::Deserialize;

#[derive(Debug, Deserialize)]
pub struct Settings {
    pub environment: String,
    pub server: Server,
    pub database: Database,
    pub jwt: Jwt,
}

#[derive(Debug, Deserialize)]
pub struct Server {
    pub host: String,
    pub port: u16,
}

#[derive(Debug, Deserialize)]
pub struct Database {
    pub url: Secret,
    pub max_connections: u32,
    pub acquire_timeout_secs: u64,
}

#[derive(Debug, Deserialize)]
pub struct Jwt {
    pub secret: Secret,
}

/// A string that never appears in logs or Debug output.
#[derive(Deserialize)]
#[serde(transparent)]
pub struct Secret(String);

impl Secret {
    pub fn expose(&self) -> &str {
        &self.0
    }
}

impl fmt::Debug for Secret {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("Secret(***)")
    }
}

impl Settings {
    pub fn load() -> Result<Self, config::ConfigError> {
        let environment = std::env::var("APP_ENV").unwrap_or_else(|_| "development".into());
        Config::builder()
            .set_default("environment", environment.clone())?
            .add_source(File::with_name("config/default"))
            .add_source(File::with_name(&format!("config/{environment}")).required(false))
            // BOOKSHELF__DATABASE__URL -> database.url, BOOKSHELF__SERVER__PORT -> server.port
            .add_source(Environment::with_prefix("BOOKSHELF").prefix_separator("__").separator("__"))
            .build()?
            .try_deserialize()
    }

    /// Checks that types alone cannot express.
    pub fn validate(&self) -> Result<(), String> {
        if self.jwt.secret.expose().len() < 32 {
            return Err("jwt.secret must be at least 32 bytes".into());
        }
        if !self.database.url.expose().starts_with("postgres://") {
            return Err("database.url must be a postgres:// URL".into());
        }
        if self.environment == "production" && self.server.host == "127.0.0.1" {
            return Err("server.host 127.0.0.1 is unreachable inside a container".into());
        }
        Ok(())
    }
}

fn main() {
    // local development only: load .env if present (never in production images)
    let _ = dotenvy::dotenv();

    let settings = match Settings::load().map_err(|e| e.to_string()).and_then(|s| s.validate().map(|()| s)) {
        Ok(settings) => settings,
        Err(err) => {
            eprintln!("invalid configuration: {err}");
            std::process::exit(2);
        }
    };
    println!("{settings:#?}"); // safe: secrets print as Secret(***)
}

$ BOOKSHELF__DATABASE__URL="postgres://bookshelf:$DB_PASSWORD@localhost/bookshelf" \
  BOOKSHELF__JWT__SECRET="$(openssl rand -hex 32)" APP_ENV=production cargo run
Settings {
    environment: "production",
    server: Server {
        host: "0.0.0.0",
        port: 3000,
    },
    database: Database {
        url: Secret(***),
        max_connections: 30,
        acquire_timeout_secs: 3,
    },
    jwt: Jwt {
        secret: Secret(***),
    },
}
$ BOOKSHELF__JWT__SECRET=short cargo run
invalid configuration: missing configuration field "database.url"

use figment::{
    Figment,
    providers::{Env, Format, Serialized, Toml},
};
use serde::{Deserialize, Serialize};

#[derive(Debug, Deserialize, Serialize)]
struct Server {
    host: String,
    port: u16,
}

#[derive(Debug, Deserialize, Serialize)]
struct AppConfig {
    server: Server,
}

#[derive(Debug, Deserialize)]
struct Flat {
    port: u16,
    #[serde(default)]
    log_json: bool,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // figment: defaults < file < environment, with provenance in error messages
    let defaults = AppConfig { server: Server { host: "127.0.0.1".into(), port: 3000 } };
    let config: AppConfig = Figment::from(Serialized::defaults(defaults))
        .merge(Toml::file("config/default.toml"))
        .merge(Env::prefixed("BOOKSHELF_").split("__")) // BOOKSHELF_SERVER__PORT -> server.port
        .extract()?;
    println!("{config:?}");

    // envy: PORT=8080 LOG_JSON=true -> Flat { port: 8080, log_json: true }
    match envy::from_env::<Flat>() {
        Ok(flat) => println!("{flat:?}"),
        Err(err) => println!("envy: {err}"),
    }
    Ok(())
}