Configuration support

[JunichiSugiura]

User story

As an application developer, I'd like a plugin that allows users to easily override app default configuration.

Example

[dependency]
config = "0.13"
serde = { version = "1.0", features = ["derive"] }
dirs = "4.0"

use dip::prelude::*;

fn main() {
    App::new()
        .add_plugin(ConfigPlugin)
        .add_system(log_config)
        .run();
}

#[ConfigPlugin]
#[derive(Debug, Deserialize)]
struct Config {
    base_url: String,
    backend: Backend,
}

#[derive(Debug, Deserialize)]
struct Backend {
    api_key: String,
    api_secret: String,
}

fn log_config(config: Res<Config>) {
    println!("{config:#?}");
}

Specs

• Config support #116

User config file path priority

1. env
2. ./{CARGO_PKG_NAME} (e.g. project root): mainly for development purposes
3. $HOME/.{CARGO_PKG_NAME}
4. $HOME/.config/{CARGO_PKG_NAME}/{CARGO_PKG_NAME}
5. $HOME/.config/{CARGO_PKG_NAME}

Supported file types

mehcode/config-rs#feature-flags

• toml
• yaml
• json
• json5
• ini
• ron

Cross-platform path

dirs-dev/dirs-rs#features

• home_dir
  • Linux/Redox: Some($HOME)
  • Windows: Some({FOLDERID_Profile})
  • macOS: Some($HOME)
• config_dir
  • Linux/Redox: Some($XDG_CONFIG_HOME) or Some($HOME/.config)
  • Windows: Some({FOLDERID_RoamingAppData})
  • macOS: Some($HOME/Library/Application Support)

ConfigPlugin derive macro

Options

• CONFIG_PATH env
  • mainly for development or testing purposes
  • e.g. CONFIG_PATH=config/development cargo run
• default_paths
  • enable/disable default lookup paths
  • e.g.

    ConfigPlugin::new().default_paths(false)

  • default to true
• default_from_str
  • To override lookup path for default file (eventually included in binary)
  • default to "config/default.toml"
  • e.g.

    ConfigPlugin:new().default_from_str("config/default.yaml")

• default_file_format
  • To override default file format
  • e.g.

    ConfigPlugin::new().default_file_format(config::FileFormat::Yaml)

  • default to config::FileFormat::Toml
• env_prefix
  • e.g.

    ConfigPlugin::new().env_prefix("APP") // → `MYAPP__BASE_URL` instead of `BASE_URL`

  • default to ""
• env_separator
  • e.g.

    ConfigPlugin::new().env_separator("___") // → BACKEND___API_KEY

  • default to "__"
    • to avoid conflicts between field name with underscore and nested field name

Watch support

• File change detection
• example

Async source support

• Fetch config file remotely
• example

Limitation

• only read, no write support for now

Dependencies

• mehcode/config-rs: ⚙️ Layered configuration system for Rust applications (with strong support for 12-factor applications).
• serde-rs/serde: Serialization framework for Rust
• dirs-dev/dirs-rs: a low-level library that provides config/cache/data paths, following the respective conventions on Linux, macOS and Windows