rust-settings

Native Rust port of go.jtlabs.io/settings.

This workspace provides a layered configuration crate that composes settings from:

1. base file (yaml/json)
2. defaults map
3. CLI-provided override files
4. env-provided override files
5. CLI arguments
6. environment variables

Later sources override earlier sources.

CI and Coverage

• CI workflow: /.github/workflows/ci.yml
• Coverage badge is powered by Codecov.
• Every CI run uploads coverage artifacts:
  • coverage-html (download and open index.html)
  • coverage-lcov (lcov.info)
• CI uploads lcov.info to Codecov for tracked percentage coverage.
• Pushes to main publish HTML coverage to GitHub Pages.
  • Expected URL: https://jtlabsio.github.io/rust-settings/
  • If your repo owner/name differs, update this URL accordingly.
  • If the repository is private, add CODECOV_TOKEN in GitHub repo secrets.

Crates

• crates/settings: runtime API (gather, ReadOptions, errors)
• crates/settings-derive: #[derive(SettingsSchema)] and #[settings(...)] metadata attributes

Quick Usage

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use settings::{gather, options, SettingsSchema};

#[derive(Debug, Deserialize, Serialize, SettingsSchema)]
struct Config {
    #[settings(arg = "--name", env = "APP_NAME")]
    name: String,
    #[settings(arg = "--created", env = "APP_CREATED")]
    created: DateTime<Utc>,
}

let mut cfg = Config {
    name: "default".into(),
    created: DateTime::parse_from_rfc3339("2020-01-01T00:00:00.000Z")
        .unwrap()
        .with_timezone(&Utc),
};

let opts = options()
    .with_base_path("./defaults.yaml")
    .with_default("name", "fallback")
    .with_env_override(vec!["GO_ENV"])
    .with_env_search_paths(vec!["./", "./config"])
    .with_env_search_pattern("config.%s");

gather(opts, &mut cfg)?;
# Ok::<(), settings::SettingsError>(())

Notes

• Attribute mappings are ergonomic defaults; explicit maps in ReadOptions override derive-provided mappings.
• Runtime injection helpers (with_runtime_args, with_runtime_env) are available for deterministic testing.