Crate config_hierarchy 

Module :: config_hierarchy

A trait-based hierarchical configuration management library for Rust applications, featuring a 6-level priority resolution system, automatic source tracking, and cross-platform file operations with atomic writes.

Overview

config_hierarchy eliminates configuration ambiguity by tracking the exact source of every configuration value. Users implement three traits and compose a zero-cost ConfigManager< D, P, V > type.

Key Capabilities:

• Priority-based resolution across 6 configuration layers (Runtime → Env → LocalCurrent → LocalParent → Global → Default)
• Source tracking for every configuration value via ConfigSource enum
• Atomic file operations with cross-platform file locking (fs2)
• Type detection with automatic string-to-type conversion
• Trait-based architecture for application-specific customization

Installation

Add config_hierarchy to your project’s Cargo.toml:

[dependencies]
config_hierarchy = { version = "0.5", features = ["full"] }

Feature Flags

Feature	Description
enabled	Core resolution engine — hierarchy, source tracking, type detection
file_ops	File persistence — YAML I/O, atomic writes, file locking, path discovery
display_table	Table output formatter
display_json	JSON output formatter
display_yaml	YAML output formatter
full	All features enabled

Quick Start

Implement three traits and compose a type alias:

use config_hierarchy::{ ConfigManager, ConfigDefaults, ConfigPaths, ConfigValidator };
use std::collections::HashMap;
use serde_json::Value as JsonValue;

struct AppDefaults;
impl ConfigDefaults for AppDefaults
{
  fn get_defaults() -> HashMap< String, JsonValue >
  {
    let mut map = HashMap::new();
    map.insert( "timeout".into(), JsonValue::Number( 30.into() ) );
    map.insert( "retries".into(), JsonValue::Number( 3.into() ) );
    map
  }

  fn get_parameter_names() -> Vec< &'static str >
  {
    vec![ "timeout", "retries" ]
  }
}

struct AppPaths;
impl ConfigPaths for AppPaths
{
  fn app_name() -> &'static str { "myapp" }
}

struct AppValidator;
impl ConfigValidator for AppValidator
{
  fn validate_parameter( _name : &str, _value : &JsonValue )
    -> Result< (), config_hierarchy::ValidationError >
  {
    Ok( () )
  }

  fn validate_all( _config : &HashMap< String, ( JsonValue, config_hierarchy::ConfigSource ) > )
    -> Vec< config_hierarchy::ValidationError >
  {
    Vec::new()
  }
}

type AppConfig = ConfigManager< AppDefaults, AppPaths, AppValidator >;

fn main()
{
  let runtime_overrides = HashMap::new();
  let config = AppConfig::resolve_all_config( &runtime_overrides );

  for ( key, ( value, source ) ) in &config
  {
    println!( "{key}: {value:?} (from {source:?})" );
  }
}

Output (with no config files or env vars present):

timeout: Number(30) (from Default)
retries: Number(3) (from Default)

If MYAPP_TIMEOUT=60 is set:

timeout: Number(60) (from Environment)
retries: Number(3) (from Default)

Documentation

See docs/ for complete specifications:

Document	Description
Feature: Config Hierarchy	All crate behaviors and responsibilities
Invariant: Resolution Hierarchy	Priority order, path formulas, dual-pattern rule
API: ConfigPaths Trait	All 15 path and env var configuration methods
API: ConfigDefaults Trait	Default values and parameter enumeration
API: ConfigValidator Trait	Per-value and cross-parameter validation
Algorithm: Type Detection	String-to-type conversion rules
Format: Config File Format	YAML file structure and fields

Tasks

See task/ for active implementation work items.

License

MIT Generic hierarchical configuration with 6-level priority and source tracking

Implement 3 traits then use ConfigManager for complete config handling

Structs

ConfigManager

Generic configuration manager with hierarchical resolution

NoValidator

Pass-through validator that accepts all configuration values without validation

ValidationError

Configuration validation error

Enums

ConfigSource

Configuration source tracking where values come from in the hierarchy

EnvVarCasing

Environment variable casing strategy

Traits

ConfigDefaults

Provides application-specific default configuration values

ConfigPaths

Provides application-specific path configuration

ConfigValidator

Provides application-specific validation logic

Functions

detect_and_convert_value

Intelligently detect value type and convert to appropriate JSON representation

discover_local_configs

Discover all local config files from current directory up to root Returns paths in priority order (current dir first, root last)

get_global_config_dir

Get OS-specific global config directory Priority: $PRO/.persistent/.{app_name} > OS-specific config dir

get_global_config_path

Get global config file path

get_local_config_path

Get local config file path in current directory

json_value_to_display_string

Extract clean string value from JsonValue

resolve_config_value

Resolve configuration value using full 6-level hierarchy Returns (value, source) tuple