GitHub - Kirky-X/confers: Confers is a modern, type safe Rust configuration management library that supports multiple configuration formats (TOML, JSON, YAML, INI) and provides validation, differential comparison, and hot reload functionality.

A modern, type-safe configuration management library for Rust

✨ Features • 🚀 Quick Start • 📚 Documentation • 💻 Examples • 🤝 Contributing

🎯 Zero-Boilerplate Configuration Management

Confers provides a declarative approach to configuration management with:

✨ Type Safety	🔄 Auto Reload	🔐 AES-256 Encryption	🌐 Remote Sources
Compile-time checks	Hot reload support	Sensitive data protection	etcd, Consul, HTTP

use confers::Config;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize, Config)]
#[config(validate)]
pub struct AppConfig {
    pub name: String,
    pub port: u16,
    pub debug: bool,
}

// Configuration loads automatically from files, env vars, and CLI args
let config = AppConfig::load()?;

📋 Table of Contents

📑 Table of Contents (Click to expand)

✨ Features
🚀 Quick Start
- 📦 Installation
- 💡 Basic Usage
📚 Documentation
💻 Examples
🏗️ Architecture
⚙️ Configuration
🧪 Testing
📊 Performance
🔒 Security
🗺️ Roadmap
🤝 Contributing
📄 License
🙏 Acknowledgments

✨ Features

🎯 Core Features	⚡ Optional Features
Always available	Enable as needed

🎯 Core Features (Always Available)

Status	Feature	Description
✅	Type-safe Configuration	Auto-generate config structs via derive macros (`derive` feature)
✅	Multi-format Support	TOML, YAML, JSON, INI configuration files
✅	Environment Variable Override	Support environment variable overrides
✅	CLI Argument Override	Support command-line argument overrides (`cli` feature)

⚡ Optional Features

Status	Feature	Description
🔍	Configuration Validation	Built-in validator integration (`validation` feature)
📊	Schema Generation	Auto-generate JSON Schema (`schema` feature)
🚀	File Watching & Hot Reload	Real-time file monitoring (`watch` feature)
🔐	Configuration Encryption	AES-256 encrypted storage (`encryption` feature)
🌐	Remote Configuration	etcd, Consul, HTTP support (`remote` feature)
📦	Audit Logging	Record access & change history (`audit` feature)
⚡	Parallel Validation	Parallel validation for large configs (`parallel` feature)
📈	System Monitoring	Memory usage monitoring (`monitoring` feature)
🔧	Configuration Diff	Compare configs with multiple output formats
🎨	Interactive Wizard	Generate config templates via CLI
🛡️	Security Enhancements	Nonce reuse detection, SSRF protection
🧩	HOCON Format	Support for Typesafe Config format
🔑	Key Management	Built-in key generation and rotation

📦 Feature Presets

Preset	Features	Use Case
minimal	`derive`	Minimal config loading (no validation, no CLI)
recommended	`derive`, `validation`	Recommended for most applications
dev	`derive`, `validation`, `cli`, `schema`, `audit`, `monitoring`, `tracing`	Development with all tools
production	`derive`, `validation`, `watch`, `encryption`, `remote`, `monitoring`, `tracing`	Production-ready configuration
full	All features	Complete feature set

Note: The cli feature automatically includes derive, validation, and encryption dependencies.

🎨 Feature Architecture

graph LR
    A[<b>Configuration Sources</b><br/>📁 Files • 🌐 Env • 💻 CLI] --> B[<b>ConfigLoader</b><br/>🔧 Core Engine]
    B --> C[<b>Validation</b><br/>✅ Type & Business Rules]
    B --> D[<b>Schema</b><br/>📄 JSON Schema Gen]
    B --> E[<b>Encryption</b><br/>🔐 AES-256-GCM]
    B --> F[<b>Audit</b><br/>📋 Access Logs]
    B --> G[<b>Monitoring</b><br/>📊 Memory Watch]
    C --> H[<b>Application Config</b><br/>🚀 Ready to Use]
    D --> H
    E --> H
    F --> H
    G --> H
    
    style A fill:#DBEAFE,stroke:#1E40AF,stroke-width:2px
    style B fill:#FEF3C7,stroke:#92400E,stroke-width:2px
    style H fill:#DCFCE7,stroke:#166534,stroke-width:2px

🚀 Quick Start

📦 Installation

🦀 Rust Installation

