Module config 

Configuration management with 8-layer cascade.

Provides a hierarchical configuration system matching hyperi-pylib (Python) and hyperi-golib (Go). Configuration is loaded from multiple sources with clear priority ordering.

Cascade Priority (highest to lowest)

1. CLI arguments (via clap integration)
2. Environment variables (with configurable prefix)
3. .env file (loaded via dotenvy)
4. PostgreSQL (optional, via config-postgres feature)
5. settings.{env}.yaml (environment-specific)
6. settings.yaml (base settings)
7. defaults.yaml
8. Hard-coded defaults

How .env Files Work in the Cascade

The .env file is loaded early in the cascade using dotenvy::dotenv(). This populates the process environment, so .env values become available via std::env::var(). The cascade then reads environment variables at layer 2, which includes both real environment variables AND .env values.

Important: Real environment variables take precedence over .env values because dotenvy does NOT overwrite existing environment variables.

Priority (highest wins):
┌─────────────────────────────────────────────────────────────┐
│ 1. CLI arguments (merged via merge_cli())                   │
├─────────────────────────────────────────────────────────────┤
│ 2. Environment variables (PREFIX_KEY)                       │
│    ↑ Includes .env values (loaded into env by dotenvy)      │
│    ↑ Real env vars win over .env (dotenvy doesn't overwrite)│
├─────────────────────────────────────────────────────────────┤
│ 3. PostgreSQL config (if config-postgres feature enabled)   │
├─────────────────────────────────────────────────────────────┤
│ 4. settings.{env}.yaml (e.g., settings.production.yaml)     │
├─────────────────────────────────────────────────────────────┤
│ 5. settings.yaml                                            │
├─────────────────────────────────────────────────────────────┤
│ 6. defaults.yaml                                            │
├─────────────────────────────────────────────────────────────┤
│ 7. Hard-coded defaults (lowest priority)                    │
└─────────────────────────────────────────────────────────────┘

Environment Variable Naming

Use the env_compat module for standardised environment variable names with legacy alias support and deprecation warnings.

Example

use hyperi_rustlib::config::{self, ConfigOptions};

// Initialise with env prefix
config::setup(ConfigOptions {
    env_prefix: "MYAPP".into(),
    ..Default::default()
}).unwrap();

// Access configuration
let cfg = config::get();
let host = cfg.get_string("database.host").unwrap_or_default();
let port = cfg.get_int("database.port").unwrap_or(5432);

Modules

env_compat

Environment variable compatibility layer.

flat_env

Flat environment variable override helpers.

registry

Reflectable configuration registry.

sensitive

Re-exports SensitiveString from the crate root for backward compatibility.

Structs

Config

Configuration manager wrapping Figment.

ConfigOptions

Configuration options.

Enums

ConfigError

Configuration errors.

Functions

get

Get the global configuration.

setup

Initialise the global configuration.

try_get

Try to get the global configuration.