configcheck

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 16, 2026 License: Apache-2.0 Imports: 10 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 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 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.

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