Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
167 changes: 167 additions & 0 deletions configcommand.go
Original file line number Diff line number Diff line change
@@ -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))
}
203 changes: 203 additions & 0 deletions configcommand_test.go
Original file line number Diff line number Diff line change
@@ -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
}
Loading
Loading