config-lib
_{^{RUST CONFIGURATION LIBRARY}}

Enterprise-Grade Multi-Format Configuration Library
High-performance configuration management with advanced caching, validation, and format preservation

config-lib is a high-performance, enterprise-grade Rust configuration library that provides unified access to 8 different configuration formats through a single, consistent API. Built from the ground up for production environments, it offers advanced features like sub-50ns cached access, hot reloading, audit logging, and comprehensive type safety.

Unlike traditional configuration libraries that focus on a single format, config-lib provides seamless multi-format support with automatic format detection, allowing you to mix and match configuration sources (JSON for APIs, TOML for Rust projects, HCL for DevOps, XML for enterprise systems) while maintaining a unified programming interface. The library automatically handles type conversions, validation, and format preservation, making it ideal for complex applications that need to integrate with multiple configuration ecosystems.

With its enterprise-focused architecture, config-lib delivers production-grade features including comprehensive error handling with zero unsafe code, multi-tier caching with lock-free read paths, environment variable overrides with smart prefix matching, and built-in audit logging for compliance requirements. The library is designed for high-throughput applications, targeting sub-50ns cached access times on hot paths and supporting hot reloading without service interruption.

Features

Multi-Format Support

CONF - Built-in parser for standard .conf files (default)
INI - Full INI file parsing with sections, comments, and data type detection
JSON - JSON format with edit capabilities and serialization
XML - Zero-copy XML parsing with quick-xml for Java/.NET environments
HCL - HashiCorp Configuration Language for DevOps workflows
Properties - Complete Java .properties file parsing with Unicode and escaping
NOML - Advanced configuration with dynamic features (feature: noml)
TOML - TOML format with format preservation (feature: toml)

Enterprise Performance

Sub-50ns Cache Access Target - Multi-tier caching designed for sub-50ns reads on hot paths
Lock-Free Notification Dispatch - on_change handlers fire inline from the reloader thread via ArcSwap<Vec<Handler>>; one atomic load + N closure calls, no channel allocation
Zero-Copy Parsing - Minimized allocations and string operations where possible
Lock-Free Read Paths - Poison-resistant locking with graceful failure recovery
Hot Value Cache - Ultra-fast access for frequently used values
Cache Hit Ratio Tracking - Built-in performance statistics and monitoring

Performance numbers, methodology, and tuning guidance live in docs/PERFORMANCE.md. The committed criterion harnesses in benches/ produce the measured baselines.

Production Features

Configuration Hot Reloading - File watching with thread-safe Arc swapping
Audit Logging System - Structured event logging with multiple sinks and severity filtering
Environment Variable Overrides - Smart caching with prefix matching and type conversion
Schema Validation - Trait-based validation system with feature gates
Format Preservation - Maintains comments, whitespace, and original formatting
Async Native - Full async/await support throughout the API

Reliability & Safety

Zero Unsafe Code - All unwrap() calls eliminated, comprehensive error handling
Type Safety - Rich type system with automatic conversions and validation
Enterprise Error Handling - Production-ready error messages with context preservation
Comprehensive Testing - Extensive unit, integration, and doc test coverage

Why Choose config-lib?

Unified Multi-Format Support

Unlike single-format libraries, config-lib provides seamless access to 8 configuration formats through one consistent API. No need to learn different libraries for TOML, JSON, XML, and HCL - one API handles them all with automatic format detection.

Enterprise-Grade Performance

Multi-tier caching with lock-free read paths is designed to deliver sub-50ns cached access on hot paths. Built for high-throughput applications with minimal performance overhead.

Production-Ready Reliability

Zero unsafe code, comprehensive error handling, and poison-resistant locking ensure your configuration system won't crash your application. Extensive testing coverage validates edge cases and error conditions.

Developer Experience First

Rich type system with automatic conversions, format preservation for round-trip editing, and detailed error messages with source location context. No more cryptic parsing errors or manual type casting.

Advanced Enterprise Features

Hot reloading without service interruption, structured audit logging for compliance, environment variable overrides with smart caching, and schema validation with custom rules - features typically requiring multiple libraries.

Installation

Add to your Cargo.toml:

[dependencies]
config-lib = "1.0"

# For enhanced functionality, enable optional features:
config-lib = { version = "1.0", features = [
    "json",           # JSON format support with serialization
    "xml",            # XML format support with quick-xml backend  
    "hcl",            # HashiCorp Configuration Language support
    "toml",           # TOML format support with preservation
    "noml",           # NOML format support with dynamic features
    "validation",     # Schema validation and type checking
    "async",          # Async operations and hot reloading
    "env-override",   # Environment variable override system
    "audit",          # Audit logging and compliance features
] }

Feature Recommendations:

