Argus: Dynamic Configuration Framework for Go

High-performance configuration management framework for Go applications with zero-allocation performance, universal format support (JSON, YAML, TOML, HCL, INI, Properties), and an ultra-fast CLI powered by Orpheus.

Live Demo

<div align="center">

See Argus in action - managing configurations across multiple formats with zero-allocation performance:

<picture> <source media="(max-width: 768px)" srcset="https://asciinema.org/a/iJZ6b5MbcbIwCfrmE8xdd5w6T.svg" width="100%"> <source media="(max-width: 1024px)" srcset="https://asciinema.org/a/iJZ6b5MbcbIwCfrmE8xdd5w6T.svg" width="90%"> <img src="https://asciinema.org/a/iJZ6b5MbcbIwCfrmE8xdd5w6T.svg" alt="Argus CLI Demo" style="max-width: 100%; height: auto;" width="800"> </picture>

Click to view interactive demo

</div>

Installation • Quick Start • Performance • Architecture • Framework • Observability • Philosophy • Documentation

Features

• Universal Format Support: JSON, YAML, TOML, HCL, INI, Properties with auto-detection
• ConfigWriter System: Atomic configuration file updates with type-safe operations
• Ultra-Fast CLI: Orpheus-powered CLI
• Professional Grade Validation: With detailed error reporting & performance recommendations
• Security Hardened: Red-team tested against path traversal, injection, DoS and resource exhaustion attacks
• Fuzz Tested: Comprehensive fuzzing for ValidateSecurePath and ParseConfig edge cases
• Zero-Allocation Design: Pre-allocated buffers eliminate GC pressure in hot paths
• Remote Config: Distributed configuration with automatic fallback (Remote → Local). Currently available: HashiCorp Consul, Redis, GitOps with more to come..
• Graceful Shutdown: Timeout-controlled shutdown for Kubernetes and production deployments
• OpenTelemetry Ready: Async tracing and metrics with zero contamination of core library
• Type-Safe Binding: Zero-reflection configuration binding with fluent API (1.6M ops/sec)
• Adaptive Optimization: Five strategies (SingleEvent, SmallBatch, LargeBatch, Light, Auto)
• Unified Audit System: SQLite-based cross-application correlation with JSONL fallback
• Scalable Monitoring: Handle 1-1000+ files simultaneously with linear performance

Compatibility and Support

Argus is designed for Go 1.24+ environments and follows Long-Term Support guidelines to ensure consistent performance across production deployments.

Installation

go get github.com/agilira/argus

Quick Start

Multi-Source Configuration Loading

import "github.com/agilira/argus"

// Load with automatic precedence: ENV vars > File > Defaults
config, err := argus.LoadConfigMultiSource("config.yaml")
if err != nil {
    log.Fatal(err)
}

watcher := argus.New(*config)

Type-Safe Configuration Binding

// Ultra-fast zero-reflection binding (1.6M ops/sec)
var (
    dbHost     string
    dbPort     int
    enableSSL  bool
    timeout    time.Duration
)

err := argus.BindFromConfig(parsedConfig).
    BindString(&dbHost, "database.host", "localhost").
    BindInt(&dbPort, "database.port", 5432).
    BindBool(&enableSSL, "database.ssl", true).
    BindDuration(&timeout, "database.timeout", 30*time.Second).
    Apply()

Real-Time Configuration Updates

// Watch any configuration format - auto-detected
watcher, err := argus.UniversalConfigWatcher("config.yaml", 
    func(config map[string]interface{}) {
        fmt.Printf("Config updated: %+v\n", config)
    })

watcher.Start()
defer watcher.Stop()

Remote Configuration

// Distributed configuration with automatic fallback
remoteManager := argus.NewRemoteConfigWithFallback(
    "https://consul.internal:8500/v1/kv/app/config",  // Primary
    "https://backup-consul.internal:8500/v1/kv/app/config", // Fallback
    "/etc/myapp/fallback.json", // Local fallback
)

watcher := argus.New(argus.Config{
    Remote: remoteManager.Config(),
})

// Graceful shutdown for Kubernetes deployments
defer watcher.GracefulShutdown(30 * time.Second)

