zirv_queue/config/

mod.rs

use std::sync::OnceLock;

use dotenvy::dotenv;
use serde::Deserialize;

/// A single global instance of the `Config` that is set once at runtime.
///
/// This static utilizes [`OnceLock`] to ensure it can be initialized only once.
/// Access it via [`Config::get_config`], which will call [`Config::from_env`]
/// if the config hasn’t been set yet.
///
/// # Example
///
/// ```rust
/// // Typically you would call `Config::init()` early in your program:
/// // Config::init().expect("Failed to initialize config");
/// // Then, later you can access the global config:
/// // let cfg = Config::get_config();
/// // println!("Database URL: {}", cfg.database_url);
/// ```
static GLOBAL_CONFIG: OnceLock<Config> = OnceLock::new();

/// Application-wide configuration loaded from environment variables.
///
/// The struct fields correspond to specific environment variables. Some fields
/// have default values specified by helper functions (e.g. `default_max_concurrent_jobs`).
///
/// # Fields
///
/// - `database_url`: **Required**. Must be present in the environment as `DATABASE_URL`.
/// - `max_concurrent_jobs`: Optional. Defaults to `4` if not set.
/// - `tick_rate_ms`: Optional. Defaults to `1000` if not set.
/// - `max_retry_attempts`: Optional. Defaults to `3` if not set.
/// - `retry_interval_ms`: Optional. Defaults to `300_000` (5 minutes) if not set.
///
/// # Example
///
/// ```rust
/// // Loading from environment:
/// // 1. Optionally load .env file
/// // 2. Read config variables (DATABASE_URL is required)
///
/// // let cfg = Config::from_env();
/// // println!("Loaded config: {:?}", cfg);
/// ```
#[derive(Deserialize, Debug)]
pub struct Config {
    /// The URL for your database connection. Must be set via `DATABASE_URL`.
    pub database_url: String,

    /// Maximum number of concurrent jobs the application will handle.
    /// Defaults to `4` if not present in the environment.
    #[serde(default = "default_max_concurrent_jobs")]
    pub max_concurrent_jobs: usize,

    /// Interval in milliseconds at which some recurring task or loop should tick.
    /// Defaults to `1000` if not set.
    #[serde(default = "default_tick_rate_ms")]
    pub tick_rate_ms: u64,

    /// Number of retry attempts for a failed operation. Defaults to `3`.
    #[serde(default = "default_max_retry_attempts")]
    pub max_retry_attempts: i32,

    /// Interval in milliseconds between retries. Defaults to `300_000` (5 minutes).
    #[serde(default = "default_retry_interval_ms")]
    pub retry_interval_ms: i64,
}

/// Provides a default value of `4` for `max_concurrent_jobs`.
fn default_max_concurrent_jobs() -> usize {
    4
}

/// Provides a default value of `1000` for `tick_rate_ms`.
fn default_tick_rate_ms() -> u64 {
    1000
}

/// Provides a default value of `3` for `max_retry_attempts`.
fn default_max_retry_attempts() -> i32 {
    3
}

/// Provides a default value of `300_000` (5 minutes) for `retry_interval_ms`.
fn default_retry_interval_ms() -> i64 {
    300_000
}

impl Config {
    /// Initializes and sets the global [`Config`] once using environment variables.
    ///
    /// This function loads a `.env` file (if present) and then constructs a `Config`
    /// from the environment using [`envy::from_env`].
    /// It attempts to store the resulting `Config` in the global static `GLOBAL_CONFIG`.
    ///
    /// If the global config is already set, an error is returned.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - **Any required environment variable** is missing (e.g. `DATABASE_URL`),
    /// - or if the config has already been set and you tried to set it again.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// // Typically called early in the program:
    /// // Config::init().expect("Failed to initialize config");
    /// ```
    pub fn init() -> Result<(), Box<dyn std::error::Error>> {
        dotenv().ok();

        let config = envy::from_env::<Config>()?;

        match GLOBAL_CONFIG.set(config) {
            Ok(_) => Ok(()),
            Err(_) => Err("Failed to set global config".into()),
        }
    }

    /// Constructs a new [`Config`] from environment variables without setting the global.
    ///
    /// This function will:
    /// 1. Load a `.env` file if present,
    /// 2. Parse environment variables into a [`Config`].
    ///
    /// # Panics
    ///
    /// Panics if any required variable (e.g. `DATABASE_URL`) is missing or invalid.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use zirv_queue::Config; // Hidden import so `Config` is recognized in the doc test
    /// let cfg = Config::from_env(); // Panics if required variables are missing
    /// println!("{:?}", cfg);
    /// ```
    pub fn from_env() -> Self {
        dotenv().ok();
        envy::from_env::<Config>().expect("Failed to read configuration from environment")
    }

    /// Returns a reference to the globally stored [`Config`].
    ///
    /// If the global config has not been set yet, this function will call
    /// [`Config::from_env`] to populate it for the first time.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// // Ensure it's initialized once, typically at startup:
    /// // Config::init().ok();
    ///
    /// // Retrieve the config anywhere else in the code:
    /// # use zirv_queue::Config; // Hidden import so `Config` is recognized in the doc test
    /// let cfg = Config::get_config();
    /// println!("Current DB URL: {}", cfg.database_url);
    /// ```
    pub fn get_config() -> &'static Config {
        GLOBAL_CONFIG.get_or_init(Config::from_env)
    }
}

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

    /// Helper function: Remove relevant environment variables for a clean test slate.
    fn clear_env_vars() {
        env::remove_var("DATABASE_URL");
        env::remove_var("MAX_CONCURRENT_JOBS");
        env::remove_var("TICK_RATE_MS");
        env::remove_var("MAX_RETRY_ATTEMPTS");
        env::remove_var("RETRY_INTERVAL_MS");
    }

    /// Test 1: Ensure default values are used for optional fields when they're not set.
    ///         `DATABASE_URL` is mandatory, so we set it to avoid panic.
    #[test]
    fn test_defaults_when_env_not_set() {
        clear_env_vars();
        env::set_var("DATABASE_URL", "mysql://root:password@localhost/db");

        let config = Config::from_env();

        // Required field
        assert_eq!(config.database_url, "mysql://root:password@localhost/db");

        // Check defaults
        assert_eq!(config.max_concurrent_jobs, 4);
        assert_eq!(config.tick_rate_ms, 1000);
        assert_eq!(config.max_retry_attempts, 3);
        assert_eq!(config.retry_interval_ms, 300_000);
    }

    /// Test 2: Ensure all set environment variables are properly loaded.
    ///         This includes both required and optional fields.
    #[test]
    fn test_custom_env_values() {
        clear_env_vars();

        env::set_var("DATABASE_URL", "postgres://user:pass@localhost/custom_db");
        env::set_var("MAX_CONCURRENT_JOBS", "8");
        env::set_var("TICK_RATE_MS", "500");
        env::set_var("MAX_RETRY_ATTEMPTS", "10");
        env::set_var("RETRY_INTERVAL_MS", "600000"); // 10 minutes

        let config = Config::from_env();

        assert_eq!(config.database_url, "postgres://user:pass@localhost/custom_db");
        assert_eq!(config.max_concurrent_jobs, 8);
        assert_eq!(config.tick_rate_ms, 500);
        assert_eq!(config.max_retry_attempts, 10);
        assert_eq!(config.retry_interval_ms, 600_000);
    }

    /// Test 3: Confirm that omitting the required `DATABASE_URL` panics in `from_env()`.
    #[test]
    #[should_panic(expected = "Failed to read configuration from environment")]
    fn test_missing_db_url_panics() {
        clear_env_vars();
        // Not setting DATABASE_URL should trigger a panic in from_env().
        let _config = Config::from_env();
    }

    /// Test 4: Validate `get_config()` lazy-initializes the global config if `init()` wasn’t called.
    ///         We also check that once set, `get_config()` always returns the same reference.
    #[test]
    fn test_get_config_lazy_initialization() {
        clear_env_vars();
        env::set_var("DATABASE_URL", "lazy://init.db");
        // Not calling `Config::init()` explicitly

        let cfg_ref_1 = Config::get_config();
        assert_eq!(cfg_ref_1.database_url, "lazy://init.db");

        // Setting environment variables after the first get_config() call
        // won't affect the config because it's already been initialized.
        env::set_var("DATABASE_URL", "changed://won_t_take_effect.db");

        let cfg_ref_2 = Config::get_config();
        assert_eq!(cfg_ref_1 as *const Config, cfg_ref_2 as *const Config);
        assert_eq!(cfg_ref_2.database_url, "lazy://init.db");
    }

    /// Test 5: Demonstrate how invalid numeric environment variables fail in `from_env()`.
    ///         We expect a panic from envy if parsing fails.
    #[test]
    #[should_panic(expected = "Failed to read configuration from environment")]
    fn test_invalid_numeric_parse_panics() {
        clear_env_vars();

        env::set_var("DATABASE_URL", "mysql://root:pwd@localhost/invalid_parse");
        env::set_var("MAX_CONCURRENT_JOBS", "not_a_number");

        // This should panic because "not_a_number" cannot be parsed into a usize.
        let _config = Config::from_env();
    }
}