kanna

kanna / config

kanna-config

v0.0.7 Go 1.27 pkg.go.dev

CI codecov Go Reference License: MIT Release English

kanna-config は、設定の構造体を、フラグ、環境変数、ファイルから読み、kanna-validator の validate タグで確かめる関数を生成します。各設定の名前は、構造体とフィールドの名前で決まります。生成されるのは、各設定を strconv で読み、各ルールを確かめる素の Go で、リフレクションは使いません。誤りは、設定した場所での名前(環境変数、ファイルのキー、フラグ)で報告します。

kanna コードジェネレータファミリーの 1 つです。go-kanna/validator のランタイムと同じく、Go 1.27 以上が必要です。

インストール

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

生成コードが import するのは、このモジュールの source パッケージ、go-kanna/validator のランタイム、読む kanna-value の型のコンストラクタです。ランタイムまでは、上のコマンドで依存に追加されます。YAML と TOML のファイルは、それぞれ別のモジュールが読みます。それを読むプログラムだけが require します:

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

使い方

設定の構造体に //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 ./... を実行すると、隣に config_gen.go が書き出されます。構造体のフラグを定義する DefineDatabaseFlags と、構造体を読む LoadDatabase です:

// 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
}

設定がどこにあるかは、プログラムが渡します:

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)

DATABASE_WRITER_URL を設定し忘れ、ファイルに pool_max_conns: 0 と書いて起動すると、LoadDatabase は、それぞれを設定した名前で誤りを返します:

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

Database.AdminURL は DATABASE_ADMIN_URL から読まれ、kanna-orm describe が -database-url を渡されないときに読む DATABASE_URL とは別の変数です。管理用の接続で describe するときは、この変数をフラグで渡します:

go tool kanna-orm describe -database-url "$DATABASE_ADMIN_URL" ./...

名前

各フィールドが 1 つの設定で、語の並びで名前が決まります。構造体の語、続いてフィールドの語です。語の分け方は、kanna-orm がフィールドから列の名前を作るのと同じです。出どころごとに、その語を自分の書き方で綴ります:

フィールド 環境変数 ファイル フラグ
Database.WriterURL DATABASE_WRITER_URL セクション database の writer_url -database-writer-url
Database.PoolMaxConns DATABASE_POOL_MAX_CONNS セクション database の pool_max_conns -database-pool-max-conns
API.Port API_PORT セクション api の port -api-port

構造体の語で、構造体ごとに設定を分けられます。2 つの構造体のフィールドで、名前がすべて一致するものは 1 つの設定を読みます。共有を意図することもあるので、止めません。たとえば、postgres.Config と redis.Config のように名前が同じ構造体は、どちらも CONFIG_HOST を読み、両方のフラグを 1 つの FlagSet に定義すると、-config-host は 1 回だけ定義されます。同じパッケージの 2 つの構造体のフィールドで、名前が一部だけ一致するものは、生成を止めます。Database.WriterURL と DatabaseWriter.URL は、DATABASE_WRITER_URL と -database-writer-url を共有しますが、ファイルのキーは別々です。App.Log と AppLog.File(APP_LOG_FILE)のように、あるフィールドの変数がほかの構造体のフィールドの変数のファイルを名指すときも、生成を止めます。kanna-config が比べるのは 1 つのパッケージの構造体どうしで、別のパッケージの構造体とは比べません。

名前は外部の名前で、デプロイの側が設定するものです。構造体の語がそれと違うときは、prefix= に snake case で書きます。たとえば、OAuth という名前の構造体は o_auth に分かれ、Config という名前の構造体の語 config は、何の設定かを表しません:

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

フィールドの語も、同じく config:"…" で書きます。OAuthToken というフィールドなら config:"oauth_token" です。Cloud Run の PORT のように実行環境が名付ける変数は、env:"…" に丸ごと書きます。接頭語は付かず、変わるのは環境変数だけです。規約で決まるのと同じ語を書いても構いません。Go の名前を変えても、設定の名前を保てます。