Directory Watching

// Watch entire directory for config files with pattern filtering
watcher, err := argus.WatchDirectory("/etc/myapp/config.d", argus.DirectoryWatchOptions{
    Patterns:  []string{"*.yaml", "*.json"},
    Recursive: true,
}, func(update argus.DirectoryConfigUpdate) {
    if update.IsDelete {
        fmt.Printf("Config removed: %s\n", update.FilePath)
    } else {
        fmt.Printf("Config updated: %s\n", update.FilePath)
    }
})
defer watcher.Close()

// Merged config from all files (alphabetical order, later overrides earlier)
watcher, err := argus.WatchDirectoryMerged("/etc/myapp/config.d", argus.DirectoryWatchOptions{
    Patterns: []string{"*.yaml"},
}, func(merged map[string]interface{}, files []string) {
    // 00-base.yaml + 10-override.yaml = merged config
    applyConfig(merged)
})

CLI Usage

# Ultra-fast configuration management CLI
argus config get config.yaml server.port
argus config set config.yaml database.host localhost
argus config convert config.yaml config.json
argus watch config.yaml --interval=1s

Orpheus CLI Integration → - Complete CLI documentation and examples

Performance

Engineered for production environments with sustained monitoring and minimal overhead:

Benchmarks

Configuration Monitoring:      12.10 ns/op     (99.999% efficiency)
Format Auto-Detection:         2.79 ns/op      (universal format support)
JSON Parsing (small):          1,712 ns/op     (616 B/op, 16 allocs/op)
JSON Parsing (large):          7,793 ns/op     (3,064 B/op, 86 allocs/op)
Event Processing:              25.51 ns/op     (BoreasLite single event, CPU-efficient)
Write Operations:              10.15 ns/op     (Ultra-fast file event writing)
vs Go Channels:                5.6x faster     (10.31 ns vs 57.62 ns/op)
CLI Command Parsing:             512 ns/op     (3 allocs/op, Orpheus framework)

Test BoreasLite ring buffer performance:

cd benchmarks && go test -bench="BenchmarkBoreasLite.*" -run=^$ -benchmem

See isolated benchmarks for detailed ring buffer performance analysis.

Scalability (Setup Performance):

File Count    Setup Time    Strategy Used
   50 files    11.92 μs/file  SmallBatch
  500 files    23.95 μs/file  LargeBatch
 1000 files    38.90 μs/file  LargeBatch

Detection rate: 100% across all scales

Optimization Strategies:

| Strategy | Best For | CPU When Idle | Event Latency | |---|---|---|---| | OptimizationSingleEvent | 1-2 files, real-time systems | High | <100ns | | OptimizationSmallBatch | 3-20 files, balanced workloads | Medium | <1us | | OptimizationLargeBatch | 20+ files, high throughput | Medium | <500us | | OptimizationLight | Config hot-reload, daemons | Near-zero | <1ms | | OptimizationAuto | Let Argus decide | Varies | Varies |

Use OptimizationLight for config files that change rarely (daemon processes, CLI tools):

watcher := argus.New(argus.Config{
    PollInterval:         10 * time.Second,
    OptimizationStrategy: argus.OptimizationLight,
})

Architecture

Argus provides intelligent configuration management through polling-based optimization with lock-free stat cache (12.10ns monitoring overhead), ultra-fast format detection (2.79ns per operation).

Complete Architecture Guide →

Parser Support

Built-in parsers optimized for rapid deployment with full specification compliance available via plugins.

Advanced Features: Complex configurations requiring full spec compliance should use plugin parsers via argus.RegisterParser(). See docs/parser-guide.md for details.

Core Framework

ConfigWriter System

Atomic configuration file management with type-safe operations across all supported formats:

// Create writer with automatic format detection
writer, err := argus.NewConfigWriter("config.yaml", argus.FormatYAML, config)
if err != nil {
    return err
}

// Type-safe value operations (zero allocations)
writer.SetValue("database.host", "localhost")
writer.SetValue("database.port", 5432)
writer.SetValue("debug", true)

// Atomic write to disk
if err := writer.WriteConfig(); err != nil {
    return err
}

// Query operations
host