config

module
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 7, 2026 License: MIT

README

config

CI Go Reference 日本語

kanna-config generates, for a struct of settings, the function that reads it from flags, the environment, and files, and checks it by the validate tags of kanna-validate. The name of each setting follows from the names of the struct and the field. What it generates is plain Go that reads each setting with strconv and checks each rule, with no reflection, and an error names the setting as it is set: the variable, the key in the file, or the flag.

It is one of the kanna family of code generators. It needs Go 1.27 or later, as the runtime of go-kanna/validate does.

Install

go get -tool github.com/go-kanna/config/cmd/kanna-config
go get github.com/go-kanna/config github.com/go-kanna/validate

The generated code imports package source of this module, the runtime of go-kanna/validate, and the constructors of the types of kanna-value it reads. A YAML or a TOML file is read by a module of its own, which only a program reading one requires:

go get github.com/go-kanna/config/yaml   # or github.com/go-kanna/config/toml

Usage

Mark a struct of settings //kanna:config:

package config

//go:generate go tool kanna-config

//kanna:config
type Database struct {
	AdminURL     string
	WriterURL    string        `validate:"required"`
	PoolMaxConns int32         `default:"10" validate:"gte=1"`
	DialTimeout  time.Duration `default:"5s"`
}

go generate ./... writes config_gen.go beside it, with DefineDatabaseFlags, which defines the struct's flags, and LoadDatabase, which reads it:

// Code generated by kanna-config. DO NOT EDIT.

func LoadDatabase(src source.Source) (Database, error) {
	var (
		x    Database
		errs validate.Errors
	)

	// ...

	x.PoolMaxConns = 10
	namePoolMaxConns := "DATABASE_POOL_MAX_CONNS"
	if v, ok, err := src.Lookup(source.Key{Env: "DATABASE_POOL_MAX_CONNS", File: []string{"database", "pool_max_conns"}, Flag: "database-pool-max-conns"}); err != nil {
		errs.Add(v.Name, err)
	} else if ok {
		namePoolMaxConns = v.Name
		if n, err := strconv.ParseInt(v.Text, 10, 32); err != nil {
			errs.Add(namePoolMaxConns, validate.FailWith("invalid", map[string]any{"type": "int32"}))
		} else {
			x.PoolMaxConns = int32(n)
		}
	}

	// ...

	if len(errs) > 0 {
		return Database{}, errs
	}

	if x.WriterURL == "" {
		errs.Add(nameWriterURL, validate.Blank())
	}

	if x.PoolMaxConns < 1 {
		errs.Add(namePoolMaxConns, validate.GreaterThanOrEqualTo[int32](1))
	}

	if len(errs) > 0 {
		return Database{}, errs
	}
	return x, nil
}

The program says where the settings are:

fs := flag.NewFlagSet("api", flag.ExitOnError)
config.DefineDatabaseFlags(fs)
_ = fs.Parse(os.Args[1:])

src, err := source.Open(source.Sources{
	Flags: fs,
	Files: []source.File{{Path: "config/production.yaml", Decode: yaml.Decode}},
})
if err != nil {
	return err
}
db, err := config.LoadDatabase(src)

With DATABASE_WRITER_URL unset and pool_max_conns: 0 in the file, LoadDatabase returns the errors under the names the settings are set by:

validate: DATABASE_WRITER_URL: blank; database.pool_max_conns: greater_than_or_equal_to (count=1)

Names

Each field is one setting, named by words: those of the struct, then those of the field, split as kanna-orm splits a field into the name of its column. Each source spells the words its own way:

Field Variable File Flag
Database.WriterURL DATABASE_WRITER_URL writer_url in section database -database-writer-url
Database.PoolMaxConns DATABASE_POOL_MAX_CONNS pool_max_conns in section database -database-pool-max-conns
API.Port API_PORT port in section api -api-port

The words of the struct set apart the settings of each struct. Two structs of one name, such as postgres.Config and redis.Config, read the same settings, which is allowed, as sharing a setting may be meant.

The names are external: what a deployment sets. Where the words of the struct are not those, write them with prefix=, in snake case: a struct named OAuth splits into o_auth, and one named Config is better set apart.

//kanna:config prefix=oauth
type OAuth struct {
	ClientID string `validate:"required"` // OAUTH_CLIENT_ID, oauth.client_id, -oauth-client-id
}