env:"…" の名前は、小文字(http_proxy)も含めて書いたとおりに読みます。ただし、空の名前と、= か NUL を含む名前はどの変数も持てないので、生成を止めます。json タグと同じく、名前は最初のカンマまでです。kanna-config にオプションはないので、カンマの後ろにオプションがあれば生成を止めます。1 つの構造体の 2 つのフィールドが同じ設定を読むときと、Password と PasswordFile のように、あるフィールドの変数がほかのフィールドの変数のファイルを名指すときも、生成を止めます。

出どころ

設定は、フラグ、環境変数、ファイル(後ろのものから)の順に探し、最初にテキストを持っていた出どころが値を決めます。空のテキストは、未設定と同じく何も決めません。DATABASE_POOL_MAX_CONNS= と空で export した環境変数は、設定しなかったのと同じです。

.env ファイルは読みません。環境変数はプロセスが持つものなので、.env を使うなら、source.Open の前に godotenv などで読み込むか、シェルや実行環境に export させてください。

環境変数には、値の代わりに、値を持つファイルのパスを渡せます。Kubernetes が Secret をマウントする形です。DATABASE_PASSWORD_FILE は、そのファイルの中身から末尾の改行を 1 つ除いたものを DATABASE_PASSWORD の値にします。両方を設定すると、誤りとして読むのを止めます。

フラグは flag パッケージのもので、DefineXFlags がプログラムのパースする FlagSet に定義します。source.Open の前にパースしてください。まだパースしていない FlagSet は source.Open が誤りにします。使うのは設定されたフラグだけです。bool のフラグは -database-debug のように単独で書けます。

-h が出すフラグの説明は、フィールドの doc コメントの 1 文目(go/doc が切り出すもの)に、環境変数の名前を続けたものです。doc コメントがなければ、Server.Level (SERVER_LEVEL) のように構造体とフィールドの名前になります。doc コメントのバッククォートは外します。flag パッケージは、バッククォートで囲んだ語をフラグの型の欄に出すからです。型の欄は、flag.Var で定義したほかのフラグと同じく value です。

  -server-port value
    	Port is the port the server listens on. (PORT) (default 8080)

ファイル

ファイルは source.File の Decode が読みます。source.JSON、github.com/go-kanna/config/yaml の yaml.Decode、github.com/go-kanna/config/toml の toml.Decode です。kanna-config はファイルを探さず、環境も見分けません。ファイルはプログラムが勝つ順(後ろのものが前のものに勝つ)に名指し、ないファイルは誤りです。

構造体ごとにファイルのセクションがあり、その各フィールドがセクションのキーです。1 つのファイルに、すべての構造体の設定を書けます:

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

ファイルの値は、環境変数と同じくそのテキストとして読みます。20 と "20" は同じに読み、YAML の 0123 は 0123 というテキストで届きます。整数の設定は Go と同じく 8 進数の 83 として読み、文字列の設定はそのまま読みます。値の場所にあるセクションやリストは誤りです。null は未設定で、null のセクションの下の設定も未設定です(YAML でキーをすべてコメントアウトしたセクションなど)。

構造体のセクションの中の、どのフィールドも読まないキーは、そのキーの名前の下の誤りになります(database.pool_max_con: is no setting of the section database)。値は含めません。キーを打ち間違えても、既定値のまま黙って動かないようにするためです。フィールドのキーと大文字小文字だけが違うキー(database.Writer_URL)は、どれのことかを示します。名前が大文字小文字だけ違う最上位のセクション(Database)も同じです(did you mean database?)。どの構造体のものでもない最上位のセクション(databse など)は見ません。同じファイルに、ほかの構造体を読むプログラムの設定があってもよいからです。照らすキーは、そのセクションを読む、同じパッケージのすべての構造体のものです。ほかのパッケージの構造体は知らないので、パッケージの違う 2 つの構造体がセクションを共有し、フィールドが違うなら、片方に prefix= を書きます。

