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 CheckHTTPURL(findings *Collector, rawURL string)
- func CheckListenAddress(findings *Collector, address string)
- func CheckNonNegative(findings *Collector, d time.Duration)
- func CheckURL(findings *Collector, rawURL string)
- func Decode(input, out any) error
- func DecodeHook() mapstructure.DecodeHookFunc
- func IsLoopbackAddress(address string) bool
- func JoinPath(base, rel string) string
- func ListenAddressesConflict(a, b string) bool
- 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) Inert(names ...string)
- 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 CheckHTTPURL ¶ added in v0.2.0
CheckHTTPURL checks a URL an HTTP client sends requests to: it must be an http or https URL with a host. An empty URL is not set and is not checked.
func CheckListenAddress ¶ added in v0.2.0
CheckListenAddress checks a listen address passed to net.Listen: it must be host:port, where the host may be empty to listen on every interface. An empty address is not set and is not checked.
Example ¶
package main
import (
"fmt"
"github.com/dioad/config/configcheck"
)
func main() {
findings := configcheck.NewCollector()
configcheck.CheckListenAddress(findings.Field("management").Field("listen-address"), "4444")
configcheck.CheckListenAddress(findings.Field("control").Field("listen-address"), ":8119")
for _, f := range findings.Findings() {
fmt.Println(f)
}
}
Output: management.listen-address: "4444": address 4444: missing port in address
func CheckNonNegative ¶ added in v0.2.0
CheckNonNegative checks that a duration is not negative.
func CheckURL ¶ added in v0.2.0
CheckURL checks a URL a client dials: it must parse and have a host. Any scheme is accepted, since a client may dial any scheme with a host and port. An empty URL is not set and is not checked.
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.
func IsLoopbackAddress ¶ added in v0.2.0
IsLoopbackAddress reports whether a host:port listen address binds only the loopback interface. An empty host listens on every interface, so it is not loopback; neither is an address that does not parse.
func JoinPath ¶
JoinPath joins a path and a path relative to it. A relative path that starts with an index or key ("[2].name") is appended without a dot.
func ListenAddressesConflict ¶ added in v0.2.0
ListenAddressesConflict reports whether two host:port listen addresses cannot both be bound: they name the same port, on the same host or with a wildcard host (empty, 0.0.0.0 or ::) on either side. Port 0 asks the system for a free port and never conflicts. Addresses that do not parse do not conflict; CheckListenAddress reports those.
Example ¶
package main
import (
"fmt"
"github.com/dioad/config/configcheck"
)
func main() {
fmt.Println(configcheck.ListenAddressesConflict(":8443", "10.0.0.5:8443"))
fmt.Println(configcheck.ListenAddressesConflict("127.0.0.1:8443", "10.0.0.5:8443"))
}
Output: true false
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.
func (*Collector) Inert ¶ added in v0.3.0
Inert adds a finding at c's path for each of names: a setting that is populated but has no effect in this configuration. A setting that silently does nothing leaves an operator believing it applies, so a command rejects it rather than warning. Each name may carry a short reason in parentheses. No names adds nothing.
type Error ¶
type Error struct {
Findings []Finding
}
Error is an error made of one or more findings.