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
11 changes: 10 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,16 @@ Checks for configuration that dioad services, libraries and plugins load:

- `configcheck` decodes configuration strictly, rejecting keys that match no
field, with the same decode hooks the dioad/cli loader uses, and reports
every problem as a finding with the path of the field it concerns.
every problem as a finding with the path of the field it concerns. It also
holds the checks services repeat for listen addresses, URLs and durations
(`CheckListenAddress`, `IsLoopbackAddress`, `ListenAddressesConflict`,
`CheckURL`, `CheckHTTPURL`, `CheckNonNegative`).
- `configwalk` reads config structs the way the loader does: keys from
`mapstructure` tags with squashed and embedded structs inlined, a walk over
every reachable struct, the defaults a constructor sets, the patterns of
weakly typed scalars, and `KeyNamingProblems`, a test helper that enforces
the key naming rules (kebab-case, no `config` suffix). A schema or example
generator, and the tests over a config type, build on it.

It depends only on the standard library, mapstructure and dioad/util, so a
library or plugin can check configuration without importing a CLI framework.
117 changes: 117 additions & 0 deletions configcheck/rules.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
package configcheck

import (
"net"
"net/netip"
"net/url"
"strings"
"time"
)

// The checks below are the ones every service repeats for its settings: listen
// addresses, URLs and durations. Each reports its findings at the collector it
// is given, which should be positioned at the setting, and each treats an empty
// value as not set, which is not its business to reject. A check mirrors what
// the code that uses the setting does with it, so a config a check passes is
// one that code accepts.

// 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.
func CheckListenAddress(findings *Collector, address string) {
if address == "" {
return
}
if _, port, err := net.SplitHostPort(address); err != nil {
findings.Errorf("%q: %v", address, err)
} else if port == "" {
findings.Errorf("%q has no port", address)
}
}

// 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 IsLoopbackAddress(address string) bool {
host, _, err := net.SplitHostPort(address)
if err != nil || host == "" {
return false
}
if strings.EqualFold(host, "localhost") {
return true
}
ip, err := netip.ParseAddr(host)

return err == nil && ip.IsLoopback()
}

// 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.
func ListenAddressesConflict(a, b string) bool {
hostA, portA, errA := net.SplitHostPort(a)
hostB, portB, errB := net.SplitHostPort(b)
if errA != nil || errB != nil || portA != portB || portA == "" || portA == "0" {
return false
}

return hostA == hostB || isWildcardHost(hostA) || isWildcardHost(hostB)
}

func isWildcardHost(host string) bool {
if host == "" {
return true
}
ip, err := netip.ParseAddr(host)

return err == nil && ip.IsUnspecified()
}

// 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 CheckURL(findings *Collector, rawURL string) {
if rawURL == "" {
return
}
u, err := url.Parse(rawURL)
if err != nil {
findings.Errorf("%v", err)

return
}
if u.Host == "" {
findings.Errorf("%q must be a URL with a host, such as https://example.com/path", rawURL)
}
}

// 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 CheckHTTPURL(findings *Collector, rawURL string) {
if rawURL == "" {
return
}
u, err := url.Parse(rawURL)
if err != nil {
findings.Errorf("%v", err)

return
}
if u.Scheme != "http" && u.Scheme != "https" {
findings.Errorf("%q must be an http or https URL", rawURL)

return
}
if u.Host == "" {
findings.Errorf("%q has no host", rawURL)
}
}

// CheckNonNegative checks that a duration is not negative.
func CheckNonNegative(findings *Collector, d time.Duration) {
if d < 0 {
findings.Errorf("%v must not be negative", d)
}
}
130 changes: 130 additions & 0 deletions configcheck/rules_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
package configcheck_test

import (
"fmt"
"testing"
"time"

"github.com/stretchr/testify/assert"

"github.com/dioad/config/configcheck"
)

func findingsOf(check func(*configcheck.Collector)) []configcheck.Finding {
c := configcheck.NewCollector()
check(c.Field("x"))

return c.Findings()
}

