A modern, type-safe configuration management library for Rust
β¨ Features β’ π Quick Start β’ π Documentation β’ π» Examples β’ π€ Contributing
Confers provides a declarative approach to configuration management with:
| β¨ Type Safety | π Auto Reload | π XChaCha20-Poly1305 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_sync()?;π Table of Contents (Click to expand)
| π― Core Features | β‘ Optional Features |
|---|---|
| Always available | Enable as needed |
|
|
| Preset | Features | Use Case |
|---|---|---|
| minimal | env, json |
Environment variables + JSON |
| recommended | toml, json, env, validation |
Recommended for most applications |
| dev | toml, json, yaml, env, cli, validation, schema, audit, profile, watch, migration, snapshot, dynamic |
Development with all tools |
| production | toml, env, watch, encryption, validation, audit, profile, metrics, schema, cli, migration, dynamic, progressive-reload, snapshot |
Production-ready configuration |
| distributed | toml, env, watch, validation, config-bus, progressive-reload, metrics, audit |
Distributed systems |
| full | All features | Complete feature set |
Note: Default features include toml, json, env. The cli feature automatically includes validation and encryption dependencies.
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/>π XChaCha20-Poly1305]
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
| Feature | Default | Description | Stability |
|---|---|---|---|
| Format Support | |||
toml |
β | TOML configuration files | Stable |
json |
β | JSON configuration files | Stable |
yaml |
β | YAML configuration files | Stable |
ini |
β | INI configuration files | Stable |
env |
β | Environment variable support | Stable |
| Core Features | |||
validation |
β | Configuration validation (garde) | Stable |
watch |
β | File watching and hot reload | Stable |
encryption |
β | XChaCha20-Poly1305 encryption | Stable |
cli |
β | CLI tool with commands | Stable |
schema |
β | JSON Schema generation | Stable |
parallel |
β | Parallel validation (rayon) | Stable |
typescript-schema |
β | TypeScript type generation | Stable |
| Advanced Features | |||
audit |
β | Audit logging | Stable |
metrics |
β | Metrics collection | Stable |
dynamic |
β | Dynamic fields | Stable |
progressive-reload |
β | Canary/linear rollout | Stable |
migration |
β | Configuration migration | Stable |
snapshot |
β | Snapshot rollback | Stable |
profile |
β | Environment profiles | Stable |
interpolation |
β | Variable interpolation | Stable |
hot-reload |
β | Hot reload (alias for watch) | Stable |
| Remote Sources | |||
remote |
β | HTTP polling | Beta |
etcd |
β | Etcd v3 integration | Beta |
consul |
β | Consul integration | Beta |
cache-redis |
β | Redis cache | Beta |
| Message Bus | |||
config-bus |
β | Config event bus | Stable |
nats-bus |
β | NATS integration | Stable |
redis-bus |
β | Redis Pub/Sub | Stable |
| Security | |||
security |
β | Security module (env validation, error sanitization) | Stable |
key |
β | Key management and rotation | Stable |
| Context & Modules | |||
context-aware |
β | Tenant-aware configuration | Stable |
modules |
β | Modular configuration | Stable |
| Infrastructure | |||
preload-validator |
β | Async preload validator | Stable |
poll |
β | HTTP polling | Stable |
vault |
β | Vault integration | Beta |
Complete, runnable examples demonstrating all major features. All examples can be found in the examples/ directory.
| Example | File | Features | Description |
|---|---|---|---|
| basic_usage | examples/src/examples/basic_usage.rs |
toml, env |
Basic configuration loading from TOML and environment variables |
| hot_reload | examples/src/examples/hot_reload.rs |
watch |
Real-time file monitoring with automatic reload |
| encryption | examples/src/examples/encryption.rs |
encryption |
Sensitive field encryption with XChaCha20-Poly1305 |
| key_rotation | examples/src/examples/key_rotation.rs |
key |
Key lifecycle management and rotation |
| migration | examples/src/examples/migration.rs |
migration |
Configuration version migration |
| dynamic_fields | examples/src/examples/dynamic_fields.rs |
dynamic |
Lock-free dynamic field updates with callbacks |
| config_groups | examples/src/examples/config_groups.rs |
modules |
Modular configuration groups |
| progressive_reload | examples/src/examples/progressive_reload.rs |
progressive-reload |
Canary deployment and health-check-based rollout |
| config_bus | examples/src/examples/config_bus.rs |
config-bus |
Multi-instance config broadcast via NATS/Redis |
| snapshot | examples/src/examples/snapshot.rs |
snapshot |
Configuration snapshots with diff and rollback |
| remote_consul | examples/src/examples/remote_consul.rs |
consul |
Remote config from HashiCorp Consul |
| remote_etcd | examples/src/examples/remote_etcd.rs |
etcd |
Remote config from etcd v3 |
| validation | examples/src/examples/validation.rs |
validation |
Configuration validation with garde |
| json_schema | examples/src/examples/json_schema.rs |
schema |
JSON Schema and TypeScript type generation |
| metrics | examples/src/examples/metrics.rs |
metrics |
Metrics collection and monitoring |
| cli_integration | examples/src/examples/cli_integration.rs |
cli |
CLI tool integration and usage |
| full_stack | examples/src/examples/full_stack.rs |
full |
Complete feature showcase |
# Run any example from the examples directory
cd examples && cargo run --bin basic_usage
cd examples && cargo run --bin encryption
cd examples && cargo run --bin full_stack
# Verify all examples compile
cd examples && ./verify_examples.sh
Individual Features:
Note: The |
Required Features: toml, env, 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_sync()?;
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_sync()?;
// Print configuration
println!("π Configuration loaded successfully!");
println!("π Name: {}", config.name);
println!("π Port: {}", config.port);
println!("π Debug: {}", config.debug);
Ok(())
}Confers provides three flexible usage patterns to suit different needs:
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_sync()?;For more control over configuration sources:
use confers::{ConfigBuilder, ConfigProviderExt};
let config = ConfigBuilder::<serde_json::Value>::new()
.file("config.toml")
.file("local.toml") // Higher priority
.env()
.build()?;
let name = config.get_string("app.name");
let port = config.get_int("app.port");For integration into frameworks and runtime flexibility:
use std::sync::Arc;
use confers::{ConfigBuilder, ConfigProviderExt};
#[derive(Debug, Clone, serde::Deserialize)]
pub struct MyConfig {
pub name: String,
pub port: u16,
}
let config = ConfigBuilder::<MyConfig>::new()
.file("config.toml")
.env()
.build()?;
let shared_config = Arc::new(config);
let service = MyService::new(shared_config);|
User Guide Complete usage guide |
API Reference Complete API docs |
Examples Code examples |
| 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 |
Confers provides a standalone command-line tool confers for configuration management:
cargo install confers# View help
confers --help
# Inspect configuration - list all keys with their sources
confers config.toml inspect
# Validate configuration file
confers config.toml validate
# Compare configuration files
confers diff --base config1.toml --overlay config2.toml
# Export merged configuration
confers config.toml export --format json
# Manage configuration snapshots
confers config.toml snapshot list
confers config.toml snapshot diff --latest 2Note: The CLI tool requires the cli feature to be enabled.
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_sync()?;
println!("β
Name: {}, Port: {}", config.name, config.port);
Ok(())
}View Output |
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_sync()?;
println!("π Server: {}:{}", config.host, config.port);
Ok(())
}View Output |
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/>XChaCha20-Poly1305]
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 | 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 | XChaCha20-Poly1305 encrypted storage | β Stable |
| Configuration Diff | Multiple output formats | β Stable |
| Interactive Wizard | Template generation | β Stable |
|
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 |
# π§ͺ 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% |
|
π Throughput
|
β±οΈ Latency
|
π 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)|
Memory Safety Zero-copy & secure cleanup |
Audited Regular security audits |
Privacy No data collection |
Compliance Industry standards |
π Security Details
| Measure | Description | API Reference |
|---|---|---|
| β Memory Protection | Automatic secure cleanup with zeroization | SecureString, zeroize crate |
| β Side-channel Protection | Constant-time cryptographic operations | XChaCha20-Poly1305 encryption |
| β Input Validation | Comprehensive input sanitization | ConfigValidator, InputValidator |
| β Audit Logging | Full operation tracking | AuditConfig, audit trails |
| β SSRF Protection | Built-in Server-Side Request Forgery prevention | HttpPolledSource, is_ip_blocked() |
| β 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 |
// 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::builder()
.max_string_length(1024)
.strict_mode()
.build();
let data: std::collections::HashMap<String, String> = std::collections::HashMap::new();
let result = validator.validate(&data);
// 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();- 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
encryptionfeature for sensitive configs - Follow principle of least privilege: Minimize sensitive data exposure
Please report security vulnerabilities to: security@confers.example
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
|
|
|
Found an issue? |
Have a great idea? |
Want to contribute code? |
π Contribution Guidelines
- 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
- β Follow Rust standard coding conventions
- β Write comprehensive tests
- β Update documentation
- β Add examples for new features
- β
Pass
cargo clippy -- -D warnings
This project is licensed under MIT License:
|
Rust |
GitHub |
| Category | Description |
|---|---|
| π Dependency Projects | serde - Serialization framework |
| figment - Configuration management | |
| validator - Validation library | |
| π₯ Contributors | Thanks to all contributors! |
| π¬ Community | Special thanks to community members |
|
Issues Report bugs & issues |
Discussions Ask questions & share ideas |
GitHub View source code |
If you find this project useful, please consider giving it a βοΈ!
Built with β€οΈ by Kirky.X
Β© 2026 Kirky.X. All rights reserved.