Installation Type	Configuration	Use Case
Default	`confers = "0.2.2"`	Includes only `derive` (minimal config loading)
Minimal	`confers = { version = "0.2.2", default-features = false, features = ["minimal"] }`	Only config loading (same as default)
Recommended	`confers = { version = "0.2.2", default-features = false, features = ["recommended"] }`	Config + validation
CLI with Tools	`confers = { version = "0.2.2", features = ["cli"] }`	CLI with validation and encryption
Full	`confers = { version = "0.2.2", features = ["full"] }`	All features

Individual Features:

Feature	Description	Default
`derive`	Derive macros for config structs	✅
`validation`	Config validation support	❌
`cli`	Command-line interface tools	❌
`watch`	File watching and hot reload	❌
`audit`	Audit logging	❌
`schema`	JSON Schema generation	❌
`parallel`	Parallel validation	❌
`monitoring`	System monitoring	❌
`remote`	Remote config (etcd, consul, http, vault)	❌
`encryption`	Config encryption	❌
`hocon`	HOCON format support	❌

🔧 CLI Command Feature Dependencies

Command	Required Features	Optional Features	Description
`generate`	`cli` (includes: `derive`, `validation`, `encryption`)	`schema`	Generate configuration templates
`validate`	`cli` (includes: `derive`, `validation`, `encryption`)	`schema`	Validate configuration files
`diff`	`cli` (includes: `derive`, `validation`, `encryption`)	-	Compare configuration files
`encrypt`	`cli` (includes: `derive`, `validation`, `encryption`)	-	Encrypt configuration values
`key`	`cli` (includes: `derive`, `validation`, `encryption`)	-	Manage encryption keys
`wizard`	`cli` (includes: `derive`, `validation`, `encryption`)	-	Interactive configuration wizard
`completions`	`cli` (includes: `derive`, `validation`, `encryption`)	-	Generate shell completions

Note: The cli feature automatically includes derive, validation, and encryption for convenience.

💡 Basic Usage

🎬 5-Minute Quick Start

Required Features: derive, validation (use: features = ["recommended"])

Step 1: Define Config Structure

use confers::Config;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize, Config)]
#[config(validate)]
#[config(env_prefix = "APP_")]
pub struct AppConfig {
    pub name: String,
    pub port: u16,
    pub debug: bool,
}

Step 2: Create Config File

# config.toml
name = "my-app"
port = 8080
debug = true

Step 3: Load Config

fn main() -> anyhow::Result<()> {
    let config = AppConfig::load()?;
    println!("✅ Loaded: {:?}", config);
    Ok(())
}

Step 4: Environment Override

# Environment variables automatically override
export APP_PORT=9090
export APP_DEBUG=true

📖 Complete Working Example

use confers::Config;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize, Config)]
#[config(validate)]
#[config(env_prefix = "APP_")]
pub struct AppConfig {
    pub name: String,
    pub port: u16,
    pub debug: bool,
}

fn main() -> anyhow::Result<()> {
    // Create config file
    let config_content = r#"
name = "my-app"
port = 8080
debug = true
"#;
    std::fs::write("config.toml", config_content)?;

    // Load configuration
    let config = AppConfig::load()?;

    // Print configuration
    println!("🎉 Configuration loaded successfully!");
    println!("📋 Name: {}", config.name);
    println!("🔌 Port: {}", config.port);
    println!("🐛 Debug: {}", config.debug);

    Ok(())
}

🎨 Three Usage Patterns

Confers provides three flexible usage patterns to suit different needs:

1️⃣ Simple Mode (Recommended)

Perfect for most applications with minimal boilerplate:

use confers::Config;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize, Config)]
#[config(validate)]
pub struct AppConfig {
    pub name: String,
    pub port: u16,
    pub debug: bool,
}

// One-line configuration loading
let config = AppConfig::load()?;

2️⃣ Builder Mode

For more control over configuration sources:

use confers::core::ConfersConfigBuilder;

let config = ConfersConfigBuilder::new()
    .with_file("config.toml")
    .with_file("local.toml")  // Higher priority
    .with_env_prefix("APP_")
    .build()?;

let name = config.get_string("app.name");
let port = config.get_int("app.port");

3️⃣ DI Mode (Dependency Injection)

For integration into frameworks and runtime flexibility:

use std::sync::Arc;
use confers::core::{ConfersConfig, FileConfersConfig};

// Use trait object for dependency injection
let shared_config: Arc<dyn ConfersConfig> = Arc::new(
    FileConfersConfig::new("config.toml")?
);

// Can be swapped at runtime
let service = MyService::new(shared_config);

