gosettings

README

Gosettings

gosettings is a Go package providing helper functions for working with settings.

Go.dev documentation:

• gosettings
• gosettings/validate
• gosettings/reader

Add it to your Go project with:

go get github.com/qdm12/gosettings

💁 Only compatible with Go 1.18+ since it now uses generics.

Features:

• Define settings struct methods:
  • Copy: use gosettings.CopyPointer and gosettings.CopySlice
  • SetDefaults: gosettings.Default* functions (see pkg.go.dev/github.com/qdm12/gosettings)
  • OverrideWith: gosettings.OverrideWith* functions (see pkg.go.dev/github.com/qdm12/gosettings)
  • Validate: validate.* functions from github.com/qdm12/gosettings/validate
• Reading settings from multiple sources with precedence with github.com/qdm12/gosettings/reader
  • Environment variable implementation env.New(env.Settings{Environ: os.Environ()}) in subpackage github.com/qdm12/gosettings/reader/sources/env
  • Flag implementation flag.New(os.Args) in subpackage github.com/qdm12/gosettings/reader/sources/flag
• Minor feature notes:
  • No use of reflect for better runtime safety
  • Single dependency on kernel.org/pub/linux/libs/security/libcap/cap to validate listening ports for programs with Linux capabalities

Philosophy

After having worked with Go and settings from different sources for years, I have come with a design I am happy with.

Settings struct

Each component has a settings struct, where the zero value of a field should be meaningless. For example, if the value 0 is allowed for a field, then it must be an *int field. On the contrary, you could have an int field if the zero value 0 is meaningless. The reasoning behind this is that you want the zero Go value to be considered as 'unset field' so that the field value can be defaulted and overridden by another settings struct. See the below interface comments for more details on what this allows.

Next, each of your settings struct should ideally implement the following interface:

type Settings interface {
 // SetDefaults sets default values for all unset fields.
 // All pointer fields must be defaulted to a non nil value.
 // Usage:
 // - Once on the base settings at the start of the program.
 // - If the user requests a reset of the settings, on an empty settings struct.
 SetDefaults()
 // Validate validates all the settings and return an error if any field value is invalid.
 // It should only be called after `SetDefaults()` is called, and therefore should assume
 // all pointer fields are set and NOT nil.
 // Usage:
 // - Validate settings early at program start
 // - Validate new settings given, after calling .Copy() + .OverrideWith(newSettings)
 Validate() (err error)
 // Copy deep copies all the settings to a new Settings object.
 // Usage:
 // - Copy settings before modifying them with OverrideWith(), to validate them with Validate() before actually using them.
 Copy() Settings
 // OverrideWith sets all the set values of the other settings to the fields of the receiver settings.
 // Usage:
 // - Update settings at runtime
 OverrideWith(other Settings)
 // ToLinesNode returns a (tree) node with the settings as lines, for displaying settings
 // in a formatted tree, where you can nest settings node to display a full settings tree.
 ToLinesNode() *gotree.Node
 // String returns the string representation of the settings.
 // It should simply return `s.ToLinesNode().String()` to show a tree of settings.
 String() string
}

💁 This is my recommendation, and obviously you don't need to:

• define this interface
• have all these methods exported
• define ToLinesNode with gotree if you don't want to

➡️ Example settings implementation

More concrete settings implementation examples using this library are notably:

• Gluetun
• qdm12/dns
• tinier

Settings methods usage

In the following Go examples, we use the example settings implementation.

Read settings from multiple sources

The Reader from the github.com/qdm12/gosettings/reader package can be used to read and parse settings from one or more sources. A source implements the interface:

type Source interface {
 String() string
 Get(key string) (value string, isSet bool)
 KeyTransform(key string) string
}

There are already defined sources such as reader.Env for environment variables.

A simple example (runnable here) would be:

flagSource := flag.New([]string{"program", "--key1=A"})
envSource := env.New(env.Settings{Environ: []string{"KEY1=B", "KEY2=2"}})
reader := reader.New(reader.Settings{
  Sources: []reader.Source{flagSource, envSource},
})

value := reader.String("KEY1")
// flag source takes precedence
fmt.Println(value) // Prints "A"

n, err := reader.Int("KEY2")
if err != nil {
  panic(err)
}
// flag source has no value, so the environment
// variable source is used.
fmt.Println(n) // Prints "2"

You can perform more advanced parsing, for example with the methods BoolPtr, CSV, Duration, Float64, Uint16Ptr, etc.

Each of these parsing methods accept some options, notably to:

• Force the string value to be lowercased
• Accept empty string values as 'set values'
• Define retro-compatible keys

Updating settings at runtime

🚧 To be completed 🚧

Documentation

Index

