README
¶
go-onlineconf
Go package go-onlineconf reads configuration files generated by onlineconf-updater.
Usage
go-onlineconf can work with context or with instanse of OnlineConf client directly.
Work with context
go-onlineconf has functions for work with context.
Initialize
Create an instance and store it into context
All static method
Getting go-onlineconf instance from context. If can't when receive error.
Example context
ctx, err := onlineconf.Initialize(context.Background())
if err != nil {
fmt.Printf("Error initialize onlineconf: %s", err)
return
}
v, ex, err := onlineconf.GetStringIfExists(ctx, "/testapp/bla")
if err != nil {
fmt.Printf("Error while getting param: %s\n", err)
return
}
if !ex {
fmt.Printf("String does not exists\n")
return
}
fmt.Printf("Value %s\n", v)
Work with instance
If you dont use context in you app, you can use static function Create for create go-onlinecong instance directly
Create
Create go-onlineconf instance and return it as result
Instance's method's
Instance of go-onlinecof has many methods for comunicate with him
Example instance directly
oc := onlineconf.Create()
v, ex, err := oc.GetStringIfExists("/testapp/bla")
if err != nil {
fmt.Printf("Error while getting param: %s\n", err)
return
}
if !ex {
fmt.Printf("String does not exists\n")
return
}
fmt.Printf("Value %s\n", v)
Support module
The go-onlineconf supports modules. All previous example works with default module 'TREE'. If you need you can use another module.
GetModule / GetOrAddModule
GetModule("name") returns already readed module by go-onlineconf instance
GetOrAddModule(name) return or add module to go-onlineconf instance
Example use non default module
ctx, err := onlineconf.Initialize(context.Background())
m, err := GetOrAddModule(ctx, "module1")
if err != nil {
fmt.Printf("Error while getting module: %s\n", err)
return
}
v, err := m.GetString("bla")
if err != nil {
fmt.Printf("Error while getting param: %s\n", err)
return
}
fmt.Printf("Value %s\n", v)
instance := onlineconf.Create()
m, err := instance.GetOrAddModule("module1")
if err != nil {
fmt.Printf("Error while getting module: %s\n", err)
return
}
v, err := m.GetString("bla")
if err != nil {
fmt.Printf("Error while getting param: %s\n", err)
return
}
fmt.Printf("Value %s\n", v)
Watcher
The go-onlineconf can watch for chanches of module files (onlineconf-updater update their).
StartWatch / StopWatch
The StartWatch method create the gorutine that listen fsnotify events. For all transfered events config storred in module replaced to new config.
The StopWatcher method stops listen fsnotify events and if onlineconf-updater gets new config the stored config in go-onlineconf module can't be replaced.
Example watcher
globalCtx, _ := Initialize(context.Background())
err := StartWatcher(globalCtx)
if err != nil {
fmt.Printf("can't start watcher: %s", err)
return
}
v, err := GetString(globalCtx, "bla")
if err != nil {
fmt.Printf("error get string: %s", err)
return
}
fmt.Printf("Value: %s\n", v) // Value: blav
// `onlineconf-updater` gets new file
v, err = GetString(globalCtx, "bla")
if err != nil {
fmt.Printf("error get string: %s", err)
return
}
fmt.Printf("Value: %s\n", v) // Value: blav1
StopWatcher(globalCtx)
Subscriptions to changes
If you need to subscribe to changes params you can use watcher mechanism.
RegisterSubscription
The RegisterSubscription saves callback and params for trigger callback on params changes. If params is nil or any of values in params array is an empty string than callback will be triggered for any changes in module.
Example subscription
globalCtx, _ := Initialize(context.Background())
err := StartWatcher(globalCtx)
if err != nil {
fmt.Printf("can't start watcher: %s", err)
return
}
params := []string{"param1", "param2"}
callback := func() error {
// Callback implementation
return nil
}
err := RegisterSubscription(globalCtx, module, params, callback)
// `onlineconf-updater` gets new file and if `param1` or `param2` is changed the `callback` will be called
StopWatcher(globalCtx)
Clone config
If you need to make readonly copy with static configuration what can't be changed you can use Clone function.
This function works only with context and uses then you write daemon app. For example than app with http server receive users request create new context for processing and clone go-onlineconf instanse into it. In this case confguration can't be changed in cloned instance even if onlineconf-updater gets new config. But at same time instanse in global context will be changed. So it's allows from start to finish processes user request gets the same config.
If you use Clone you must use Release method if you finished work with that context. After Release all modules from instanse is droped
Example clone config
var globalCtx, _ = Initialize(context.Background())
err := StartWatcher(globalCtx)
if err != nil {
fmt.Printf("can't start watcher: %s", err)
return
}
v, err := GetString(globalCtx, "bla")
if err != nil {
fmt.Printf("error get string", err)
return
}
fmt.Printf("Value: %s\n", v) // Value: blav
newCtx := context.Background()
newCtx, _ = Clone(globalCtx, newCtx)
// `onlineconf-updater` gets new config
v, err = GetString(globalCtx, "bla")
if err != nil {
fmt.Printf("error get string", err)
return
}
fmt.Printf("Value: %s\n", v) // Value: blav1
v, err = GetString(newCtx, "bla")
if err != nil {
fmt.Printf("error get string", err)
return
}
fmt.Printf("Value: %s\n", v) // Value: blav
err = Release(globalCtx, newCtx)
if err != nil {
fmt.Printf("error release: %s", err)
return
}
Initialization options
Path for search module
The go-onlineconf module use default path for search module files /usr/local/etc/onlineconf. If you want to change it you can use onlineconf.WithConfigDir in initialize function.
Logger instance
The go-onlineconf has LoggerInterface for work with you project logger. If you want to use you owned logger you need to use onlineconf.WithLogger method in initialize instance.
Example options
tmpConfDir := "/opt/myproject/etc/"
type MyLogger struct{}
func (l *MyLogger) Warn(ctx context.Context, msg string, args ...any) {
/// ...
}
func (l *MyLogger) Error(ctx context.Context, msg string, args ...any) {
// ...
}
func (l *MyLogger) Fatal(ctx context.Context, msg string, args ...any) {
// ...
}
globalCtx, _ := onlineconf.Initialize(context.Background(), onlineconf.WithConfigDir(tmpConfDir), onlineconf.WithLogger(&MyLogger{}))
Directories