Keep the bans, the clients and GeoJS's answers in state files (closes #17)

smallwebwaf now copies its state to bans.json, clients.json and
lookups.json in SWWAF_STATE_DIR, as "Persistent state" in SPEC.md
describes, and reads them back at start, so a restart lifts no ban and
gives no client a fresh allowance. Each client gains a history, and a
ban's notes count the netblock's requests. bans.json is written
SWWAF_STATE_WRITE_DELAY after a ban, every file every
SWWAF_STATE_COUNTER_INTERVAL and at the stop, each through a synced
temporary file renamed over it. A file that does not parse, an unknown
version or an unwritable directory stops the start. The image gets
/var/lib/smallwebwaf, which the run script gives to the smallwebwaf user.

Deviation: no AS number or name, and no ban cause, reason or lifting yet.

Model: opus-5-5

internal/bans/bans.go

@@ -1,6 +1,7 @@
 // Package bans is the ban ledger: the bans smallwebwaf makes on the
 // netblocks of clients that break a rate limit, with their notes, as the
-// "Bans" section of SPEC.md describes. The bans are kept in memory only.
+// "Bans" section of SPEC.md describes. The bans are kept in memory, and
+// written to bans.json and read from it by the state package.
 package bans
 
 import (
@@ -58,41 +59,52 @@ func (b Ban) ActiveAt(now time.Time) bool {
 	return b.Permanent() || now.Before(b.Expires)
 }
 
-// Notes are what an admin needs to decide whether to lift a ban.
+// Notes are what an admin needs to decide whether to lift a ban. The
+// JSON names are those of bans.json.
+//
+//nolint:tagliatelle // the state files use snake_case, as the request log does
 type Notes struct {
 	// Country is the client's country, when it was looked up.
-	Country string
+	Country string `json:"country"`
 	// Limit, Window and Count are the limit that was broken, its window,
 	// "minute", "hour" or "day", and the count reached: the client's
 	// requests in the window, the one that broke the limit included.
 	// These are the requests that counted toward the ban, and the window
 	// is the time over which they came.
-	Limit  int64
-	Window string
-	Count  float64
+	Limit  int64   `json:"limit"`
+	Window string  `json:"window"`
+	Count  float64 `json:"count"`
 	// Request is the request that broke the limit.
-	Request Request
-	// Refused is how many requests the ban has refused so far.
-	Refused int64
+	Request Request `json:"request"`
+	// Requests is how many requests the netblock has sent since it was
+	// first seen, and Refused how many of them the ban has refused so
+	// far. Both go up with each request the ban refuses.
+	Requests int64 `json:"requests"`
+	Refused  int64 `json:"refused"`
 	// EarlierBans is how many bans the netblock had before this one.
-	EarlierBans int
+	EarlierBans int `json:"earlier_bans"`
 }
 
 // Request is a request in a ban's notes. Each text is cut to 256 bytes.
+//
+//nolint:tagliatelle // the state files use snake_case, as the request log does
 type Request struct {
-	Time   time.Time
-	Method string
-	Host   string
+	Time   time.Time `json:"time"`
+	Method string    `json:"method"`
+	Host   string    `json:"host"`
 	// Path is the path with its query string.
-	Path string
+	Path string `json:"path"`
 	// Status is what the client was sent, 0 if nothing was.
-	Status    int
-	UserAgent string
+	Status    int    `json:"status"`
+	UserAgent string `json:"user_agent"`
 }
 
 // Ledger holds the bans. It is safe for concurrent use.
 type Ledger struct {
 	rules Rules
+	// changed receives a value when a ban is made, unless one is waiting
+	// already.
+	changed chan struct{}
 
 	mu sync.Mutex
 	// netblocks holds each banned netblock's bans, oldest first. Each
@@ -111,7 +123,17 @@ func New(rules Rules) *Ledger {
 		panic(err) // NewLRU fails only for a size below one
 	}
 
-	return &Ledger{rules: rules, netblocks: netblocks}
+	return &Ledger{
+		rules:     rules,
+		changed:   make(chan struct{}, 1),
+		netblocks: netblocks,
+	}
+}
+
+// Changed receives a value after a ban is made, so that bans.json can be
+// written. Several bans made before it is read leave one value.
+func (l *Ledger) Changed() <-chan struct{} {
+	return l.changed
 }
 
 // Check is called for each request from netblock, at now. It reports
@@ -133,6 +155,7 @@ func (l *Ledger) Check(netblock netip.Prefix, now time.Time) (Ban, bool) {
 		return Ban{}, false
 	}
 
+	last.Notes.Requests++
 	last.Notes.Refused++
 
 	return *last, true
@@ -169,21 +192,13 @@ func (l *Ledger) BanForLimit(netblock netip.Prefix, now time.Time, notes Notes)
 		Expires:  l.expiry(last, now),
 		Notes:    notes,
 	}
