configuration

README

Configuration

What does this library?

This library provides a simple way to load configuration from different sources.

It supports:

• Environment variables
• Command line flags
• Configuration files
  • JSON
  • YAML
  • TOML
  • Properties
• Configuration from a struct
• HTTP API (get and set configuration)
• Monitor File changes

Installation

go get gitlab.schukai.com/oss/libraries/go/application/configuration

Note: This library uses Go Modules to manage dependencies.

Usage

Initialize

A new configuration is created using the configuration.New() function. The passed structure is used type for the configuration. The values are taken as default values of the configuration.

package main

import (
    "fmt"
    "os"
    "gitlab.schukai.com/oss/libraries/go/application/configuration"
)

func main(){
  config := struct {
    Host string
    Port int
  }{
    Host: "localhost",
    Port: 8080,
  }

  c := configuration.New(config)

  fmt.Println(c.Config().Host)
  fmt.Println(c.Config().Port)

}

Configuration values can come from different sources. The order of sources is important.

Environment variables

With the Environment function, you can load configuration from environment variables.

package main

import (
    "fmt"
    "os"
    "gitlab.schukai.com/oss/libraries/go/application/configuration"
)

func main(){
  config := struct {
    Host string `env:"HOST"`
  }{
    Host: "localhost",
  }

  // Set value
  os.Setenv("HOST", "www.example.com")

  s := configuration.New(config)
  fmt.Println(s.Config().Host) // localhost

  s.InitFromEnv("") // no prefix
  fmt.Println(s.Config().Host) // www.example.com

}

Command line flags

Obviously, you can also load configuration from command line flags. This library supports the standard library flag package.

package main

import (
    "fmt"
    "os"
   "flag"
    "gitlab.schukai.com/oss/libraries/go/application/configuration"
)

func main(){
  config := struct {
    Host string `flag:"host"`
  }{
    Host: "localhost",
  }

  // Set value
  flag.String("host", "www.example.com", "help message for host flag")
  flag.Parse()

  s := configuration.New(config)
  s.InitFromFlagSet(flag.CommandLine)

  fmt.Println(s.Config().Host) // www.example.com

}

Do you want to allow the user to specify a configuration via the command line, so you can use the AddFileFromFlagSet function. This function expects a flag.FlagSet.

Import files and streams

You can load configuration from files and streams. With the Import() function you import files and streams. The specified files are loaded first, and then the streams.

The configurations are merged. If a value is already set, it is overwritten by the specified value. So if a value is set in etc and in the more specific File in the user home directory, the value is taken from the user home directory.

package main

import (
   "fmt"
   "os"
   "flag"
   "gitlab.schukai.com/oss/libraries/go/application/configuration"
)

func main() {

   config := struct {
      Host string
   }{
      Host: "localhost",
   }

   c := configuration.New(config)

   c.SetMnemonic("my-app")
   c.SetDefaultDirectories()
   c.Import()

   fmt.Println(c.Config().Host)

}

The configuration would then be looked for in the following places:

• ~/config.yaml (working directory)
• ~/.config/my-app/config.yaml
• /etc/my-app/config.yaml

Configuration files

Configuration files are certainly the most common way to define configurations. These can be in different formats. The following formats are currently supported: JSON, YAML, TOML and Properties.

With files, the approach is slightly different. Here the function AddDirectory() first, specify directories in which to search for the file. The file is then searched for in the order of the directories. If the file is found is loaded.

The helper function AddWorkingDirectory() adds the current working directory.

With AddEtcDirectory() the directory etc is added under Unix.

AddUserConfigDirectory() adds the directory ~.config on Unix. It will uses the os.UserConfigDir() method. Thus, it is possible to use the directory can also be used on other operating systems.

The SetDefaultDirectories() method sets the paths to the default values. Become internal the paths with AddWorkingDirectory(), AddEtcDirectory() and AddUserConfigDirectory() set.

The directory structure can be specified directly with the SetDirectories() function. This overwrites the directory structure specified with AddDirectory().

The filename of the configuration file is specified with SetFileName(). The file name is searched for with the extension .json, .yaml, .yml, .toml or .properties.

If a format is specified with the SetFileFormat() method, only files with searched for this ending.

As an extra, you can specify your own file system with SetFilesystem(). This is useful for testing.

Furthermore, the AddFile() function can be used to add a file directly. This makes sense if you are given a file as a parameter or if you don't want to have a multi-level structure.

Watch files

If you want to watch configuration files for changes, you can use the Watch() function. With the function StopWatch() you can stop watching the files. The function returns a bool channel on which the status of the watch is reported.

If the watch has ended, a true is sent over the channel. If an error occurs, a false is sent.

Streams

The configuration can also be loaded from a stream. This is useful if you want to load the configuration from other sources. For example, from a database.

With the AddReader() function, you can add a stream to the configuration. The stream is then searched for in the order of the streams. If the stream is found is loaded.

HTTP API

The configuration can also be changed via HTTP. This is useful if you want to change the configuration at runtime. For example, if you would like to change the configuration of a service.

With a Get request, the configuration is returned as the format specified in the Accept header. If no format is specified, the configuration is returned in JSON format.

With a Post request, the configuration can be changed. The configuration is then taken from the body of the request. The format is determined by the Content-Type header. If no format is specified, the configuration is taken from the JSON format.

config := struct {
   Host string
}
s := New(config)
mux := http.NewServeMux()
mux.HandleFunc("/config", s.ServeHTTP)

There is also a middleware to get access to the configuration.

config := struct {
    Host string
}
s := New(config)
mux := http.NewServeMux()
mux.Use(s.Middleware)

The configuration can then be accessed via the config context.

func handler(w http.ResponseWriter, r *http.Request) {
	config := r.Context().Value("config").(struct {
		Host string
	})
	fmt.Println(config.Host)
}

On change

If you want to be notified when the configuration changes, you can use the OnChange() function. This function takes a callback function as a parameter.

The following program gives the following output Change from localhost to www.example.com.

package main

import (
   "fmt"
   "os"
   "flag"
   "gitlab.schukai.com/oss/libraries/go/application/configuration"
)

func main() {
   config := struct {
      Host string
   }{
      Host: "localhost",
   }

   s := configuration.New(config)

   closeChan := make(chan bool)

   s.OnChange(func(event configuration.ChangeEvent) {
      log := event.Changlog
      msg := fmt.Sprintf("Change from %s to %s", log[0].From, log[0].To)
      fmt.Println(msg)
      closeChan <- true
   })

   c := s.Config()
   c.Host = "www.example.com"

   s.SetConfig(c)

   // Wait for change
   select {
   case <-closeChan:
   }

}

Error handling

If an error occurs, it is returned by the function Errors(). The errors can be handled as usual.

The HasErrors() function can be used to check whether errors have occurred.

Contributing

Merge requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please make sure to update tests as appropriate.

Versioning is done with SemVer. Changelog is generated with git-chglog

Commit messages should follow the Conventional Commits specification. Messages are started with a type, which is one of the following:

• feat: A new feature
• fix: A bug fix
• doc: Documentation only changes
• refactor: A code change that neither fixes a bug nor adds a feature
• perf: A code change that improves performance
• test: Adding missing or correcting existing tests
• chore: Other changes that don't modify src or test files

The footer would be used for a reference to an issue or a breaking change.

A commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in semantic versioning). A BREAKING CHANGE can be part of commits of any type.

the following is an example of a commit message:

feat: add 'extras' field

License

AGPL-3.0

Documentation

Index

• Variables
• type ChangeEvent
• type EventHook
• type FlagDoesNotExistError
• type FlagNotFoundError
• type Format
  • func (f Format) Extension() string
  • func (f Format) String() string
• type FormatNotSupportedError
• type MismatchedTypeError
• type PathAlreadyExistsError
• type PathDoesNotExistError
• type Settings
  • func New[C any](defaults C) *Settings[C]
  • func (s *Settings[C]) AddDirectory(d string) *Settings[C]
  • func (s *Settings[C]) AddEtcDirectory() *Settings[C]
  • func (s *Settings[C]) AddFile(file string, format Format) *Settings[C]
  • func (s *Settings[C]) AddFileFromFlagSet(flagset *flag.FlagSet, name string, format Format) *Settings[C]
  • func (s *Settings[C]) AddReader(r io.Reader, format Format) *Settings[C]
  • func (s *Settings[C]) AddUserConfigDirectory() *Settings[C]
  • func (s *Settings[C]) AddWorkingDirectory() *Settings[C]
  • func (s *Settings[C]) Config() C
  • func (s *Settings[C]) Directories() []string
  • func (s *Settings[C]) Errors() []error
  • func (s *Settings[C]) Export() *Settings[C]
  • func (s *Settings[C]) HasErrors() bool
  • func (s *Settings[C]) Import() *Settings[C]
  • func (s *Settings[C]) InitFromEnv(prefix string) *Settings[C]
  • func (s *Settings[C]) InitFromFlagSet(flagset *flag.FlagSet) *Settings[C]
  • func (s *Settings[C]) Middleware(next http.Handler) http.Handler
  • func (s *Settings[C]) OnChange(hook EventHook) *Settings[C]
  • func (s *Settings[C]) ResetErrors() *Settings[C]
  • func (s *Settings[C]) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *Settings[C]) SetConfig(config C) *Settings[C]
  • func (s *Settings[C]) SetDefaultDirectories() *Settings[C]
  • func (s *Settings[C]) SetDirectories(d []string) *Settings[C]
  • func (s *Settings[C]) SetFileFormat(format Format) *Settings[C]
  • func (s *Settings[C]) SetFileName(name string) *Settings[C]
  • func (s *Settings[C]) SetFilesystem(f fs.FS) *Settings[C]
  • func (s *Settings[C]) SetMnemonic(mnemonic string) *Settings[C]
  • func (s *Settings[C]) StopWatching() *Settings[C]
  • func (s *Settings[C]) Watch() *Settings[C]
  • func (s *Settings[C]) Write(writer io.Writer, format Format) *Settings[C]
  • func (s *Settings[C]) WriteFile(fn string, format Format) *Settings[C]
• type UnsupportedReflectKindError
• type UnsupportedTypeError

Variables

var FileNameEmptyError = errors.New("file name is empty")

var MnemonicEmptyError = errors.New("mnemonic is empty")

var NoFileImportedError = errors.New("no file imported")

var NoFilesToWatchError = errors.New("no files to watch")

var WatchAlreadyInitializedError = errors.New("watch already initialized")

var WatchAlreadyRunningError = errors.New("watch already running")

var WatchListNotInitializedError = errors.New("watch list not initialized")

var WatchNotInitializedError = errors.New("watch not initialized")

var WatchNotRunningError = errors.New("watch not running")

Types

type ChangeEvent

type ChangeEvent struct {
	Changlog diff.Changelog
}

type EventHook

type EventHook func(event ChangeEvent)

type FlagDoesNotExistError

type FlagDoesNotExistError error

type FlagNotFoundError

type FlagNotFoundError error

This error indicates that the flag is not found

type Format

type Format int

const (
	Yaml Format = iota
	Json
	Toml
	Properties
)

func (Format) Extension

func (f Format) Extension() string

func (Format) String

func (f Format) String() string

type FormatNotSupportedError

type FormatNotSupportedError error

FormatNotSupportedError is returned when the format is not supported

type MismatchedTypeError

type MismatchedTypeError error

MismatchedTypeError is used to indicate that the type is not matching

type PathAlreadyExistsError

type PathAlreadyExistsError error

PathAlreadyExistsError is returned when a files already exists

type PathDoesNotExistError

type PathDoesNotExistError error

PathDoesNotExistError is returned when a files do not exist

type Settings

type Settings[C any] struct {
	sync.Mutex
	// contains filtered or unexported fields
}

func New

func New[C any](defaults C) *Settings[C]

NewSetting creates a new configuration setting with the given defaults.

func (*Settings[C]) AddDirectory

func (s *Settings[C]) AddDirectory(d string) *Settings[C]

AddPath adds a directory to the configuration directory

func (*Settings[C]) AddEtcDirectory

func (s *Settings[C]) AddEtcDirectory() *Settings[C]

Add the Unix etc directory to the configuration directory

func (*Settings[C]) AddFile

func (s *Settings[C]) AddFile(file string, format Format) *Settings[C]

AddFiles adds a file to the list of files to import

func (*Settings[C]) AddFileFromFlagSet

func (s *Settings[C]) AddFileFromFlagSet(flagset *flag.FlagSet, name string, format Format) *Settings[C]

AddFileFromFlagSet adds a file to the configuration The file is read from the flag specified by the name

func (*Settings[C]) AddReader

func (s *Settings[C]) AddReader(r io.Reader, format Format) *Settings[C]

func (*Settings[C]) AddUserConfigDirectory

func (s *Settings[C]) AddUserConfigDirectory() *Settings[C]

Add the user configuration directory to the configuration directory The mnemonic must be set for this function

func (*Settings[C]) AddWorkingDirectory

func (s *Settings[C]) AddWorkingDirectory() *Settings[C]

Add the current working directory to the configuration directory

func (*Settings[C]) Config

func (s *Settings[C]) Config() C

Config() returns the configuration

func (*Settings[C]) Directories

func (s *Settings[C]) Directories() []string

Path returns the configuration directory

func (*Settings[C]) Errors

func (s *Settings[C]) Errors() []error

Get all errors

func (*Settings[C]) Export

func (s *Settings[C]) Export() *Settings[C]

func (*Settings[C]) HasErrors

func (s *Settings[C]) HasErrors() bool

Check if the setting contains errors

func (*Settings[C]) Import

func (s *Settings[C]) Import() *Settings[C]

func (*Settings[C]) InitFromEnv

func (s *Settings[C]) InitFromEnv(prefix string) *Settings[C]

func (*Settings[C]) InitFromFlagSet

func (s *Settings[C]) InitFromFlagSet(flagset *flag.FlagSet) *Settings[C]

InitFromFlagSet initializes the configuration from the command line flags.

func (*Settings[C]) Middleware

func (s *Settings[C]) Middleware(next http.Handler) http.Handler

ContextKey is the key used to store the configuration in the request context This is used by the middleware

func (*Settings[C]) OnChange

func (s *Settings[C]) OnChange(hook EventHook) *Settings[C]

func (*Settings[C]) ResetErrors

func (s *Settings[C]) ResetErrors() *Settings[C]

ResetError is used to reset the error to nil After calling this function, the call HasErrors() will return false

func (*Settings[C]) ServeHTTP

func (s *Settings[C]) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements the http.Handler interface

func (*Settings[C]) SetConfig

func (s *Settings[C]) SetConfig(config C) *Settings[C]

func (*Settings[C]) SetDefaultDirectories

func (s *Settings[C]) SetDefaultDirectories() *Settings[C]

Add the current working directory, the user configuration directory and the Unix etc directory to the configuration directory

func (*Settings[C]) SetDirectories

func (s *Settings[C]) SetDirectories(d []string) *Settings[C]

Set all configuration directories

func (*Settings[C]) SetFileFormat

func (s *Settings[C]) SetFileFormat(format Format) *Settings[C]

func (*Settings[C]) SetFileName

func (s *Settings[C]) SetFileName(name string) *Settings[C]

Set the file name without extension

func (*Settings[C]) SetFilesystem

func (s *Settings[C]) SetFilesystem(f fs.FS) *Settings[C]

func (*Settings[C]) SetMnemonic

func (s *Settings[C]) SetMnemonic(mnemonic string) *Settings[C]

Set the mnemonic The mnemonic is used to identify the configuration in the configuration file

func (*Settings[C]) StopWatching

func (s *Settings[C]) StopWatching() *Settings[C]

func (*Settings[C]) Watch

func (s *Settings[C]) Watch() *Settings[C]

Watch the given file for changes

func (*Settings[C]) Write

func (s *Settings[C]) Write(writer io.Writer, format Format) *Settings[C]

func (*Settings[C]) WriteFile

func (s *Settings[C]) WriteFile(fn string, format Format) *Settings[C]

type UnsupportedReflectKindError

type UnsupportedReflectKindError error

At the reflect level, some types are not supported

type UnsupportedTypeError

type UnsupportedTypeError error

UnsupportedTypeError is returned when the type is not supported