• func BoolToYesNo(b *bool) string
• func CopyPointer[T any](original *T) (copied *T)
• func CopySlice[T any](original []T) (copied []T)
• func DefaultComparable[T comparable](existing, defaultValue T) (result T)
• func DefaultPointer[T any](existing *T, defaultValue T) (result *T)
• func DefaultSlice[T any](existing, defaultValue []T) (result []T)
• func DefaultValidator[T SelfValidator](existing, defaultValue T) (result T)
• func ObfuscateKey(key string) (obfuscatedKey string)
• func OverrideWithComparable[T comparable](existing, other T) (result T)
• func OverrideWithPointer[T any](existing, other *T) (result *T)
• func OverrideWithSlice[T any](existing, other []T) (result []T)
• func OverrideWithValidator[T SelfValidator](existing, other T) (result T)
• type SelfValidator

Functions

func BoolToYesNo

func BoolToYesNo(b *bool) string

BoolToYesNo returns "yes" if the given boolean is true, "no" if the given boolean is false, and an empty string if the given boolean pointer is nil.

func CopyPointer

func CopyPointer[T any](original *T) (copied *T)

CopyPointer returns a new pointer to the copied value of the original argument value.

func CopySlice

func CopySlice[T any](original []T) (copied []T)

CopySlice returns a new slice with each element of the original slice copied.

func DefaultComparable

func DefaultComparable[T comparable](existing, defaultValue T) (result T)

DefaultComparable returns the existing argument if it is not the zero value, otherwise it returns the defaultValue argument. If used with an interface and an implementation of the interface, it must be instantiated with the interface type, for example: variable := DefaultComparable[Interface](variable, &implementation{}) Avoid using this function for non-interface pointers, use DefaultPointer instead to create a new pointer.

func DefaultPointer

func DefaultPointer[T any](existing *T, defaultValue T) (result *T)

DefaultPointer returns the existing argument if it is not nil. Otherwise it returns a new pointer to the defaultValue argument. To default an interface to an implementation, use DefaultComparable.

func DefaultSlice

func DefaultSlice[T any](existing, defaultValue []T) (result []T)

DefaultSlice returns the existing slice argument if is not nil. Otherwise it returns a new slice with the copied values of the defaultValue slice argument. Note it is preferrable to use this function for added mutation safety on the result, but one can use DefaultSliceRaw if performance matters.

func DefaultValidator

func DefaultValidator[T SelfValidator](existing, defaultValue T) (
	result T)

DefaultValidator returns the existing argument if it is valid, otherwise it returns the defaultValue argument.

func ObfuscateKey

func ObfuscateKey(key string) (obfuscatedKey string)

ObfuscateKey returns an obfuscated key for logging purposes. If the key is empty, `[not set]` is returned. If the key has up to 128 bits of security with 2 characters removed, it will be obfuscated as `[set]`. If the key has at least 128 bits of security if at least 2 characters are removed from it, it will be obfuscated as `start_of_key...end_of_key`, where the start and end parts are each at least 1 character long, and up to 3 characters long. Note the security bits are calculated by assuming each unique character in the given key is a symbol in the alphabet, which gives a worst case scenario regarding the alphabet size. This will likely produce lower security bits estimated compared to the actual security bits of the key, but it's better this way to avoid divulging information about the key when it should not be. Finally, the 128 bits security is chosen because this function is to be used for logging purposes, which should not be exposed publicly either.

func OverrideWithComparable

func OverrideWithComparable[T comparable](existing, other T) (result T)

OverrideWithComparable returns the other argument if it is not the zero value, otherwise it returns the existing argument. If used with an interface and an implementation of the interface, it must be instantiated with the interface type, for example: variable := OverrideWithComparable[Interface](variable, &implementation{}) Avoid using this function for non-interface pointers, use OverrideWithPointer instead to create a new pointer.

func OverrideWithPointer

func OverrideWithPointer[T any](existing, other *T) (result *T)

OverrideWithPointer returns the existing argument if the other argument is nil. Otherwise it returns a new pointer to the copied value of the other argument value, for added mutation safety. To override an interface and an implementation, use OverrideWithComparable.

func OverrideWithSlice

func OverrideWithSlice[T any](existing, other []T) (result []T)

OverrideWithSlice returns the existing slice argument if the other slice argument is nil. Otherwise it returns a new slice with the copied values of the other slice argument. Note it is preferrable to use this function for added mutation safety on the result, but one can use OverrideWithSliceRaw if performance matters.

func OverrideWithValidator

func OverrideWithValidator[T SelfValidator](existing, other T) (
	result T)

OverrideWithValidator returns the existing argument if other is not valid, otherwise it returns the other argument.

Types

type SelfValidator

type SelfValidator interface {
	// IsValid returns true if the value is valid, false otherwise.
	IsValid() bool
}

SelfValidator is an interface for a type that can validate itself. This is notably the case of netip.IP and netip.Prefix, and can be implemented by the user of this library as well.