Skip to content
efuturetodayPublic

About

Configuration for Go services: typed structs from files, environment and flags, checked at start

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

88 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

gonf

The Go gopher lifting a gear that forms the O of GONF

Go Reference Build Status Go Version License

gonf fills your Go structs from files, environment and flags, and checks them before your service starts.

  • Typed structs: no string lookups, no casts
  • Fail fast: every error at start, with file and line
  • Layering: defaults, files, .env, env and flags, each one on top
  • Any profiles: dev, staging, local, combined
  • Explain: see where each value came from
  • Env without binding: APP_DB_URL sets app.db.url, typos warned
  • Formats: properties, JSON, YAML, .env
  • Sources: files, env, flags, secret mounts, your own
  • No secret logging: **** in logs, errors and docs
  • Expressions: ${app.db.host}, ${file::/run/secrets/db}
  • Safe reload: a broken change never goes live
  • Generated docs: key reference and JSON Schema
  • Extensible: own sources, formats and functions
  • Library modules: packages bring their own config
  • Zero dependencies: core is standard library only

Getting started

go get github.com/efuturetoday/gonf

Describe your settings as a struct. default and desc are optional:

type Config struct {
	Port int `default:"8080" desc:"HTTP port"`
	DB   struct {
		Host     string              `default:"localhost" desc:"database host"`
		URL      string              `desc:"connection string"`
		Password gonf.Secret[string] `default:"change-me"`
	}
}

var appConfig = gonf.NewMapping[Config]("app")

gonf.NewMapping ties the struct to the name app: the field DB.URL becomes the key app.db.url. Put values in config/app.properties:

app.port=8000
app.db.host=db.internal
app.db.url=postgres://${app.db.host}:5432/app

Load the configuration and read the struct in main.go:

func main() {
	cfg, err := boot.Load(context.Background(), boot.WithMappings(appConfig))
	if err != nil {
		log.Fatal(err)
	}

	for _, w := range cfg.Warnings() {
		log.Println("warning:", w)
	}

	c := appConfig.Get(cfg)
	fmt.Println("port:    ", c.Port)
	fmt.Println("db.url:  ", c.DB.URL)
	fmt.Println("password:", c.DB.Password)

	// go run . app.db.url
	if len(os.Args) > 1 {
		fmt.Println(cfg.Explain(os.Args[1]))
	}
}

The complete program is in examples/quickstart. Run it from that directory:

Terminal: go run prints the port, the database URL and the masked password

$ go run .
port:     8000
db.url:   postgres://db.internal:5432/app
password: ****

boot.Load found config/app.properties by itself. Now set a value with an environment variable. It wins over the file:

$ APP_PORT=9000 go run .
port:     9000
db.url:   postgres://db.internal:5432/app
password: ****

That is the whole idea: a struct, a file, and the environment on top.

Examples

Each example below runs against the quickstart program.

A mistake in the file

Say config/app.properties has a typo, ulr instead of url:

app.port=8000
app.db.host=db.internal
app.db.ulr=postgres://${app.db.host}:5432/app

The program stops at start and reports every problem, not only the first:

Terminal: the program stops at start and lists both problems, with a did-you-mean suggestion

$ go run .
gonf: bind "app": 2 problems:
  app.db.url: required, no value
  app.db.ulr: unknown key, did you mean app.db.url? (from file:config/app.properties:3)

A wrong type is caught the same way, for example app.port=80x:

gonf: bind "app": app.port: invalid int "80x" (from file:config/app.properties:1)

Where does a value come from?

The quickstart prints cfg.Explain(key) for a key given on the command line:

$ APP_PORT=9000 go run . app.port
app.port = 9000 (env:APP_PORT)
  overrides 8000 (file:config/app.properties:1)
  default 8080 (main.go:30)

The first line is the value in use and where it comes from. The lines below show what it replaced, and the default from the struct tag. More in Where does a value come from?.

Profiles

A profile is a named set of values for one environment. Add config/app-dev.properties:

app.db.host=localhost

and start with GONF_PROFILE=dev:

$ GONF_PROFILE=dev go run . app.db.url
port:     8000
db.url:   postgres://localhost:5432/app
password: ****
app.db.url = postgres://localhost:5432/app (file:config/app.properties:3)

The profile file replaced app.db.host, and app.db.url, which refers to it, followed. More in Profiles.

Secrets

Password is a gonf.Secret[string], so it prints as **** with fmt, JSON, slog and in Explain. Your code gets the real value when it asks for it:

password := c.DB.Password.Value()

More in Secrets.

Expressions and functions

A value can refer to another key with ${...}, as app.db.url does with ${app.db.host}. A function takes the form ${name::argument}. Read the password from the environment variable DB_PASSWORD:

app.db.url=postgres://localhost/app
app.db.password=${env::DB_PASSWORD}
$ DB_PASSWORD=s3cret go run . app.db.password
port:     8080
db.url:   postgres://localhost/app
password: ****
app.db.password = **** (file:config/app.properties:2, via env)
  default **** (main.go:30)

If DB_PASSWORD is not set, the start fails with a message that names the key and the line. More in Sources.

Modules

The core has no dependencies. Everything else is a module of its own, released with the same version:

Module
format/yaml YAML files: go get github.com/efuturetoday/gonf/format/yaml
cmd/gonf gonf encrypt for encrypted values: go install github.com/efuturetoday/gonf/cmd/gonf@latest

Planned: HashiCorp Vault, Azure Key Vault, Azure App Configuration, AWS SSM Parameter Store, AWS Secrets Manager, GCP Secret Manager.

Next steps

  • Profiles: %dev. keys, app-dev.properties, activating profiles.
  • Structs: names, defaults, optional fields, lists, maps, validation, unknown keys, and converters for types of other packages.
  • Secrets: gonf.Secret[T], what gets masked, and encrypted values.
  • Where does a value come from?: cfg.Explain shows the winning value, its file and line, and what it overrides; cfg.Warnings() and cfg.Sources() show what was skipped and loaded.
  • Configuration reference: generate a table of all keys with their environment variables, types and defaults, and a JSON Schema for editors.
  • Sources and formats: .properties, JSON, YAML, .env, the environment, flags, secret directories, expressions with functions such as what git knows, and your own Sources.
  • Reloading: boot.Watch keeps the configuration current when files change, and keeps the previous one if a change is invalid.

The API reference is on pkg.go.dev.

More programs in examples/:

gonf, viper or koanf?

gonf viper koanf
Config typed structs keys by name, Unmarshal keys by name, Unmarshal
Unknown keys error at start ignored by default ignored
Environment matched against your structs AutomaticEnv, BindEnv provider with a transform
Origin of a value cfg.Explain no no
Global state none a global instance by default none
Dependencies standard library many one module per provider
  • gonf: typed configuration, checked before the service starts.
  • viper: the largest ecosystem, remote providers.
  • koanf: providers and parsers assembled by hand.

Contributing

Issues and pull requests are welcome. Run go vet ./..., go test -race ./... and golangci-lint run, also in format/yaml and cmd/gonf. Pull request titles follow Conventional Commits; releases and the changelog are made from them. Report vulnerabilities as described in SECURITY.md.

License

Apache License 2.0

The gonf logo is based on the Go gopher by Renée French, licensed under CC BY 4.0.

About

Configuration for Go services: typed structs from files, environment and flags, checked at start

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages