Serve Prometheus metrics behind SWWAF_METRICS_TOKEN (closes #23)

GET /_smallwebwaf/metrics answers in the Prometheus text format for a
request carrying SWWAF_METRICS_TOKEN, 401 without it and 404 while it is
unset. Every request under /_smallwebwaf/ but the health check now goes
through the checks and is answered where it would be forwarded, 404 for
any path but the metrics, so none reaches the app. SWWAF_METRICS_TOP_N
bounds the series by country, the rest counted as other.

Judgement call: a request answered at smallwebwaf's own endpoints is
neither forwarded nor refused in the client's history.
Deviation: go.mod and go.sum written by hand from the module proxy and
sum.golang.org, as go runs only through make.
Deviation: no metrics yet for state files read again after an edit or
edits set aside; that work is not merged.

Model: opus-5-5

internal/config/config.go

@@ -17,6 +17,7 @@ import (
 	"strconv"
 	"strings"
 	"time"
+	"unicode/utf8"
 )
 
 // Config is smallwebwaf's settings. A timeout, size or rate limit of zero
@@ -103,6 +104,12 @@ type Config struct {
 	StateDir             string
 	StateWriteDelay      time.Duration
 	StateCounterInterval time.Duration
+	// MetricsToken is the bearer token a scraper sends for the metrics
+	// (SWWAF_METRICS_TOKEN), "" while it is unset and the metrics are off.
+	// MetricsTopN is how many countries get series of their own in the
+	// metrics (SWWAF_METRICS_TOP_N).
+	MetricsToken string
+	MetricsTopN  int
 
 	// settings are the values read, as given or by default, for the
 	// log line at start.
@@ -119,6 +126,10 @@ const (
 	mebibyte = 1 << 20
 	gibibyte = 1 << 30
 	ipv4Bits = 32
+	// minTokenLength is the fewest characters a token may have.
+	minTokenLength = 32
+	// masked is what the log shows for a token that is set.
+	masked = "********"
 )
 
 var (
@@ -150,6 +161,7 @@ var (
 		"is not the length of an IPv4 netblock, from 0 to 32, such as 24")
 	errNotAbsolutePath = errors.New(
 		"is not an absolute path, such as /var/lib/smallwebwaf")
+	errShortToken = errors.New("is shorter than 32 characters")
 )
 
 // FromEnvironment reads the settings with lookupEnv, normally
@@ -188,6 +200,8 @@ func FromEnvironment(lookupEnv func(string) (string, bool)) (*Config, error) {
 		StateDir:             env.absolutePath("SWWAF_STATE_DIR", "/var/lib/smallwebwaf"),
 		StateWriteDelay:      env.durationNotOff("SWWAF_STATE_WRITE_DELAY", "10s"),
 		StateCounterInterval: env.durationNotOff("SWWAF_STATE_COUNTER_INTERVAL", "15m"),
+		MetricsToken:         env.token("SWWAF_METRICS_TOKEN"),
+		MetricsTopN:          env.numberNotOff("SWWAF_METRICS_TOP_N", "50"),
 	}
 
 	for _, country := range cfg.ExclusivelyAllowedCountries {
@@ -353,6 +367,26 @@ func (e *environment) absolutePath(name, defaultValue string) string {
 	return path
 }
 
+// token reads a setting that is a bearer token. Unset, it is "", which
+// switches off what it guards; set, it must be at least minTokenLength
+// characters. Neither the log nor an error shows its value.
+func (e *environment) token(name string) string {
+	value, set := e.lookupEnv(name)
+	if !set {
+		e.settings = append(e.settings, slog.String(name, ""))
+
+		return ""
+	}
+
+	e.settings = append(e.settings, slog.String(name, masked))
+
+	if utf8.RuneCountInString(value) < minTokenLength {
+		e.check(name, errShortToken)
+	}
+
+	return value
+}
+
 // parseDuration reads a duration in Go's syntax, such as 90s or 15m, a
 // whole number of days such as 7d, or off.
 func parseDuration(value string) (time.Duration, error) {

internal/config/config_test.go

@@ -44,8 +44,13 @@ const (
 	stateDir                = "SWWAF_STATE_DIR"
 	stateWriteDelay         = "SWWAF_STATE_WRITE_DELAY"
 	stateCounterInterval    = "SWWAF_STATE_COUNTER_INTERVAL"
+	metricsToken            = "SWWAF_METRICS_TOKEN" //nolint:gosec // the setting's name
+	metricsTopN             = "SWWAF_METRICS_TOP_N"
 )
 
+// token is a token of 32 characters, the shortest allowed.
+const token = "0123456789abcdef0123456789abcdef"
+
 // off switches a timeout, a size limit or a rate limit off.
 const off = "off"
 
@@ -98,6 +103,8 @@ func TestDefaults(t *testing.T) {
 		StateDir:                    "/var/lib/smallwebwaf",
 		StateWriteDelay:             10 * time.Second,
 		StateCounterInterval:        15 * time.Minute,
+		MetricsToken:                "",
+		MetricsTopN:                 50,
 	})
 
 	if cfg.UpstreamURL.String() != "http://127.0.0.1:8081" {
@@ -145,6 +152,8 @@ func TestValuesAsSet(t *testing.T) {
 		stateDir:                "/srv/waf-state",
 		stateWriteDelay:         "500ms",
 		stateCounterInterval:    "1h",
+		metricsToken:            token,
+		metricsTopN:             "10",
 	})
 
 	wantSettings(t, cfg, config.Config{
@@ -169,6 +178,8 @@ func TestValuesAsSet(t *testing.T) {
 		StateDir:                    "/srv/waf-state",
 		StateWriteDelay:             500 * time.Millisecond,
 		StateCounterInterval:        time.Hour,
+		MetricsToken:                token,
+		MetricsTopN:                 10,
 	})
 
 	if cfg.UpstreamURL.String() != "https://app.internal:8443/" {
@@ -344,6 +355,7 @@ func TestInvalidValueStopsTheStart(t *testing.T) {
 		{stateDir, ""}, {stateDir, "state"}, {stateDir, "./var/lib/smallwebwaf"},
 		{stateWriteDelay, off}, {stateWriteDelay, "0s"},
 		{stateCounterInterval, off}, {stateCounterInterval, "15"},
+		{metricsTopN, off}, {metricsTopN, "0"}, {metricsTopN, "-1"},
 	} {
 		t.Run(tc.name+"="+tc.value, func(t *testing.T) {
 			t.Parallel()
@@ -360,6 +372,39 @@ func TestInvalidValueStopsTheStart(t *testing.T) {
 	}
 }
 
+func TestShortTokenStopsTheStartWithoutShowingIt(t *testing.T) {
+	t.Parallel()
+
+	// Characters are counted, not bytes: each é takes two.
+	for _, value := range []string{"", token[1:], strings.Repeat("é", 31)} {
+		t.Run(value, func(t *testing.T) {
+			t.Parallel()
+
+			_, err := config.FromEnvironment(environment{metricsToken: value}.lookupEnv)
+
+			want := metricsToken + ": is shorter than 32 characters"
+			if err == nil || err.Error() != want {
+				t.Errorf("error %v, want %s", err, want)
+			}
+		})
+	}
+}
+
+func TestTokenIsLoggedMasked(t *testing.T) {
+	t.Parallel()
+
+	cfg := fromEnvironment(t, environment{metricsToken: token})
+
+	var out bytes.Buffer
+
+	slog.New(slog.NewJSONHandler(&out, nil)).Info("starting", "settings", cfg)
+
+	if strings.Contains(out.String(), token) ||
+		!strings.Contains(out.String(), `"`+metricsToken+`":"********"`) {
+		t.Errorf("the token is not logged masked: %s", out.String())
+	}
+}
+
 func TestLogsEachSettingWithItsValue(t *testing.T) {
 	t.Parallel()
 
@@ -407,6 +452,8 @@ func TestLogsEachSettingWithItsValue(t *testing.T) {
 		stateDir:                "/var/lib/smallwebwaf",
 		stateWriteDelay:         "10s",
 		stateCounterInterval:    "15m",
+		metricsToken:            "",
+		metricsTopN:             "50",
 	}
 	if !maps.Equal(line.Settings, want) {
 		t.Errorf("logged settings\n%v\nwant\n%v", line.Settings, want)
@@ -435,7 +482,8 @@ func wantSettings(t *testing.T, got *config.Config, want config.Config) {
 	wantBanSettings(t, got, want)
 }
 
-// wantBanSettings checks the settings for bans and the state files.
+// wantBanSettings checks the settings for bans, the state files and the
+// metrics.
 func wantBanSettings(t *testing.T, got *config.Config, want config.Config) {
 	t.Helper()
 
@@ -453,6 +501,11 @@ func wantBanSettings(t *testing.T, got *config.Config, want config.Config) {
 		got.StateCounterInterval != want.StateCounterInterval {
 		t.Errorf("state settings\n%+v\nwant\n%+v", got, want)
 	}
+
+	if got.MetricsToken != want.MetricsToken || got.MetricsTopN != want.MetricsTopN {
+		t.Errorf("metrics token %q and top %d, want %q and %d",
+			got.MetricsToken, got.MetricsTopN, want.MetricsToken, want.MetricsTopN)
+	}
 }
 
 // wantNetblocks checks a list of netblocks.