📚 Documentation

User Guide

Complete usage guide

API Reference

Complete API docs

Examples

Code examples

📖 Additional Resources

Resource	Description
❓ FAQ	Frequently asked questions
📖 Contributing Guide	Code contribution guidelines
📘 API Reference	Complete API documentation
🏗️ Architecture Decisions	ADR documentation
📚 Library Integration Guide	How to integrate confers CLI into your projects

🔌 Library Integration

Confers provides a unified ConfersCli API for easy integration into other Rust projects.

Quick Start

[dependencies]
confers = { version = "0.2.2", features = ["cli"] }

use confers::ConfersCli;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Generate configuration template
    ConfersCli::generate(Some("config.toml"), "full")?;
    
    // Validate configuration
    ConfersCli::validate("config.toml", "full")?;
    
    // Compare configurations
    ConfersCli::diff("config1.toml", "config2.toml", Some("unified"))?;
    
    // Encrypt values
    let encrypted = ConfersCli::encrypt("secret", None)?;
    
    Ok(())
}

Available Methods

Method	Description	Example
`generate(output, level)`	Generate config templates	`ConfersCli::generate(Some("app.toml"), "minimal")?`
`validate(config, level)`	Validate config files	`ConfersCli::validate("app.toml", "full")?`
`diff(file1, file2, format)`	Compare configs	`ConfersCli::diff("old.toml", "new.toml", Some("side-by-side"))?`
`encrypt(value, key)`	Encrypt values	`ConfersCli::encrypt("secret", None)?`
`wizard(non_interactive)`	Interactive setup	`ConfersCli::wizard(false)?`
`completions(shell)`	Generate completions	`ConfersCli::completions("bash")?`
`key(subcommand)`	Key management	`ConfersCli::key(&KeySubcommand::Generate)?`
`schema(struct_name, output)`	Generate JSON Schema	`ConfersCli::schema("AppConfig", Some("schema.json"))?`

📚 Complete Integration Guide →

💻 Examples

💡 Real-World Examples

📝 Example 1: Basic Configuration

use confers::Config;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize, Config)]
#[config(validate)]
pub struct BasicConfig {
    pub name: String,
    pub port: u16,
}

fn basic_example() -> anyhow::Result<()> {
    let config = BasicConfig::load()?;
    println!("✅ Name: {}, Port: {}", config.name, config.port);
    Ok(())
}

View Output

✅ Name: my-app, Port: 8080

🔥 Example 2: Advanced Configuration

use confers::Config;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize, Config)]
#[config(validate)]
#[config(env_prefix = "MYAPP_")]
pub struct AdvancedConfig {
    #[config(description = "Server port number")]
    pub port: u16,
    #[config(default = "localhost")]
    pub host: String,
    #[config(sensitive = true)]
    pub api_key: String,
}

fn advanced_example() -> anyhow::Result<()> {
    let config = AdvancedConfig::load()?;
    println!("🚀 Server: {}:{}", config.host, config.port);
    Ok(())
}

View Output

🚀 Server: localhost:8080

📂 Explore All Examples →

🏗️ Architecture

🏗️ System Architecture

graph TB
    subgraph Sources ["📥 Configuration Sources"]
        A[📁 Local Files<br/>TOML, JSON, YAML, INI]
        B[🌐 Environment Variables]
        C[💻 CLI Arguments]
        D[☁️ Remote Sources<br/>etcd, Consul, HTTP]
    end
    
    subgraph Core ["🔧 Core Engine"]
        E[⚡ ConfigLoader<br/>Multi-source Merge]
    end
    
    subgraph Processing ["🔨 Processing Layer"]
        F[✅ Validation<br/>Type & Business Rules]
        G[📄 Schema Generation]
        H[🔐 Encryption<br/>AES-256-GCM]
        I[📋 Audit Logging]
        J[👁️ File Watching]
        K[📊 Memory Monitoring]
    end
    
    subgraph Output ["📤 Application"]
        L[🚀 Application Configuration<br/>Type-Safe & Validated]
    end
    
    Sources --> Core
    Core --> Processing
    Processing --> Output
    
    style Sources fill:#DBEAFE,stroke:#1E40AF
    style Core fill:#FEF3C7,stroke:#92400E
    style Processing fill:#EDE9FE,stroke:#5B21B6
    style Output fill:#DCFCE7,stroke:#166534

📐 Component Status

