Reactive Configuration for Go. Watch. Validate. Apply.
Hot-reload configuration from files, Redis, Consul, or any source. Invalid configs rejected, previous retained, your application only ever sees valid data.
Get Startedimport "github.com/zoobz-io/flux"
type Config struct {
Port int `json:"port"`
Host string `json:"host"`
}
func (c Config) Validate() error {
if c.Port < 1 || c.Port > 65535 {
return errors.New("invalid port")
}
return nil
}
// Watch a file, validate changes, apply safely
capacitor := flux.New[Config](
file.New("/etc/app/config.json"),
func(ctx context.Context, prev, curr Config) error {
log.Printf("Port changed: %d -> %d", prev.Port, curr.Port)
return reconfigureServer(curr)
},
)
capacitor.Start(ctx) // Start watching
capacitor.State() // Loading → Healthy → Degraded
cfg, _ := capacitor.Current() // Always the last valid config
// Invalid config pushed? Rejected. Previous config retained.
// Source goes down? Keeps watching for recovery.Why Flux?
Configuration that updates itself — safely, observably, without restarts.
Validation-First Pipeline
Source → Deserialize → Validate → Callback. If any step fails, the previous valid config is retained automatically.
Four-State Machine
Loading, Healthy, Degraded, Empty — explicit transitions, not hidden in callbacks. Always know your config health.
Multi-Source Composition
Merge defaults, files, and remote configs with Compose(). Priority-based overrides validated as a single unit.
Eight Pluggable Providers
File, Redis, Consul, etcd, NATS, Kubernetes ConfigMap, ZooKeeper, Firestore. One Watcher interface.
Production Observability
Capitan signals on every state transition, error type, and change detection. Metrics and alerting out of the box.
Deterministic Testing
Sync mode disables goroutines, fake clock controls time, channel watchers eliminate flakiness.
Capabilities
Watch, validate, and apply configuration changes from any source — with safe fallback on failure.
| Feature | Description | Link |
|---|---|---|
| Hot-Reload Files | Watch JSON or YAML files. Changes trigger immediate reload with validation before application. | File Config |
| Multi-Source Merging | Combine defaults, local files, and remote overrides into a single validated config. Later sources win. | Multi-Source |
| Custom Watchers | One interface method: Watch(ctx) returns a byte channel. Build HTTP polling, AWS SSM, or gRPC streaming sources. | Custom Watcher |
| Graceful Degradation | Detect Degraded state, use fallback config, automatic recovery on next valid push. Error history for debugging. | State Management |
| Provider Ecosystem | Redis for shared flags, Consul for service mesh, etcd for Kubernetes, Firestore for GCP. Same API everywhere. | Providers |
| Change Callbacks | Callbacks receive both previous and current config. Compare to make smart decisions about what changed. | Concepts |
Articles
Browse the full flux documentation.