https://github.com/agilira/argus
Argus is a high-performance, OS-independent dynamic configuration framework for Go, built for applications that demand real-time updates, universal format support, and production-grade reliability — without service restarts.
https://github.com/agilira/argus
agilira audit-trail configuration-management dynamic-configuration file-watcher go hcl high-performance hot-reload ini lock-free properties toml xantos-powered yaml
Last synced: about 1 month ago
JSON representation
Argus is a high-performance, OS-independent dynamic configuration framework for Go, built for applications that demand real-time updates, universal format support, and production-grade reliability — without service restarts.
- Host: GitHub
- URL: https://github.com/agilira/argus
- Owner: agilira
- License: mpl-2.0
- Created: 2025-08-24T21:30:15.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-08-26T23:06:52.000Z (7 months ago)
- Last Synced: 2025-08-27T07:37:19.973Z (7 months ago)
- Topics: agilira, audit-trail, configuration-management, dynamic-configuration, file-watcher, go, hcl, high-performance, hot-reload, ini, lock-free, properties, toml, xantos-powered, yaml
- Language: Go
- Homepage: https://github.com/agilira/argus
- Size: 6.63 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: changelog/v1.0.0.txt
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
- Audit: audit.go
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-go - argus - File watching and configuration management with MPSC ring buffer, adaptive batching strategies, and universal format parsing (JSON, YAML, TOML, INI, HCL, Properties). (Configuration / Standard CLI)
- awesome-go-with-stars - argus - 02-23 | (Configuration / Standard CLI)
- awesome-go - argus - File watching and configuration management with MPSC ring buffer, adaptive batching strategies, and universal format parsing (JSON, YAML, TOML, INI, HCL, Properties). (Configuration / Standard CLI)
- awesome-go-cn - argus
- fucking-awesome-go - argus - File watching and configuration management with MPSC ring buffer, adaptive batching strategies, and universal format parsing (JSON, YAML, TOML, INI, HCL, Properties). (Configuration / Standard CLI)
README
# 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](https://github.com/agilira/orpheus).
[](https://github.com/agilira/argus/actions/workflows/ci.yml)
[](https://github.com/agilira/argus/actions/workflows/codeql.yml)
[](https://github.com/agilira/argus/actions/workflows/ci.yml)
[](https://goreportcard.com/report/github.com/agilira/argus)
[](https://github.com/agilira/argus)
[](https://github.com/agilira/argus)
[](https://www.bestpractices.dev/projects/11273)
[](https://github.com/avelino/awesome-go)
## Live Demo
See Argus in action - managing configurations across multiple formats with zero-allocation performance:
*[Click to view interactive demo](https://asciinema.org/a/iJZ6b5MbcbIwCfrmE8xdd5w6T)*
**[Installation](#installation) • [Quick Start](#quick-start) • [Performance](#performance) • [Architecture](#architecture) • [Framework](#core-framework) • [Observability](#observability--integrations) • [Philosophy](#the-philosophy-behind-argus) • [Documentation](#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](https://github.com/agilira/orpheus)-powered CLI
- **Professional Grade Validation**: With detailed error reporting & performance recommendations
- **Security Hardened**: [Red-team tested](argus_security_test.go) against path traversal, injection, DoS and resource exhaustion attacks
- **Fuzz Tested**: [Comprehensive fuzzing](argus_fuzz_test.go) 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](https://github.com/agilira/argus-provider-consul), [Redis](https://github.com/agilira/argus-provider-redis), [GitOps](https://github.com/agilira/argus-provider-git) 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**: Four strategies (SingleEvent, SmallBatch, LargeBatch, 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
```bash
go get github.com/agilira/argus
```
## Quick Start
### Multi-Source Configuration Loading
```go
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
```go
// 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
```go
// 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
```go
// 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
```go
// 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
```bash
# 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 →](./docs/cli-integration.md)** - 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**:
```bash
cd benchmarks && go test -bench="BenchmarkBoreasLite.*" -run=^$ -benchmem
```
See [isolated benchmarks](./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*
## 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 →](./docs/ARCHITECTURE.md)**
### 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](docs/parser-guide.md) for details.
## Core Framework
### ConfigWriter System
Atomic configuration file management with type-safe operations across all supported formats:
```go
// 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 := writer.GetValue("database.host") // 30ns, 0 allocs
keys := writer.ListKeys("database") // Lists all database.* keys
exists := writer.DeleteValue("old.setting") // Removes key if exists
```
### Configuration Binding
```go
// Ultra-fast configuration binding - zero reflection
var (
dbHost string
dbPort int
enableSSL bool
timeout time.Duration
)
err := argus.BindFromConfig(config).
BindString(&dbHost, "database.host", "localhost").
BindInt(&dbPort, "database.port", 5432).
BindBool(&enableSSL, "database.ssl", true).
BindDuration(&timeout, "database.timeout", 30*time.Second).
Apply()
// Variables are now populated and ready to use!
```
**Performance**: 1,645,489 operations/second with single allocation per bind
**[Full API Reference →](./docs/API-REFERENCE.md)**
## Observability & Integrations
Professional OTEL tracing integration with zero core dependency pollution:
```go
// Clean separation: core Argus has no OTEL dependencies
auditLogger, _ := argus.NewAuditLogger(argus.DefaultAuditConfig())
// Optional OTEL wrapper (only when needed)
tracer := otel.Tracer("my-service")
wrapper := NewOTELAuditWrapper(auditLogger, tracer)
// Use either logger or wrapper seamlessly
wrapper.LogConfigChange("/etc/config.json", oldConfig, newConfig)
```
**[Complete OTEL Integration Example →](./examples/otel_integration/)**
## The Philosophy Behind Argus
Argus Panoptes was no ordinary guardian. While others slept, he watched. While others blinked, his hundred eyes remained ever vigilant. Hera chose him not for his strength, but for something rarer—his ability to see everything without ever growing weary.
The giant understood that true protection came not from reactive force, but from constant, intelligent awareness. His vigilance was not frantic or wasteful—each eye served a purpose, each moment of watching was deliberate.
When Zeus finally overcame the great guardian, Hera honored Argus by placing his hundred eyes upon the peacock's tail, ensuring his watchful spirit would endure forever.
### Unified Audit Configuration
```go
// Unified SQLite audit (recommended for cross-application correlation)
config := argus.DefaultAuditConfig() // Uses unified SQLite backend
// Legacy JSONL audit (for backward compatibility)
config := argus.AuditConfig{
Enabled: true,
OutputFile: filepath.Join(os.TempDir(), "argus-audit.jsonl"), // .jsonl = JSONL backend
MinLevel: argus.AuditInfo,
}
// Explicit unified SQLite configuration
config := argus.AuditConfig{
Enabled: true,
OutputFile: "", // Empty = unified SQLite backend
MinLevel: argus.AuditCritical,
}
```
## Documentation
**Quick Links:**
- **[Quick Start Guide](./docs/quick-start.md)** - Get running in 2 minutes
- **[Orpheus CLI Integration](./docs/cli-integration.md)** - Complete CLI documentation and examples
- **[API Reference](./docs/API-REFERENCE.md)** - Complete API documentation
- **[Audit System](./docs/audit-system.md)** - Comprehensive audit and compliance guide
- **[Examples](./examples/)** - Production-ready configuration patterns
## License
Argus is licensed under the [Mozilla Public License 2.0](./LICENSE.md).
---
Argus • an AGILira fragment