README
¶
config
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-validator. 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/validator does.
Install
go get -tool github.com/go-kanna/config/cmd/kanna-config
go get github.com/go-kanna/config github.com/go-kanna/validator
The generated code imports package source of this module, the runtime of go-kanna/validator, 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 validator.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, validator.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, validator.Blank())
}
if x.PoolMaxConns < 1 {
errs.Add(namePoolMaxConns, validator.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:
validator: 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, as does a field whose variable names the file of another's, such as PasswordFile beside Password.
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.
A file that does not decode is reported by where it is wrong, such as read config/production.yaml: line 2, column 13 is not valid YAML, and not by what the library decoding it says, which may quote a secret written there. A YAML file holds one document, and a second, after a ---, is an error where it starts. source.JSON reads with encoding/json/v2, so a name a JSON object holds twice is an error where the second one is. A Decode of your own should say no more either: source.Open returns its error as it is.
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, or math.NaN() and math.Inf(1) for NaN and +Inf, which no constant holds and whose rules are checked on reading. 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, and so are all the rules of a field whose required or omitempty asks the IsZero method of its type. 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, and dive on its field checks each element, under the name of the setting with the index, as CORS_ALLOWED_ORIGINS[1]. 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-validator, and LoadX checks them; the struct needs no //kanna:validate. A validate(errs *validator.Errors) method of the struct, the hook of kanna-validator, runs after the tags.
LoadX returns errors in two steps:
- It reads every setting, and returns the errors of those that cannot be read, checking no rule.
- 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-validator does, by its JSON name, or else its Go name. kanna-config checks the hook's paths on generating, and moves what the hook 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. What a rule returns is returned as it is, as in kanna-validator, 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 validator.Fail keep it out.
required is a rule of the value, as in kanna-validator: 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 ofX, each named and with its default, asLoadXreads them.LoadX(src source.Source) (X, error), which readsXand checks it. The error, when there is one, is avalidator.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
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
|