mats/fancy-dns
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Make the API response contract a test; fix what it found

Browse Source 
The console's TypeScript types are hand-written and apiFetch ends in
`JSON.parse(text) as T`, so nothing in the toolchain compared them with the
Go structs. A field that lost its json tag, or a response a struct never had,
showed up as an empty table in a browser and nowhere else: the Go suite was
green and the console was wrong. internal/app/contract_test.go now asserts the
exact JSON key set of every admin endpoint, driven through the real router
with the real hook implementations, plus a test that drives the two write
endpoints with the exact payload web/src builds.

The drift it found, all four fixed here:

blocklist.Source and SourceMeta had no json tags at all, so GET /api/blocklists
sent Go field names ("URL"/"Format") where the console expects snake_case: the
Sources table rendered blank rows and its per-row toggle posted
`name: undefined`. Tagged to match ParseStats.

acl.GroupSummary was flat where the console reads a nested `match` object — the
same shape config.Group has — so every group card read "matches nothing". The
four match fields are nested now, under a new acl.Match.

PUT /api/clients answered 400 `json: unknown field "ptr_suffixes"` to the
console's payload, because config.Group and config.Match carried yaml tags only
and the decoder runs with DisallowUnknownFields. Both structs have json tags
now; the same applies to config.UpstreamServer and UpstreamBootstrap.

PUT /api/upstreams answered 400 `json: unknown field "health"`, because the
console round-trips the whole server object it read, runtime health fields
included. They are accepted and ignored, because the server owns them, and they
are `yaml:"-"` so settings.yaml does not gain runtime state.

Also fixed, each with a test:

A duration on the wire was a nanosecond count. config.Duration had a
MarshalYAML but no MarshalJSON, so bootstraps[].refresh arrived as 30000000000
while the console typed the field as a string, and healthcheck_interval was a
float of seconds in one place and a string in another. Durations on the wire
are duration strings everywhere now — the same spelling config.yaml uses — and a
bare JSON number is still accepted and means seconds, not nanoseconds.
TestDurationJSONForm used to pin the old behaviour and now pins the new one,
saying in its comment that the old behaviour was the bug.

A log row's key set depended on the row. api.LogEntry was omitempty on
client_group, response, upstream and list, so a query with no ACL group
arrived without the key and the console rendered "undefined" where the column
should be empty. The contract test can only pin one shape if the server emits
one, so nothing on that struct is omitempty any more.

A dead peer stayed in the cluster peer list forever. Cluster.seen was only ever
added to and deleted from on an explicit `bye`, so a node that crashed — or
whose Valkey connection died — was reported as a live peer for the life of the
process, and its stale blocklist digest was flagged as divergence forever.
Peers() now reaps peers unheard for peer_ttl*4 and stamps each state with the
receiver's own clock, so clock skew between two machines can neither reap a
healthy peer nor keep a dead one. Discover() ages out the same way on the
publisher's own last_seen stamp, because the keyed Valkey record outlives a
crash: a live node keeps refreshing the key's TTL, so a dead node's field stayed
readable for the life of the fleet.

peer_ttl: 0 would have crashed the process. time.NewTicker(PeerTTL/2) panics on
a non-positive period and `EXPIRE key 0` deletes the heartbeat key, so a config
that left peer_ttl unset would have taken the process down at Start, or made
every instance believe it is alone in the fleet. Both go through peerTTL() and
peerDeadline(), which fall back to the default.

Two cluster tests raced on the wire, not on the product, and one was
environment-dependent rather than wrong. A node that joined after another's
heartbeat was in flight hears about it on the next tick, so "b does not see a"
read immediately after "a sees b" is a coin flip; the divergence test waited for
a digest on the wrong node's view of the fleet; and 127.0.0.1:1 is only
unbindable outside a container that sets
net.ipv4.ip_unprivileged_port_start=0, where it binds and the partial-bind test
fails with both transports up. That test now occupies a port with a live
listener in the test process, which is a deterministic EADDRINUSE on every
machine and every uid.