Component	Description	Status
ConfigLoader	Core loader with multi-source support	✅ Stable
Configuration Validation	Built-in validator integration	✅ Stable
Schema Generation	Auto-generate JSON Schema	✅ Stable
File Watching	Real-time monitoring with hot reload	✅ Stable
Remote Configuration	etcd, Consul, HTTP support	🚧 Beta
Audit Logging	Record access and change history	✅ Stable
Encrypted Storage	AES-256 encrypted storage	✅ Stable
Configuration Diff	Multiple output formats	✅ Stable
Interactive Wizard	Template generation	✅ Stable

⚙️ Configuration

🎛️ Configuration Options

Basic Configuration

[project]
name = "my-app"
version = "1.0.0"

[server]
host = "localhost"
port = 8080

[features]
debug = true
logging = true

Advanced Configuration

[project]
name = "my-app"
version = "1.0.0"

[server]
host = "0.0.0.0"
port = 8080
workers = 4

[database]
url = "postgres://localhost/db"
pool_size = 10

[performance]
cache_size = 1000

🔧 All Configuration Options

Option	Type	Default	Description
`name`	String	-	Project name
`version`	String	"1.0.0"	Version number
`host`	String	"localhost"	Server host
`port`	u16	8080	Server port
`debug`	Boolean	false	Enable debug mode
`workers`	usize	4	Number of worker threads
`cache_size`	usize	1000	Cache size in MB

🧪 Testing

🎯 Test Coverage

# 🧪 Run all tests
cargo test --all-features

# 📊 Generate coverage report
cargo tarpaulin --out Html

# ⚡ Run benchmarks
cargo bench

# 🎯 Run specific test
cargo test test_name

📊 Test Statistics

Category	Test Count	Coverage
🧪 Unit Tests	50+	85%
🔗 Integration Tests	20+	80%
⚡ Performance Tests	10+	75%
📈 Total	80+	80%

📊 Performance

⚡ Benchmark Results

📊 Throughput

Operation	Performance
Config Load	1,000,000 ops/sec
Validation	500,000 ops/sec
Schema Gen	2,000,000 ops/sec

⏱️ Latency

Percentile	Latency
P50	0.5ms
P95	1.2ms
P99	2.5ms

📈 Detailed Benchmarks

# Run benchmarks
cargo bench

# Sample output:
test bench_config_load  ... bench: 1,000 ns/iter (+/- 50)
test bench_validate     ... bench: 2,000 ns/iter (+/- 100)
test bench_schema_gen   ... bench: 500 ns/iter (+/- 25)

🔒 Security

🛡️ Security Features

Memory Safety
Zero-copy & secure cleanup

Audited
Regular security audits

Privacy
No data collection

Compliance
Industry standards

🔐 Security Details

🛡️ Security Measures

Measure	Description	API Reference
✅ Memory Protection	Automatic secure cleanup with zeroization	`SecureString`, `zeroize` crate
✅ Side-channel Protection	Constant-time cryptographic operations	AES-256-GCM encryption
✅ Input Validation	Comprehensive input sanitization	`ConfigValidator`, `InputValidator`
✅ Audit Logging	Full operation tracking	`AuditConfig`, audit trails
✅ SSRF Protection	Server-Side Request Forgery prevention	`validate_remote_url()`
✅ Sensitive Data Detection	Automatic detection of sensitive fields	`SensitiveDataDetector`
✅ Error Sanitization	Remove sensitive info from error messages	`ErrorSanitizer`, `SecureLogger`
✅ Nonce Reuse Detection	Prevent cryptographic nonce reuse	Built into encryption module

🔐 Security APIs

// Secure string handling
use confers::security::{SecureString, SensitivityLevel};
let secure_str = SecureString::new("sensitive_data", SensitivityLevel::High);

// Input validation
use confers::security::ConfigValidator;
let validator = ConfigValidator::new();
let result = validator.validate_input(user_input);

// Error sanitization
use confers::security::ErrorSanitizer;
let sanitizer = ErrorSanitizer::default();
let safe_error = sanitizer.sanitize(&error_message);

// Audit logging
#[cfg(feature = "audit")]
use confers::audit::AuditConfig;
let audit = AuditConfig::new().enable_sensitive_field_tracking();

🚨 Security Best Practices

Use SecureString for sensitive data: Automatically zeroizes memory
Enable audit logging: Track all configuration access and changes
Validate all inputs: Use built-in validators for user inputs
Use encryption: Enable encryption feature for sensitive configs
Follow principle of least privilege: Minimize sensitive data exposure

📧 Reporting Security Issues

Please report security vulnerabilities to: security@confers.example

