servewaf: each decision heuristic is its own module (closes #195)

Each check servewaf runs on a request is a type in its own file behind
one interface, heuristic, and is registered in one of four ordered lists
in heuristics.go. Order and behaviour are unchanged.

Every refusal now logs heuristic, the name of the heuristic that made
it, and heuristic_figures, the figures it acted on. A ban by
refusal_limit or byte_limits after the answer logs report_heuristic and
report_heuristic_figures instead, so a line can name both. All four are
in docs/request-log.md, and SPEC.md names each heuristic at its step.

Model: opus-5-5

SPEC.md

@@ -125,7 +125,7 @@ produces a final answer ends the checks. Step 15 runs for each request
 limits apply to the whole exchange. Each step names the section that holds its
 rules. Each check is a heuristic. Its name, in parentheses below, is the value
 of the request log's `heuristic` field. `refusal_limit` and `byte_limits` give
-theirs in `after_answer_heuristic` instead.
+theirs in `report_heuristic` instead.
 
 1. `GET /_smallwebwaf/healthz` is answered at once by `rproxy`, before any
    check, so a health checker never needs an exemption and is never refused.

docs/request-log.md

@@ -127,11 +127,10 @@ Every one of these lines has:
     - `core_rule_set`: `score`, and `threshold`, `SWWAF_WAF_ANOMALY_THRESHOLD`;
     - `refusal_limit`: `window`, `count` and `limit`, of the error burst;
     - `byte_limits`: `window`, `count` and `limit`, the count in bytes.
-- `after_answer_heuristic`: the heuristic that banned the client after
+- `report_heuristic`: the heuristic that banned the client after `servewaf`
-  `servewaf` answered the request, in `observe` mode too: `refusal_limit` or
+  answered the request, in `observe` mode too: `refusal_limit` or `byte_limits`.
-  `byte_limits`.
+- `report_heuristic_figures`: an object of the figures that heuristic acted on,
-- `after_answer_heuristic_figures`: an object of the figures that heuristic
+  as listed above.
-  acted on, as listed above.
 
     `byte_limits` bans when the report comes, so only the `report` line names
     it.

internal/requestlog/requestlog.go

@@ -136,11 +136,10 @@ type Line struct {
 	// name.
 	Heuristic        string         `json:"heuristic,omitempty"`
 	HeuristicFigures map[string]any `json:"heuristic_figures,omitempty"`
-	// AfterAnswerHeuristic and AfterAnswerHeuristicFigures are the same for
+	// ReportHeuristic and ReportHeuristicFigures are the same for the
-	// the heuristic that banned the client after servewaf answered the
+	// heuristic that banned the client after servewaf answered the request.
-	// request.
+	ReportHeuristic        string         `json:"report_heuristic,omitempty"`
-	AfterAnswerHeuristic        string         `json:"after_answer_heuristic,omitempty"`
+	ReportHeuristicFigures map[string]any `json:"report_heuristic_figures,omitempty"`
-	AfterAnswerHeuristicFigures map[string]any `json:"after_answer_heuristic_figures,omitempty"` //nolint:lll // a struct tag cannot be split
 	// LimitPercent and LimitPercentSetting are, for a request the rate
 	// limits counted whose client a biased threshold gives a percentage of
 	// the rate limits below 100, that percentage and the setting that gave

internal/servewaf/bytelimits_test.go

@@ -104,12 +104,12 @@ func TestByteLimitBanNamesItsHeuristicWindowCountAndLimit(t *testing.T) {
 	s, _ := startWithAnswers(t, map[string]string{bytesLimitPerMinute: byteLimit})
 
 	line, _ := s.download()
-	wantAfterAnswerHeuristic(t, line, "", "null")
+	wantReportHeuristic(t, line, "", "null")
 
 	// Two answers of 70 bytes are over the limit of 99.
 	line, _ = s.download()
 	wantHeuristic(t, line, "", "null")
-	wantAfterAnswerHeuristic(t, line, "byte_limits",
+	wantReportHeuristic(t, line, "byte_limits",
 		`{"window": "minute", "count": 140, "limit": 99}`)
 }
 

internal/servewaf/headerlimits.go

@@ -25,7 +25,7 @@ func (headerLimits) name() string { return "header_limits" }
 
 func (headerLimits) check(_ context.Context, rq *request, _ time.Time) *verdict {
 	fields, cookies := rq.headerCounts()
-	if !overHeaderLimits(fields, cookies) {
+	if fields <= maxHeaderFields && cookies <= maxCookies {
 		return nil
 	}
 
@@ -38,10 +38,12 @@ func (headerLimits) check(_ context.Context, rq *request, _ time.Time) *verdict
 	}
 }
 
-// overHeaderLimits reports whether a request with these counts of header fields
+// overHeaderLimits reports whether the request is over the header limits: it
-// and cookies, as headerCounts counts them, is over the header limits: it has
+// has more than maxHeaderFields fields or more than maxCookies cookies, as
-// more than maxHeaderFields fields or more than maxCookies cookies.
+// headerCounts counts them.
-func overHeaderLimits(fields, cookies int) bool {
+func (rq *request) overHeaderLimits() bool {
+	fields, cookies := rq.headerCounts()
+
 	return fields > maxHeaderFields || cookies > maxCookies
 }
 

internal/servewaf/heuristics.go

@@ -104,15 +104,15 @@ func (rq *request) runHeuristics(
 }
 
 // runBanningHeuristics runs list, afterAnswer or onReport, on the request at
-// the time it is called. The log line's after_answer_heuristic and
+// the time it is called. The log line's report_heuristic and
-// after_answer_heuristic_figures name the heuristic that gave a verdict, and
+// report_heuristic_figures name the heuristic that gave a verdict, and give its
-// give its figures, so that heuristic and heuristic_figures still name the one
+// figures, so that heuristic and heuristic_figures still name the one that
-// that refused the request. ctx is the request's own context.
+// refused the request. ctx is the request's own context.
 func (rq *request) runBanningHeuristics(ctx context.Context, list []heuristic) {
 	name, v := rq.firstVerdict(ctx, list, rq.h.now())
 	if v != nil {
-		rq.line.AfterAnswerHeuristic = name
+		rq.line.ReportHeuristic = name
-		rq.line.AfterAnswerHeuristicFigures = v.figures
+		rq.line.ReportHeuristicFigures = v.figures
 	}
 }
 

internal/servewaf/refusallimit_test.go

@@ -115,13 +115,13 @@ func TestRefusalLimitBanNamesItsHeuristicWindowCountAndLimit(t *testing.T) {
 
 	line := blockRule.send(s, client)
 	wantHeuristic(t, line, "rule_files", ruleFigures)
-	wantAfterAnswerHeuristic(t, line, "", "null")
+	wantReportHeuristic(t, line, "", "null")
 
 	// The second refusal is the request refusal_limit bans for, and the line
 	// names both.
 	line = blockRule.send(s, client)
 	wantHeuristic(t, line, "rule_files", ruleFigures)
-	wantAfterAnswerHeuristic(t, line, "refusal_limit",
+	wantReportHeuristic(t, line, "refusal_limit",
 		`{"window": "minute", "count": 2, "limit": 1}`)
 }
 

internal/servewaf/requestlog_test.go

@@ -286,17 +286,16 @@ func wantHeuristic(t *testing.T, line logLine, heuristic, figures string) {
 	}
 }
 
-// wantAfterAnswerHeuristic checks after_answer_heuristic and
+// wantReportHeuristic checks report_heuristic and report_heuristic_figures as
-// after_answer_heuristic_figures as wantHeuristic checks heuristic and
+// wantHeuristic checks heuristic and heuristic_figures.
-// heuristic_figures.
+func wantReportHeuristic(t *testing.T, line logLine, heuristic, figures string) {
-func wantAfterAnswerHeuristic(t *testing.T, line logLine, heuristic, figures string) {
 	t.Helper()
 
-	if line.AfterAnswerHeuristic != heuristic ||
+	if line.ReportHeuristic != heuristic ||
-		!reflect.DeepEqual(line.AfterAnswerHeuristicFigures, decodeFigures(t, figures)) {
+		!reflect.DeepEqual(line.ReportHeuristicFigures, decodeFigures(t, figures)) {
-		t.Errorf("log line has after_answer_heuristic %q with "+
+		t.Errorf("log line has report_heuristic %q with report_heuristic_figures %v, "+
-			"after_answer_heuristic_figures %v, want %q with %s",
+			"want %q with %s",
-			line.AfterAnswerHeuristic, line.AfterAnswerHeuristicFigures, heuristic, figures)
+			line.ReportHeuristic, line.ReportHeuristicFigures, heuristic, figures)
 	}
 }
 

internal/servewaf/servewaf.go

@@ -152,7 +152,7 @@ func (rq *request) refusedWhateverTheAnswer(now time.Time) bool {
 
 	_, decided := rq.crowdSecDecisionInForce(now)
 
-	return decided || overHeaderLimits(rq.headerCounts()) ||
+	return decided || rq.overHeaderLimits() ||
 		rq.refusedByBlocklists(rq.h.lists.ListedBy(rq.client)) ||
 		rq.overAWholeRateLimit(now)
 }