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
The generated code imports package source of this module and the runtime of go-kanna/validator, which the
line above already requires, 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
Use
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
pathPoolMaxConns := validator.Field("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.Path, err)
} else if ok {
pathPoolMaxConns = v.Path
if n, err := strconv.ParseInt(v.Text, 0, 32); err != nil {
errs.Add(pathPoolMaxConns, 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(pathWriterURL, validator.Blank())
}
if x.PoolMaxConns < 1 {
errs.Add(pathPoolMaxConns, 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)
Database.AdminURL is read from DATABASE_ADMIN_URL, a different variable from the DATABASE_URL that kanna-orm describe reads when it is given no -database-url. To describe with the admin connection, pass the variable by the flag:
go tool kanna-orm describe -database-url "$DATABASE_ADMIN_URL" ./...
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. Fields of two structs whose names all agree read one setting, which is allowed, as sharing a setting may be meant: two structs of one name, such as postgres.Config and redis.Config, both read CONFIG_HOST, and defining the flags of both on one FlagSet defines -config-host once. Fields of two structs of one package whose names agree only in part stop the run, such as Database.WriterURL and DatabaseWriter.URL, which share DATABASE_WRITER_URL and -database-writer-url but not the key of a file, as does a field whose variable names the file of another struct's, such as AppLog.File (APP_LOG_FILE) beside App.Log. kanna-config compares the structs of one package, not those of different packages.
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 the word config of a struct named Config says nothing of what it holds.
//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: An exported DATABASE_POOL_MAX_CONNS= is the same as an unset variable.
kanna-config reads no .env file. The environment is the process's own, so load such a file before source.Open with a
library such as godotenv, or let the shell or the runtime export it.
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 before source.Open, which rejects one not parsed yet; only the flags set count. A bool flag may stand alone, as -database-debug.
The help of a flag, which -h prints, is the first sentence of the field's doc comment, as go/doc finds it, followed by the variable. Without a doc comment, it names the struct and the field, as in Server.Level (SERVER_LEVEL). A back quote in the doc comment is dropped, since the flag package would show the word it quotes as the type of the flag. The type shows as value, as for any flag that flag.Var defines:
-server-port value
Port is the port the server listens on. (PORT) (default 8080)
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, and a YAML 0123 reads as 0123, which an integer setting reads as Go does, as the octal 83, and a string setting as it is. A section or a list where a value goes is an error. A null is unset, and so is each setting under a null section, such as a YAML section whose keys are all commented out.
A key in the section of a struct that none of its fields reads is an error under its name, without its value, such as
database.pool_max_con: is no setting of the section database, so that a misspelt key does not leave its default in
place. A key that differs from one of them in case alone, such as database.Writer_URL, says which it means, as does a
section at the top whose name differs in case alone, such as Database (did you mean database?). A section of no
struct, such as databse, is not looked at, as the same file may hold the settings of a program that reads other
structs. The keys known are those of every struct of the package that reads the section. A struct of another package is
not known, so when two structs of different packages share a section and their fields differ, write prefix= on one of
them.
The TOML library does not give the text of a number, a date, or a time, so they are written back from what they are: a number in decimal, so that 0x1F reads as 31 and 1_000 as 1000; a float with its point, so that 1.0 reads as 1.0, which an integer setting rejects, and 1.20 as 1.2; and a date or a time in the form of RFC 3339, with no time zone it does not name, so that 1979-05-27 reads as 1979-05-27 and 1979-05-27 07:32:00Z as 1979-05-27T07:32:00Z. Quote a value to read it as it is written.
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. So does a default of such a field, in any struct.
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, an integer as it is written, such as x.DirMode = 0755, 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.
An enum of kanna-value with no default is as good as required. Given nowhere, it stays the zero value, which the enum's Validate rejects as inclusion. Add validate:"omitempty" to let it stay unset.
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, as a Go literal: 0755 is octal, and 0x1F, 0o755, 0b101, and 1_000 read too |
| a float, or a type defined on one | strconv.ParseFloat, at its size |
An integer is read as a Go integer literal, the way flag.Int of the flag package reads one, in a variable, a flag, and a file alike: 0x1F, 0o755, 0b101, and 1_000 read, and a leading 0 makes the rest octal, so 0755 reads as 493 and 08080 is an error. When a decimal number fails to read only because of its leading 0, the error gets the param octal=true, as in DATABASE_POOL_MAX_CONNS: invalid (octal=true, type=int32). A default like that stops the run and gives the same reason. Write a decimal number without a leading zero, as in PORT=8080.
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. A list type with UnmarshalText looks like this:
// Origins is read from a comma-separated list, such as CORS_ALLOWED_ORIGINS=https://a.example,https://b.example.
type Origins []string
func (o *Origins) UnmarshalText(text []byte) error {
*o = strings.Split(string(text), ",")
return nil
}
//kanna:config
type CORS struct {
AllowedOrigins Origins `validate:"required,dive,max=20"`
}
Here dive checks each origin, and a long second one is reported as CORS_ALLOWED_ORIGINS[1]: too_long (count=20). A min, max, or len on the list itself counts its elements, and reports too_few, too_many, or wrong_count, not the too_short, too_long, or wrong_length of a string.
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. A default that cannot be read when the program runs gets the param default=true besides, and not its text, as in SERVER_LEVEL: invalid (default=true, type=slog.Level); the rules it breaks get none.
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. In the path's Segments, a variable or a flag is one field segment, however it is spelled, and a setting in a file is two, its section and its key, as validator.Field("database", "pool_max_conns") makes them. 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 validator.Field with 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, in Field and Segments alike, 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 |
Three more things differ:
- A field with no
envtag is read too, by the name its struct and field give it, and it gets a flag as well. Tag a fieldconfig:"-"to leave it out. - Nothing corresponds to
Options.Prefix. A prefix belongs to a struct (prefix=), and a variable written withenv:"…"takes none. - kanna-config reads no
.envfile. A program that used godotenv keeps calling it beforesource.Open.
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, including that no output is left over; 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 |
The packages default to the one in the current directory, so //go:generate go tool kanna-config needs no argument. A
run that succeeds prints nothing but its warnings. One is about the run itself: when no struct in its packages is marked
//kanna:config, it succeeds, since a //go:generate line left behind does no harm, but says so:
$ go generate ./...
warning: no struct is marked //kanna:config in example.com/app/config
The directive on anything but a struct type, such as type Level string, a type alias, an interface, or a function, is
an error, since nothing reads it there.
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.
Development
make test # unit tests, in the root module and in yaml and toml
make lint # golangci-lint
make example # regenerate the example, vet it, and run it
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. |
|
octal
Package octal tells an integer that a leading 0 made octal.
|
Package octal tells an integer that a leading 0 made octal. |
|
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
|