Documentation
¶
Overview ¶
Package configcheck reports configuration problems as findings, each with the path of the field it concerns, so a command can report every problem in a configuration at once instead of stopping at the first.
It also holds the decode hook used to load configuration and a strict decoder built on it. The package depends only on the standard library, mapstructure and github.com/dioad/util, so libraries and plugins can validate configuration the same way the github.com/dioad/cli loader does without importing a CLI framework.
Index ¶
- Constants
- func Decode(input, out any) error
- func DecodeHook() mapstructure.DecodeHookFunc
- func JoinPath(base, rel string) string
- type Collector
- func (c *Collector) Add(err error)
- func (c *Collector) Err() error
- func (c *Collector) Errorf(format string, args ...any)
- func (c *Collector) Field(name string) *Collector
- func (c *Collector) Findings() []Finding
- func (c *Collector) Index(i int) *Collector
- func (c *Collector) Key(k string) *Collector
- func (c *Collector) Path() string
- type Error
- type Finding
Examples ¶
Constants ¶
const UnknownKeyMessage = "unknown key"
UnknownKeyMessage is the Message of a finding Decode reports for a key that matches no field.
Variables ¶
This section is empty.
Functions ¶
func Decode ¶
Decode decodes input, typically a map[string]any read from a configuration file, into out, which must be a non-nil pointer. It decodes as the cli loader does, with DecodeHook and mapstructure's weakly typed input (so a number decodes into a string field, as viper allows), and additionally rejects keys that match no field.
Every problem is reported, as an *Error whose findings are sorted by path and whose paths are relative to input: "tunnels[0].tls-server-config" for an unknown key, "routes[dmarc].max-size" inside a map. Fields that decode cleanly are set even when others fail. Any other error means out could not be decoded into at all, which is a programming error rather than a configuration problem.
func DecodeHook ¶
func DecodeHook() mapstructure.DecodeHookFunc
DecodeHook returns the decode hook used to load configuration: it decodes util.MaskedString, time.Duration, net.IP and net.IPNet values from strings. Use it for any decode of configuration that must accept exactly what the cli loader accepts.
Types ¶
type Collector ¶
type Collector struct {
// contains filtered or unexported fields
}
Collector accumulates findings. A collector derived with Field, Index or Key adds findings under a longer path but shares its findings with the collector it came from, so a check can be handed a collector for its own sub-tree and write paths relative to it.
The zero value is an empty collector at the root path. Collectors are safe for concurrent use once created, but a zero-value collector must not be first used from several goroutines at once.
Example ¶
package main
import (
"fmt"
"github.com/dioad/config/configcheck"
)
func main() {
type tunnel struct {
Name string `mapstructure:"name"`
Port int `mapstructure:"port"`
}
raw := []map[string]any{
{"name": "web", "port": 8080},
{"port": 22, "tls-server-config": map[string]any{}},
}
c := configcheck.NewCollector()
tunnels := c.Field("tunnels")
for i, entry := range raw {
var t tunnel
entryCollector := tunnels.Index(i)
entryCollector.Add(configcheck.Decode(entry, &t))
if t.Name == "" {
entryCollector.Field("name").Errorf("is required")
}
}
fmt.Println(c.Err())
}
Output: tunnels[1].tls-server-config: unknown key tunnels[1].name: is required
func NewCollector ¶
func NewCollector() *Collector
NewCollector returns an empty collector at the root path.
func (*Collector) Add ¶
Add adds err to c. An *Error, such as one returned by Decode, contributes each of its findings with c's path prefixed; any other error becomes one finding at c's path. A nil err adds nothing.
func (*Collector) Field ¶
Field returns a collector for the struct field or map entry name, joined with a dot: "traffic" then "tunnels" gives "traffic.tunnels".
func (*Collector) Findings ¶
Findings returns every finding added through c or any collector sharing its findings, in the order they were added.
type Error ¶
type Error struct {
Findings []Finding
}
Error is an error made of one or more findings.