Ban the netblock of a client that breaks a rate limit, in memory (closes #18)

A request over a rate limit is refused with SWWAF_BAN_RESPONSE and bans
the client's netblock: an hour at first, three times the last ban when
broken again within a day of its end, permanent past seven days. The
ban ledger in internal/bans is checked after the static lists and
before the lookup, and the requests it refuses are not counted. A ban
resets the client's counters and carries notes holding the request
that broke the limit, as SPEC.md now says. At most SWWAF_MAX_BANS are
held. SWWAF_BAN_RESPONSE also answers SWWAF_DENY_NETS and the country
lists.

Judgement call: the six ban settings cannot be off.
Judgement call: a permanent ban's ban_expires is "permanent".

Model: opus-5-5

internal/bans/bans.go

@@ -0,0 +1,255 @@
+// 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.
+package bans
+
+import (
+	"net/netip"
+	"slices"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/hashicorp/golang-lru/v2/simplelru"
+)
+
+// repeatFactor is how many times as long as the netblock's last ban a ban
+// for a limit broken again within the repeat window lasts.
+const repeatFactor = 3
+
+// maxTextBytes is how much of each text in a ban's notes is kept.
+const maxTextBytes = 256
+
+// Rules are how long a ban for a broken limit lasts, and how many bans
+// are held.
+type Rules struct {
+	// LimitBanDuration is how long a first ban lasts.
+	LimitBanDuration time.Duration
+	// LimitBanRepeatWindow is how soon after the netblock's last ban
+	// ended a broken limit counts as a repeat, which bans for
+	// repeatFactor times as long as that ban.
+	LimitBanRepeatWindow time.Duration
+	// MaxBanDuration is the longest ban; a ban that would be longer is
+	// permanent instead.
+	MaxBanDuration time.Duration
+	// MaxBans is the most bans held, at least one. Past it, the earliest
+	// ban of the netblock that has gone longest without a request is
+	// dropped.
+	MaxBans int
+}
+
+// Ban is a ban on a netblock for a broken limit, the only kind of ban
+// smallwebwaf makes so far.
+type Ban struct {
+	Netblock netip.Prefix
+	Start    time.Time
+	// Expires is when the ban ends, zero for a permanent ban.
+	Expires time.Time
+	Notes   Notes
+}
+
+// Permanent reports whether the ban never runs out.
+func (b Ban) Permanent() bool {
+	return b.Expires.IsZero()
+}
+
+// ActiveAt reports whether the ban refuses requests at now.
+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.
+type Notes struct {
+	// Country is the client's country, when it was looked up.
+	Country string
+	// 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
+	// Request is the request that broke the limit.
+	Request Request
+	// Refused is how many requests the ban has refused so far.
+	Refused int64
+	// EarlierBans is how many bans the netblock had before this one.
+	EarlierBans int
+}
+
+// Request is a request in a ban's notes. Each text is cut to 256 bytes.
+type Request struct {
+	Time   time.Time
+	Method string
+	Host   string
+	// Path is the path with its query string.
+	Path string
+	// Status is what the client was sent, 0 if nothing was.
+	Status    int
+	UserAgent string
+}
+
+// Ledger holds the bans. It is safe for concurrent use.
+type Ledger struct {
+	rules Rules
+
+	mu sync.Mutex
+	// netblocks holds each banned netblock's bans, oldest first. Each
+	// request from a netblock makes it the most recently seen.
+	netblocks *simplelru.LRU[netip.Prefix, *[]Ban]
+	// held is how many bans netblocks holds, at most rules.MaxBans.
+	held int
+}
+
+// New returns a Ledger with no ban yet.
+func New(rules Rules) *Ledger {
+	// Every netblock held has a ban, so there are never more netblocks
+	// than rules.MaxBans, and the LRU never drops one itself.
+	netblocks, err := simplelru.NewLRU[netip.Prefix, *[]Ban](rules.MaxBans, nil)
+	if err != nil {
+		panic(err) // NewLRU fails only for a size below one
+	}
+
+	return &Ledger{rules: rules, netblocks: netblocks}
+}
+
+// Check is called for each request from netblock, at now. It reports
+// whether a ban on netblock is active, and returns that ban, with the
+// request counted among those it refused.
+func (l *Ledger) Check(netblock netip.Prefix, now time.Time) (Ban, bool) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	bans, found := l.netblocks.Get(netblock)
+	if !found {
+		return Ban{}, false
+	}
+
+	// A ban is made only once the one before has ended, so only the last
+	// can be active.
+	last := &(*bans)[len(*bans)-1]
+	if !last.ActiveAt(now) {
+		return Ban{}, false
+	}
+
+	last.Notes.Refused++
+
+	return *last, true
+}
+
+// BanForLimit bans netblock at now for a broken limit, with notes, and
+// returns the ban. A first ban lasts LimitBanDuration. A ban made within
+// LimitBanRepeatWindow after the netblock's last ban ended lasts
+// repeatFactor times as long as that one. A ban that would be longer
+// than MaxBanDuration is permanent instead. If a ban on netblock is still
+// active, as when two of its requests break a limit at once, that ban is
+// returned and no other is made. The ledger fills in the notes' Refused
+// and EarlierBans itself.
+func (l *Ledger) BanForLimit(netblock netip.Prefix, now time.Time, notes Notes) Ban {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	var last *Ban
+
+	bans, found := l.netblocks.Get(netblock)
+	if found {
+		last = &(*bans)[len(*bans)-1]
+		if last.ActiveAt(now) {
+			return *last
+		}
+
+		notes.EarlierBans = last.Notes.EarlierBans + 1
+	}
+
+	notes.Request = notes.Request.cut()
+	ban := Ban{
+		Netblock: netblock,
+		Start:    now,
+		Expires:  l.expiry(last, now),
+		Notes:    notes,
+	}
+
+	if l.held == l.rules.MaxBans {
+		l.dropOne()
+	}
+
+	// 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
+}
+
+// Bans returns the bans held on netblock, oldest first. It is not a
+// request from netblock, and leaves when it was last seen unchanged.
+func (l *Ledger) Bans(netblock netip.Prefix) []Ban {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	bans, found := l.netblocks.Peek(netblock)
+	if !found {
+		return nil
+	}
+
+	return slices.Clone(*bans)
+}
+
+// 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.
+func (l *Ledger) expiry(last *Ban, now time.Time) time.Time {
+	length := l.rules.LimitBanDuration
+
+	if last != nil && now.Sub(last.Expires) <= l.rules.LimitBanRepeatWindow {
+		lastLength := last.Expires.Sub(last.Start)
+		// This is repeatFactor * lastLength > MaxBanDuration, written so
+		// that it cannot overflow.
+		if lastLength > l.rules.MaxBanDuration/repeatFactor {
+			return time.Time{}
+		}
+
+		length = repeatFactor * lastLength
+	}
+
+	if length > l.rules.MaxBanDuration {
+		return time.Time{}
+	}
+
+	return now.Add(length)
+}
+
+// dropOne drops the earliest ban of the netblock that has gone longest
+// without a request, and the netblock with it if that was its only ban.
+func (l *Ledger) dropOne() {
+	netblock, bans, _ := l.netblocks.GetOldest()
+	if len(*bans) == 1 {
+		l.netblocks.Remove(netblock)
+	} else {
+		*bans = slices.Delete(*bans, 0, 1)
+	}
+
+	l.held--
+}
+
+// cut returns r with each text cut to maxTextBytes and copied, so that
+// the notes do not keep the rest of the request in memory.
+func (r Request) cut() Request {
+	r.Method = cutText(r.Method)
+	r.Host = cutText(r.Host)
+	r.Path = cutText(r.Path)
+	r.UserAgent = cutText(r.UserAgent)
+
+	return r
+}
+
+// cutText returns a copy of the first maxTextBytes of text.
+func cutText(text string) string {
+	return strings.Clone(text[:min(len(text), maxTextBytes)])
+}