+	l.add(ban)
 
-	if l.held == l.rules.MaxBans {
-		l.dropOne()
+	select {
+	case l.changed <- struct{}{}:
+	default: // a value is waiting already
 	}
 
-	// dropOne can have dropped netblock's last ban, and netblock with it.
-	bans, found = l.netblocks.Peek(netblock)
-	if !found {
-		bans = &[]Ban{}
-		l.netblocks.Add(netblock, bans)
-	}
-
-	*bans = append(*bans, ban)
-	l.held++
-
 	return ban
 }
 
@@ -201,6 +216,63 @@ func (l *Ledger) Bans(netblock netip.Prefix) []Ban {
 	return slices.Clone(*bans)
 }
 
+// Snapshot returns every ban held, sorted by netblock, and each
+// netblock's bans oldest first, as bans.json lists them.
+func (l *Ledger) Snapshot() []Ban {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	held := make([]Ban, 0, l.held)
+	for _, bans := range l.netblocks.Values() {
+		held = append(held, *bans...)
+	}
+
+	slices.SortStableFunc(held, func(a, b Ban) int {
+		return a.Netblock.Compare(b.Netblock)
+	})
+
+	return held
+}
+
+// Load puts bans read from bans.json into a ledger that holds none yet,
+// in the order they started, so that a netblock whose last ban started
+// latest counts as the most recently seen. Each text in their notes is
+// cut to 256 bytes, and past MaxBans the earliest bans are dropped, as
+// when they are made.
+func (l *Ledger) Load(bans []Ban) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	bans = slices.Clone(bans)
+	slices.SortStableFunc(bans, func(a, b Ban) int {
+		return a.Start.Compare(b.Start)
+	})
+
+	for _, ban := range bans {
+		ban.Notes.Request = ban.Notes.Request.cut()
+		l.add(ban)
+	}
+}
+
+// add adds ban to its netblock's bans, after the last, and makes its
+// netblock the most recently seen. With MaxBans held, it drops one first.
+func (l *Ledger) add(ban Ban) {
+	if l.held == l.rules.MaxBans {
+		l.dropOne()
+	}
+
+	// dropOne can have dropped the netblock's last ban, and the netblock
+	// with it.
+	bans, found := l.netblocks.Get(ban.Netblock)
+	if !found {
+		bans = &[]Ban{}
+		l.netblocks.Add(ban.Netblock, bans)
+	}
+
+	*bans = append(*bans, ban)
+	l.held++
+}
+
 // expiry returns when a ban for a broken limit made at now ends, or zero
 // when it is permanent. last is the netblock's last ban, which has ended,
 // or nil when it has none.

internal/bans/bans_test.go

@@ -135,7 +135,7 @@ func TestCheckRefusesWhileTheBanLastsAndCountsTheRefusals(t *testing.T) {
 
 	ledger := bans.New(defaultRules())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
-	ban := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
+	ban := ledger.BanForLimit(netblock, midnight(), bans.Notes{Requests: 5})
 
 	for range 3 {
 		got, banned := ledger.Check(netblock, ban.Expires.Add(-time.Nanosecond))
@@ -154,9 +154,11 @@ func TestCheckRefusesWhileTheBanLastsAndCountsTheRefusals(t *testing.T) {
 		t.Error("the ban did not end")
 	}
 
-	refused := ledger.Bans(netblock)[0].Notes.Refused
-	if refused != 3 {
-		t.Errorf("the notes count %d refused requests, want 3", refused)
+	// The netblock's requests went from 5 to 8 with the three refused.
+	notes := ledger.Bans(netblock)[0].Notes
+	if notes.Refused != 3 || notes.Requests != 8 {
+		t.Errorf("the notes count %d refused requests of %d, want 3 of 8",
+			notes.Refused, notes.Requests)
 	}
 }
 

internal/bans/snapshot_test.go

@@ -0,0 +1,151 @@
+package bans_test
+
+import (
+	"net/netip"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/bans"
+)
+
+func TestChangedAfterABanIsMade(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+
+	wantChanged(t, ledger, false)
+
+	ledger.BanForLimit(netblock, midnight(), bans.Notes{})
+	wantChanged(t, ledger, true)
+
+	// A limit broken during the ban makes no other, and a refusal changes
+	// only the counts in the notes, which wait for the interval's write.
+	ledger.BanForLimit(netblock, midnight().Add(time.Minute), bans.Notes{})
+	ledger.Check(netblock, midnight().Add(time.Minute))
+	wantChanged(t, ledger, false)
+
+	// Two bans before the value is read leave one.
+	ledger.BanForLimit(netip.MustParsePrefix("203.0.113.10/32"), midnight(), bans.Notes{})
+	ledger.BanForLimit(netip.MustParsePrefix("203.0.113.11/32"), midnight(), bans.Notes{})
+	wantChanged(t, ledger, true)
+	wantChanged(t, ledger, false)
+}
+
+func TestSnapshotListsEveryBanByNetblock(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	v6 := netip.MustParsePrefix("2001:db8::/64")
+	high := netip.MustParsePrefix("203.0.113.10/32")
+	low := netip.MustParsePrefix("203.0.113.9/32")
+
+	first := ledger.BanForLimit(v6, midnight(), bans.Notes{})
+	ledger.BanForLimit(high, midnight(), bans.Notes{})
+	ledger.BanForLimit(low, midnight(), bans.Notes{})
+	ledger.BanForLimit(v6, first.Expires, bans.Notes{})
+
+	snapshot := ledger.Snapshot()
+
+	got := make([]string, 0, len(snapshot))
+	for _, ban := range snapshot {
+		got = append(got, ban.Netblock.String()+" "+ban.Start.Format(time.Kitchen))
+	}
+
+	want := []string{
+		"203.0.113.9/32 12:00AM", "203.0.113.10/32 12:00AM",
+		"2001:db8::/64 12:00AM", "2001:db8::/64 1:00AM",
+	}
+	if !slices.Equal(got, want) {
+		t.Errorf("snapshot %v, want %v", got, want)
+	}
+}
+
+func TestLoadedBansCarryOn(t *testing.T) {
+	t.Parallel()
+
+	before := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+	ban := before.BanForLimit(netblock, midnight(), bans.Notes{Limit: 1})
+
+	// Loaded into a new ledger, as across a restart, the ban still refuses
+	// while it lasts, and once it has ended a broken limit bans for three
+	// times as long, with the loaded ban counted among the earlier ones.
+	after := bans.New(defaultRules())
+	after.Load(before.Snapshot())
+
+	_, banned := after.Check(netblock, ban.Expires.Add(-time.Second))
+	if !banned {
+		t.Error("the loaded ban does not refuse")
+	}
+
+	again := after.BanForLimit(netblock, ban.Expires, bans.Notes{})
+	if again.Expires.Sub(again.Start) != 3*time.Hour || again.Notes.EarlierBans != 1 {
+		t.Errorf("the next ban lasts %s with %d earlier bans, want 3h and 1",
+			again.Expires.Sub(again.Start), again.Notes.EarlierBans)
+	}
+}
+
+func TestLoadKeepsAtMostMaxBansDroppingTheEarliest(t *testing.T) {
+	t.Parallel()
+
+	// bans.json lists the bans by netblock, not in the order they began.
+	later := bans.Ban{Netblock: netip.MustParsePrefix("203.0.113.1/32"), Start: midnight()}
+	earlier := bans.Ban{
+		Netblock: netip.MustParsePrefix("203.0.113.2/32"),
+		Start:    midnight().Add(-time.Hour),
+	}
+
+	rules := defaultRules()
+	rules.MaxBans = 1
+	ledger := bans.New(rules)
+	ledger.Load([]bans.Ban{later, earlier})
+
+	held := ledger.Snapshot()
+	if len(held) != 1 || held[0] != later {
+		t.Errorf("the ledger holds %+v, want only the ban that began later", held)
+	}
+}
+
+func TestLoadCutsTheTextsTo256Bytes(t *testing.T) {
+	t.Parallel()
+
+	long := strings.Repeat("a", 300)
+	ban := bans.Ban{
+		Netblock: netip.MustParsePrefix("203.0.113.9/32"),
+		Start:    midnight(),
+		Notes: bans.Notes{Request: bans.Request{
+			Method: long, Host: long, Path: long, UserAgent: long,
+		}},
+	}
+
+	ledger := bans.New(defaultRules())
+	ledger.Load([]bans.Ban{ban})
+
+	cut := long[:256]
+	want := bans.Request{Method: cut, Host: cut, Path: cut, UserAgent: cut}
+
+	got := ledger.Snapshot()[0].Notes.Request
+	if got != want {
+		t.Errorf("the notes keep %+v, want each text cut to 256 bytes", got)
+	}
+}
+
+// wantChanged checks whether the ledger's Changed has a value to read.
+func wantChanged(t *testing.T, ledger *bans.Ledger, want bool) {
+	t.Helper()
+
+	got := false
+
+	select {
+	case <-ledger.Changed():
+		got = true
+	default:
+	}
+
+	if got != want {
+		t.Errorf("Changed has a value: %t, want %t", got, want)
+	}
+}