TOML のライブラリは数・日付・時刻のテキストを渡さないので、その値から書き戻します。数は 10 進数で、0x1F は 31、1_000 は 1000 と読みます。浮動小数は小数点つきで、1.0 は 1.0(整数の設定では誤り)、1.20 は 1.2 と読みます。日付と時刻は RFC 3339 の形で、書いていないタイムゾーンは付けず、1979-05-27 は 1979-05-27、1979-05-27 07:32:00Z は 1979-05-27T07:32:00Z と読みます。書いたとおりに読みたい値は、引用符で囲みます。

読めないファイルは、read config/production.yaml: line 2, column 13 is not valid YAML のように、どこが誤りかで報告します。読むライブラリが出すメッセージは、そこに書いた秘密を引用しうるので見せません。YAML のファイルに書ける文書は 1 つで、--- のあとの 2 つ目の文書は、その位置で誤りにします。source.JSON は encoding/json/v2 で読むので、JSON のオブジェクトに同じ名前を 2 回書くと、2 つ目の位置で誤りにします。自分で書く Decode も、それ以上を言わないようにします。source.Open はその誤りをそのまま返すからです。

読まないフィールド

構造体のフィールドはすべて読みます。非公開のフィールド、埋め込んだフィールド、_ のフィールドは読めないので、生成を止めます。設定から与えないフィールドには config:"-" を付けます。LoadX のあとでシークレットマネージャから読むパスワードなどです:

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

LoadX はそのフィールドをゼロ値のままにし、そのルールも確かめません。あとでプログラムが値を入れるからです。//kanna:validate も付けた構造体なら、その Validate が確かめます。//kanna:validate のない構造体で、そのフィールドにルールを書くと、ルールが一度も実行されないので生成を止めます。config:"-" のフィールドに既定値を書いたときも、生成を止めます。

既定値

どこにも設定されていなければ、フィールドはゼロ値になるか、タグの default の値になります:

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

文字列、bool、数、time.Duration、kanna-value の enum の既定値は、生成時に読み、Go の値(x.PoolMaxConns = 10、整数は書いたとおりの x.DirMode = 0755、x.DialTimeout = 5 * time.Second、enum の定数)として書き出します。NaN と +Inf は定数で表せないので math.NaN() と math.Inf(1) で書き、ルールは読むときに確かめます。読めなければ生成を止めます。そのうえで、値だけで、プログラムのコードを動かさず、ほかのフィールドなしに判定できるルール(required、長さ、比較、oneof、pattern)で確かめます。拒否されれば生成を止めます。設定しない限り、起動のたびに失敗するからです。rule=Type、eqfield、email、url、uuid、フックは読むときに確かめます。required や omitempty が型の IsZero メソッドに聞くフィールドも、そのルールをすべて読むときに確かめます。kanna-value の値オブジェクトと UnmarshalText を持つ型の既定値は、設定と同じく、どこにも設定されていないときに読みます。

default のない kanna-value の enum は、事実上必須です。どこにも設定されなければゼロ値のままで、enum の Validate が inclusion として拒否します。未設定を許すなら validate:"omitempty" を付けます。

読める型

フィールドの型に最初に当てはまったもので読みます:

型 読み方
time.Duration time.ParseDuration(30s、5m)。ナノ秒の数としては読まない
kanna-value の値オブジェクト 持つ値を下のとおりに読み、コンストラクタに渡す
kanna-value の enum コンストラクタ
ポインタが UnmarshalText を持つ型 UnmarshalText(slog.Level、netip.Addr、time.Time)
文字列か、それを基にした型 テキストのまま
bool か、それを基にした型 strconv.ParseBool
整数か、それを基にした型 strconv.ParseInt か strconv.ParseUint(その大きさで)。Go のリテラルとして読むので、0755 は 8 進数で、0x1F、0o755、0b101、1_000 も読めます
浮動小数点数か、それを基にした型 strconv.ParseFloat(その大きさで)

