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{}))