conf

README

conf

Package conf provides a set of utilities for mapping configuration settings (from env vars, flags and secret managers) to struct fields.

import "github.com/fritzkeyzer/conf"

Usage

Example from examples/main.go

package main

import (
	"os"

	"github.com/fritzkeyzer/conf"
)

type Config struct {
	Host    string `env:"HOST" flag:"--host"`
	Verbose bool   `flag:"-v"`
	Count   int    `flag:"--count"`
	DB      struct {
		Name string `env:"DB_NAME"`
		User string `env:"DB_USER" secret:"db-user"`
		Pass string `env:"DB_PASS" secret:"db-pass"`
	}
}

// main demonstrates various functions of the conf package
//   - LoadEnv loads fields from environment variables
//   - LoadFlags loads fields from command line flags
//   - LoadSecrets loads fields from a secret manager
//   - Print prints the config to stdout
func main() {
	// for demo purposes, we set the env vars here
	os.Setenv("HOST", "localhost")
	os.Setenv("DB_NAME", "app")
	os.Setenv("DB_USER", "user from env")
	os.Setenv("DB_PASS", "pass from env")

	var cfg Config

	if err := conf.LoadEnv(&cfg); err != nil {
		panic(err)
	}

	// fields can be overridden by flags, eg: host, verbose or count
	if err := conf.LoadFlags(&cfg); err != nil {
		panic(err)
	}

	// fields can be loaded from a secret manager
	if err := conf.LoadSecrets(&cfg, &SecretManager{}); err != nil {
		panic(err)
	}

	// notice how the secret fields are masked with ***
	conf.Print(&cfg)

	// Output:
	// ---------------------------
	//  Host      = "localhost"
	//  Verbose   = false
	//  DB
	//    .Name   = "app"
	//    .User   = "user"
	//    .Pass   ***
	// ---------------------------
}

// SecretManager is a mock secret manager, for demo purposes
type SecretManager struct{}

func (sm *SecretManager) Load(key string) (string, bool, error) {
	if key == "db-user" {
		return "user from secret manager", true, nil
	}

	if key == "db-pass" {
		return "secret password 1337", true, nil
	}

	return "", false, nil
}

Documentation

Overview

Package conf provides a set of utilities for mapping configuration settings (from env vars, flags and secret managers) to struct fields.

Index

• func GetFlag(flag string, args []string) (val string, found bool)
• func LoadEnv(ptr any) error
• func LoadFlags(ptr any) error
• func LoadSecrets(ptr any, source SecretSource) error
• func Print(ptr any)
• func PrintToString(ptr any) string
• type Field
  • func FlattenStructFields(ptr any) ([]Field, error)
  • func (f *Field) EnvVar() (string, bool)
  • func (f *Field) ExportValue() (string, error)
  • func (f *Field) FlagName() (string, bool)
  • func (f *Field) SecretKey() (string, bool)
  • func (f *Field) SetValue(rawVal string, found bool) error
• type SecretSource

Examples

• GetFlag

Functions

func GetFlag

func GetFlag(flag string, args []string) (val string, found bool)

GetFlag is a utility to extract a flag from a slice of CLI args. It returns the value of the flag and a boolean indicating whether the flag was found. For example, args could be os.Args[1:]. flag should include the prefix, eg: "--verbose" or "-v" GetFlag supports the following formats:

flag=value
flag="value"
flag='value'
flag value
flag "value"
flag 'value'

Example

args := []string{"nonsense", "--xyz=abc", "nonsense", "-v"}

xyz, _ := GetFlag("--xyz", args)
_, verbose := GetFlag("-v", args)

fmt.Printf("xyz = %q, verbose = %v", xyz, verbose)

Output:

xyz = "abc", verbose = true

func LoadEnv

func LoadEnv(ptr any) error

LoadEnv recursively scans struct fields for the env tag then sets the values from the corresponding env var. Eg:

type Config struct {
	Host string `env:"HOST"`
}

func LoadFlags

func LoadFlags(ptr any) error

LoadFlags recursively scans struct fields for the `flag` tag then sets the values from CLI flags. Eg:

type Config struct {
	Host    string `flag:"--host"`
	Verbose bool   `flag:"-v"`
}

func LoadSecrets

func LoadSecrets(ptr any, source SecretSource) error

LoadSecrets recursively scans struct fields for the secret tag then sets the values from the secret SecretSource. Eg:

type Config struct {
	Host string `secret:"host"`
}

func Print

func Print(ptr any)

Print wraps PrintToString and prints the result to stdout. Example output:

Host      = "localhost"
Verbose   = false
DB
  .Name   = "app"
  .User   = "user"
  .Pass   ***

func PrintToString

func PrintToString(ptr any) string

PrintToString returns a string representation of the config struct. Secrets are masked. Example output:

Host      = "localhost"
Verbose   = false
DB
  .Name   = "app"
  .User   = "user"
  .Pass   ***

Types

type Field

type Field struct {
	// contains filtered or unexported fields
}

Field represents a struct field

func FlattenStructFields

func FlattenStructFields(ptr any) ([]Field, error)

FlattenStructFields returns a flat slice of Field from recursively traversing the struct fields of v.

• unexported fields are omitted
• fields marked with an env, flag or secret tag are included, but their children are not

func (*Field) EnvVar

func (f *Field) EnvVar() (string, bool)

EnvVar returns the `env` tag value and a bool indicating if the field has the `env` tag.

func (*Field) ExportValue

func (f *Field) ExportValue() (string, error)

ExportValue returns the value of the field as a string. If the field is not a string it will be marshalled to JSON.

func (*Field) FlagName

func (f *Field) FlagName() (string, bool)

FlagName returns the `flag` tag value and a bool indicating if the field has the `flag` tag.

func (*Field) SecretKey

func (f *Field) SecretKey() (string, bool)

SecretKey returns the `secret` tag value and a bool indicating if the field has the `secret` tag.

func (*Field) SetValue

func (f *Field) SetValue(rawVal string, found bool) error

SetValue from a string. If the field is not a string or a bool, it will be unmarshalled from JSON.

type SecretSource

type SecretSource interface {
	// Load a secret from the source. Returns the secret value, a boolean indicating if the secret was found and an error.
	// NOTE: Load should not return an error if the secret was not found, but should instead return "", false, nil.
	Load(key string) (string, bool, error)
}

SecretSource interface allows any secret manager to be used, by wrapping it in a type that implements this interface.