hotswap-config

A high-performance, hot-reloadable configuration store with wait-free reads and transactional updates for Rust applications.

Core Features

• Wait-free reads via atomic pointer swap (ArcSwap pattern) - readers never block
• File watching (cross-platform, notify crate) with automatic reload
• Subscribers: Register callbacks for async/sync notifications on config changes
• Validation + atomic rollback: Invalid configs are rejected; readers never see partial state

Advanced Features (Optional)

• Partial updates: RFC 6902 JSON Patch for surgical field changes (feature: partial-updates)
• Versioned history: Point-in-time rollback with timestamps (feature: rollback)
• Gradual rollout / A/B testing: Percentage-based, key-scoped canary deployment (feature: gradual-rollout)
• Remote HTTP sources: Fetch config from HTTP(S) endpoints with Bearer/Basic auth (feature: remote)
• OpenTelemetry metrics: Track reload success/failures, latency, config age (feature: metrics)

Performance (Benchmarked)

Test System: Apple MacBook Pro (M3 Pro, 12-core, 18GB unified memory), macOS 26.0.1, Rust 1.87.0 Build: cargo bench --release (LTO=true, opt-level=3, codegen-units=1) Methodology: Criterion 0.5, 100 samples, warm L3 cache

Readers are wait-free: ArcSwap::load() is a single atomic read. Writers build new config off-to-the-side, validate, then atomically swap. Old readers continue using the previous Arc until dropped.

See benches/README.md for full methodology, CPU governor settings, and raw criterion reports.

Quick Start

Add to Cargo.toml:

[dependencies]
hotswap-config = "0.1"
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.0", features = ["full"] }

10-line working example:

use hotswap_config::prelude::*;
use serde::Deserialize;

#[derive(Debug, Deserialize, Clone)]
struct AppConfig {
    server_port: u16,
    feature_flag: bool,
}

#[tokio::main]
async fn main() -> Result<()> {
    // Load config with file watching (auto-reloads on change)
    let config = HotswapConfig::builder()
        .with_file("config/default.yaml")
        .with_env_overrides("APP", "__")  // APP_SERVER_PORT=8080 overrides file
        .with_validation(|cfg: &AppConfig| {
            if cfg.server_port < 1024 {
                return Err(ValidationError::invalid_field("server_port", "must be >= 1024"));
            }
            Ok(())
        })
        .build::<AppConfig>()
        .await?;

    // Wait-free reads (no locks!)
    let cfg = config.get();  // Returns Arc<AppConfig>
    println!("Server starting on port {}", cfg.server_port);

    // Subscribe to changes
    let _subscription = config.subscribe(|new_cfg| {
        println!("Config reloaded! Feature flag: {}", new_cfg.feature_flag);
    });

    // Config automatically reloads when config/default.yaml changes
    // Invalid configs are rejected; old config stays active

    Ok(())
}

With partial updates (JSON Patch):

// Feature: partial-updates
config.update_field("/feature_flag", true).await?;  // Atomic update with validation

Feature Flags

Default features: file-watch, validation

Enable features in Cargo.toml:

[dependencies]
hotswap-config = { version = "0.1", features = ["partial-updates", "rollback", "yaml"] }

Configuration Sources & Precedence

Config sources are merged by priority (highest wins):

1. Environment variables (priority: 300) - APP_SERVER__PORT=8080
2. Remote HTTP sources (priority: 250, if enabled)
3. Environment-specific files (priority: 110+) - config/production.yaml
4. Default files (priority: 100) - config/default.yaml

Supported Formats

• YAML (.yaml, .yml) - Feature: yaml
• TOML (.toml) - Feature: toml
• JSON (.json) - Feature: json

Format detected automatically by file extension.

Safety & Failure Modes

Validation

• When: Before initial load and before every update/reload
• What: Custom validation functions (Fn(&T) -> Result<(), ValidationError>)
• Failure: Validation errors reject the update; readers continue using old config
• Guarantee: Readers never see invalid or partial config state

Remote HTTP Sources (feature: remote)

• TLS: Supports HTTPS with native TLS roots (rustls, native-certs)
• Authentication: Bearer token or Basic auth
• Retry/backoff: On network errors, keeps last-known-good config
• Security: Does not currently support certificate pinning or config signatures (planned for v0.2.0)

File Watching

• Cross-platform: Uses notify crate (inotify/kqueue/FSEvents)
• Debouncing: 500ms default (configurable) to avoid rapid reloads
• Error handling: File watch errors log but don't crash; manual reload() still works

Testing & QA

• ✅ 80+ unit & integration tests - All feature combinations covered
• ✅ Concurrency tests - Validated with Tokio test framework
• ✅ Property-based tests - Using proptest for validation logic
• ✅ CI Matrix - GitHub Actions on Linux, macOS (ARM64)
• ✅ 6 runnable examples - examples/ directory with full scenarios

Running Tests

# All tests with all features
cargo test --all-features

# Specific feature combinations
cargo test --features yaml,validation
cargo test --features "partial-updates,rollback"

# No default features
cargo test --no-default-features

Running Examples

# Service configuration (comprehensive example with validation)
cargo run --example service_config --features yaml

# Hot reload demonstration
cargo run --example hot_reload --features yaml

# Subscriber notifications
cargo run --example subscribers --features yaml

# Partial updates
cargo run --example partial_updates --features "yaml,partial-updates"

# Rollback demonstration
cargo run --example rollback --features "yaml,rollback"

# Gradual rollout
cargo run --example gradual_rollout --features "yaml,gradual-rollout"

# Remote HTTP source
cargo run --example remote_config --features "remote,yaml"

Documentation

• API Documentation: docs.rs/hotswap-config
• Examples: examples/ directory
• Design Document: DESIGN.md
• Contributing: CONTRIBUTING.md
• Changelog: CHANGELOG.md

Comparison with Other Crates

Platform Support

• Platforms: Linux, macOS, Windows (via notify crate)
• MSRV: Rust 1.87.0 (edition 2024)
• no_std: Not supported (requires std::sync::Arc, tokio runtime)

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

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

Acknowledgments

• Built on the excellent arc-swap crate for lock-free atomic updates
• Configuration parsing via config crate
• File watching via notify crate
• Pattern proven at scale in production microservices handling 1M+ permission checks/second

Status: v0.1.0 - Production-ready, API stable

Built with ❤️ by Daniel Curtis