flowconf

README

FlowConf

The extendable, configurable application configuration and secret manager package for the Go language.

At its core, FlowConf permits the declaration of configurations and secrets in an easily understandable format. FlowConf does not hide the implementation details or where each secret is stored. In order to resolve a secret, a user needs to have permission to view that secret.

Usage

import "github.com/SamuelTissot/flowconf"

// load source from file
sources, err := flowconf.NewSourcesFromFilepaths("fileOne.json", "fileTwo.toml")
if err != nil {
	// handle error
}

// create the builder
builder := flowconf.NewBuilder(sources...)

var conf Configuration // your declared Configuration struct
err = builder.Build(&conf)
if err != nil {
// handle error
}

// USE Configuration

Examples

With Only Static (files) Source

see static source example

Full Example with a Secret Manager

see Secret Manager Example

Documentation

Overview

Package flowconf enable easy configuration and handling of secrets in applications.

It works similar to cascading style sheets where the latest configurations overrides the old one. Making and ideal development tool for several development environment, local, staging, and production

in addition it will resolve secrets from an external secret manager like Google Cloud Secret Manager

It's easily extendable and customizable for your configuration needs

Index

• Variables
• type Builder
  • func NewBuilder(staticSources ...*StaticSource) *Builder
  • func (builder *Builder) Build(config any) error
  • func (builder *Builder) BuildCtx(ctx context.Context, config any) error
  • func (builder *Builder) SetSecretManagers(managers ...SecretManager)
• type Format
• type Opener
• type SecretManager
• type StaticSource
  • func LoadSourcesWithOpener(opener Opener, filepaths ...string) ([]*StaticSource, error)
  • func NewSource(name string, format Format, reader io.ReadCloser) *StaticSource
  • func NewSourcesFromEmbeddedFileSystem(fs embed.FS, filepaths ...string) ([]*StaticSource, error)
  • func NewSourcesFromFilepaths(filepaths ...string) ([]*StaticSource, error)

Examples

• Builder.Build (FromStaticSource)

Variables

var (
	NotAPtrErr = errors.New("config needs to be a pointer")
	IsNilErr   = errors.New("config is nil")
)

Types

type Builder

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

func NewBuilder

func NewBuilder(staticSources ...*StaticSource) *Builder

func (*Builder) Build

func (builder *Builder) Build(config any) error

Example (FromStaticSource)

package main

import (
	"fmt"
	"github.com/SamuelTissot/flowconf"
	"io"
	"strings"
	"time"
)

func main() {

	type MyConfiguration struct {
		MeaningOfLife   int
		Cats            []string
		Pi              float64
		Perfection      []int
		BackToTheFuture time.Time
		Secret          string
		Tag             string `json:"TagValue" toml:"TagValue"`
	}

	tomlSource := `
MeaningOfLife = 42
Cats = [ "James", "Bond" ]
Pi = 3.14
Perfection = [ 6, 28, 496, 8128 ]
BackToTheFuture = 1985-10-21T01:22:00Z

# get the secret from gcp secret manager ( we are not using a secret manager in this example so this will stay the same)
Secret = "@managerprefix::projects/id/secrets/name-of-secret"

# change the name with tags
TagValue = 'tag value'
`

	overrideWith := `
{
	"Cats" : [ "Bob", "Morane" ]
}
`

	// Build the source from files or io.reader
	// to build sources from multiple files you can use
	// sources, err := flowconf.NewSourcesFromFilepaths("config.toml", "config-local.json", "another-config.json")
	//
	// HERE we will only build manually one source from an io.Reader
	source := flowconf.NewSource("example.toml", flowconf.Toml, io.NopCloser(strings.NewReader(tomlSource)))
	overrideSource := flowconf.NewSource("override.json", flowconf.Json, io.NopCloser(strings.NewReader(overrideWith)))

	// create the builder
	builder := flowconf.NewBuilder(source, overrideSource)
	// add secret manager if you need to
	// builder.SetSecretManagers(....)

	// populate the configuration with the builder
	conf := new(MyConfiguration)
	err := builder.Build(conf)
	if err != nil {
		// handle error
		panic(err)
	}

	fmt.Println()
	fmt.Println(conf.MeaningOfLife)
	fmt.Println(strings.Join(conf.Cats, ", "))
	fmt.Println(conf.Pi)
	fmt.Println(conf.Tag)
	// ...

}

Output:

42
Bob, Morane
3.14
tag value

func (*Builder) BuildCtx

func (builder *Builder) BuildCtx(ctx context.Context, config any) error

func (*Builder) SetSecretManagers

func (builder *Builder) SetSecretManagers(managers ...SecretManager)

type Format

type Format string

Format represents a string type that specifies a format.

const (
	Toml Format = "toml"
	Json Format = "json"
)

type Opener

type Opener interface {
	Open(filepath string) (io.ReadCloser, error)
}

Opener is an interface for opening files on the file system or embedded filesystem

type SecretManager

type SecretManager interface {
	// Prefix return the string to look for in the configuration in order to
	// do the substitution in the format of @<PREFIX>::<PATH/KEY>
	//
	// Example for GCP Secret Manager
	// Prefix() --> gcpsecretmanager
	// Usage --> @gcpsecretmanager::project/*/location/*/...
	Prefix() string
	// Secret returns the secret for the given key
	// the key is the @<PREFIX>::<KEY>
	Secret(ctx context.Context, key string) (string, error)
}

SecretManager interface defines the methods required for accessing secrets.

type StaticSource

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

StaticSource represent a config input

func LoadSourcesWithOpener

func LoadSourcesWithOpener(opener Opener, filepaths ...string) ([]*StaticSource, error)

func NewSource

func NewSource(name string, format Format, reader io.ReadCloser) *StaticSource

func NewSourcesFromEmbeddedFileSystem

func NewSourcesFromEmbeddedFileSystem(fs embed.FS, filepaths ...string) ([]*StaticSource, error)

func NewSourcesFromFilepaths

func NewSourcesFromFilepaths(filepaths ...string) ([]*StaticSource, error)