internal/server/counters_test.go covers the counter-key layer that no other
test touched: the "<transport>.<field>" keyspace, that the aggregate folds only
the known fields, and that the snapshot is safe while counters move.

Two pinned behaviours changed on purpose, each with a test that says so:

An RPZ record did not cover the name it names. rpzRule gave a bare owner name
the subdomain form (*.name), so analytics.example.org. in a policy zone blocked
cdn.analytics.example.org. and left analytics.example.org. resolving normally —
and an rpz-passthru. record did not allowlist its own domain either. RPZ
semantics say the record applies to the domain and everything under it, so a
bare owner now takes the apex form **.name; an owner written with an explicit *.
is still strict, so a zone that wants subdomain-only behaviour can still ask for
it. This changes which queries get blocked for an existing policy zone, which is
why it wanted a decision. TestExampleRPZZoneCoversTheApexItNames pins both
halves and the example zone now says which half it relies on.

metrics.OutcomeLocal had no producer. The engine reported a local-zone answer as
qlog.ActionAllow, which outcomeFor mapped to OutcomeUpstream, so every locally
answered query was counted as an upstream one and the outcome="local" series was
never published — the dashboard's local column was permanently empty.
Response.Local is now set on the local-zone path and outcomeFor consults it
first. That moves published counters, so the README's metrics section says so
too.
This commit is contained in:
developer committed 2026-09-27 18:42:59 +00:00
1 parent e8c5b414d9
commit 9881d2a095
23 files changed
+1302 -242
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

