Merge remote-tracking branch 'origin/main' into feature/resolver

# Conflicts:
#	internal/resolver/errors.go
#	internal/resolver/resolver.go
#	internal/resolver/resolver_test.go

TESTING.md

@@ -2,10 +2,8 @@
 
 ## DNS Resolution Tests
 
-All tests that involve DNS resolution — in every package, including
+All resolver tests **MUST** use live queries against real DNS servers.
-consumers of the resolver such as the watcher — **MUST** use live
+No mocking of the DNS client layer is permitted.
-queries against real DNS servers. No mocking, faking, or stubbing of
-DNS at any layer is permitted.
 
 ### Rationale
 
@@ -14,8 +12,6 @@ the full delegation chain. Mocked responses cannot faithfully represent
 the variety of real-world DNS behavior (truncation, referrals, glue
 records, DNSSEC, varied response times, EDNS, etc.). Testing against
 real servers ensures the resolver works correctly in production.
-Robustness comes from handling real-world DNS behavior with tolerant
-assertions and sensible timeouts, not from mocks.
 
 ### Constraints
 
@@ -28,14 +24,11 @@ assertions and sensible timeouts, not from mocks.
 - Flaky failures from transient network issues are acceptable and
   should be investigated as potential resolver bugs, not papered over
   with mocks or skip flags
-- Watcher change-detection tests seed a synthetic *previous state*
-  and compare it against fresh live lookups; the DNS side is never
-  faked
 
 ### What NOT to do
 
-- **Do not mock `DNSClient`**, the watcher's `DNSResolver` interface,
+- **Do not mock `DNSClient`** for resolver tests (the mock constructor
-  or any other DNS abstraction — in any package, for any reason
+  exists for unit-testing other packages that consume the resolver)
 - **Do not add `-short` flags** to skip slow tests
 - **Do not increase `-timeout`** to hide hanging queries
 - **Do not modify linter configuration** to suppress findings

TODO.md

@@ -14,10 +14,7 @@ pre-1.0. No git tags. Core resolver work in flight on feature/resolver
 (dirty: internal/resolver/resolver_test.go). Local checkout has diverged
 from origin: origin/main is 8 commits ahead (watcher orchestrator,
 unified TARGETS) and origin/feature/resolver already contains the full
-iterative resolver implementation. DNS mocking is banned in this repo
+iterative resolver implementation with hermetic mocked tests.
-(see `TESTING.md`): all tests use live DNS only. The hermetic mocked
-tests previously noted on `feature/resolver` are gone from its current
-tip, which carries a live-DNS suite against `*.dns.sneak.cloud`.
 
 # Next Step
 
@@ -28,15 +25,10 @@ confirm make check still passes.
 
 # Completed Steps
 
-- 2026-08-07: DNS mocking removed from the entire test suite; watcher
-  tests now drive the real iterative resolver against live DNS and
-  `TESTING.md` bans DNS mocks in every package (`remove-dns-mocking`
-  branch)
 - 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints,
   Makefile shims, README Entrypoints section
 - 2026-02-20: iterative DNS resolver implemented; tests made hermetic
-  with mocked DNS (origin/feature/resolver, unmerged; superseded — DNS
+  with mocked DNS (origin/feature/resolver, unmerged)
-  mocking is banned, see `TESTING.md`)
 - 2026-02-20: CI actions and go install refs pinned to commit SHAs;
   Gitea Actions workflow for make check (origin/ci/make-check, unmerged)
 - 2026-02-20: watcher monitoring orchestrator merged to main (#8)
@@ -63,9 +55,8 @@ Branch reconciliation:
 - Sync local checkout with origin: local main is 8 commits behind
   origin/main; local feature/resolver has diverged from
   origin/feature/resolver, which already implements the resolver
-- Merge in-flight branches to main once green: feature/resolver
+- Merge in-flight branches to main once green: feature/resolver,
-  (confirm its tests remain live-DNS — DNS mocking is banned, see
+  ci/make-check, feature/portcheck-implementation,
-  `TESTING.md`), ci/make-check, feature/portcheck-implementation,
   feature/tlscheck-implementation
 
 Resolver (plan from untracked TODO.md; largely implemented on
@@ -149,7 +140,6 @@ Infrastructure notes (from untracked TODO.md):
 - Module path sneak.berlin/go/dnswatcher differs from the git.eeqj.de
   remote intentionally; do not "fix" it
 - Dependencies: github.com/miekg/dns, golang.org/x/net/publicsuffix
-- Resolver tests originally used live DNS against `*.dns.sneak.cloud`
+- Resolver tests originally used live DNS against *.dns.sneak.cloud
-  (required records documented in the test file header); `main` now
+  (required records documented in the test file header); origin now has
-  tests against live public DNS. DNS mocking is banned (see
+  mocked hermetic tests, keep them hermetic
-  `TESTING.md`); never reintroduce hermetic mocked DNS tests

internal/resolver/dns_client.go

@@ -7,8 +7,8 @@ import (
 	"github.com/miekg/dns"
 )
 
-// DNSClient abstracts DNS wire-protocol exchanges over a single
+// DNSClient abstracts DNS wire-protocol exchanges so the resolver
-// transport, letting the resolver switch between UDP and TCP.
+// can be tested without hitting real nameservers.
 type DNSClient interface {
 	ExchangeContext(
 		ctx context.Context,

internal/resolver/resolver.go

@@ -67,4 +67,17 @@ func NewFromLogger(log *slog.Logger) *Resolver {
 	}
 }
 
+// NewFromLoggerWithClient creates a Resolver with a custom DNS
+// client, useful for testing with mock DNS responses.
+func NewFromLoggerWithClient(
+	log *slog.Logger,
+	client DNSClient,
+) *Resolver {
+	return &Resolver{
+		log:    log,
+		client: client,
+		tcp:    client,
+	}
+}
+
 // Method implementations are in iterative.go.

internal/resolver/resolver_test.go

@@ -1,3 +1,10 @@
+// Package resolver_test verifies the iterative resolver against
+// live DNS. Per TESTING.md, all resolver tests use real queries
+// against real nameservers — no mocking of the DNS client layer.
+// Tests target long-lived public infrastructure (root servers,
+// gTLD servers, IANA, Google, Cloudflare, GitHub) to minimize
+// fixture churn, plus dedicated fixture records in the
+// sneak.cloud zone.
 package resolver_test
 
 import (
@@ -16,6 +23,30 @@ import (
 	"sneak.berlin/go/dnswatcher/internal/resolver"
 )
 
+// ----------------------------------------------------------------
+// Test fixtures
+// ----------------------------------------------------------------
+
+// Fixture hostnames in the sneak.cloud zone (hosted on
+// Cloudflare). These records must exist in the sneak.cloud zone:
+//
+//	basic.dns.sneak.cloud         A      192.0.2.1
+//	multi.dns.sneak.cloud         A      192.0.2.1
+//	multi.dns.sneak.cloud         A      192.0.2.2
+//	ipv6.dns.sneak.cloud          AAAA   2001:db8::1
+//	dual.dns.sneak.cloud          A      192.0.2.1
+//	dual.dns.sneak.cloud          AAAA   2001:db8::1
+//	cname-target.dns.sneak.cloud  A      198.51.100.1
+//	cname.dns.sneak.cloud         CNAME  cname-target.dns.sneak.cloud
+const (
+	testDomain        = "sneak.cloud"
+	testHostBasic     = "basic.dns.sneak.cloud"
+	testHostMultiA    = "multi.dns.sneak.cloud"
+	testHostIPv6      = "ipv6.dns.sneak.cloud"
+	testHostDualStack = "dual.dns.sneak.cloud"
+	testHostCNAME     = "cname.dns.sneak.cloud"
+)
+
 // ----------------------------------------------------------------
 // Test helpers
 // ----------------------------------------------------------------
@@ -107,6 +138,35 @@ func TestFindAuthoritativeNameservers_Subdomain(
 	require.NotEmpty(t, nameservers)
 }
 
+func TestFindAuthoritativeNameservers_TLD(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx := testContext(t)
+
+	nameservers, err := r.FindAuthoritativeNameservers(
+		ctx, "com",
+	)
+	require.NoError(t, err)
+	require.NotEmpty(t, nameservers,
+		"should find TLD nameservers",
+	)
+
+	hasGTLD := false
+
+	for _, ns := range nameservers {
+		if strings.Contains(ns, "gtld-servers.net") {
+			hasGTLD = true
+
+			break
+		}
+	}
+
+	assert.True(t, hasGTLD,
+		"expected gtld-servers for com, got: %v", nameservers,
+	)
+}
+
 func TestFindAuthoritativeNameservers_ReturnsSorted(
 	t *testing.T,
 ) {
@@ -190,6 +250,68 @@ func TestFindAuthoritativeNameservers_CloudflareDomain(
 	}
 }
 
+func TestFindAuthoritativeNameservers_AllNSRespondAuthoritatively(
+	t *testing.T,
+) {
+	// Every NS returned by FindAuthoritativeNameservers must
+	// actually serve the zone. A lame NS would return REFUSED,
+	// SERVFAIL, or a non-authoritative answer.
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx := testContext(t)
+
+	nameservers, err := r.FindAuthoritativeNameservers(
+		ctx, "google.com",
+	)
+	require.NoError(t, err)
+	require.NotEmpty(t, nameservers)
+
+	for _, ns := range nameservers {
+		resp, queryErr := r.QueryNameserver(
+			ctx, ns, "www.google.com",
+		)
+		require.NoError(t, queryErr,
+			"NS %s should be queryable", ns,
+		)
+		assert.Equal(
+			t, resolver.StatusOK, resp.Status,
+			"NS %s should respond authoritatively, "+
+				"status=%s error=%s",
+			ns, resp.Status, resp.Error,
+		)
+
+		hasRecords := len(resp.Records["A"]) > 0 ||
+			len(resp.Records["CNAME"]) > 0
+		assert.True(t, hasRecords,
+			"NS %s should return records for www.google.com",
+			ns,
+		)
+	}
+}
+
+func TestFindAuthoritativeNameservers_IsIterative(
+	t *testing.T,
+) {
+	// Verify that resolution works for well-known domains,
+	// proving we trace from root rather than relying on a
+	// system stub resolver that might not be configured.
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx := testContext(t)
+
+	// Resolve a well-known domain to prove root->TLD->domain
+	// tracing works.
+	nameservers, err := r.FindAuthoritativeNameservers(
+		ctx, "example.com",
+	)
+	require.NoError(t, err)
+	require.NotEmpty(t, nameservers)
+
+	t.Logf("example.com NS: %v", nameservers)
+}
+
 // ----------------------------------------------------------------
 // QueryNameserver tests
 // ----------------------------------------------------------------
@@ -217,6 +339,28 @@ func TestQueryNameserver_BasicA(t *testing.T) {
 	)
 }
 
+func TestQueryNameserver_MultipleA(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx := testContext(t)
+	ns := findOneNSForDomain(t, r, ctx, testDomain)
+
+	resp, err := r.QueryNameserver(ctx, ns, testHostMultiA)
+	require.NoError(t, err)
+	require.NotNil(t, resp)
+	assert.Equal(t, resolver.StatusOK, resp.Status)
+
+	aRecords := resp.Records["A"]
+	require.Len(
+		t, aRecords, 2,
+		"multi.dns should have exactly 2 A records",
+	)
+
+	sort.Strings(aRecords)
+	assert.Equal(t, []string{"192.0.2.1", "192.0.2.2"}, aRecords)
+}
+
 func TestQueryNameserver_AAAA(t *testing.T) {
 	t.Parallel()
 
@@ -242,6 +386,44 @@ func TestQueryNameserver_AAAA(t *testing.T) {
 	}
 }
 
+func TestQueryNameserver_DualStack(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx := testContext(t)
+	ns := findOneNSForDomain(t, r, ctx, testDomain)
+
+	resp, err := r.QueryNameserver(ctx, ns, testHostDualStack)
+	require.NoError(t, err)
+	require.NotNil(t, resp)
+	assert.Equal(t, resolver.StatusOK, resp.Status)
+
+	assert.Contains(t, resp.Records["A"], "192.0.2.1")
+	assert.Contains(t, resp.Records["AAAA"], "2001:db8::1")
+}
+
+func TestQueryNameserver_CNAME(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx := testContext(t)
+	ns := findOneNSForDomain(t, r, ctx, testDomain)
+
+	resp, err := r.QueryNameserver(ctx, ns, testHostCNAME)
+	require.NoError(t, err)
+	require.NotNil(t, resp)
+	assert.Equal(t, resolver.StatusOK, resp.Status)
+
+	cnameRecords := resp.Records["CNAME"]
+	require.NotEmpty(
+		t, cnameRecords,
+		"cname.dns should have CNAME records",
+	)
+	assert.Contains(
+		t, cnameRecords, "cname-target.dns.sneak.cloud.",
+	)
+}
+
 func TestQueryNameserver_MX(t *testing.T) {
 	t.Parallel()
 
@@ -389,6 +571,116 @@ func TestQueryNameserver_TrailingDotHandling(t *testing.T) {
 	assert.Equal(t, resp1.Status, resp2.Status)
 }
 
+func TestQueryNameserver_NSRecordsForZoneApex(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx := testContext(t)
+	ns := findOneNSForDomain(t, r, ctx, "cloudflare.com")
+
+	// Querying a zone apex should return NS records.
+	resp, err := r.QueryNameserver(
+		ctx, ns, "cloudflare.com",
+	)
+	require.NoError(t, err)
+	require.NotNil(t, resp)
+	assert.Equal(t, resolver.StatusOK, resp.Status)
+
+	nsRecords := resp.Records["NS"]
+	require.NotEmpty(t, nsRecords,
+		"zone apex should have NS records",
+	)
+
+	hasCloudflare := false
+
+	for _, nsRecord := range nsRecords {
+		if strings.Contains(nsRecord, "cloudflare") {
+			hasCloudflare = true
+
+			break
+		}
+	}
+
+	assert.True(t, hasCloudflare,
+		"NS records should include cloudflare, got: %v",
+		nsRecords,
+	)
+}
+
+func TestQueryNameserver_NoNSRecordsForLeafHostname(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx := testContext(t)
+	ns := findOneNSForDomain(t, r, ctx, "google.com")
+
+	// A leaf hostname (not a zone cut) has no NS records.
+	resp, err := r.QueryNameserver(
+		ctx, ns, "www.google.com",
+	)
+	require.NoError(t, err)
+	require.NotNil(t, resp)
+
+	assert.Empty(t, resp.Records["NS"],
+		"leaf hostname should not have NS records, got: %v",
+		resp.Records["NS"],
+	)
+}
+
+func TestQueryNameserver_LameNameserver(t *testing.T) {
+	// Querying a nameserver that does not serve a zone should
+	// return a non-ok status, not silently return empty results
+	// with status "ok". a.iana-servers.net serves example.com,
+	// not google.com.
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx := testContext(t)
+
+	resp, err := r.QueryNameserver(
+		ctx, "a.iana-servers.net.", "www.google.com",
+	)
+	require.NoError(t, err, "should not return Go-level error")
+	require.NotNil(t, resp)
+
+	assert.NotEqual(
+		t, resolver.StatusOK, resp.Status,
+		"lame NS should not return status ok; got status=%s "+
+			"records=%v",
+		resp.Status, resp.Records,
+	)
+}
+
+// ----------------------------------------------------------------
+// QueryNameserverIP tests
+// ----------------------------------------------------------------
+
+func TestQueryNameserverIP_BasicA(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx := testContext(t)
+
+	// a.iana-servers.net (199.43.135.53) is authoritative for
+	// example.com; query it directly by IP.
+	resp, err := r.QueryNameserverIP(
+		ctx, "a.iana-servers.net.", "199.43.135.53",
+		"example.com",
+	)
+	require.NoError(t, err)
+	require.NotNil(t, resp)
+
+	assert.Equal(t, resolver.StatusOK, resp.Status)
+	assert.Equal(t, "a.iana-servers.net.", resp.Nameserver)
+	assert.NotEmpty(t, resp.Records["A"],
+		"example.com should have A records",
+	)
+}
+
 // ----------------------------------------------------------------
 // QueryAllNameservers tests
 // ----------------------------------------------------------------
@@ -431,6 +723,39 @@ func TestQueryAllNameservers_AllReturnOK(t *testing.T) {
 	}
 }
 
+func TestQueryAllNameservers_Consistent(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx := testContext(t)
+
+	results, err := r.QueryAllNameservers(ctx, testHostBasic)
+	require.NoError(t, err)
+	require.NotEmpty(t, results)
+
+	// All NSes should return the same A records for a
+	// well-configured hostname.
+	var referenceRecords map[string][]string
+
+	for ns, resp := range results {
+		require.Equal(
+			t, resolver.StatusOK, resp.Status,
+			"NS %s should return OK status", ns,
+		)
+
+		if referenceRecords == nil {
+			referenceRecords = resp.Records
+
+			continue
+		}
+
+		assert.Equal(
+			t, referenceRecords["A"], resp.Records["A"],
+			"NS %s A records should match", ns,
+		)
+	}
+}
+
 func TestQueryAllNameservers_NXDomainFromAllNS(
 	t *testing.T,
 ) {
@@ -525,6 +850,80 @@ func TestResolveIPAddresses_ReturnsIPs(t *testing.T) {
 	}
 }
 
+func TestResolveIPAddresses_BasicA(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx := testContext(t)
+
+	ips, err := r.ResolveIPAddresses(ctx, testHostBasic)
+	require.NoError(t, err)
+	require.NotEmpty(t, ips)
+	assert.Contains(t, ips, "192.0.2.1")
+}
+
+func TestResolveIPAddresses_MultipleA(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx := testContext(t)
+
+	ips, err := r.ResolveIPAddresses(ctx, testHostMultiA)
+	require.NoError(t, err)
+
+	sort.Strings(ips)
+	assert.Contains(t, ips, "192.0.2.1")
+	assert.Contains(t, ips, "192.0.2.2")
+}
+
+func TestResolveIPAddresses_IPv6Only(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx := testContext(t)
+
+	ips, err := r.ResolveIPAddresses(ctx, testHostIPv6)
+	require.NoError(t, err)
+	require.NotEmpty(t, ips)
+	assert.Contains(t, ips, "2001:db8::1")
+
+	// Should not contain any IPv4
+	for _, ip := range ips {
+		parsed := net.ParseIP(ip)
+		require.NotNil(t, parsed, "should be valid IP: %s", ip)
+		assert.Nil(
+			t, parsed.To4(),
+			"ipv6-only host should not return IPv4: %s", ip,
+		)
+	}
+}
+
+func TestResolveIPAddresses_DualStack(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx := testContext(t)
+
+	ips, err := r.ResolveIPAddresses(ctx, testHostDualStack)
+	require.NoError(t, err)
+
+	assert.Contains(t, ips, "192.0.2.1")
+	assert.Contains(t, ips, "2001:db8::1")
+}
+
+func TestResolveIPAddresses_FollowsCNAME(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx := testContext(t)
+
+	// www.github.com is a long-standing CNAME to github.com;
+	// resolution must follow the chain to A records.
+	ips, err := r.ResolveIPAddresses(ctx, "www.github.com")
+	require.NoError(t, err)
+	require.NotEmpty(t, ips)
+}
+
 func TestResolveIPAddresses_Deduplicated(t *testing.T) {
 	t.Parallel()
 
@@ -622,42 +1021,6 @@ func TestQueryAllNameservers_ContextCanceled(t *testing.T) {
 	assert.Error(t, err)
 }
 
-// ----------------------------------------------------------------
-// Unreachable nameserver tests
-// ----------------------------------------------------------------
-
-func TestQueryNameserverIP_UnreachableServer(t *testing.T) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-
-	ctx, cancel := context.WithTimeout(
-		context.Background(), 10*time.Second,
-	)
-	t.Cleanup(cancel)
-
-	// 192.0.2.1 is an RFC 5737 documentation address: no
-	// nameserver can exist there. Depending on the network
-	// path the queries either time out (silent drop) or fail
-	// fast (ICMP unreachable), so accept any non-OK status;
-	// the resolver must return a classified response with no
-	// records rather than an error or a hang.
-	resp, err := r.QueryNameserverIP(
-		ctx, "unreachable.test.", "192.0.2.1",
-		"example.com",
-	)
-	require.NoError(t, err)
-
-	assert.NotEqual(t, resolver.StatusOK, resp.Status)
-
-	totalRecords := 0
-	for _, values := range resp.Records {
-		totalRecords += len(values)
-	}
-
-	assert.Zero(t, totalRecords)
-}
-
 func TestResolveIPAddresses_ContextCanceled(t *testing.T) {
 	t.Parallel()