{"id":30769966,"url":"https://github.com/agilira/argus","last_synced_at":"2026-05-03T01:03:51.778Z","repository":{"id":311837787,"uuid":"1043904687","full_name":"agilira/argus","owner":"agilira","description":"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.","archived":false,"fork":false,"pushed_at":"2026-02-02T18:53:51.000Z","size":14850,"stargazers_count":165,"open_issues_count":0,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-02-03T08:45:06.703Z","etag":null,"topics":["agilira-orpheus","cli","configuration-management","go","hcl","high-performance","hot-reload","ini","properties","toml","yaml"],"latest_commit_sha":null,"homepage":"https://github.com/agilira/argus","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agilira.png","metadata":{"files":{"readme":"README.md","changelog":"changelog/v1.0.0.txt","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":"audit.go","citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-24T21:30:15.000Z","updated_at":"2026-02-02T18:30:34.000Z","dependencies_parsed_at":"2025-08-27T07:37:25.445Z","dependency_job_id":"3a7b2b4a-fd3e-4918-a7df-13991b41651b","html_url":"https://github.com/agilira/argus","commit_stats":null,"previous_names":["agilira/argus"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/agilira/argus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Fargus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Fargus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Fargus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Fargus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agilira","download_url":"https://codeload.github.com/agilira/argus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Fargus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31535203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agilira-orpheus","cli","configuration-management","go","hcl","high-performance","hot-reload","ini","properties","toml","yaml"],"created_at":"2025-09-04T23:02:48.400Z","updated_at":"2026-05-03T01:03:51.761Z","avatar_url":"https://github.com/agilira.png","language":"Go","funding_links":[],"categories":["配置","Configuration"],"sub_categories":["标准CLI","Standard CLI"],"readme":"# Argus: Dynamic Configuration Framework for Go\n\n![Argus Banner](assets/banner.png)\n\nHigh-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).\n\n[![CI/CD Pipeline](https://github.com/agilira/argus/actions/workflows/ci.yml/badge.svg)](https://github.com/agilira/argus/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/agilira/argus/actions/workflows/codeql.yml/badge.svg)](https://github.com/agilira/argus/actions/workflows/codeql.yml)\n[![Security](https://img.shields.io/badge/security-gosec-brightgreen.svg)](https://github.com/agilira/argus/actions/workflows/ci.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/agilira/argus?v=2)](https://goreportcard.com/report/github.com/agilira/argus)\n[![Test Coverage](https://img.shields.io/badge/coverage-87.7%25-brightgreen)](https://github.com/agilira/argus)\n[![CLI Coverage](https://img.shields.io/badge/cli_coverage-77.5%25-green)](https://github.com/agilira/argus)\n![Xantos Powered](https://img.shields.io/badge/Xantos-Powered-8A2BE2)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/11273/badge)](https://www.bestpractices.dev/projects/11273)\n[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)\n\n## Live Demo\n\n\u003cdiv align=\"center\"\u003e\n\nSee Argus in action - managing configurations across multiple formats with zero-allocation performance:\n\n\u003cpicture\u003e\n  \u003csource media=\"(max-width: 768px)\" srcset=\"https://asciinema.org/a/ZuUskxFCGcotZJ61.svg\" width=\"100%\"\u003e\n  \u003csource media=\"(max-width: 1024px)\" srcset=\"https://asciinema.org/a/ZuUskxFCGcotZJ61.svg\" width=\"90%\"\u003e\n  \u003cimg src=\"https://asciinema.org/a/ZuUskxFCGcotZJ61.svg\" alt=\"Argus CLI Demo\" style=\"max-width: 100%; height: auto;\" width=\"800\"\u003e\n\u003c/picture\u003e\n\n*[Click to view interactive demo](https://asciinema.org/a/ZuUskxFCGcotZJ61)*\n\n\u003c/div\u003e\n\n**[Installation](#installation) • [Quick Start](#quick-start) • [Performance](#performance) • [Architecture](#architecture) • [Framework](#core-framework) • [Observability](#observability--integrations) • [Philosophy](#the-philosophy-behind-argus) • [Documentation](#documentation)**\n\n\n### Features\n\n- **Universal Format Support**: JSON, YAML, TOML, HCL, INI, Properties with auto-detection\n- **ConfigWriter System**: Atomic configuration file updates with type-safe operations\n- **Ultra-Fast CLI**: [Orpheus](https://github.com/agilira/orpheus)-powered CLI\n- **Professional Grade Validation**: With detailed error reporting \u0026 performance recommendations\n- **Security Hardened**: [Red-team tested](argus_security_test.go) against path traversal, injection, DoS and resource exhaustion attacks\n- **Fuzz Tested**: [Comprehensive fuzzing](argus_fuzz_test.go) for ValidateSecurePath and ParseConfig edge cases\n- **Zero-Allocation Design**: Pre-allocated buffers eliminate GC pressure in hot paths\n- **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..\n- **Graceful Shutdown**: Timeout-controlled shutdown for Kubernetes and production deployments\n- **OpenTelemetry Ready**: Async tracing and metrics with zero contamination of core library\n- **Type-Safe Binding**: Zero-reflection configuration binding with fluent API (1.6M ops/sec)\n- **Adaptive Optimization**: Five strategies (SingleEvent, SmallBatch, LargeBatch, Light, Auto) \n- **Unified Audit System**: SQLite-based cross-application correlation with JSONL fallback\n- **Scalable Monitoring**: Handle 1-1000+ files simultaneously with linear performance\n\n## Compatibility and Support\n\nArgus is designed for Go 1.24+ environments and follows Long-Term Support guidelines to ensure consistent performance across production deployments.\n\n## Installation\n\n```bash\ngo get github.com/agilira/argus\n```\n\n## Quick Start\n\n### Multi-Source Configuration Loading\n```go\nimport \"github.com/agilira/argus\"\n\n// Load with automatic precedence: ENV vars \u003e File \u003e Defaults\nconfig, err := argus.LoadConfigMultiSource(\"config.yaml\")\nif err != nil {\n    log.Fatal(err)\n}\n\nwatcher := argus.New(*config)\n```\n\n### Type-Safe Configuration Binding\n```go\n// Ultra-fast zero-reflection binding (1.6M ops/sec)\nvar (\n    dbHost     string\n    dbPort     int\n    enableSSL  bool\n    timeout    time.Duration\n)\n\nerr := argus.BindFromConfig(parsedConfig).\n    BindString(\u0026dbHost, \"database.host\", \"localhost\").\n    BindInt(\u0026dbPort, \"database.port\", 5432).\n    BindBool(\u0026enableSSL, \"database.ssl\", true).\n    BindDuration(\u0026timeout, \"database.timeout\", 30*time.Second).\n    Apply()\n```\n\n### Real-Time Configuration Updates\n```go\n// Watch any configuration format - auto-detected\nwatcher, err := argus.UniversalConfigWatcher(\"config.yaml\", \n    func(config map[string]interface{}) {\n        fmt.Printf(\"Config updated: %+v\\n\", config)\n    })\n\nwatcher.Start()\ndefer watcher.Stop()\n```\n\n### Remote Configuration\n```go\n// Distributed configuration with automatic fallback\nremoteManager := argus.NewRemoteConfigWithFallback(\n    \"https://consul.internal:8500/v1/kv/app/config\",  // Primary\n    \"https://backup-consul.internal:8500/v1/kv/app/config\", // Fallback\n    \"/etc/myapp/fallback.json\", // Local fallback\n)\n\nwatcher := argus.New(argus.Config{\n    Remote: remoteManager.Config(),\n})\n\n// Graceful shutdown for Kubernetes deployments\ndefer watcher.GracefulShutdown(30 * time.Second)\n```\n\n### Directory Watching\n```go\n// Watch entire directory for config files with pattern filtering\nwatcher, err := argus.WatchDirectory(\"/etc/myapp/config.d\", argus.DirectoryWatchOptions{\n    Patterns:  []string{\"*.yaml\", \"*.json\"},\n    Recursive: true,\n}, func(update argus.DirectoryConfigUpdate) {\n    if update.IsDelete {\n        fmt.Printf(\"Config removed: %s\\n\", update.FilePath)\n    } else {\n        fmt.Printf(\"Config updated: %s\\n\", update.FilePath)\n    }\n})\ndefer watcher.Close()\n\n// Merged config from all files (alphabetical order, later overrides earlier)\nwatcher, err := argus.WatchDirectoryMerged(\"/etc/myapp/config.d\", argus.DirectoryWatchOptions{\n    Patterns: []string{\"*.yaml\"},\n}, func(merged map[string]interface{}, files []string) {\n    // 00-base.yaml + 10-override.yaml = merged config\n    applyConfig(merged)\n})\n```\n\n### CLI Usage\n```bash\n# Ultra-fast configuration management CLI\nargus config get config.yaml server.port\nargus config set config.yaml database.host localhost\nargus config convert config.yaml config.json\nargus watch config.yaml --interval=1s\n```\n**[Orpheus CLI Integration →](./docs/cli-integration.md)** - Complete CLI documentation and examples\n\n## Performance\n\nEngineered for production environments with sustained monitoring and minimal overhead:\n\n### Benchmarks\n```\nConfiguration Monitoring:      12.10 ns/op     (99.999% efficiency)\nFormat Auto-Detection:         2.79 ns/op      (universal format support)\nJSON Parsing (small):          1,712 ns/op     (616 B/op, 16 allocs/op)\nJSON Parsing (large):          7,793 ns/op     (3,064 B/op, 86 allocs/op)\nEvent Processing:              25.51 ns/op     (BoreasLite single event, CPU-efficient)\nWrite Operations:              10.15 ns/op     (Ultra-fast file event writing)\nvs Go Channels:                5.6x faster     (10.31 ns vs 57.62 ns/op)\nCLI Command Parsing:             512 ns/op     (3 allocs/op, Orpheus framework)\n```\n**Test BoreasLite ring buffer performance**:\n```bash\ncd benchmarks \u0026\u0026 go test -bench=\"BenchmarkBoreasLite.*\" -run=^$ -benchmem\n```\nSee [isolated benchmarks](./benchmarks/) for detailed ring buffer performance analysis.\n\n**Scalability (Setup Performance):**\n```\nFile Count    Setup Time    Strategy Used\n   50 files    11.92 μs/file  SmallBatch\n  500 files    23.95 μs/file  LargeBatch\n 1000 files    38.90 μs/file  LargeBatch\n```\n*Detection rate: 100% across all scales*\n\n**Optimization Strategies:**\n\n| Strategy | Best For | CPU When Idle | Event Latency |\n|---|---|---|---|\n| `OptimizationSingleEvent` | 1-2 files, real-time systems | High | \u003c100ns |\n| `OptimizationSmallBatch` | 3-20 files, balanced workloads | Medium | \u003c1us |\n| `OptimizationLargeBatch` | 20+ files, high throughput | Medium | \u003c500us |\n| `OptimizationLight` | Config hot-reload, daemons | Near-zero | \u003c1ms |\n| `OptimizationAuto` | Let Argus decide | Varies | Varies |\n\nUse `OptimizationLight` for config files that change rarely (daemon processes, CLI tools):\n\n```go\nwatcher := argus.New(argus.Config{\n    PollInterval:         10 * time.Second,\n    OptimizationStrategy: argus.OptimizationLight,\n})\n```\n\n## Architecture\n\nArgus 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).\n\n**[Complete Architecture Guide →](./docs/ARCHITECTURE.md)**\n\n\n### Parser Support\n\nBuilt-in parsers optimized for rapid deployment with full specification compliance available via plugins.\n\n\u003e **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.\n\n\n## Core Framework\n\n### ConfigWriter System\nAtomic configuration file management with type-safe operations across all supported formats:\n\n```go\n// Create writer with automatic format detection\nwriter, err := argus.NewConfigWriter(\"config.yaml\", argus.FormatYAML, config)\nif err != nil {\n    return err\n}\n\n// Type-safe value operations (zero allocations)\nwriter.SetValue(\"database.host\", \"localhost\")\nwriter.SetValue(\"database.port\", 5432)\nwriter.SetValue(\"debug\", true)\n\n// Atomic write to disk\nif err := writer.WriteConfig(); err != nil {\n    return err\n}\n\n// Query operations\nhost := writer.GetValue(\"database.host\")      // 30ns, 0 allocs\nkeys := writer.ListKeys(\"database\")           // Lists all database.* keys\nexists := writer.DeleteValue(\"old.setting\")   // Removes key if exists\n```\n\n### Configuration Binding\n\n```go\n// Ultra-fast configuration binding - zero reflection\nvar (\n    dbHost     string\n    dbPort     int\n    enableSSL  bool\n    timeout    time.Duration\n)\n\nerr := argus.BindFromConfig(config).\n    BindString(\u0026dbHost, \"database.host\", \"localhost\").\n    BindInt(\u0026dbPort, \"database.port\", 5432).\n    BindBool(\u0026enableSSL, \"database.ssl\", true).\n    BindDuration(\u0026timeout, \"database.timeout\", 30*time.Second).\n    Apply()\n\n// Variables are now populated and ready to use!\n```\n\n**Performance**: 1,645,489 operations/second with single allocation per bind\n\n**[Full API Reference →](./docs/API-REFERENCE.md)**\n\n\n## Observability \u0026 Integrations\n\nProfessional OTEL tracing integration with zero core dependency pollution:\n\n```go\n// Clean separation: core Argus has no OTEL dependencies\nauditLogger, _ := argus.NewAuditLogger(argus.DefaultAuditConfig())\n\n// Optional OTEL wrapper (only when needed)\ntracer := otel.Tracer(\"my-service\")\nwrapper := NewOTELAuditWrapper(auditLogger, tracer)\n\n// Use either logger or wrapper seamlessly\nwrapper.LogConfigChange(\"/etc/config.json\", oldConfig, newConfig)\n```\n\n**[Complete OTEL Integration Example →](./examples/otel_integration/)**\n\n## The Philosophy Behind Argus\n\nArgus 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.\n\nThe 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.\n\nWhen 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.\n\n### Unified Audit Configuration\n```go\n// Unified SQLite audit (recommended for cross-application correlation)\nconfig := argus.DefaultAuditConfig()  // Uses unified SQLite backend\n\n// Legacy JSONL audit (for backward compatibility)\nconfig := argus.AuditConfig{\n    Enabled:    true,\n    OutputFile: filepath.Join(os.TempDir(), \"argus-audit.jsonl\"), // .jsonl = JSONL backend\n    MinLevel:   argus.AuditInfo,\n}\n\n// Explicit unified SQLite configuration\nconfig := argus.AuditConfig{\n    Enabled:    true,\n    OutputFile: \"\",  // Empty = unified SQLite backend\n    MinLevel:   argus.AuditCritical,\n}\n```\n\n## Documentation\n\n**Quick Links:**\n- **[Quick Start Guide](./docs/quick-start.md)** - Get running in 2 minutes\n- **[Orpheus CLI Integration](./docs/cli-integration.md)** - Complete CLI documentation and examples\n- **[API Reference](./docs/API-REFERENCE.md)** - Complete API documentation  \n- **[Audit System](./docs/audit-system.md)** - Comprehensive audit and compliance guide\n- **[Examples](./examples/)** - Production-ready configuration patterns\n\n## License\n\nArgus is licensed under the [Mozilla Public License 2.0](./LICENSE.md).\n\n---\n\nArgus • an AGILira fragment\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagilira%2Fargus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagilira%2Fargus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagilira%2Fargus/lists"}