Alerts to a JSON webhook, with a cooldown and an hourly summary (closes #26)

SWWAF_ALERT_WEBHOOK_URL gets one JSON POST per alert, in SPEC.md's
schema, with SWWAF_ALERT_WEBHOOK_HEADERS: ban and permanent_ban, with
the ban's notes, in observe mode too, marked mode observe and worked
out only when the alert would be sent; source_failure for GeoJS;
file_error for a rule or state file with an error. SWWAF_ALERT_EVENTS
chooses; SWWAF_ALERT_COOLDOWN holds back repeats by netblock, file or
source; past SWWAF_ALERT_MAX_PER_HOUR the hour ends in one summary. A
bounded queue, retried with backoff, holds up no request; a 4xx other
than 408 and 429 gives the alert up. alerts.json keeps the queue, the
cooldowns and the hour. Nothing shows the URL's path or query.

Judgement call: the summary's event is summary, which SPEC.md omits.
Judgement call: an admin's ban raises no alert.

Model: opus-5-5

internal/rules/rules.go

@@ -22,6 +22,7 @@ import (
 
 	"github.com/fsnotify/fsnotify"
 
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
 	"sneak.berlin/go/smallwebwaf/internal/config"
 )
 
@@ -100,6 +101,8 @@ type Params struct {
 	// ProcessLog receives how many rules were read, and the error in a
 	// rule file edited while smallwebwaf runs.
 	ProcessLog *slog.Logger
+	// Alerts receive a file_error alert for that error.
+	Alerts *alerts.Queue
 }
 
 // Files are the rule files of a running smallwebwaf, and the rules read
@@ -126,7 +129,7 @@ func Load(params Params) (*Files, error) {
 		return f, nil
 	}
 
-	rules, err := read(params.Dir)
+	rules, _, err := read(params.Dir)
 	if err != nil {
 		return nil, err
 	}
@@ -223,13 +226,21 @@ func (f *Files) readAfterChanges(
 }
 
 // readAgain reads the rule files again, in place of the rules loaded, or
-// logs the error that keeps the rules as they were.
+// logs the error that keeps the rules as they were, and raises a
+// file_error alert for it, for the file it is in.
 func (f *Files) readAgain() {
-	rules, err := read(f.params.Dir)
+	rules, path, err := read(f.params.Dir)
 	if err != nil {
-		f.params.ProcessLog.Error(
-			"a rule file has an error, and the rules stay as they were",
-			"error", err.Error())
+		const kept = "a rule file has an error, and the rules stay as they were"
+
+		// Raised before it is logged, so that the alert is there once the
+		// log line is.
+		f.params.Alerts.Raise(alerts.Alert{
+			Event:  alerts.EventFileError,
+			Reason: kept,
+			Detail: map[string]any{"file": path, "error": err.Error()},
+		})
+		f.params.ProcessLog.Error(kept, "error", err.Error())
 
 		return
 	}
@@ -246,13 +257,14 @@ func (f *Files) logRead(count int) {
 }
 
 // read returns the rules of every rule file in dir, in the order of the
-// files' names, and then of their lines. A file whose name starts with a
-// dot, such as an editor's lock file .#50-app.rules, is not a rule file,
-// as a shell's *.rules would not match it.
-func read(dir string) ([]Rule, error) {
+// files' names, and then of their lines, or an error, with the path of the
+// rule file it is in, or dir. A file whose name starts with a dot, such as
+// an editor's lock file .#50-app.rules, is not a rule file, as a shell's
+// *.rules would not match it.
+func read(dir string) ([]Rule, string, error) {
 	entries, err := os.ReadDir(dir)
 	if err != nil {
-		return nil, fmt.Errorf("SWWAF_RULES_DIR cannot be read: %w", err)
+		return nil, dir, fmt.Errorf("SWWAF_RULES_DIR cannot be read: %w", err)
 	}
 
 	var rules []Rule
@@ -266,13 +278,15 @@ func read(dir string) ([]Rule, error) {
 			continue
 		}
 
-		rules, err = readFile(filepath.Join(dir, name), rules, places)
+		path := filepath.Join(dir, name)
+
+		rules, err = readFile(path, rules, places)
 		if err != nil {
-			return nil, err
+			return nil, path, err
 		}
 	}
 
-	return rules, nil
+	return rules, "", nil
 }
 
 // readFile appends the rules of the rule file at path to rules. places

internal/rules/rules_test.go

@@ -7,12 +7,15 @@ import (
 	"maps"
 	"net/http"
 	"net/http/httptest"
+	"net/url"
 	"os"
 	"path/filepath"
 	"slices"
 	"strconv"
 	"testing"
+	"time"
 
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
 	"sneak.berlin/go/smallwebwaf/internal/rules"
 )
 
@@ -337,7 +340,7 @@ func TestEditsTakenInWhileRunning(t *testing.T) {
 	t.Parallel()
 
 	dir := writeFiles(t, ruleFiles{firstFile: "first path block ^/first\n"})
-	files, lines := watch(t, dir)
+	files, lines, _ := watch(t, dir)
 
 	// matches reports whether path matches a rule.
 	matches := func(path string) bool { return len(files.Match(get(t, path))) == 1 }
@@ -366,7 +369,7 @@ func TestBrokenEditKeepsTheRulesAsTheyWere(t *testing.T) {
 	t.Parallel()
 
 	dir := writeFiles(t, ruleFiles{firstFile: "first path block ^/first\n"})
-	files, lines := watch(t, dir)
+	files, lines, queue := watch(t, dir)
 
 	// The edit's second line has an unknown action, so the rules stay as
 	// they were, the first line's earlier version included.
@@ -380,13 +383,27 @@ func TestBrokenEditKeepsTheRulesAsTheyWere(t *testing.T) {
 		t.Errorf("logged %v, want an error %q", line, want)
 	}
 
+	// The error is raised as a file_error alert too, for the file.
+	wantFileError := func() {
+		t.Helper()
+
+		waiting := queue.Snapshot().Waiting
+		if len(waiting) != 1 || waiting[0].Event != alerts.EventFileError ||
+			waiting[0].Reason != hasError || waiting[0].Detail["error"] != want ||
+			waiting[0].Detail["file"] != filepath.Join(dir, firstFile) {
+			t.Errorf("alerts waiting %+v, want one file_error alert for %q", waiting, want)
+		}
+	}
+	wantFileError()
+
 	wantMatched(t, files, get(t, "/first"), "first")
 	wantMatched(t, files, get(t, "/second"))
 
-	// Once mended, the file is read again.
+	// Once mended, the file is read again, and raises no alert.
 	save(t, dir, firstFile, "first path block ^/edited\nsecond path ban ^/second\n")
 	lines.waitUntil(t, func() bool { return len(files.Match(get(t, "/second"))) == 1 })
 	wantMatched(t, files, get(t, "/edited"), "first")
+	wantFileError()
 }
 
 func TestDefaultFileBansProbesAtTheSiteRootAlone(t *testing.T) {
@@ -504,7 +521,8 @@ func save(t *testing.T, dir, name, content string) {
 }
 
 // newParams returns Params for the rule files in dir, switched on, with
-// the process log in the processLog returned.
+// the process log in the processLog returned, and the alerts waiting in a
+// queue for a webhook that is never sent them.
 func newParams(dir string) (rules.Params, processLog) {
 	lines := make(processLog, maxLogLines)
 
@@ -512,6 +530,12 @@ func newParams(dir string) (rules.Params, processLog) {
 		Dir:        dir,
 		Enabled:    true,
 		ProcessLog: slog.New(slog.NewJSONHandler(lines, nil)),
+		Alerts: alerts.New(alerts.Params{
+			WebhookURL: &url.URL{Scheme: "https", Host: "alerts.example"},
+			Events:     alerts.Events(),
+			Cooldown:   15 * time.Minute,
+			Now:        time.Now,
+		}),
 	}, lines
 }
 
@@ -531,8 +555,9 @@ func load(t *testing.T, files ruleFiles) *rules.Files {
 }
 
 // watch loads the rules in dir, runs their Watch until the test ends, and
-// waits until it watches the directory.
-func watch(t *testing.T, dir string) (*rules.Files, processLog) {
+// waits until it watches the directory. It returns the alerts' queue as
+// well.
+func watch(t *testing.T, dir string) (*rules.Files, processLog, *alerts.Queue) {
 	t.Helper()
 
 	params, lines := newParams(dir)
@@ -557,7 +582,7 @@ func watch(t *testing.T, dir string) (*rules.Files, processLog) {
 
 	lines.waitFor(t, watching)
 
-	return files, lines
+	return files, lines, params.Alerts
 }
 
 // wantRefused checks that loading the rule files in dir fails with the

internal/rules/watch_internal_test.go

@@ -13,6 +13,8 @@ import (
 	"time"
 
 	"github.com/fsnotify/fsnotify"
+
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
 )
 
 // The tests below run readAfterChanges in a synctest bubble, where time is
@@ -91,6 +93,7 @@ func load(t *testing.T, dir string) *Files {
 
 	files, err := Load(Params{
 		Dir: dir, Enabled: true, ProcessLog: slog.New(slog.DiscardHandler),
+		Alerts: alerts.New(alerts.Params{}),
 	})
 	if err != nil {
 		t.Fatalf("load: %v", err)