整数は、flag パッケージの flag.Int と同じく、Go の整数リテラルの規則で読みます。環境変数、フラグ、ファイルのどれでも同じです。0x1F、0o755、0b101、1_000 も読めます。先頭が 0 なら 8 進数なので、0755 は 493 になり、08080 は誤りです。10 進数が先頭の 0 のせいで読めないときは、DATABASE_POOL_MAX_CONNS: invalid (octal=true, type=int32) のように、誤りに octal=true のパラメータが付きます。既定値が先頭の 0 のせいで読めないときは、その理由を示して生成を止めます。10 進数は、PORT=8080 のように先頭に 0 を付けずに書きます。

それ以外の型(ポインタ、スライス、マップ、構造体など)は、生成を止めます。カンマで区切ったリストなどは、UnmarshalText を持つ型を作って読みます。そのフィールドの dive は、要素を 1 つずつ確かめ、誤りを添字を付けた設定の名前(CORS_ALLOWED_ORIGINS[1])の下に置きます。入れ子の設定は、//kanna:config を付けた別の構造体にします。UnmarshalText を持つリストの型は、たとえば次のように書きます:

// 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"`
}

dive が各 origin を確かめ、2 つ目が長すぎれば CORS_ALLOWED_ORIGINS[1]: too_long (count=20) と報告します。リスト自体に書いた min、max、len は要素の数を数え、文字列の too_short、too_long、wrong_length ではなく、too_few、too_many、wrong_count を報告します。

読めなかった誤りは、値ではなく、コードとパラメータで報告します。設定は秘密を持ちうるからです。読めない数、bool、期間は、型を付けた invalid です(DATABASE_POOL_MAX_CONNS: invalid (type=int32))。コンストラクタや UnmarshalText が返した誤りは、kanna-value のルールのようにコードを持てばそのまま返し、持たなければ型を付けた invalid にします。slog.Level の誤りは値を含むからです。コードがあっても値を含むことはあるので、コードとパラメータに何を入れるかは、その型を書いた人の責任です。type パラメータは、ログや構造化された誤りのためのもので、翻訳の文言で表示できるとは約束しません。実行時に読む既定値が読めなかったときは、既定値のテキストは付けず、default=true のパラメータを加えます(SERVER_LEVEL: invalid (default=true, type=slog.Level))。既定値が破ったルールの誤りには付けません。

検証

validate タグは kanna-validator と同じ意味で、LoadX が確かめます。//kanna:validate は要りません。構造体の validate(errs *validator.Errors) メソッド(kanna-validator のフック)は、タグのあとで呼びます。

LoadX は 2 段階で誤りを返します:

  1. すべての設定を読み、読めなかったものがあれば、その誤りを返します。このときはルールを確かめません。
  2. すべて読めたら、ルールとフックの誤りを返します。

読めなかった設定のフィールドは、読んだ値を持ちません。そのままルールを確かめると、フィールドをまたぐルールやフックが、欠けた値を見て誤りを報告しかねないからです。

誤りは、その設定をした場所での名前の下に置きます。環境変数、database.pool_max_conns、-database-pool-max-conns のいずれかで、どこにも設定されていなければ環境変数の名前です。パスの Segments では、環境変数とフラグは綴りによらず 1 つのフィールドの区切りで、ファイルの設定はセクションとキーの 2 つの区切りです(validator.Field("database", "pool_max_conns") と同じ)。フィールドの型自身の Validate が返す誤りは、その名前の下に残ります(DATABASE_PRIMARY.host)。フックは kanna-validator と同じく、フィールドを validator.Field と JSON の名前(なければ Go の名前)で名指します。kanna-config は、フックのパスを生成時に確かめ、フックが返した誤りを、Field でも Segments でも、フィールドの設定の名前の下に移します。パスのうち、フィールドの名前より後ろはそのまま残します。構造体全体の誤りは base のままです。

コード付きにするのは、読むときの誤りだけです。ルールが返した誤りは、kanna-validator と同じくそのまま返します。同じルールが LoadX と Validate で同じ誤りを返すようにするためです。誤りに値を含めないのは、ルールを書いた人の責任です。kanna-value の rule.Fail と validator.Fail は値を含めません。