Minimal: Use default features for CONF/INI/Properties support
Web Applications: Add "json", "env-override", "validation"
DevOps Tools: Add "hcl", "toml", "async", "audit"
Enterprise Systems: Add "xml", "validation", "audit", "env-override"
Full Featured: Include all features for maximum flexibility

Quick Start

use config_lib::Config;

// Parse any supported format automatically
let mut config = Config::from_string(r#"
[database]
host = "localhost"
port = 5432
username = "admin"

[app]
name = "MyApp"
debug = true
"#, None)?;

// Access values with type safety
let host = config.get("database.host")?.as_string()?;
let port = config.get("database.port")?.as_integer()?;
let debug = config.get("app.debug")?.as_bool()?;

// Modify configuration (preserves format and comments)
config.set("database.port", 5433)?;
config.set("app.version", "1.0.0")?;

println!("Connecting to {}:{}", host, port);

Multi-Format Support

use config_lib::Config;

// All 8 formats now fully operational
let config = Config::from_string(r#"
[server]
port = 8080
host = "localhost"
"#, Some("toml"))?;

// Consistent API patterns across all parsers
let port = config.get("server.port")?.as_integer()?;
let timeout = config.get("server.timeout")
    .and_then(|v| v.as_integer().ok())
    .unwrap_or(30);
let name = config.get("app.name")
    .and_then(|v| v.as_string().ok())
    .unwrap_or_else(|| "DefaultApp".to_string());

// Check existence
if config.contains_key("server.ssl") {
    println!("SSL configuration found");
}

Read-only mode and forward-compatible options

ConfigOptions is the structured place to express the small set of behaviors that should not be enabled by default — making a Config read-only, sizing the cache, etc. The struct is #[non_exhaustive] so v1.x MINOR releases can add new knobs without breaking SemVer; callers go through the consuming builder methods.

use config_lib::{Config, ConfigOptions};

// Default options — caching on, writes allowed.
let _cfg = Config::with_options(ConfigOptions::default());

// Read-only configuration for a hot path that must never be mutated.
let opts = ConfigOptions::new().read_only(true);
let mut locked = Config::with_options(opts);
assert!(locked.set("foo", "bar").is_err());   // rejected

Default Configuration Settings

config-lib provides multiple powerful methods for setting default/preset values that serve as fallbacks when keys are missing from configuration files. This ensures your application always has sensible defaults while allowing configuration files to override specific values.

Method 1: ConfigBuilder with Presets (Recommended)

use config_lib::{ConfigBuilder, Value};
use std::collections::HashMap;

// Set up comprehensive default values before loading config files
let mut defaults = HashMap::new();
defaults.insert("app.name".to_string(), Value::String("MyApplication".to_string()));
defaults.insert("app.version".to_string(), Value::String("1.0.0".to_string()));
defaults.insert("app.debug".to_string(), Value::Bool(false));

// Server defaults
defaults.insert("server.host".to_string(), Value::String("localhost".to_string()));
defaults.insert("server.port".to_string(), Value::Integer(8080));
defaults.insert("server.timeout".to_string(), Value::Integer(30));
defaults.insert("server.workers".to_string(), Value::Integer(4));

// Database defaults
defaults.insert("database.host".to_string(), Value::String("localhost".to_string()));
defaults.insert("database.port".to_string(), Value::Integer(5432));
defaults.insert("database.pool_size".to_string(), Value::Integer(10));
defaults.insert("database.timeout".to_string(), Value::Integer(60));

// Logging defaults
defaults.insert("logging.level".to_string(), Value::String("info".to_string()));
defaults.insert("logging.file".to_string(), Value::String("app.log".to_string()));
defaults.insert("logging.max_size".to_string(), Value::String("10MB".to_string()));

// Create config with defaults, then load from file
let config = ConfigBuilder::new()
    .with_defaults(defaults)         // Apply presets first
    .from_file("app.conf")?          // File values override presets
    .build()?;

// All values are guaranteed to exist (from file or defaults)
let app_name = config.get("app.name")?.as_string()?;           // File value or "MyApplication"
let port = config.get("server.port")?.as_integer()?;           // File value or 8080
let pool_size = config.get("database.pool_size")?.as_integer()?; // File value or 10
let log_level = config.get("logging.level")?.as_string()?;      // File value or "info"

Method 2: Inline defaults at the access site

The simplest pattern when defaults are only needed at the call site — no parallel defaults table to maintain, no unwrap on a key that may not exist.

use config_lib::Config;

let config = Config::from_file("production.conf")?;

let environment = config
    .get("app.environment")
    .and_then(|v| v.as_string().ok())
    .map(str::to_owned)
    .unwrap_or_else(|| "development".to_string());

let cache_ttl: i64 = config
    .get("cache.ttl")
    .and_then(|v| v.as_integer().ok())
    .unwrap_or(3600);

let workers: i64 = config
    .get("server.workers")
    .and_then(|v| v.as_integer().ok())
    .unwrap_or(4);

The richer separate-defaults-table pattern is also available on Config directly — call cfg.set_default(key, value)? to populate the defaults table, then cfg.get_or_default(key) to resolve against the main value tree with the defaults as a fallback. The deprecated EnterpriseConfig::set_default / get_or_default behavior is fully preserved on Config; see examples/enterprise_demo.rs.

Method 3: Inline Defaults with get_or()

use config_lib::Config;

// Load configuration file
let config = Config::from_file("app.conf")?;

// Provide defaults inline when accessing values
let app_config = AppConfig {
    name: config.get_or("app.name", "DefaultApp".to_string()),
    port: config.get_or("server.port", 8080),
    debug: config.get_or("app.debug", false),
    timeout: config.get_or("server.timeout", 30),
    
    // Database configuration with sensible defaults
    db_host: config.get_or("database.host", "localhost".to_string()),
    db_port: config.get_or("database.port", 5432),
    db_pool_size: config.get_or("database.pool_size", 10),
    
    // Feature flags with conservative defaults
    analytics_enabled: config.get_or("features.analytics", false),
    cache_enabled: config.get_or("features.cache", true),
    monitoring_enabled: config.get_or("features.monitoring", false),
};

Best Practices for Default Configuration

Use Sensible Defaults: Choose defaults that work for most use cases
Document Defaults: Keep defaults in sync with documentation
Environment-Specific: Use different defaults for dev/staging/production
Type Safety: Ensure defaults match expected types
Validation: Validate both defaults and overrides
Performance: Use Enterprise config for high-performance scenarios

// Example: Production-ready defaults with validation
use config_lib::{ConfigBuilder, Value, validation::Validator};

// Production defaults (secure and performant)
let defaults = HashMap::from([
    ("server.host".to_string(), Value::String("127.0.0.1".to_string())), // Secure default
    ("server.port".to_string(), Value::Integer(8443)),                     // HTTPS default
    ("server.ssl_enabled".to_string(), Value::Bool(true)),                // Secure by default
    ("database.ssl_mode".to_string(), Value::String("require".to_string())), // Secure DB
    ("logging.level".to_string(), Value::String("warn".to_string())),      // Production logging
    ("features.debug".to_string(), Value::Bool(false)),                   // Disable debug
]);

// Validation rules for all values (including defaults)
let validator = Validator::new()
    .add_rule("server.port", ValidationRule::IntegerRange(1, 65535))
    .add_rule("server.host", ValidationRule::Required)
    .add_rule("logging.level", ValidationRule::OneOf(vec!["error", "warn", "info", "debug"]));

let config = ConfigBuilder::new()
    .with_defaults(defaults)
    .from_file("production.conf")?
    .with_validation(validator)         // Validate defaults + file values
    .build()?;

Environment Variable Integration

use config_lib::{Config, env_override::EnvOverride};

// Load configuration with environment variable overrides
let mut config = Config::from_file("app.conf")?;

// Enable environment variable overrides with prefix
let env_override = EnvOverride::new()
    .with_prefix("MYAPP_")  // Maps MYAPP_DATABASE_HOST to database.host
    .with_separator("_")    // Use underscore as path separator
    .case_insensitive();    // MYAPP_database_HOST also works

config.apply_env_overrides(&env_override)?;

// Now environment variables override file values:
// MYAPP_DATABASE_HOST=prod.db.com overrides database.host from file
// MYAPP_SERVER_PORT=9090 overrides server.port from file
let host = config.get("database.host")?.as_string()?;  // From env or file
let port = config.get("server.port")?.as_integer()?;   // From env or file

Configuration Validation & Type Safety

use config_lib::{Config, validation::{Validator, ValidationRule}};

// Define validation rules for configuration
let validator = Validator::new()
    .add_rule("server.port", ValidationRule::IntegerRange(1, 65535))
    .add_rule("database.host", ValidationRule::Required)
    .add_rule("app.name", ValidationRule::StringPattern(r"^[a-zA-Z][a-zA-Z0-9_-]*$"))
    .add_rule("logging.level", ValidationRule::OneOf(vec!["debug", "info", "warn", "error"]));

let mut config = Config::from_file("app.conf")?;

// Validate configuration before use
validator.validate(&config)?;  // Fails fast with detailed error messages

// Safe access with automatic type conversion
let port = config.get("server.port")?.as_integer()?;  // Guaranteed valid range
let log_level = config.get("logging.level")?.as_string()?;  // Guaranteed valid value

Hot Reloading & Audit Logging

use config_lib::{Config, audit};

// Enable audit logging
let audit_logger = audit::AuditLogger::new()
    .with_console_sink(audit::Severity::Info)
    .with_file_sink("config_audit.log", audit::Severity::Warning)?;

// Hot reloading configuration
let config = Config::from_file_with_hot_reload("app.conf", move |new_config| {
    println!("Configuration reloaded!");
    audit_logger.log_reload("app.conf", "admin");
})?;

Advanced Multi-File Configuration

use config_lib::{ConfigBuilder, ConfigMergeStrategy};

// Load and merge multiple configuration files
let config = ConfigBuilder::new()
    .from_file("default.conf")?     // Base configuration
    .merge_file("environment.json", ConfigMergeStrategy::Override)?  // Environment overrides
    .merge_file("local.toml", ConfigMergeStrategy::Additive)?        // Local additions
    .merge_file("secrets.hcl", ConfigMergeStrategy::SecureOverride)? // Secure values
    .build()?;

// Access merged configuration
let database_url = config.get("database.url")?.as_string()?;  // From secrets.hcl
let app_name = config.get("app.name")?.as_string()?;          // From default.conf
let debug_mode = config.get("debug")?.as_bool()?;             // From environment.json

Documentation & Resources

Documentation

Documentation Index - Complete documentation hub and navigation
API Reference - Comprehensive API documentation with examples
Valid Formats - Detailed format specifications and examples
Code Guidelines - Development standards and best practices

External Resources

API Documentation - Complete API reference with examples
Crate Registry - Official crate distribution
Examples Directory - 20+ comprehensive examples covering all features
Performance Benchmarks - Detailed performance analysis and comparisons
NOML Language - NOML language specification and usage.

Getting Started Guides

Quick Start Guide - Basic configuration loading and access
Multi-Format Demo - Working with different configuration formats
Enterprise Features - Advanced caching and performance
Hot Reloading - Dynamic configuration updates
Validation System - Schema validation and type checking

Common Use Cases

Web Applications: Environment overrides, JSON/TOML configs
DevOps Tools: HCL integration, audit logging, hot reloading
Enterprise Systems: XML support, validation, caching
Microservices: Multi-format support, environment-based configuration

Version Compatibility

Rust: 1.75+ for the default feature set; 1.82+ when the noml or toml features are enabled (upstream noml = "=0.9.0" declares 1.82)
Edition: 2021
MSRV Policy: MINOR releases may bump MSRV within the last-12-stable-Rust-versions window; PATCH releases never bump MSRV
API Stability: v1.x public API is frozen per docs/STABILITY-1.0.md. Growth-likely enums (Error, ConfigChangeEvent, etc.) are #[non_exhaustive]; new variants land in MINOR releases without breaking SemVer
Feature Flags: All optional features maintain independent compatibility

Development Setup

git clone https://github.com/jamesgober/config-lib.git
cd config-lib
cargo test --all-features  # Run comprehensive test suite
cargo bench               # Performance benchmarks
cargo clippy              # Lint checks (should show zero warnings)

Contributing

We welcome contributions! See our Contributing Guide for details.

License

config-lib is dual-licensed under either of:

Apache License, Version 2.0 — see LICENSE-APACHE or apache.org/licenses/LICENSE-2.0
MIT License — see LICENSE-MIT or opensource.org/licenses/MIT

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in config-lib by you, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.

Unless required by applicable law or agreed to in writing, software distributed under the Licenses is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

Name		Name	Last commit message	Last commit date
Latest commit History 140 Commits
.github/workflows		.github/workflows
benches		benches
docs		docs
examples		examples
fuzz		fuzz
src		src
tests		tests
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE-APACHE		LICENSE-APACHE
LICENSE-MIT		LICENSE-MIT
README.md		README.md
REPS.md		REPS.md
clippy.toml		clippy.toml
deny.toml		deny.toml
rustfmt.toml		rustfmt.toml
typos.toml		typos.toml

Folders and files

Latest commit

History

Repository files navigation

config-lib RUST CONFIGURATION LIBRARY

Features

Multi-Format Support

Enterprise Performance

Production Features

Reliability & Safety

Why Choose config-lib?

Unified Multi-Format Support

Enterprise-Grade Performance

Production-Ready Reliability

Developer Experience First

Advanced Enterprise Features

Installation

Quick Start

Multi-Format Support

Read-only mode and forward-compatible options

Default Configuration Settings

Method 1: ConfigBuilder with Presets (Recommended)

Method 2: Inline defaults at the access site

Method 3: Inline Defaults with get_or()

Best Practices for Default Configuration

Environment Variable Integration

Configuration Validation & Type Safety

Hot Reloading & Audit Logging

Advanced Multi-File Configuration

Documentation & Resources

Documentation

External Resources

Getting Started Guides

Common Use Cases

Version Compatibility

Development Setup

Contributing

License

Contribution

About

Topics

Resources

License

Licenses found

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 15

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

config-lib
_{^{RUST CONFIGURATION LIBRARY}}

Packages