From 5e150fc5712be3a3e4c689b60ed44dff039dc0e9 Mon Sep 17 00:00:00 2001 From: Pat Downey Date: Sat, 14 Nov 2026 20:34:40 +0000 Subject: [PATCH] feat: add NewConfigCommand, and document the config-key vocabulary NewConfigCommand returns a config command with validate, example and schema subcommands for a service's config type. validate checks a file without starting the service and reports every unknown key, with its full path, and every setting Validate rejects, together. example and schema are generated from the config struct's mapstructure keys and desc tags, or supplied by the service when it generates richer ones at build time. doc/config-keys.md records the key vocabulary Dioad services share, taken from connect's convention, and how keys, flags and environment variables relate. examples/config-command is a runnable service using the command. The optional key-alias mechanism in the issue is not included. Fixes #19 Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01SS4MAwAn85D1gkEzLtjYaZ --- README.md | 6 + configcommand.go | 167 +++++++++++++++++++++ configcommand_test.go | 203 +++++++++++++++++++++++++ configdoc.go | 215 +++++++++++++++++++++++++++ doc/config-keys.md | 63 ++++++++ examples/config-command/README.md | 43 ++++++ examples/config-command/main.go | 76 ++++++++++ examples/config-command/main_test.go | 51 +++++++ go.mod | 2 +- 9 files changed, 825 insertions(+), 1 deletion(-) create mode 100644 configcommand.go create mode 100644 configcommand_test.go create mode 100644 configdoc.go create mode 100644 doc/config-keys.md create mode 100644 examples/config-command/README.md create mode 100644 examples/config-command/main.go create mode 100644 examples/config-command/main_test.go diff --git a/README.md b/README.md index 54ecf5a..e0757a3 100644 --- a/README.md +++ b/README.md @@ -287,6 +287,12 @@ Configuration and persistence paths default to container volumes when running in See the `example/` directory for a complete working example demonstrating logging configuration and level testing. +[`examples/config-command`](examples/config-command/README.md) shows a service with +`config validate`, `config example` and `config schema` subcommands, from +`cli.NewConfigCommand`. [Config keys for Dioad services](doc/config-keys.md) +records the key vocabulary the services share and how keys, flags and +environment variables relate. + ## Dependencies - [spf13/cobra](https://github.com/spf13/cobra) - CLI framework diff --git a/configcommand.go b/configcommand.go new file mode 100644 index 0000000..d4fe0e1 --- /dev/null +++ b/configcommand.go @@ -0,0 +1,167 @@ +package cli + +import ( + "errors" + "fmt" + "io" + + "github.com/spf13/cobra" + + "github.com/dioad/config/configcheck" +) + +// ConfigCommandOpt is a functional option for NewConfigCommand. +type ConfigCommandOpt func(*configCommand) + +type configCommand struct { + defaultFile string + example func() ([]byte, error) + schema func() ([]byte, error) +} + +// WithConfigCommandFile sets the config file "config validate" checks when it +// is not given --config, normally the file the service loads. +func WithConfigCommandFile(path string) ConfigCommandOpt { + return func(c *configCommand) { c.defaultFile = path } +} + +// WithConfigExample makes "config example" print what example returns, in place +// of the example NewConfigCommand generates from the config struct. Use it when +// a service generates a richer one at build time, with comments taken from the +// struct's doc comments. +func WithConfigExample(example func() ([]byte, error)) ConfigCommandOpt { + return func(c *configCommand) { c.example = example } +} + +// WithConfigSchema makes "config schema" print what schema returns, in place of +// the schema NewConfigCommand generates from the config struct. +func WithConfigSchema(schema func() ([]byte, error)) ConfigCommandOpt { + return func(c *configCommand) { c.schema = schema } +} + +// NewConfigCommand returns a "config" command with three subcommands, for a +// service whose config type is built by newConfig and described as kind (for +// example "accounting"): +// +// - validate checks a config file without starting the service. It reports +// every key that matches no setting, with its full path, and every setting +// the config's Validate method rejects, and exits non-zero if there is any. +// - example prints an example config file listing every setting. +// - schema prints the JSON Schema of the config file. +// +// newConfig should return the config with its defaults set, so the example shows +// them. Add the command to the service's root with AddCommand; it reads no +// configuration of its own. +func NewConfigCommand(kind string, newConfig func() Validator, opts ...ConfigCommandOpt) *cobra.Command { + c := &configCommand{} + for _, opt := range opts { + opt(c) + } + if c.example == nil { + c.example = func() ([]byte, error) { return ConfigExample(newConfig()) } + } + if c.schema == nil { + c.schema = func() ([]byte, error) { return ConfigSchema(newConfig()) } + } + + cmd := &cobra.Command{ + Use: "config", + Short: fmt.Sprintf("Check, show and describe the %s config file", kind), + } + cmd.AddCommand(c.validateCommand(kind, newConfig), c.exampleCommand(kind), c.schemaCommand(kind)) + + return cmd +} + +func (c *configCommand) validateCommand(kind string, newConfig func() Validator) *cobra.Command { + cmd := &cobra.Command{ + Use: "validate", + Short: fmt.Sprintf("Check a %s config file for unknown keys and invalid settings", kind), + Long: fmt.Sprintf(`Check a %[1]s config file without starting the %[1]s. + +Reports every key that matches no setting, with its full path (for example a +renamed or misspelled key), and every setting the %[1]s would reject at +startup, all together. Exits non-zero if any problem is found.`, kind), + Args: cobra.NoArgs, + SilenceUsage: true, + RunE: func(cmd *cobra.Command, _ []string) error { + return ValidateConfigFile(cmd.OutOrStdout(), cmd.Flag("config").Value.String(), newConfig()) + }, + } + cmd.Flags().StringP("config", "c", c.defaultFile, "config file to check") + + return cmd +} + +func (c *configCommand) exampleCommand(kind string) *cobra.Command { + return &cobra.Command{ + Use: "example", + Short: fmt.Sprintf("Print an example %s config file listing every setting", kind), + Long: fmt.Sprintf(`Print an example %[1]s config file that lists every setting it can have, +each with its description as a comment and its default value, or an empty +value where it has none. + +The example is a reference to copy settings from, not a config to run as it +is: some settings must be set to work.`, kind), + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { return writeOut(cmd.OutOrStdout(), c.example) }, + } +} + +func (c *configCommand) schemaCommand(kind string) *cobra.Command { + return &cobra.Command{ + Use: "schema", + Short: fmt.Sprintf("Print the JSON Schema of a %s config file", kind), + Long: fmt.Sprintf(`Print the JSON Schema of a %s config file, for an editor or a validator to +check a file against. The schema checks each key and the type of each value; it +does not apply the rules "config validate" applies beyond that.`, kind), + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { return writeOut(cmd.OutOrStdout(), c.schema) }, + } +} + +func writeOut(w io.Writer, generate func() ([]byte, error)) error { + out, err := generate() + if err != nil { + return err + } + _, err = w.Write(out) + + return err +} + +// ValidateConfigFile checks the config file at path as the service would at +// startup, without starting it, and writes the result to w: every problem, one +// per line, or a line saying the file is valid. The file is decoded strictly +// into cfg, so a key that matches no field is a problem, and cfg's Validate +// method is then called, so a setting it rejects is too; all are reported +// together. It returns an error if the file is invalid or cannot be read. +func ValidateConfigFile(w io.Writer, path string, cfg Validator) error { + err := DecodeConfigFile(path, cfg) + var decodeFindings *configcheck.Error + if err != nil && !errors.As(err, &decodeFindings) { + return err + } + + findings := configcheck.NewCollector() + findings.Add(err) + findings.Add(cfg.Validate()) + + all := findings.Findings() + if len(all) == 0 { + _, err = fmt.Fprintf(w, "%s is valid\n", path) + + return err + } + + if _, err = fmt.Fprintf(w, "%s:\n", path); err != nil { + return err + } + for _, f := range all { + if _, err = fmt.Fprintf(w, " %s\n", f); err != nil { + return err + } + } + + return fmt.Errorf("%s: %d configuration problem(s) found", path, len(all)) +} diff --git a/configcommand_test.go b/configcommand_test.go new file mode 100644 index 0000000..226a10f --- /dev/null +++ b/configcommand_test.go @@ -0,0 +1,203 @@ +package cli_test + +import ( + "bytes" + "encoding/json" + "errors" + "fmt" + "os" + "strings" + "testing" + "time" + + "github.com/spf13/cobra" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/dioad/cli" +) + +type tlsBlock struct { + CertFile string `desc:"path to the certificate" mapstructure:"cert-file"` +} + +type serviceConfig struct { + ListenAddress string `desc:"address to listen on" mapstructure:"listen-address"` + Workers int `desc:"number of workers" mapstructure:"workers"` + DrainDelay time.Duration `desc:"how long to keep serving after a stop request" mapstructure:"drain-delay"` + Origins []string `desc:"origins allowed by CORS" mapstructure:"cors-allowed-origins"` + TLS tlsBlock `mapstructure:"tls-server"` + Labels map[string]string `desc:"free-form labels" mapstructure:"labels"` + Ignored string `mapstructure:"-"` +} + +func newServiceConfig() cli.Validator { + return &serviceConfig{ListenAddress: ":8080", Workers: 4, DrainDelay: 5 * time.Second} +} + +func (c *serviceConfig) Validate() error { + if c.Workers < 1 { + return errors.New("workers must be at least 1") + } + + return nil +} + +func runConfigCommand(t *testing.T, args ...string) (string, error) { + t.Helper() + root := &cobra.Command{Use: "svc"} + root.AddCommand(cli.NewConfigCommand("svc", newServiceConfig)) + var out bytes.Buffer + root.SetOut(&out) + root.SetErr(&out) + root.SetArgs(append([]string{"config"}, args...)) + err := root.Execute() + + return out.String(), err +} + +func writeConfig(t *testing.T, content string) string { + t.Helper() + path := t.TempDir() + "/svc.yaml" + require.NoError(t, os.WriteFile(path, []byte(content), 0o600)) + + return path +} + +func TestConfigValidate_AcceptsAGoodFile(t *testing.T) { + t.Parallel() + path := writeConfig(t, "listen-address: ':9000'\nworkers: 2\n") + + out, err := runConfigCommand(t, "validate", "--config", path) + + require.NoError(t, err) + assert.Equal(t, path+" is valid\n", out) +} + +func TestConfigValidate_ReportsEveryProblemTogether(t *testing.T) { + t.Parallel() + path := writeConfig(t, "workers: 0\nlisten-adress: ':1'\ntls-server:\n cert: x\n") + + out, err := runConfigCommand(t, "validate", "--config", path) + + require.ErrorContains(t, err, "3 configuration problem(s) found") + assert.Contains(t, out, "listen-adress", "a misspelt key is named") + assert.Contains(t, out, "tls-server.cert", "an unknown nested key is reported with its full path") + assert.Contains(t, out, "workers must be at least 1", "a setting Validate rejects is reported with them") +} + +func TestConfigValidate_ReportsAFileThatCannotBeRead(t *testing.T) { + t.Parallel() + + _, err := runConfigCommand(t, "validate", "--config", t.TempDir()+"/missing.yaml") + + require.ErrorContains(t, err, "reading config file") +} + +func TestConfigValidate_UsesTheDefaultFile(t *testing.T) { + t.Parallel() + path := writeConfig(t, "workers: 3\n") + root := &cobra.Command{Use: "svc"} + root.AddCommand(cli.NewConfigCommand("svc", newServiceConfig, cli.WithConfigCommandFile(path))) + var out bytes.Buffer + root.SetOut(&out) + root.SetArgs([]string{"config", "validate"}) + + require.NoError(t, root.Execute()) + assert.Equal(t, path+" is valid\n", out.String()) +} + +func TestConfigExample_ListsEverySettingWithItsDescriptionAndDefault(t *testing.T) { + t.Parallel() + + out, err := runConfigCommand(t, "example") + + require.NoError(t, err) + assert.Equal(t, `# address to listen on +listen-address: :8080 +# number of workers +workers: 4 +# how long to keep serving after a stop request +drain-delay: 5s +# origins allowed by CORS +cors-allowed-origins: [] +tls-server: + # path to the certificate + cert-file: "" +# free-form labels +labels: {} +`, out) +} + +func TestConfigExample_IsAValidConfigFile(t *testing.T) { + t.Parallel() + out, err := runConfigCommand(t, "example") + require.NoError(t, err) + + validated, err := runConfigCommand(t, "validate", "--config", writeConfig(t, out)) + + require.NoError(t, err, validated) +} + +func TestConfigSchema_DescribesEachKeyAndRejectsOthers(t *testing.T) { + t.Parallel() + + out, err := runConfigCommand(t, "schema") + + require.NoError(t, err) + var schema struct { + Type string `json:"type"` + AdditionalProperties bool `json:"additionalProperties"` + Properties map[string]map[string]any `json:"properties"` + } + require.NoError(t, json.Unmarshal([]byte(out), &schema)) + assert.Equal(t, "object", schema.Type) + assert.False(t, schema.AdditionalProperties, "an unknown key is rejected") + assert.Equal(t, "string", schema.Properties["listen-address"]["type"]) + assert.Equal(t, "address to listen on", schema.Properties["listen-address"]["description"]) + assert.Equal(t, "integer", schema.Properties["workers"]["type"]) + assert.Equal(t, "string", schema.Properties["drain-delay"]["type"], "a duration is written as a string") + assert.Equal(t, "array", schema.Properties["cors-allowed-origins"]["type"]) + assert.Equal(t, "object", schema.Properties["tls-server"]["type"]) + assert.NotContains(t, schema.Properties, "Ignored") +} + +func TestConfigCommand_ExampleAndSchemaCanBeSuppliedByTheService(t *testing.T) { + t.Parallel() + root := &cobra.Command{Use: "svc"} + root.AddCommand(cli.NewConfigCommand("svc", newServiceConfig, + cli.WithConfigExample(func() ([]byte, error) { return []byte("custom example\n"), nil }), + cli.WithConfigSchema(func() ([]byte, error) { return []byte("{}\n"), nil }), + )) + + for args, want := range map[string]string{"example": "custom example\n", "schema": "{}\n"} { + var out bytes.Buffer + root.SetOut(&out) + root.SetArgs([]string{"config", args}) + require.NoError(t, root.Execute()) + assert.Equal(t, want, out.String()) + } +} + +func ExampleNewConfigCommand() { + root := &cobra.Command{Use: "svc"} + root.AddCommand(cli.NewConfigCommand("svc", newServiceConfig)) + + file, _ := os.CreateTemp("", "svc-*.yaml") + defer func() { _ = os.Remove(file.Name()) }() + _, _ = file.WriteString("workers: 0\nlisten-adress: ':1'\n") + _ = file.Close() + + var out bytes.Buffer + root.SetOut(&out) + root.SetErr(&out) + root.SetArgs([]string{"config", "validate", "--config", file.Name()}) + _ = root.Execute() + + fmt.Print(strings.ReplaceAll(out.String(), file.Name(), "svc.yaml")) + // Output: + // svc.yaml: + // listen-adress: unknown key + // workers must be at least 1 + // Error: svc.yaml: 2 configuration problem(s) found +} diff --git a/configdoc.go b/configdoc.go new file mode 100644 index 0000000..83400de --- /dev/null +++ b/configdoc.go @@ -0,0 +1,215 @@ +package cli + +import ( + "encoding" + "encoding/json" + "fmt" + "reflect" + "strings" + "time" + + "go.yaml.in/yaml/v3" +) + +// configField is one key of a config struct: what a file may set, and how. +type configField struct { + key string + desc string + field reflect.StructField + value reflect.Value +} + +var ( + durationType = reflect.TypeFor[time.Duration]() + textUnmarshaler = reflect.TypeFor[encoding.TextUnmarshaler]() +) + +// configFields lists the keys of struct value v as the config is decoded from +// them: each exported field under its mapstructure key, or its lower-cased +// name, and the fields of a squashed or embedded struct inline. A field tagged +// `mapstructure:"-"` is not a key. +func configFields(v reflect.Value) []configField { + var fields []configField + t := v.Type() + for i := range t.NumField() { + field := t.Field(i) + if field.PkgPath != "" && !field.Anonymous { + continue + } + name, options, _ := strings.Cut(field.Tag.Get("mapstructure"), ",") + if name == "-" { + continue + } + + inline := strings.Contains(","+options+",", ",squash,") || (field.Anonymous && name == "") + fieldValue := v.Field(i) + if inline { + if inner, ok := structValue(fieldValue); ok { + fields = append(fields, configFields(inner)...) + } + + continue + } + if name == "" { + name = strings.ToLower(field.Name) + } + fields = append(fields, configField{key: name, desc: field.Tag.Get("desc"), field: field, value: fieldValue}) + } + + return fields +} + +// structValue returns v as a struct value, following pointers, and reports +// whether it is one. A nil pointer yields a zero value of its element type. +func structValue(v reflect.Value) (reflect.Value, bool) { + t := v.Type() + for t.Kind() == reflect.Pointer { + t = t.Elem() + } + if t.Kind() != reflect.Struct || isScalarStruct(t) { + return reflect.Value{}, false + } + for v.Kind() == reflect.Pointer { + if v.IsNil() { + return reflect.New(t).Elem(), true + } + v = v.Elem() + } + + return v, true +} + +// isScalarStruct reports whether struct type t is written as a single string +// in a config file, because it knows how to unmarshal itself from text. +func isScalarStruct(t reflect.Type) bool { + return reflect.PointerTo(t).Implements(textUnmarshaler) +} + +// ConfigExample returns an example config file for cfg, a pointer to a config +// struct: every key a file can set, each with its `desc` tag as a comment and +// the value cfg holds, so a config built with its defaults shows them. A key +// with no default shows its type's zero value. +func ConfigExample(cfg any) ([]byte, error) { + v := reflect.ValueOf(cfg) + root, ok := structValue(v) + if !ok { + return nil, fmt.Errorf("cli: config example needs a pointer to a struct, got %T", cfg) + } + + node := exampleStruct(root) + out, err := yaml.Marshal(node) + if err != nil { + return nil, fmt.Errorf("cli: rendering config example: %w", err) + } + + return out, nil +} + +func exampleStruct(v reflect.Value) *yaml.Node { + node := &yaml.Node{Kind: yaml.MappingNode} + for _, f := range configFields(v) { + key := &yaml.Node{Kind: yaml.ScalarNode, Value: f.key, HeadComment: f.desc} + node.Content = append(node.Content, key, exampleValue(f.value)) + } + + return node +} + +func exampleValue(v reflect.Value) *yaml.Node { + if inner, ok := structValue(v); ok { + return exampleStruct(inner) + } + for v.Kind() == reflect.Pointer || v.Kind() == reflect.Interface { + if v.IsNil() { + return &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!null", Value: "null"} + } + v = v.Elem() + } + + node := &yaml.Node{} + if err := node.Encode(scalarOrCollection(v)); err != nil { + return &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!null", Value: "null"} + } + + return node +} + +// scalarOrCollection returns the value yaml should encode for v. +func scalarOrCollection(v reflect.Value) any { + switch { + case v.Type() == durationType: + return time.Duration(v.Int()).String() + case v.Kind() == reflect.Slice && v.IsNil(): + return []any{} + case v.Kind() == reflect.Map && v.IsNil(): + return map[string]any{} + } + + return v.Interface() +} + +// ConfigSchema returns a JSON Schema for the config file of cfg, a pointer to a +// config struct. It checks each key and the type of each value, takes each +// description from the field's `desc` tag, and rejects keys that match no +// field, as the strict decode does. A duration, or any type that unmarshals +// from text, is a string. +func ConfigSchema(cfg any) ([]byte, error) { + root, ok := structValue(reflect.ValueOf(cfg)) + if !ok { + return nil, fmt.Errorf("cli: config schema needs a pointer to a struct, got %T", cfg) + } + + schema := structSchema(root) + schema["$schema"] = "https://json-schema.org/draft/2020-12/schema" + out, err := json.MarshalIndent(schema, "", " ") + if err != nil { + return nil, fmt.Errorf("cli: rendering config schema: %w", err) + } + + return append(out, '\n'), nil +} + +func structSchema(v reflect.Value) map[string]any { + properties := map[string]any{} + for _, f := range configFields(v) { + property := typeSchema(f.field.Type) + if f.desc != "" { + property["description"] = f.desc + } + properties[f.key] = property + } + + return map[string]any{"type": "object", "properties": properties, "additionalProperties": false} +} + +func typeSchema(t reflect.Type) map[string]any { + for t.Kind() == reflect.Pointer { + t = t.Elem() + } + + switch { + case t == durationType || isScalarStruct(t): + return map[string]any{"type": "string"} + case t.Kind() == reflect.Struct: + return structSchema(reflect.New(t).Elem()) + } + + switch t.Kind() { + case reflect.String: + return map[string]any{"type": "string"} + case reflect.Bool: + return map[string]any{"type": "boolean"} + case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64, + reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64: + return map[string]any{"type": "integer"} + case reflect.Float32, reflect.Float64: + return map[string]any{"type": "number"} + case reflect.Slice, reflect.Array: + return map[string]any{"type": "array", "items": typeSchema(t.Elem())} + case reflect.Map: + return map[string]any{"type": "object", "additionalProperties": typeSchema(t.Elem())} + } + + // An interface, or anything else a file may set to any value. + return map[string]any{} +} diff --git a/doc/config-keys.md b/doc/config-keys.md new file mode 100644 index 0000000..00c29e9 --- /dev/null +++ b/doc/config-keys.md @@ -0,0 +1,63 @@ +# Config keys for Dioad services + +Dioad services share one vocabulary for config keys, so an operator who knows +one service can read another's config. `dioad/connect`'s servers set the +convention; this page records it. The same keys are the flag and environment +names: see [Keys, flags and environment variables](#keys-flags-and-environment-variables). + +A runnable service that follows these rules, with `config validate`, +`config example` and `config schema`, is in +[`examples/config-command`](../examples/config-command/README.md). + +## Vocabulary + +| Setting | Key | Notes | +|---|---|---| +| Logging | `log.*` | `log.level`, `log.file`, `log.use-local-time`, and so on. Provided by `cli.CommonConfig`. | +| Management listener | `management.*` | A nested block with its own `listen-address` and `tls-server`, for health, metrics and status. | +| TLS for a listener | `tls-server` | Not `tls-server-config`: the type says it is config. | +| TLS for an outbound connection | `tls-client` | Not `tls-client-config`. | +| Time to keep serving after a stop request | `drain-delay` | One key, a duration (`5s`). A load balancer sees the service not ready for this long before it stops. | +| Listening without authentication | `allow-unauthenticated`, and `allow-unauthenticated-non-loopback` | The second, narrower key lets a listener that is not on loopback run without authentication. Without it, such a listener is rejected unless the TLS config requires client certificates. Set it only when the network in front of the listener is trusted. | + +`connect` implements `tls-server`, `tls-client`, `drain-delay`, `management.*` +and `allow-unauthenticated-non-loopback`. It has no plain +`allow-unauthenticated` key: the agent's management listener is controlled by +`local-auth-disabled`. A service that needs the broader setting should use +`allow-unauthenticated` and say what it covers. + +## Keys, flags and environment variables + +A setting has one name, derived from its config key: + +| Config key | Flag | Environment variable (`` is the app name) | +|---|---|---| +| `log.level` | `--log-level` | `_LOG_LEVEL` | +| `management.listen-address` | `--management-listen-address` | `_MANAGEMENT_LISTEN_ADDRESS` | +| `cors-allowed-origins` | `--cors-allowed-origins` | `_CORS_ALLOWED_ORIGINS` | + +`cli.NewCommand` names a flag after its field's `mapstructure` key path, and +binds it to that key, so the flag, the file and the environment all set the +same value. A struct squashed into its parent (`mapstructure:",squash"`) adds +no prefix. To choose a flag's name yourself, give the field a `flag:"name"` +tag; its children are then prefixed with it. + +Flags generated under older names, such as `--logging-level`, are still +accepted as hidden, deprecated aliases. + +## Writing a config type + +- Give every field a `mapstructure` key in kebab-case and a `desc` tag. The + `desc` is the flag's help text, the comment in `config example` and the + description in `config schema`. +- Implement `cli.Validator` (`Validate() error`), reporting problems with + `configcheck.Collector` so each names its key path. +- Add `cli.NewConfigCommand(kind, newConfig)` to the service's root command, so + operators can check a file with `config validate` before starting the service. +- Guard the help text in a test: `require.Empty(t, cli.UndocumentedFlags(root))`. + +## Renaming a key + +Renaming a key breaks existing files, and the strict decode rejects the old +name. Until `cli` offers a key alias mechanism, rename a key in a release that +says so, and have `Validate` report the old key's presence with the new name. diff --git a/examples/config-command/README.md b/examples/config-command/README.md new file mode 100644 index 0000000..86de22a --- /dev/null +++ b/examples/config-command/README.md @@ -0,0 +1,43 @@ +# config-command + +A small service command with the three `config` subcommands that +`cli.NewConfigCommand` provides. Its `run` command prints a greeting and exits, +so the example starts no long-lived process. + +```console +$ go run ./examples/config-command config example +# what to say +greeting: hello +# how many times to say it +repeat: 1 +# how long to keep running after a stop request +drain-delay: 5s +management: + # address of the management listener + listen-address: 127.0.0.1:4444 +``` + +`config validate` checks a file without running the service, and reports every +problem together. For a file with a misspelt key and a value `Validate` rejects: + +```console +$ cat greeter.yaml +greeting: hi +repeat: 0 +management: + listen-adress: ":1" + +$ go run ./examples/config-command config validate --config greeter.yaml +greeter.yaml: + management.listen-adress: unknown key + repeat must be at least 1, got 0 +Error: greeter.yaml: 2 configuration problem(s) found +``` + +`config schema` prints a JSON Schema for editors and validators. + +The flags follow the config keys: `management.listen-address` is +`--management-listen-address` on `run`. See +[Config keys for Dioad services](../../doc/config-keys.md) for the vocabulary. + +`main_test.go` runs each of these commands. diff --git a/examples/config-command/main.go b/examples/config-command/main.go new file mode 100644 index 0000000..3c5312a --- /dev/null +++ b/examples/config-command/main.go @@ -0,0 +1,76 @@ +// Command config-command shows a service command with the "config validate", +// "config example" and "config schema" subcommands that cli.NewConfigCommand +// provides. Its run command prints its configuration and exits, so the example +// has no long-lived process. +// +// See README.md for the output on a bad config file. +package main + +import ( + "context" + "fmt" + "os" + "time" + + "github.com/spf13/cobra" + + "github.com/dioad/cli" +) + +// Config is the greeter's configuration. Every field has a desc tag, which is +// its flag's help text, its comment in "config example" and its description in +// "config schema". +type Config struct { + Greeting string `desc:"what to say" mapstructure:"greeting"` + Repeat int `desc:"how many times to say it" mapstructure:"repeat"` + DrainDelay time.Duration `desc:"how long to keep running after a stop request" mapstructure:"drain-delay"` + Management Management `mapstructure:"management"` +} + +// Management is a nested block: its keys are management.listen-address in the +// file and --management-listen-address on the command line. +type Management struct { + ListenAddress string `desc:"address of the management listener" mapstructure:"listen-address"` +} + +// NewConfig returns the configuration with its defaults set, which is what +// "config example" shows. +func NewConfig() *Config { + return &Config{Greeting: "hello", Repeat: 1, DrainDelay: 5 * time.Second, Management: Management{ListenAddress: "127.0.0.1:4444"}} +} + +// Validate rejects settings the service cannot run with. "config validate" +// reports these together with any unknown keys. +func (c *Config) Validate() error { + if c.Repeat < 1 { + return fmt.Errorf("repeat must be at least 1, got %d", c.Repeat) + } + + return nil +} + +func run(_ context.Context, cfg *Config) error { + for range cfg.Repeat { + fmt.Println(cfg.Greeting) + } + + return nil +} + +func newRootCommand() *cobra.Command { + root := &cobra.Command{Use: "greeter", Short: "Say hello"} + + serve := cli.NewCommand(&cobra.Command{Use: "run", Short: "Say the greeting"}, run, NewConfig(), + cli.WithConfigFlag(""), cli.WithConfigValidation()) + root.AddCommand(serve) + root.AddCommand(cli.NewConfigCommand("greeter", func() cli.Validator { return NewConfig() })) + + return root +} + +func main() { + ctx := cli.Context(context.Background(), cli.SetOrgName("dioad"), cli.SetAppName("greeter")) + if err := newRootCommand().ExecuteContext(ctx); err != nil { + os.Exit(1) + } +} diff --git a/examples/config-command/main_test.go b/examples/config-command/main_test.go new file mode 100644 index 0000000..b836612 --- /dev/null +++ b/examples/config-command/main_test.go @@ -0,0 +1,51 @@ +package main + +import ( + "bytes" + "os" + "path/filepath" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func execute(t *testing.T, args ...string) (string, error) { + t.Helper() + root := newRootCommand() + var out bytes.Buffer + root.SetOut(&out) + root.SetErr(&out) + root.SetArgs(args) + err := root.Execute() + + return out.String(), err +} + +func TestExample_ConfigValidateReportsABadFile(t *testing.T) { + path := filepath.Join(t.TempDir(), "greeter.yaml") + require.NoError(t, os.WriteFile(path, []byte("greeting: hi\nrepeat: 0\nmanagement:\n listen-adress: ':1'\n"), 0o600)) + + out, err := execute(t, "config", "validate", "--config", path) + + require.Error(t, err) + assert.Contains(t, out, "management.listen-adress: unknown key") + assert.Contains(t, out, "repeat must be at least 1, got 0") +} + +func TestExample_ConfigExampleShowsDefaults(t *testing.T) { + out, err := execute(t, "config", "example") + + require.NoError(t, err) + assert.Contains(t, out, "# what to say\ngreeting: hello\n") + assert.Contains(t, out, "listen-address: 127.0.0.1:4444") +} + +func TestExample_FlagNamesFollowTheConfigKeys(t *testing.T) { + root := newRootCommand() + runCmd, _, err := root.Find([]string{"run"}) + require.NoError(t, err) + + assert.NotNil(t, runCmd.Flags().Lookup("management-listen-address")) + assert.NotNil(t, runCmd.Flags().Lookup("drain-delay")) +} diff --git a/go.mod b/go.mod index 309cc89..cc73698 100644 --- a/go.mod +++ b/go.mod @@ -11,6 +11,7 @@ require ( github.com/spf13/viper v1.21.0 github.com/stretchr/testify v1.12.1 github.com/urfave/sflags v0.4.2-0.20250718033027-b88b11ddd16a + go.yaml.in/yaml/v3 v3.0.5 gopkg.in/natefinch/lumberjack.v2 v2.2.1 ) @@ -28,7 +29,6 @@ require ( github.com/spf13/afero v1.15.0 // indirect github.com/spf13/cast v1.10.0 // indirect github.com/subosito/gotenv v1.6.0 // indirect - go.yaml.in/yaml/v3 v3.0.5 // indirect golang.org/x/sys v0.45.0 // indirect golang.org/x/text v0.37.0 // indirect gopkg.in/yaml.v3 v3.0.1 // indirect