metrics: one Params with a small interface per part, in place of seven Add… calls #438

Open
opened 2026-11-19 17:13:13 +01:00 by clawbot · 1 comment
Collaborator

From the architecture review, "The smaller packages", under "metrics depends on what it measures": #283 (comment). Approved for building, with the recommended option, "interfaces in metrics": #283 (comment). The code was read at 809d266 on next. Line numbers are that commit's.

The review put one thing first: the parts built in one place. The fx wiring did that, so nothing blocks this.

What is there

  • metrics.New(busiestCount int, instanceName string) takes its arguments by position (internal/metrics/metrics.go:69).
  • Seven Add… methods then connect the parts, each by its concrete type: AddBansAndClients(*bans.Ledger, *ratelimit.Limiter, …), AddRules(*rules.Files), AddRemoteLog(*remotelog.Sender), AddReputation(*reputation.Lists, *reputation.DNSBL), AddAbuseIPDB(*reputation.AbuseIPDB), AddAlerts(*alerts.Queue), AddLookupFile(…).
  • newMetrics in internal/sww/waf.go:343 calls them in an order only the comments set: AddRules "once, before RuleMatched", AddAbuseIPDB "once, after AddReputation". Until its Add… call, a part's metric fields (ruleMatches, reputationHits) are nil.
  • metrics imports eight internal packages, most of them for a part's type.
  • metrics has no test file. Every other package with production code has one.

Why it matters

  • A new part that has numbers adds an import to metrics, an Add… method, and a call at the correct place in another file. A call out of order is a nil pointer when the daemon is up.
  • Nothing can build metrics with stand-in parts, so nothing tests it alone.

What changes

  • metrics declares, beside each group of metrics, a small interface of the two or three methods it reads from that part.
  • All parts are handed in at once through metrics.Params, and New(params) registers everything. There is no call order and no nil metric field. The seven Add… methods go.
  • metrics drops each import it holds only for a part's concrete type.

The sketch from the review; the names are placeholders:

// banCounts is what the metrics read from the ban ledger.
type banCounts interface {
	Made(cause string) int
	Count(now time.Time) (active, permanent int)
}

type Params struct {
	BusiestCount int
	InstanceName string
	Now          func() time.Time
	Bans         banCounts
	Clients      clientCounts
	// one field per part; nil for a part that is off
}

func New(params Params) *Metrics
  • A trap for the fields of parts that can be off (the lookup database, the remote log sender, AbuseIPDB without a key): a nil *lookup.File put in an interface field is not a nil interface. newMetrics sets such a field only while the part is on.
  • One test in internal/metrics builds the metrics with stand-in parts and reads one metric of each from the handler.

What stays

  • Every metric keeps its name, help text, labels and values, as docs/metrics.md lists them.
  • A part that is off still adds no metric of its own.
  • The three public counters GeoJS's callbacks increment (GeoJSRequests, GeoJSFailures, RequestsWithoutGeoJSAnswer) stay as they are. The review wanted GeoJS to expose them as methods; internal/geojs has since been built to report through callbacks instead.
  • The state file metrics (StateFileWritten and its two neighbours) stay until the SQLite state store (#217) removes internal/state.
  • The event methods (RequestEnded, LimitHit, Offences and the rest) keep the types they take.

Done when

  • metrics.New takes one Params, and metrics has no Add… method;
  • metrics imports no internal package only for a part's type;
  • behaviour is unchanged: every existing test passes with no assertion changed;
  • make check passes;
  • the PR body lists every new interface 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 smaller packages", under "`metrics` depends on what it measures": https://git.eeqj.de/sneak/smallwebwaf/issues/283#issuecomment-173847. Approved for building, with the recommended option, "interfaces in `metrics`": https://git.eeqj.de/sneak/smallwebwaf/issues/283#issuecomment-183550. The code was read at `809d266` on `next`. Line numbers are that commit's. The review put one thing first: the parts built in one place. The fx wiring did that, so nothing blocks this. ### What is there - `metrics.New(busiestCount int, instanceName string)` takes its arguments by position (`internal/metrics/metrics.go:69`). - Seven `Add…` methods then connect the parts, each by its concrete type: `AddBansAndClients(*bans.Ledger, *ratelimit.Limiter, …)`, `AddRules(*rules.Files)`, `AddRemoteLog(*remotelog.Sender)`, `AddReputation(*reputation.Lists, *reputation.DNSBL)`, `AddAbuseIPDB(*reputation.AbuseIPDB)`, `AddAlerts(*alerts.Queue)`, `AddLookupFile(…)`. - `newMetrics` in `internal/sww/waf.go:343` calls them in an order only the comments set: `AddRules` "once, before RuleMatched", `AddAbuseIPDB` "once, after AddReputation". Until its `Add…` call, a part's metric fields (`ruleMatches`, `reputationHits`) are nil. - `metrics` imports eight internal packages, most of them for a part's type. - `metrics` has no test file. Every other package with production code has one. ### Why it matters - A new part that has numbers adds an import to `metrics`, an `Add…` method, and a call at the correct place in another file. A call out of order is a nil pointer when the daemon is up. - Nothing can build `metrics` with stand-in parts, so nothing tests it alone. ### What changes - `metrics` declares, beside each group of metrics, a small interface of the two or three methods it reads from that part. - All parts are handed in at once through `metrics.Params`, and `New(params)` registers everything. There is no call order and no nil metric field. The seven `Add…` methods go. - `metrics` drops each import it holds only for a part's concrete type. The sketch from the review; the names are placeholders: ```go // banCounts is what the metrics read from the ban ledger. type banCounts interface { Made(cause string) int Count(now time.Time) (active, permanent int) } type Params struct { BusiestCount int InstanceName string Now func() time.Time Bans banCounts Clients clientCounts // one field per part; nil for a part that is off } func New(params Params) *Metrics ``` - A trap for the fields of parts that can be off (the lookup database, the remote log sender, AbuseIPDB without a key): a nil `*lookup.File` put in an interface field is not a nil interface. `newMetrics` sets such a field only while the part is on. - One test in `internal/metrics` builds the metrics with stand-in parts and reads one metric of each from the handler. ### What stays - Every metric keeps its name, help text, labels and values, as `docs/metrics.md` lists them. - A part that is off still adds no metric of its own. - The three public counters GeoJS's callbacks increment (`GeoJSRequests`, `GeoJSFailures`, `RequestsWithoutGeoJSAnswer`) stay as they are. The review wanted GeoJS to expose them as methods; `internal/geojs` has since been built to report through callbacks instead. - The state file metrics (`StateFileWritten` and its two neighbours) stay until the SQLite state store (https://git.eeqj.de/sneak/smallwebwaf/issues/217) removes `internal/state`. - The event methods (`RequestEnded`, `LimitHit`, `Offences` and the rest) keep the types they take. ### Done when - `metrics.New` takes one `Params`, and `metrics` has no `Add…` method; - `metrics` imports no internal package only for a part's type; - behaviour is unchanged: every existing test passes with no assertion changed; - `make check` passes; - the PR body lists every new interface 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
Author
Collaborator

PR: #456, branch issue-438-metrics-params.

metrics.New takes one Params holding each part behind a small interface. The Add… methods are gone, and metrics no longer imports remotelog or rules. The PR body lists every new interface and field.

Judgement call: the table of clients and the rule files share one interface, sized (Len), because the linter refuses two identical interfaces.

Model: opus-5-5

PR: https://git.eeqj.de/sneak/smallwebwaf/pulls/456, branch `issue-438-metrics-params`. `metrics.New` takes one `Params` holding each part behind a small interface. The `Add…` methods are gone, and `metrics` no longer imports `remotelog` or `rules`. The PR body lists every new interface and field. Judgement call: the table of clients and the rule files share one interface, `sized` (`Len`), because the linter refuses two identical interfaces. Model: opus-5-5
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/smallwebwaf#438