The words of a field are written likewise with config:"…", such as config:"oauth_token" for a field OAuthToken. A variable a platform names, such as the PORT of Cloud Run, is written whole with env:"…", which takes no prefix and changes the variable alone. Words the convention would give anyway may be written too, to keep a name when the Go name changes.

A name of env:"…" is read as written, lower case included (http_proxy), but for an empty one and one holding = or NUL, which no variable has. As in a json tag, the name ends at the first comma: an option after it stops the run, as kanna-config takes none. Two fields of one struct reading one setting stop the run.

Sources

A setting is looked for in the flags, then in the environment, then in the files, the last first, and the first to give it text gives its value. An empty text gives none, as an unset one does: DATABASE_POOL_MAX_CONNS= in a file of variables is the same as no line.

A variable may hold, rather than the value, the path of a file holding it, as Kubernetes mounts a secret: DATABASE_PASSWORD_FILE gives DATABASE_PASSWORD the content of that file, less one line ending at its end. Both set stop the read with an error.

Flags are those of the flag package, defined by DefineXFlags on a FlagSet the program parses; only the flags set count. A bool flag may stand alone, as -database-debug.

Files

A file is read by the Decode of its source.File: source.JSON, yaml.Decode of github.com/go-kanna/config/yaml, or toml.Decode of github.com/go-kanna/config/toml. kanna-config does not look for files, nor tell environments apart: the program names the files, in the order they win, a later over an earlier, and a file that is not there is an error.

Each struct is a section of the file, and each of its fields a key in it, so that one file holds the settings of every struct:

database:
  writer_url: postgres://writer@db/app
  pool_max_conns: 20
api:
  port: 8080

A value in a file is read as its text, as a variable is: 20 and "20" read the same. A section or a list where a value goes is an error. A null is unset.

Fields not read

Each field of the struct is read. An unexported field, an embedded one, and one named _ cannot be, and stop the run. Tag a field the settings do not give config:"-", such as a password the program reads from a secret manager after LoadX:

type Database struct {
	WriterURL string `validate:"required"`
	Password  string `config:"-"`
}

LoadX leaves such a field zero, and does not check its rules, as the program fills it later; a struct marked //kanna:validate as well checks them in its Validate. A rule of such a field in a struct without //kanna:validate would never run, and stops the run, as does a default of such a field.

Defaults

A setting given nowhere leaves its field zero, or gives it the default of its tag:

type Database struct {
	PoolMaxConns int32         `default:"10"`
	DialTimeout  time.Duration `default:"5s"`
}

The default of a string, a bool, a number, a time.Duration, or an enum of kanna-value is read on generating, and written as a Go value: x.PoolMaxConns = 10, x.DialTimeout = 5 * time.Second, a constant of the enum. One that does not read stops the run. It is checked then by the rules that tell by the value alone, run no code of the program, and need no other field: required, the lengths, the comparisons, oneof, and pattern. A default one of them rejects stops the run, as it would fail every start without the setting. rule=Type, eqfield, email, url, uuid, and the hook are checked on reading. The default of a value type of kanna-value or of a type with UnmarshalText is read when the setting is given nowhere, as a setting is.

Types it reads

The first of these that fits a field's type reads it:

Type Read with
time.Duration time.ParseDuration (30s, 5m), not as a number of nanoseconds
a value type of kanna-value what it holds, read as below, passed to its constructor
an enum of kanna-value its constructor
a type whose pointer has UnmarshalText UnmarshalText (slog.Level, netip.Addr, time.Time)
a string, or a type defined on one the text as it is
a bool, or a type defined on one strconv.ParseBool
an integer, or a type defined on one strconv.ParseInt or strconv.ParseUint, at its size
a float, or a type defined on one strconv.ParseFloat, at its size

Any other type, such as a pointer, a slice, a map, or a struct, stops the run. A list, such as one separated by commas, is read by a type of its own with UnmarshalText; settings that nest are a struct of their own, marked //kanna:config.

What cannot be read is reported by a code and its params, never by the value, which a setting may keep secret: a number, a bool, or a duration that does not read is invalid with the type, as in DATABASE_POOL_MAX_CONNS: invalid (type=int32). What a constructor or an UnmarshalText returns is kept when it has a code, as the rules of kanna-value do, and otherwise is invalid with the type: the error of slog.Level holds the value. Having a code is no proof of holding no value; what a code and its params say is up to whoever writes the type. The type param is there for a log or a structured error, and no promise of a placeholder a translation can show.

Checking