required は kanna-validator と同じく値のルールです。ゼロ値を拒否し、明示した 0 や false も拒否します。ゼロでない既定値があれば、どこにも設定されていなくても通ります。変数が設定されているかを確かめる書き方はありません。文字列の既定値なら、LoadX では required は必ず満たされますが、//kanna:validate も付けた構造体の Validate では、手で組み立てた値も確かめます。

LoadX のために Validate は生成しません。ほかで呼びたいときは、//kanna:validate も付けます。そのときも LoadX は自分でルールを確かめるので、付けても LoadX は変わりません。

生成されるもの

//kanna:config を付けた構造体 X ごとに、config_gen.go に次の 2 つを書きます:

  • DefineXFlags(fs *flag.FlagSet): X のフラグを、LoadX が読む名前と既定値で定義します。
  • LoadX(src source.Source) (X, error): X を読んで確かめます。エラーは、あれば validator.Errors です。

同じ名前の関数を手で書いていると、生成を止めます。kanna-di は、X のパッケージにある LoadX を、source.Source から X を作るものとして見つけます。

LoadX のテストは、t.Setenv で変数を設定します。t.Parallel とは一緒に使えません。設定を使う側のテストは、構造体を直接作り、並列にできます。

caarlos0/env から移る

env:"…" に書いた名前は caarlos0/env と同じに読み、envDefault:"…" は default:"…" になります。ただし、読み方は違います。空の変数は未設定で、読める型は上のものだけで、required はゼロ値を拒否します。ほかのタグとオプションは、違いを示して生成を止めます:

caarlos0/env kanna-config
envDefault:"…" default:"…"
env:"X,required" 変数が設定されているかは確かめません。validate:"required" は値がゼロでないことを求め、0 や false も拒否します
env:"X,notEmpty" 近いのは validate:"required" ですが、0 や false も拒否します
envPrefix 入れ子の構造体は読みません。//kanna:config を付けた別の構造体にし、接頭語は prefix= で書きます
envSeparator、envKeyValSeparator スライスとマップは読みません。UnmarshalText を持つ型を作ります
env:"X,file" X_FILE がファイルを名指します。ほかの形で渡すパスは、LoadX のあとで config:"-" のフィールドに読みます
env:"X,expand" LoadX のあとで os.ExpandEnv を呼びます
env:"X,unset" LoadX のあとで os.Unsetenv を呼びます
env:"X,init" ポインタは読まないので、要りません

ほかにも違う点が 3 つあります。

  • env タグのないフィールドも、構造体とフィールドの名前で決まる名前で読み、フラグも作ります。読ませないフィールドには config:"-" を付けます。
  • Options.Prefix にあたるものはありません。接頭語は構造体ごとに prefix= で決め、env:"…" で書いた変数には付きません。
  • .env ファイルは読みません。godotenv で読んでいたプログラムは、これまでどおり source.Open の前に自分で読み込みます。

フラグ

kanna-config [flags] [packages]
フラグ 意味
-tags <list> カンマ区切りのビルドタグ
-check 書き出す代わりに、出力が最新であることを検証する。不要な出力が残っていないことも含む。KANNA_CHECK=1 でも同じ
-v 書き出した、削除した、変更しなかったファイルを一覧表示する
-deps 実行が読み書きするものを、kanna コマンドのために JSON で表示して終了する
-version バージョンを表示する

対象のパッケージは、指定しなければカレントディレクトリのパッケージなので、//go:generate go tool kanna-config に引数は不要です。成功した実行は、警告以外何も出力しません。警告の 1 つは実行そのものについてのものです。対象のパッケージに //kanna:config を付けた構造体が 1 つもなければ、残っている //go:generate の行は無害なので成功しますが、そのことを知らせます:

$ go generate ./...
warning: no struct is marked //kanna:config in example.com/app/config

構造体の型でないもの(type Level string、型の別名、インターフェース、関数など)に付けたディレクティブは、読まれることがないのでエラーです。

サンプル

example は、サーバーの設定を、YAML のファイル、TOML のファイル、環境変数、フラグから読み、それぞれが与えるものと、読めない設定やルールに反する設定の誤りを表示します。CI はこれを再生成し、出力が変わる場合は失敗します。

開発

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

ライセンス

MIT