app-policy/checker: cache pending-policy verdicts per policy store generation

[dimitri-nicolo]

Description

Third of the stack for CORE-13316, stacked on #13896 (which is on #13895); review the last commit only.

A verdict is a function of the endpoint's applicable rules, the store's IP sets and the flow. For a flow with no L7 attributes — every flow the collector evaluates — the criteria in match() reduce to protocol, source and destination address, destination port and, only where a rule looks at it, source port; identity and HTTP criteria match such a flow whatever the rule says. So a store can remember the verdict for that key, and a flow that repeats an earlier flow's endpoints on a new source port (a client reconnecting, which is most of what a node sees) is answered without walking the policy set. On a large set that is the difference between a millisecond and a map lookup.

What changes

• policystore.PolicyStore gains a Generation that ProcessUpdate moves on every update but InSync, and an optional Verdicts *VerdictCache bound to it. Entries are valid for one generation; the cache starts over when the store moves on, so a cached verdict never outlives the policies, IP sets or endpoints it was computed from. Coarse (an IP set delta anywhere empties it) and safe; finer invalidation is the sweep-invalidation work later in the epic. The cache is bounded and starts over when full rather than keeping an LRU list.
• checker.Evaluate consults the cache when the store has one. Whether the source port is part of the key is decided once per endpoint, scope, direction and generation by walking the endpoint's applicable rules (SrcPorts, NotSrcPorts, named source ports). Failed evaluations are not cached. Flows carrying identity or HTTP attributes (Dikastes requests) and flows with a nil address bypass it. A cached trace is shared between callers; the collector already copies it.
• The collector gets the cache through policystore.WithVerdictCache, so every store its manager creates — including on reconnect — carries one, and reports felix_collector_policy_eval_cache_{hits,misses,resets,evictions}_total.
• FlowLogsPolicyEvaluationCacheSize sizes it (default 65536, 0 disables). It is a config-file / environment-variable parameter with no FelixConfiguration field yet, so that it picks to release branches without an API change (the epic's backport-first rule); the API field can follow on master. Docs regenerated with calico-felix-docgen.

Numbers — BenchmarkEvaluateVerdictCache, composite reference set, egress direction (18,662 rules), sampler flow model (10% of flows miss every rule, matching flows aimed uniformly at the walk), -benchtime 100x -cpu 1, one laptop core:

Case	ns/op	hit ratio
Uncached, 50% repeats	1,002,986	–
Cached, 0% deliberate repeats	723,532	0.11
Cached, 50% repeats	308,299	0.62
Cached, 90% repeats	78,505	0.92

The real hit ratio depends on the node's traffic; the collector's hits/misses counters report it.

Relation to #13267 / its rebase. Both change Evaluate; the cache wrapper is a dozen lines in front of the walk, so whichever lands second rebases trivially. The cache also helps the compiled engine: a hit skips the walk entirely.

Testing

go test ./app-policy/policystore/ ./app-policy/checker/      # ok, ok (12s: differential corpus + named cases through a cached store, twice, vs uncached; invalidation via ProcessUpdate; source-port keying; L7/nil bypass)
go test ./felix/collector/                                    # ok (wiring test + full suite)
go test ./felix/config/                                       # ok
go test ./app-policy/checker/ -run '^$' -bench BenchmarkEvaluateVerdictCache -benchmem -benchtime 100x -cpu 1
cd felix && go run ./cmd/calico-felix-docgen --format=json > docs/config-params.json && go run ./cmd/calico-felix-docgen --format=md > docs/config-params.md

Release note:

Felix: the flow log collector now caches pending-policy verdicts so that flows repeating an earlier flow's endpoints do not re-walk large policy sets. FlowLogsPolicyEvaluationCacheSize (config file / environment variable) sizes the cache; 0 disables it.

AI assistance: Written with Claude Code (Claude Fable 5.1); the author reviewed the diff and ran the tests and benchmarks above.

By opening this PR you take responsibility for every line in it, and you agree to explain the change yourself during review rather than routing review comments back through an agent. See AI_POLICY.md.

🤖 Generated with Claude Code