The validate tags mean what they mean to kanna-validate, and LoadX checks them; the struct needs no //kanna:validate. A validate(errs *validate.Errors) method of the struct, the hook of kanna-validate, runs after the tags.

LoadX returns errors in two steps:

  1. It reads every setting, and returns the errors of those that cannot be read, checking no rule.
  2. Once all are read, it returns the errors of the rules and the hook.

A setting that cannot be read leaves its field without the value read, and checking the rules then could report a rule across fields, or the hook, that the value it lacks breaks.

An error goes under the name of the setting where it was set: the variable, database.pool_max_conns, or -database-pool-max-conns. A setting given nowhere goes under its variable. What a field's own Validate reports stays under that name, as DATABASE_PRIMARY.host. The hook names a field as kanna-validate does, by its JSON name, or else its Go name, and checks its paths on generating; kanna-config moves what it reports under the name of the field's setting, keeping what follows. An error on the struct as a whole stays under base.

Only reading turns an error into a code. The rules return what they return, as in kanna-validate, so that one rule reports the same in LoadX and in Validate: keeping a value out of an error is up to whoever writes the rule, and rule.Fail of kanna-value and validate.Fail keep it out.

required is a rule of the value, as in kanna-validate: it rejects the zero value, an explicit 0 or false included, and lets a setting given nowhere through when its default is not zero. Nothing tells whether a variable is set. With a string default, required holds in LoadX always, and still checks a value the program makes by hand in the Validate of a struct marked //kanna:validate.

No Validate is generated for LoadX. To call one elsewhere, mark the struct //kanna:validate too; LoadX still checks the rules itself, so that the mark changes nothing of it.

What it generates

For each struct X marked //kanna:config, config_gen.go holds:

  • DefineXFlags(fs *flag.FlagSet), which defines the flags of X, each named and with its default, as LoadX reads them.
  • LoadX(src source.Source) (X, error), which reads X and checks it. The error, when there is one, is a validate.Errors.

A function of the same name written by hand stops the run. kanna-di finds LoadX in the package of X as what provides X from a source.Source.

A test of LoadX sets the variables with t.Setenv, which rules out t.Parallel. A test of what uses the settings makes the struct itself, and runs in parallel.

Moving from caarlos0/env

A name written env:"…" reads as it does in caarlos0/env, and its envDefault:"…" becomes default:"…", but the reading differs: an empty variable is unset, only the types above read, and required rejects the zero value. The other tags and options stop the run, saying what differs:

caarlos0/env kanna-config
envDefault:"…" default:"…"
env:"X,required" Nothing tells whether a variable is set. validate:"required" asks for a value that is not zero, which rejects 0 and false as well
env:"X,notEmpty" validate:"required" comes near, but rejects 0 and false as well
envPrefix No nested struct is read: mark it //kanna:config of its own, its prefix with prefix=
envSeparator, envKeyValSeparator No slice or map is read: give the field a type of its own with UnmarshalText
env:"X,file" X_FILE names the file; to read a path given otherwise, read it after LoadX into a field marked config:"-"
env:"X,expand" Call os.ExpandEnv after LoadX
env:"X,unset" Call os.Unsetenv after LoadX
env:"X,init" No pointer is read, so there is nothing to make

Flags

kanna-config [flags] [packages]
Flag Meaning
-tags <list> comma-separated build tags
-check verify the output is up to date instead of writing it, no stale output left included; KANNA_CHECK=1 does the same
-v list the files written, removed, and left unchanged
-deps print what a run reads and writes, as JSON, for the kanna command, and exit
-version print the version

Example

example reads the settings of a server from a YAML file, a TOML file, the environment, and flags, and prints what each gives, and what is wrong with settings that cannot be read or break a rule. CI regenerates it and fails if the output changes.

License

MIT

Directories

Path Synopsis
cmd
kanna-config command
Command kanna-config generates the functions reading the settings of structs marked //kanna:config from flags, the environment, and files.
Command kanna-config generates the functions reading the settings of structs marked //kanna:config from flags, the environment, and files.
internal
gen
Package gen is kanna-config: it generates, for each struct marked //kanna:config, the function reading it from flags, the environment, and files, and checking it by its validate tags, and the function defining its flags.
Package gen is kanna-config: it generates, for each struct marked //kanna:config, the function reading it from flags, the environment, and files, and checking it by its validate tags, and the function defining its flags.
Package source finds the settings that the code kanna-config generates reads a struct from.
Package source finds the settings that the code kanna-config generates reads a struct from.
toml module
yaml module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL