fix(resolver): scope allowlist-only mode to the whole client - #2249

Fixes #2207

Problem

A group holding only allowlist entries (no denylists key) put the whole client into exclusive "allow nothing else" mode, even when that client was also assigned ordinary denylist groups. The flag was ORed across the client's groups and the branch returned before the denylist was ever consulted:

allowlistOnlyAllowed := r.hasAllowlistOnlyAllowed(groupsToCheck) // any group -> true
...
if allowlistOnlyAllowed {
    return true, r.handleBlocked(..., "BLOCKED (ALLOWLIST ONLY)", ""), nil
}
if matches := r.matches(groupsToCheck, r.denylistMatcher, domain); ... // never reached

So the config from the issue — a shared ads denylist plus a small client-specific allowlist group — blocked everything for that client:

macan   wikipedia.org        -> BLOCKED (ALLOWLIST ONLY)
macan   google.com           -> BLOCKED (ALLOWLIST ONLY)
macan   doubleclick.net      -> BLOCKED (ALLOWLIST ONLY)   <- attribution lost
default wikipedia.org        -> RESOLVED
default doubleclick.net      -> BLOCKED (ads: doubleclick.net)

Note the third line: denylist hits also lost their attribution, since the exclusive branch returned before the match was known. The query log and the reason metric label saw BLOCKED (ALLOWLIST ONLY) with an empty reason label rather than the group and rule that matched.

The reporter's workaround was a dummy .invalid domain in a denylist for that group. It works because determineAllowlistOnlyGroups tests key presence in cfg.Denylists, not whether the group denies anything — undiscoverable from the docs.

Fix

Exclusive mode now requires that every group assigned to the client be allowlist-only. hasAllowlistOnlyAllowed is gone; groupsToCheckForClient returns the flag alongside the active groups.

Exclusivity is derived from the client's configured groups, before the schedule and disable-API filtering. Deriving it from the active groups would introduce a new bug: deactivating the denylist group would leave only the allowlist group active and promote its exceptions into a whitelist, so disabling blocking would block more. There is a test pinning that.

This keeps the pure allow-only use case (a client whose groups are all allowlist-only) working exactly as before — every pre-existing allowlist-only spec passes unchanged.

Docs

The documented behaviour was wrong on two counts, both corrected in docs/configuration.md and docs/config.yml:

• Scope — it read as a per-group rule; exclusive mode is a property of the client.
• "only domains from this list" — the permitted set is the union of the allowlists across all of the client's groups. (Verified: a domain allowlisted only in the ads group resolves for a client whose exclusive mode came from a different group.)

The docs now also state that allowlist precedence holds across a client's groups, which is the supported way to add client-specific exceptions to a shared denylist without duplicating it. Added schedule rule 5 noting exclusivity follows configuration, not currently-active groups.

Tests

Written test-first; the failing cases were observed before the fix.

Unit (resolver/blocking_resolver_test.go) — 5 new specs, 3 of which failed against the old code:

• resolves a domain on neither list
• still blocks a denylisted domain, naming the group that blocked it
• allowlist group excepts a domain the other group denies
• clients without the allowlist-only group unaffected
• denylist group disabled via API -> still not exclusive mode

The mixed case had no coverage at all before this: every existing allowlist-only spec used clients whose groups were all allowlist-only, which is why this shipped.

E2E (e2e/blocking_test.go) — 3 new specs over two list servers. Against a pre-fix image the first one reproduces the report end to end:

Expected ... unrelated.com. 21600 IN A 0.0.0.0
to contain domain 'unrelated.com.', type 'A', answer '1.2.3.4'

Also replaced the stale note claiming allow-only mode could not be tested here.

Verification

• ./resolver suite: 713/713 pass
• full e2e suite: 163/163 pass
• golangci-lint (v2.12.2): 0 issues
• gofmt clean

https://claude.ai/code/session_01QyEFFhrY3j9QtGzR2wUJr9