From the architecture review, "The decision pipeline: the heuristics", under "A heuristic declares nothing it needs": #283 (comment). Approved for building: #283 (comment). The code was read at 809d266 on next, where discriminator is now waf. Line numbers are that commit's.
This is the first of three steps the review orders inside the heuristics. The other two, typed facts on decision and the status on the verdict, build on it.
What is there
All sixteen heuristics in internal/waf are empty structs: type denyNets struct{}.
check(ctx, rq *request, now) is handed the whole request. Through rq.h it reaches the whole handler: every part waf is given, and all of config.WAF.
The six lists in internal/waf/heuristics.go are functions that build their slice again for every request: beforeLookup(), afterLookup(), besideLookup(), afterBesideLookup(), afterAnswer(), onReport().
findBesideLookup and runBesideLookup (internal/waf/besidelookup.go) make a heuristic only to read its name: trapPaths{}.name().
Why it matters
What a heuristic reads is found only by reading its body. The comment at the top of each file names its settings, and nothing holds that comment to the code.
None can be built with test values and called. Every heuristic's test starts a whole waf from a map of settings, sends requests over HTTP and reads the log line.
A heuristic with a new collaborator needs a new field on handler: a change outside its file. The issue that ordered modular heuristics (#195) asked for one file and one line in one place.
What changes
Each heuristic is a struct that holds its own settings and collaborators.
newHandler builds the six lists once, and the handler keeps them. That one place then shows which settings and parts each heuristic uses.
typedenyNetsstruct{netblocks[]netip.Prefix// SWW_WAF_DENY_NETS}func(ddenyNets)check(_context.Context,rq*request,_time.Time)*verdict{for_,netblock:=ranged.netblocks{// ...// in newHandler, onceh.beforeLookup=[]heuristic{headerLimits{},tagLists{lists:params.Lists},routeWatchTags{routeWatch:params.RouteWatch},denyNets{netblocks:cfg.DenyNets},activeBan{ledger:params.Ledger,observe:cfg.Observe},}
The review does not say what becomes of the code several heuristics share: banForLimit, banForAttack, alertBan, noteHit, limitPercentages, countedByRateLimits, clientGroup. It stays shared. It takes what it needs as arguments, or lives on a small struct that the heuristics using it hold. A heuristic never reaches the handler for it.
The work beside the lookup (findBesideLookup) uses the same three built heuristics as the list, in place of making new ones for their names.
One test builds one heuristic by itself with test values, such as denyNets, gives it a request with a client address, and checks the verdict.
The comment at the top of heuristics.go on adding a heuristic says where its settings and parts are handed to it.
What stays
The heuristic interface, the order of every list, and the rule that the first verdict ends the checks.
The request's own steps that are no heuristic keep using the handler: startLookUp, allow, deny, finish, addToHistory, countAnomalies.
The tests that drive a whole waf.
Done when
no heuristic is an empty struct unless it needs nothing, and no check reads rq.h;
the lists are built once, in newHandler;
behaviour is unchanged: every existing test passes with no assertion changed;
make check passes;
the PR body lists every new type and field name. Each says what the thing is to a reader of that one file, the standard of the symbol names audit (#213).
If this is more than one PR can carry, say so on this issue instead of starting.
Model: fable-5-2
From the architecture review, "The decision pipeline: the heuristics", under "A heuristic declares nothing it needs": https://git.eeqj.de/sneak/smallwebwaf/issues/283#issuecomment-173833. Approved for building: https://git.eeqj.de/sneak/smallwebwaf/issues/283#issuecomment-183550. The code was read at `809d266` on `next`, where `discriminator` is now `waf`. Line numbers are that commit's.
This is the first of three steps the review orders inside the heuristics. The other two, typed facts on `decision` and the status on the verdict, build on it.
### What is there
- All sixteen heuristics in `internal/waf` are empty structs: `type denyNets struct{}`.
- `check(ctx, rq *request, now)` is handed the whole request. Through `rq.h` it reaches the whole `handler`: every part `waf` is given, and all of `config.WAF`.
- The six lists in `internal/waf/heuristics.go` are functions that build their slice again for every request: `beforeLookup()`, `afterLookup()`, `besideLookup()`, `afterBesideLookup()`, `afterAnswer()`, `onReport()`.
- `findBesideLookup` and `runBesideLookup` (`internal/waf/besidelookup.go`) make a heuristic only to read its name: `trapPaths{}.name()`.
### Why it matters
- What a heuristic reads is found only by reading its body. The comment at the top of each file names its settings, and nothing holds that comment to the code.
- None can be built with test values and called. Every heuristic's test starts a whole `waf` from a map of settings, sends requests over HTTP and reads the log line.
- A heuristic with a new collaborator needs a new field on `handler`: a change outside its file. The issue that ordered modular heuristics (https://git.eeqj.de/sneak/smallwebwaf/issues/195) asked for one file and one line in one place.
### What changes
- Each heuristic is a struct that holds its own settings and collaborators.
- `newHandler` builds the six lists once, and the handler keeps them. That one place then shows which settings and parts each heuristic uses.
- A heuristic's `check` no longer reads `rq.h`.
Before (`denynets.go`, `heuristics.go`):
```go
type denyNets struct{}
func (denyNets) check(_ context.Context, rq *request, _ time.Time) *verdict {
for _, netblock := range rq.h.config.DenyNets {
// ...
func beforeLookup() []heuristic {
return []heuristic{headerLimits{}, tagLists{}, routeWatchTags{}, denyNets{}, activeBan{}}
}
```
After (the field names are placeholders):
```go
type denyNets struct {
netblocks []netip.Prefix // SWW_WAF_DENY_NETS
}
func (d denyNets) check(_ context.Context, rq *request, _ time.Time) *verdict {
for _, netblock := range d.netblocks {
// ...
// in newHandler, once
h.beforeLookup = []heuristic{
headerLimits{},
tagLists{lists: params.Lists},
routeWatchTags{routeWatch: params.RouteWatch},
denyNets{netblocks: cfg.DenyNets},
activeBan{ledger: params.Ledger, observe: cfg.Observe},
}
```
- The review does not say what becomes of the code several heuristics share: `banForLimit`, `banForAttack`, `alertBan`, `noteHit`, `limitPercentages`, `countedByRateLimits`, `clientGroup`. It stays shared. It takes what it needs as arguments, or lives on a small struct that the heuristics using it hold. A heuristic never reaches the handler for it.
- The work beside the lookup (`findBesideLookup`) uses the same three built heuristics as the list, in place of making new ones for their names.
- One test builds one heuristic by itself with test values, such as `denyNets`, gives it a request with a client address, and checks the verdict.
- The comment at the top of `heuristics.go` on adding a heuristic says where its settings and parts are handed to it.
### What stays
- The `heuristic` interface, the order of every list, and the rule that the first verdict ends the checks.
- The request's own steps that are no heuristic keep using the handler: `startLookUp`, `allow`, `deny`, `finish`, `addToHistory`, `countAnomalies`.
- The tests that drive a whole `waf`.
### Done when
- no heuristic is an empty struct unless it needs nothing, and no `check` reads `rq.h`;
- the lists are built once, in `newHandler`;
- behaviour is unchanged: every existing test passes with no assertion changed;
- `make check` passes;
- the PR body lists every new type and field name. Each says what the thing is to a reader of that one file, the standard of the symbol names audit (https://git.eeqj.de/sneak/smallwebwaf/issues/213).
If this is more than one PR can carry, say so on this issue instead of starting.
Model: fable-5-2
clawbot
self-assigned this 2026-11-19 17:13:13 +01:00
Every heuristic now holds its own settings and parts, built once in newHandler. Shared code lives on three small structs the heuristics hold: banMaker, reputationHitNoter and biasedThresholds. A standalone denyNets test builds the heuristic and checks it with no handler.
Rule suppressed: //nolint:funlen on newHandler, following the existing config and metrics precedent.
Unrelated flake: in one make check run, with host load near 280, TestCoreRuleSetRefusesAttacksInBlockModeAndOnlyLogsThemInDetectMode/SQL_injection_after_1000_query_parameters hit a read timeout under -race. The next runs passed.
Model: opus-5-5
PR: https://git.eeqj.de/sneak/smallwebwaf/pulls/462 (branch `issue-441-heuristic-structs`).
Every heuristic now holds its own settings and parts, built once in `newHandler`. Shared code lives on three small structs the heuristics hold: `banMaker`, `reputationHitNoter` and `biasedThresholds`. A standalone `denyNets` test builds the heuristic and checks it with no handler.
- Rule suppressed: `//nolint:funlen` on `newHandler`, following the existing `config` and `metrics` precedent.
- Unrelated flake: in one `make check` run, with host load near 280, `TestCoreRuleSetRefusesAttacksInBlockModeAndOnlyLogsThemInDetectMode/SQL_injection_after_1000_query_parameters` hit a read timeout under `-race`. The next runs passed.
Model: opus-5-5
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
From the architecture review, "The decision pipeline: the heuristics", under "A heuristic declares nothing it needs": #283 (comment). Approved for building: #283 (comment). The code was read at
809d266onnext, wherediscriminatoris nowwaf. Line numbers are that commit's.This is the first of three steps the review orders inside the heuristics. The other two, typed facts on
decisionand the status on the verdict, build on it.What is there
internal/wafare empty structs:type denyNets struct{}.check(ctx, rq *request, now)is handed the whole request. Throughrq.hit reaches the wholehandler: every partwafis given, and all ofconfig.WAF.internal/waf/heuristics.goare functions that build their slice again for every request:beforeLookup(),afterLookup(),besideLookup(),afterBesideLookup(),afterAnswer(),onReport().findBesideLookupandrunBesideLookup(internal/waf/besidelookup.go) make a heuristic only to read its name:trapPaths{}.name().Why it matters
waffrom a map of settings, sends requests over HTTP and reads the log line.handler: a change outside its file. The issue that ordered modular heuristics (#195) asked for one file and one line in one place.What changes
newHandlerbuilds the six lists once, and the handler keeps them. That one place then shows which settings and parts each heuristic uses.checkno longer readsrq.h.Before (
denynets.go,heuristics.go):After (the field names are placeholders):
banForLimit,banForAttack,alertBan,noteHit,limitPercentages,countedByRateLimits,clientGroup. It stays shared. It takes what it needs as arguments, or lives on a small struct that the heuristics using it hold. A heuristic never reaches the handler for it.findBesideLookup) uses the same three built heuristics as the list, in place of making new ones for their names.denyNets, gives it a request with a client address, and checks the verdict.heuristics.goon adding a heuristic says where its settings and parts are handed to it.What stays
heuristicinterface, the order of every list, and the rule that the first verdict ends the checks.startLookUp,allow,deny,finish,addToHistory,countAnomalies.waf.Done when
checkreadsrq.h;newHandler;make checkpasses;If this is more than one PR can carry, say so on this issue instead of starting.
Model: fable-5-2
PR: #462 (branch
issue-441-heuristic-structs).Every heuristic now holds its own settings and parts, built once in
newHandler. Shared code lives on three small structs the heuristics hold:banMaker,reputationHitNoterandbiasedThresholds. A standalonedenyNetstest builds the heuristic and checks it with no handler.//nolint:funlenonnewHandler, following the existingconfigandmetricsprecedent.make checkrun, with host load near 280,TestCoreRuleSetRefusesAttacksInBlockModeAndOnlyLogsThemInDetectMode/SQL_injection_after_1000_query_parametershit a read timeout under-race. The next runs passed.Model: opus-5-5