func TestCheckListenAddress(t *testing.T) {
t.Parallel()

for _, ok := range []string{"", ":1080", "0.0.0.0:1080", "localhost:0", "[::1]:8443"} {
assert.Empty(t, findingsOf(func(c *configcheck.Collector) { configcheck.CheckListenAddress(c, ok) }), ok)
}
assert.Equal(t, []configcheck.Finding{{Path: "x", Message: `"1080": address 1080: missing port in address`}},
findingsOf(func(c *configcheck.Collector) { configcheck.CheckListenAddress(c, "1080") }))
assert.Equal(t, []configcheck.Finding{{Path: "x", Message: `"localhost:" has no port`}},
findingsOf(func(c *configcheck.Collector) { configcheck.CheckListenAddress(c, "localhost:") }))
}

func TestCheckURL(t *testing.T) {
t.Parallel()

for _, ok := range []string{"", "https://example.com/path", "http://localhost:8080", "tcp://example.com:8119"} {
assert.Empty(t, findingsOf(func(c *configcheck.Collector) { configcheck.CheckURL(c, ok) }), ok)
}
assert.Equal(t, []configcheck.Finding{{Path: "x", Message: `"example.com:8119" must be a URL with a host, such as https://example.com/path`}},
findingsOf(func(c *configcheck.Collector) { configcheck.CheckURL(c, "example.com:8119") }))
}

func TestCheckHTTPURL(t *testing.T) {
t.Parallel()

for _, ok := range []string{"", "https://events.example.com/event", "http://localhost:8120/event"} {
assert.Empty(t, findingsOf(func(c *configcheck.Collector) { configcheck.CheckHTTPURL(c, ok) }), ok)
}
assert.Equal(t, []configcheck.Finding{{Path: "x", Message: `"wss://events.example.com" must be an http or https URL`}},
findingsOf(func(c *configcheck.Collector) { configcheck.CheckHTTPURL(c, "wss://events.example.com") }))
assert.Equal(t, []configcheck.Finding{{Path: "x", Message: `"https:///event" has no host`}},
findingsOf(func(c *configcheck.Collector) { configcheck.CheckHTTPURL(c, "https:///event") }))
}

func TestCheckNonNegative(t *testing.T) {
t.Parallel()

assert.Empty(t, findingsOf(func(c *configcheck.Collector) { configcheck.CheckNonNegative(c, 0) }))
assert.Equal(t, []configcheck.Finding{{Path: "x", Message: "-1s must not be negative"}},
findingsOf(func(c *configcheck.Collector) { configcheck.CheckNonNegative(c, -time.Second) }))
}

func TestIsLoopbackAddress(t *testing.T) {
t.Parallel()

tests := map[string]bool{
"127.0.0.1:5555": true,
"[::1]:5555": true,
"localhost:5555": true,
"LOCALHOST:5555": true,
"0.0.0.0:5555": false,
":5555": false,
"10.0.0.5:5555": false,
"[::]:5555": false,
"example.com:5555": false,
"not-an-address": false,
"": false,
}
for address, want := range tests {
t.Run(address, func(t *testing.T) {
t.Parallel()
assert.Equal(t, want, configcheck.IsLoopbackAddress(address))
})
}
}

func TestListenAddressesConflict(t *testing.T) {
t.Parallel()

tests := []struct {
a, b string
want bool
}{
{"0.0.0.0:8443", "0.0.0.0:8443", true},
{"127.0.0.1:8443", "127.0.0.1:8443", true},
{"0.0.0.0:8443", "127.0.0.1:8443", true},
{":8443", "10.0.0.5:8443", true},
{"[::]:8443", "127.0.0.1:8443", true},
{"127.0.0.1:8443", "10.0.0.5:8443", false},
{"0.0.0.0:8443", "0.0.0.0:8444", false},
{"127.0.0.1:0", "127.0.0.1:0", false},
{"not-an-address", "not-an-address", false},
{"", "", false},
}
for _, tt := range tests {
t.Run(tt.a+" "+tt.b, func(t *testing.T) {
t.Parallel()
assert.Equal(t, tt.want, configcheck.ListenAddressesConflict(tt.a, tt.b))
assert.Equal(t, tt.want, configcheck.ListenAddressesConflict(tt.b, tt.a), "the check is symmetric")
})
}
}

func ExampleCheckListenAddress() {
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 ExampleListenAddressesConflict() {
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
}
Loading
Loading