🗺️ Roadmap

🎯 Development Roadmap

gantt
    title Confers Development Roadmap
    dateFormat  YYYY-MM
    section Core Features ✅
    Type-safe Configuration     :done, 2024-01, 2024-06
    Multi-format Support       :done, 2024-02, 2024-06
    Environment Variable Override     :done, 2024-03, 2024-06
    section Validation System ✅
    Basic Validation Integration     :done, 2024-04, 2024-07
    Parallel Validation Support     :done, 2024-05, 2024-08
    section Advanced Features 🚧
    Schema Generation      :active, 2024-06, 2024-09
    File Watching Hot Reload   :done, 2024-07, 2024-09
    Remote Configuration Support     :active, 2024-08, 2024-12
    Audit Logging         :done, 2024-08, 2024-10

✅ Completed

Type-safe Configuration
Multi-format Support (TOML, YAML, JSON, INI)
Environment Variable Override
Configuration Validation System
Schema Generation
File Watching & Hot Reload
Audit Logging
Encrypted Storage Support
Remote Configuration Support (etcd, Consul, HTTP)

📋 Planned

🤝 Contributing

💖 Thank You to All Contributors!

🐛 Report Bugs

Found an issue?
Create Issue

💡 Feature Suggestions

Have a great idea?
Start Discussion

🔧 Submit PR

Want to contribute code?
Fork & PR

📝 Contribution Guidelines

🚀 How to Contribute

Fork this repository
Clone your fork: git clone https://github.com/yourusername/confers.git
Create a branch: git checkout -b feature/amazing-feature
Make your changes
Test your changes: cargo test --all-features
Commit your changes: git commit -m 'feat: Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Create a Pull Request

📋 Code Standards

✅ Follow Rust standard coding conventions
✅ Write comprehensive tests
✅ Update documentation
✅ Add examples for new features
✅ Pass cargo clippy -- -D warnings

📄 License

This project is licensed under MIT License:

🙏 Acknowledgments

🌟 Built With Amazing Tools

Rust

GitHub

Open Source

Community

💝 Special Thanks

Category	Description
🌟 Dependency Projects	serde - Serialization framework
	figment - Configuration management
	validator - Validation library
👥 Contributors	Thanks to all contributors!
💬 Community	Special thanks to community members

📞 Contact & Support

Issues

Report bugs & issues

Discussions

Ask questions & share ideas

GitHub

View source code

⭐ Star History

💝 Support This Project

If you find this project useful, please consider giving it a ⭐️!

Built with ❤️ by Kirky.X

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 191 Commits
.github/workflows		.github/workflows
benches		benches
docs		docs
examples		examples
macros		macros
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.tarpaulin.toml		.tarpaulin.toml
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README_zh.md		README_zh.md
deny.toml		deny.toml

Folders and files

Latest commit

History

Repository files navigation

🎯 Zero-Boilerplate Configuration Management

📋 Table of Contents

✨ Features

🎯 Core Features (Always Available)

⚡ Optional Features

📦 Feature Presets

🎨 Feature Architecture

🚀 Quick Start

📦 Installation

🦀 Rust Installation

🔧 CLI Command Feature Dependencies

💡 Basic Usage

🎬 5-Minute Quick Start

🎨 Three Usage Patterns

1️⃣ Simple Mode (Recommended)

2️⃣ Builder Mode

3️⃣ DI Mode (Dependency Injection)

📚 Documentation

📖 Additional Resources

🔌 Library Integration

Quick Start

Available Methods

💻 Examples

💡 Real-World Examples

📝 Example 1: Basic Configuration

🔥 Example 2: Advanced Configuration

🏗️ Architecture

🏗️ System Architecture

📐 Component Status

⚙️ Configuration

🎛️ Configuration Options

🧪 Testing

🎯 Test Coverage

📊 Performance

⚡ Benchmark Results

🔒 Security

🛡️ Security Features

🛡️ Security Measures

🔐 Security APIs

🚨 Security Best Practices

📧 Reporting Security Issues

🗺️ Roadmap

🎯 Development Roadmap

✅ Completed

📋 Planned

🤝 Contributing

💖 Thank You to All Contributors!

🐛 Report Bugs

💡 Feature Suggestions

🔧 Submit PR

🚀 How to Contribute

📋 Code Standards

📄 License

🙏 Acknowledgments

🌟 Built With Amazing Tools

💝 Special Thanks

📞 Contact & Support

⭐ Star History

💝 Support This Project

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages