configcheck

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

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

Examples

Constants

View Source
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

func CheckHTTPURL(findings *Collector, rawURL string)

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

func CheckListenAddress(findings *Collector, address string)

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

func CheckNonNegative(findings *Collector, d time.Duration)

CheckNonNegative checks that a duration is not negative.

func CheckURL added in v0.2.0

func CheckURL(findings *Collector, rawURL string)

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

func Decode(input, out any) error

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

func IsLoopbackAddress(address string) bool

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

func JoinPath(base, rel string) string

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

func ListenAddressesConflict(a, b string) bool

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

func (c *Collector) Add(err error)

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) Err

func (c *Collector) Err() error

Err returns the findings as an *Error, or nil if there are none.

func (*Collector) Errorf

func (c *Collector) Errorf(format string, args ...any)

Errorf adds a finding at c's path.

func (*Collector) Field

func (c *Collector) Field(name string) *Collector

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

func (c *Collector) Findings() []Finding

Findings returns every finding added through c or any collector sharing its findings, in the order they were added.

func (*Collector) Index

func (c *Collector) Index(i int) *Collector

Index returns a collector for element i of a list: "tunnels[2]".

func (*Collector) Inert added in v0.3.0

func (c *Collector) Inert(names ...string)

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.

func (*Collector) Key

func (c *Collector) Key(k string) *Collector

Key returns a collector for the map entry k in bracket form, "routes[dmarc]", matching the paths Decode reports for map entries.

func (*Collector) Path

func (c *Collector) Path() string

Path returns the path findings added to c are reported under.

type Error

type Error struct {
	Findings []Finding
}

Error is an error made of one or more findings.

func (*Error) Error

func (e *Error) Error() string

Error returns the findings one per line.

type Finding

type Finding struct {
	// Path locates the field, for example "traffic.tunnels[2].subdomain".
	// It is empty for a problem with the configuration as a whole.
	Path string
	// Message describes the problem.
	Message string
}

Finding is one configuration problem.

func (Finding) String

func (f Finding) String() string

String returns the finding as "path: message", or just the message when Path is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL