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