internal/blocklist/example_test.go
+43 -28
View File
@@ -32,13 +32,13 @@ func TestExampleRPZZoneBlocksWhatItSays(t *testing.T) {
{"*.doubleclick.net.", ActionNXDomain, ""},
{"*.ads.example.com.", ActionNXDomain, ""},
{"*.tracker.example.net.", ActionNXDomain, ""},
// A bare owner name in a policy zone is given the subdomain form,
// which covers the name's children but not the name itself; see
// TestExampleRPZZoneApexIsNotCovered.
{"*.analytics.example.org.", ActionNXDomain, ""},
// A bare owner name takes the apex form, so the record covers the
// domain and everything under it; see
// TestExampleRPZZoneCoversTheApexItNames.
{"**.analytics.example.org.", ActionNXDomain, ""},
{"*.noisy-cdn.example.", ActionDrop, ""},
{"*.metrics.internal.", ActionPassthrough, ""},
{"*.blocked.example.", ActionRedirect, "192.0.2.10"},
{"**.metrics.internal.", ActionPassthrough, ""},
{"**.blocked.example.", ActionRedirect, "192.0.2.10"},
}
got := make([]ruleWant, 0, len(rules))
for _, r := range rules {
@@ -103,20 +103,18 @@ func TestExampleRPZZoneMatchesTheNamesItNames(t *testing.T) {
}
}
// TestExampleRPZZoneApexIsNotCovered pins a real gap rather than an intention.
// TestExampleRPZZoneCoversTheApexItNames pins RPZ semantics on the shipped
// policy zone: a record names a domain, and it applies to that domain AND
// everything below it.
//
// An RPZ record names the domain it applies to, and in RPZ semantics that means
// the domain and everything below it. rpzRule gives a bare owner name the
// subdomain form ("*.name"), and a subdomain-form rule does not match the name
// itself — so `analytics.example.org.` in a policy zone blocks
// sub.analytics.example.org. and leaves analytics.example.org. resolving
// normally. The apex form ("**.name") is what covers both.
//
// Not changed here: it alters which queries get blocked for anyone already
// running a policy zone, and the previous round's decision was to pin the
// open questions rather than change behaviour. If this is fixed, the fix is one
// character in rpzRule ("*." -> "**.") plus this test and the STATUS.md entry.
func TestExampleRPZZoneApexIsNotCovered(t *testing.T) {
// This was a real gap, pinned rather than fixed for several rounds: rpzRule
// gave a bare owner name the strict-subdomain form ("*.name"), so
// `analytics.example.org.` blocked cdn.analytics.example.org. and left
// analytics.example.org. resolving normally. DECIDED: rpzRule now uses the
// apex form ("**.name") for a bare owner, which is what RFC 7766 says. An
// owner written with an explicit "*." is still strict, so a zone that wants
// subdomain-only behaviour can ask for it.
func TestExampleRPZZoneCoversTheApexItNames(t *testing.T) {
path := filepath.Join("..", "..", "deploy", "zones", "local.rpz.zone.example")
rules, _, err := parseRPZFiles([]string{path})
if err != nil {
@@ -128,16 +126,33 @@ func TestExampleRPZZoneApexIsNotCovered(t *testing.T) {
}
set := b.Build()
for _, name := range []string{"doubleclick.net.", "ads.example.com.", "analytics.example.org."} {
if e := set.Match(name); e != nil {
t.Errorf("%s matched %v; a policy record for a domain is expected to cover "+
"the domain itself as well as its subdomains (see STATUS.md)", name, e)
// The record for analytics.example.org. was written with a bare owner, so
// it covers the apex as well as its children.
for _, name := range []string{"analytics.example.org.", "cdn.analytics.example.org."} {
e := set.Match(name)
if e == nil {
t.Errorf("%s is not matched by the example policy zone", name)
continue
}
if e.IsAllow() {
t.Errorf("%s matched an allow rule, want a block", name)
}
}
// The same gap on the other side: an rpz-passthru. for the apex does not
// allowlist the apex, so a name on the blocklist stays blocked.
if e := set.Match("metrics.internal."); e != nil && e.IsAllow() {
t.Errorf("metrics.internal. matched the allow rule %v; the apex of an "+
"rpz-passthru. record is not covered", e)
// The same on the allow side: an rpz-passthru. for a bare owner must
// allowlist the apex too, or a name on the blocklist stays blocked.
if e := set.Match("metrics.internal."); e == nil || !e.IsAllow() {
t.Errorf("metrics.internal. = %v, want the rpz-passthru allow rule to cover the apex", e)
}
// A bare-owner redirect covers its apex as well, which is the point of
// pointing a name at a landing page.
if e := set.Match("blocked.example."); e == nil || e.Action != ActionRedirect {
t.Errorf("blocked.example. = %v, want the redirect to cover the apex", e)
}
// The example's other records carry an explicit "*." owner, so they stay
// strict and the pin above is not masking a blanket change of behaviour.
for _, name := range []string{"doubleclick.net.", "ads.example.com."} {
if e := set.Match(name); e != nil {
t.Errorf("%s matched %v; an explicit \"*.\" owner must stay strict", name, e)
}
}
}
internal/blocklist/manager.go
+5 -5
View File
@@ -24,13 +24,13 @@ import (
// Source is a compiled list plus the bookkeeping the UI shows.
type Source struct {
Name string
Format Format
Meta SourceMeta
Stats ParseStats
Name string `json:"name"`
Format Format `json:"format"`
Meta SourceMeta `json:"meta"`
Stats ParseStats `json:"stats"`
// Digest identifies the compiled content, so instances can tell whether
// they hold the same rules without shipping the rules around.
Digest string
Digest string `json:"digest"`
}
// State is the compiled blocklist plus its per-source detail.
internal/blocklist/parse.go
+7 -1
View File
@@ -489,7 +489,13 @@ func rpzRule(rec zonefile.Record, ttl uint32, opt ParseOptions) (Rule, bool) {
return Rule{}, false
}
if !strings.HasPrefix(pattern, "*") && opt.Subdomains {
pattern = "*." + pattern
// RPZ semantics: a record names a domain and applies to that domain
// AND everything under it, so a bare owner name takes the apex form
// "**.". The subdomain form "*." would block sub.name and leave name
// itself resolving, which is not what a policy record says. An owner
// written as "*." is left exactly as written, so a zone that wants
// strict-subdomain behaviour can still ask for it.
pattern = "**." + pattern
}
return Rule{Name: pattern, Action: action, Response: resp, TTL: ttl}, true
}
internal/blocklist/parse_test.go
+22 -12
View File
@@ -281,15 +281,17 @@ func TestParseRPZ(t *testing.T) {
t.Fatalf("Parse: %v", err)
}
want := []string{
// A bare owner name becomes the STRICT-subdomain form "*." (RPZ
// semantics: the policy covers what is under the name), unlike the
// hosts parser which uses "**.". Zone owner names keep their
// trailing dot; Builder.Add strips it at compile time.
"*.example.com. nxdomain ttl=3600",
// A bare owner name becomes the APEX form "**." (RPZ semantics: the
// policy covers the name and everything under it), unlike the hosts
// parser's strict "*." and the hosts parser's "**." for a leading
// dot. An owner written with an explicit wildcard is left alone. Zone
// owner names keep their trailing dot; Builder.Add strips it at
// compile time.
"**.example.com. nxdomain ttl=3600",
"*.sub.example.org. drop ttl=3600",
"**.both.example.net. passthrough ttl=3600",
"*.redirect.example.gov. redirect ttl=3600 resp=127.0.0.2",
"*.redirect6.example.gov. redirect ttl=3600 resp=::1",
"**.redirect.example.gov. redirect ttl=3600 resp=127.0.0.2",
"**.redirect6.example.gov. redirect ttl=3600 resp=::1",
}
if got := ruleStrings(rules); !sameRules(got, want) {
t.Errorf("rules = %v,\nwant %v", got, want)
@@ -318,19 +320,27 @@ func TestParseRPZ(t *testing.T) {
if err != nil {
t.Fatalf("Parse: %v", err)
}
if got := ruleStrings(cname); !sameRules(got, []string{"*.shop.example.com. cname ttl=60 resp=parked.example.net."}) {
if got := ruleStrings(cname); !sameRules(got, []string{"**.shop.example.com. cname ttl=60 resp=parked.example.net."}) {
t.Errorf("cname rules = %v", got)
}
// The compiled forms behave as documented: "*." skips the apex while
// "**." covers it.
// The compiled forms behave as documented: a bare owner name covers the
// apex AND its children, an explicit "*." covers only children.
s := mustBuild(rules...)
if e := s.Match("example.com"); e != nil {
t.Errorf("RPZ \"example.com CNAME .\" matched the apex: %q, want nil (strict \"*.\")", e.Name)
if e := s.Match("example.com"); e == nil || e.Action != ActionNXDomain {
t.Errorf("example.com: %+v, want nxdomain (a bare owner name covers the apex)", e)
}
if e := s.Match("www.example.com"); e == nil || e.Action != ActionNXDomain {
t.Errorf("www.example.com: %+v, want nxdomain", e)
}
// "*.sub.example.org" was written with an explicit wildcard, so it stays
// strict: the subdomain is blocked, the apex is not.
if e := s.Match("sub.example.org"); e != nil {
t.Errorf("sub.example.org: %+v, want nil (an explicit \"*.\" owner is strict)", e)
}
if e := s.Match("deep.sub.example.org"); e == nil || e.Action != ActionDrop {
t.Errorf("deep.sub.example.org: %+v, want drop", e)
}
if e := s.Match("both.example.net"); e == nil || e.Action != ActionPassthrough {
t.Errorf("both.example.net: %+v, want passthrough (\"**.\" covers the apex)", e)
}
internal/blocklist/set.go
+14 -14
View File
@@ -196,20 +196,20 @@ type RuleCounts struct {
// SourceMeta describes one contributing source.
type SourceMeta struct {
Name string
Format string
Rules int
Bytes int64
ETag string
LastMod string
UpdatedAt time.Time
Duration time.Duration
Err string
Enabled bool
URL string
Path string
Stale bool
HTTPStatus int
Name string `json:"name"`
Format string `json:"format"`
Rules int `json:"rules"`
Bytes int64 `json:"bytes"`
ETag string `json:"etag"`
LastMod string `json:"last_mod"`
UpdatedAt time.Time `json:"updated_at"`
Duration time.Duration `json:"duration"`
Err string `json:"err"`
Enabled bool `json:"enabled"`
URL string `json:"url"`
Path string `json:"path"`
Stale bool `json:"stale"`
HTTPStatus int `json:"http_status"`
}
// Builder accumulates rules and produces a Set.