fix: distinguish timeout from negative DNS responses (closes #35)

Reviewed-on: #23

TESTING.md

@@ -0,0 +1,34 @@
+# Testing Policy
+
+## DNS Resolution Tests
+
+All resolver tests **MUST** use live queries against real DNS servers.
+No mocking of the DNS client layer is permitted.
+
+### Rationale
+
+The resolver performs iterative resolution from root nameservers through
+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.
+
+### Constraints
+
+- Tests hit real DNS infrastructure and require network access
+- Test duration depends on network conditions; timeout tuning keeps
+  the suite within the 30-second target
+- Query timeout is calibrated to 3× maximum antipodal RTT (~300ms)
+  plus processing margin
+- Root server fan-out is limited to reduce parallel query load
+- Flaky failures from transient network issues are acceptable and
+  should be investigated as potential resolver bugs, not papered over
+  with mocks or skip flags
+
+### What NOT to do
+
+- **Do not mock `DNSClient`** for resolver tests (the mock constructor
+  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

internal/resolver/errors.go

@@ -4,11 +4,6 @@ import "errors"
 
 // Sentinel errors returned by the resolver.
 var (
-	// ErrNotImplemented indicates a method is stubbed out.
-	ErrNotImplemented = errors.New(
-		"resolver not yet implemented",
-	)
-
 	// ErrNoNameservers is returned when no authoritative NS
 	// could be discovered for a domain.
 	ErrNoNameservers = errors.New(

internal/resolver/iterative.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"math/rand"
 	"net"
 	"sort"
 	"strings"
@@ -13,7 +14,7 @@ import (
 )
 
 const (
-	queryTimeoutDuration = 700 * time.Millisecond
+	queryTimeoutDuration = 2 * time.Second
 	maxRetries           = 2
 	maxDelegation        = 20
 	timeoutMultiplier    = 2
@@ -41,6 +42,22 @@ func rootServerList() []string {
 	}
 }
 
+const maxRootServers = 3
+
+// randomRootServers returns a shuffled subset of root servers.
+func randomRootServers() []string {
+	all := rootServerList()
+	rand.Shuffle(len(all), func(i, j int) {
+		all[i], all[j] = all[j], all[i]
+	})
+
+	if len(all) > maxRootServers {
+		return all[:maxRootServers]
+	}
+
+	return all
+}
+
 func checkCtx(ctx context.Context) error {
 	err := ctx.Err()
 	if err != nil {
@@ -291,17 +308,8 @@ func (r *Resolver) resolveNSIPs(
 	return ips
 }
 
-// publicResolvers returns well-known public recursive DNS resolvers.
-func publicResolvers() []string {
-	return []string{
-		"1.1.1.1", // Cloudflare
-		"8.8.8.8", // Google
-		"9.9.9.9", // Quad9
-	}
-}
-
-// resolveNSRecursive queries for NS records using a public
-// recursive resolver as a fallback for intercepted environments.
+// resolveNSRecursive queries for NS records using recursive
+// resolution as a fallback for intercepted environments.
 func (r *Resolver) resolveNSRecursive(
 	ctx context.Context,
 	domain string,
@@ -311,7 +319,7 @@ func (r *Resolver) resolveNSRecursive(
 	msg.SetQuestion(domain, dns.TypeNS)
 	msg.RecursionDesired = true
 
-	for _, ip := range publicResolvers() {
+	for _, ip := range randomRootServers() {
 		if checkCtx(ctx) != nil {
 			return nil, ErrContextCanceled
 		}
@@ -332,8 +340,7 @@ func (r *Resolver) resolveNSRecursive(
 	return nil, ErrNoNameservers
 }
 
-// resolveARecord resolves a hostname to IPv4 addresses using
-// public recursive resolvers.
+// resolveARecord resolves a hostname to IPv4 addresses.
 func (r *Resolver) resolveARecord(
 	ctx context.Context,
 	hostname string,
@@ -343,7 +350,7 @@ func (r *Resolver) resolveARecord(
 	msg.SetQuestion(hostname, dns.TypeA)
 	msg.RecursionDesired = true
 
-	for _, ip := range publicResolvers() {
+	for _, ip := range randomRootServers() {
 		if checkCtx(ctx) != nil {
 			return nil, ErrContextCanceled
 		}
@@ -395,7 +402,7 @@ func (r *Resolver) FindAuthoritativeNameservers(
 		candidate := strings.Join(labels[i:], ".") + "."
 
 		nsNames, err := r.followDelegation(
-			ctx, candidate, rootServerList(),
+			ctx, candidate, randomRootServers(),
 		)
 		if err == nil && len(nsNames) > 0 {
 			sort.Strings(nsNames)
@@ -428,6 +435,23 @@ func (r *Resolver) QueryNameserver(
 	return r.queryAllTypes(ctx, nsHostname, nsIPs[0], hostname)
 }
 
+// QueryNameserverIP queries a nameserver by its IP address directly,
+// bypassing NS hostname resolution.
+func (r *Resolver) QueryNameserverIP(
+	ctx context.Context,
+	nsHostname string,
+	nsIP string,
+	hostname string,
+) (*NameserverResponse, error) {
+	if checkCtx(ctx) != nil {
+		return nil, ErrContextCanceled
+	}
+
+	hostname = dns.Fqdn(hostname)
+
+	return r.queryAllTypes(ctx, nsHostname, nsIP, hostname)
+}
+
 func (r *Resolver) queryAllTypes(
 	ctx context.Context,
 	nsHostname string,
@@ -455,6 +479,7 @@ func (r *Resolver) queryAllTypes(
 type queryState struct {
 	gotNXDomain bool
 	gotSERVFAIL bool
+	gotTimeout  bool
 	hasRecords  bool
 }
 
@@ -492,6 +517,10 @@ func (r *Resolver) querySingleType(
 ) {
 	msg, err := r.queryDNS(ctx, nsIP, hostname, qtype)
 	if err != nil {
+		if isTimeout(err) {
+			state.gotTimeout = true
+		}
+
 		return
 	}
 
@@ -529,12 +558,26 @@ func collectAnswerRecords(
 	}
 }
 
+// isTimeout checks whether an error is a network timeout.
+func isTimeout(err error) bool {
+	var netErr net.Error
+	if errors.As(err, &netErr) {
+		return netErr.Timeout()
+	}
+
+	return false
+}
+
 func classifyResponse(resp *NameserverResponse, state queryState) {
 	switch {
 	case state.gotNXDomain && !state.hasRecords:
 		resp.Status = StatusNXDomain
+	case state.gotTimeout && !state.hasRecords:
+		resp.Status = StatusTimeout
+		resp.Error = "all queries timed out"
 	case state.gotSERVFAIL && !state.hasRecords:
 		resp.Status = StatusError
+		resp.Error = "server returned SERVFAIL"
 	case !state.hasRecords && !state.gotNXDomain:
 		resp.Status = StatusNoData
 	}

internal/resolver/resolver.go

@@ -17,6 +17,7 @@ const (
 	StatusError    = "error"
 	StatusNXDomain = "nxdomain"
 	StatusNoData   = "nodata"
+	StatusTimeout  = "timeout"
 )
 
 // MaxCNAMEDepth is the maximum CNAME chain depth to follow.

internal/resolver/resolver_test.go

@@ -10,6 +10,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/miekg/dns"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
@@ -622,6 +623,59 @@ func TestQueryAllNameservers_ContextCanceled(t *testing.T) {
 	assert.Error(t, err)
 }
 
+// ----------------------------------------------------------------
+// Timeout tests
+// ----------------------------------------------------------------
+
+func TestQueryNameserverIP_Timeout(t *testing.T) {
+	t.Parallel()
+
+	log := slog.New(slog.NewTextHandler(
+		os.Stderr,
+		&slog.HandlerOptions{Level: slog.LevelDebug},
+	))
+
+	r := resolver.NewFromLoggerWithClient(
+		log, &timeoutClient{},
+	)
+
+	ctx, cancel := context.WithTimeout(
+		context.Background(), 10*time.Second,
+	)
+	t.Cleanup(cancel)
+
+	// Query any IP — the client always returns a timeout error.
+	resp, err := r.QueryNameserverIP(
+		ctx, "unreachable.test.", "192.0.2.1",
+		"example.com",
+	)
+	require.NoError(t, err)
+
+	assert.Equal(t, resolver.StatusTimeout, resp.Status)
+	assert.NotEmpty(t, resp.Error)
+}
+
+// timeoutClient simulates DNS timeout errors for testing.
+type timeoutClient struct{}
+
+func (c *timeoutClient) ExchangeContext(
+	_ context.Context,
+	_ *dns.Msg,
+	_ string,
+) (*dns.Msg, time.Duration, error) {
+	return nil, 0, &net.OpError{
+		Op:  "read",
+		Net: "udp",
+		Err: &timeoutError{},
+	}
+}
+
+type timeoutError struct{}
+
+func (e *timeoutError) Error() string   { return "i/o timeout" }
+func (e *timeoutError) Timeout() bool   { return true }
+func (e *timeoutError) Temporary() bool { return true }
+
 func TestResolveIPAddresses_ContextCanceled(t *testing.T) {
 	t.Parallel()
 

internal/watcher/watcher.go

@@ -6,6 +6,7 @@ import (
 	"log/slog"
 	"sort"
 	"strings"
+	"sync"
 	"time"
 
 	"go.uber.org/fx"
@@ -49,6 +50,8 @@ type Watcher struct {
 	notify           Notifier
 	cancel           context.CancelFunc
 	firstRun         bool
+	expiryNotifiedMu sync.Mutex
+	expiryNotified   map[string]time.Time
 }
 
 // New creates a new Watcher instance wired into the fx lifecycle.
@@ -65,6 +68,7 @@ func New(
 		tlsCheck:       params.TLSCheck,
 		notify:         params.Notify,
 		firstRun:       true,
+		expiryNotified: make(map[string]time.Time),
 	}
 
 	lifecycle.Append(fx.Hook{
@@ -108,6 +112,7 @@ func NewForTest(
 		tlsCheck:       tc,
 		notify:         n,
 		firstRun:       true,
+		expiryNotified: make(map[string]time.Time),
 	}
 }
 
@@ -206,6 +211,28 @@ func (w *Watcher) checkDomain(
 		Nameservers: nameservers,
 		LastChecked: now,
 	})
+
+	// Also look up A/AAAA records for the apex domain so that
+	// port and TLS checks (which read HostnameState) can find
+	// the domain's IP addresses.
+	records, err := w.resolver.LookupAllRecords(ctx, domain)
+	if err != nil {
+		w.log.Error(
+			"failed to lookup records for domain",
+			"domain", domain,
+			"error", err,
+		)
+
+		return
+	}
+
+	prevHS, hasPrevHS := w.state.GetHostnameState(domain)
+	if hasPrevHS && !w.firstRun {
+		w.detectHostnameChanges(ctx, domain, prevHS, records)
+	}
+
+	newState := buildHostnameState(records, now)
+	w.state.SetHostnameState(domain, newState)
 }
 
 func (w *Watcher) detectNSChanges(
@@ -691,6 +718,22 @@ func (w *Watcher) checkTLSExpiry(
 		return
 	}
 
+	// Deduplicate expiry warnings: don't re-notify for the same
+	// hostname within the TLS check interval.
+	dedupKey := fmt.Sprintf("expiry:%s:%s", hostname, ip)
+
+	w.expiryNotifiedMu.Lock()
+
+	lastNotified, seen := w.expiryNotified[dedupKey]
+	if seen && time.Since(lastNotified) < w.config.TLSInterval {
+		w.expiryNotifiedMu.Unlock()
+
+		return
+	}
+
+	w.expiryNotified[dedupKey] = time.Now()
+	w.expiryNotifiedMu.Unlock()
+
 	msg := fmt.Sprintf(
 		"Host: %s\nIP: %s\nCN: %s\n"+
 			"Expires: %s (%.0f days)",

internal/watcher/watcher_test.go

@@ -273,6 +273,10 @@ func setupBaselineMocks(deps *testDeps) {
 		"ns1.example.com.",
 		"ns2.example.com.",
 	}
+	deps.resolver.allRecords["example.com"] = map[string]map[string][]string{
+		"ns1.example.com.": {"A": {"93.184.216.34"}},
+		"ns2.example.com.": {"A": {"93.184.216.34"}},
+	}
 	deps.resolver.allRecords["www.example.com"] = map[string]map[string][]string{
 		"ns1.example.com.": {"A": {"93.184.216.34"}},
 		"ns2.example.com.": {"A": {"93.184.216.34"}},
@@ -290,6 +294,14 @@ func setupBaselineMocks(deps *testDeps) {
 			"www.example.com",
 		},
 	}
+	deps.tlsChecker.certs["93.184.216.34:example.com"] = &tlscheck.CertificateInfo{
+		CommonName: "example.com",
+		Issuer:     "DigiCert",
+		NotAfter:   time.Now().Add(90 * 24 * time.Hour),
+		SubjectAlternativeNames: []string{
+			"example.com",
+		},
+	}
 }
 
 func assertNoNotifications(
@@ -322,14 +334,74 @@ func assertStatePopulated(
 		)
 	}
 
-	if len(snap.Hostnames) != 1 {
+	// Hostnames includes both explicit hostnames and domains
+	// (domains now also get hostname state for port/TLS checks).
+	if len(snap.Hostnames) < 1 {
 		t.Errorf(
-			"expected 1 hostname in state, got %d",
+			"expected at least 1 hostname in state, got %d",
 			len(snap.Hostnames),
 		)
 	}
 }
 
+func TestDomainPortAndTLSChecks(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{"example.com"}
+
+	w, deps := newTestWatcher(t, cfg)
+
+	deps.resolver.nsRecords["example.com"] = []string{
+		"ns1.example.com.",
+	}
+	deps.resolver.allRecords["example.com"] = map[string]map[string][]string{
+		"ns1.example.com.": {"A": {"93.184.216.34"}},
+	}
+	deps.portChecker.results["93.184.216.34:80"] = true
+	deps.portChecker.results["93.184.216.34:443"] = true
+	deps.tlsChecker.certs["93.184.216.34:example.com"] = &tlscheck.CertificateInfo{
+		CommonName: "example.com",
+		Issuer:     "DigiCert",
+		NotAfter:   time.Now().Add(90 * 24 * time.Hour),
+		SubjectAlternativeNames: []string{
+			"example.com",
+		},
+	}
+
+	w.RunOnce(t.Context())
+
+	snap := deps.state.GetSnapshot()
+
+	// Domain should have port state populated
+	if len(snap.Ports) == 0 {
+		t.Error("expected port state for domain, got none")
+	}
+
+	// Domain should have certificate state populated
+	if len(snap.Certificates) == 0 {
+		t.Error("expected certificate state for domain, got none")
+	}
+
+	// Verify port checker was actually called
+	deps.portChecker.mu.Lock()
+	calls := deps.portChecker.calls
+	deps.portChecker.mu.Unlock()
+
+	if calls == 0 {
+		t.Error("expected port checker to be called for domain")
+	}
+
+	// Verify TLS checker was actually called
+	deps.tlsChecker.mu.Lock()
+	tlsCalls := deps.tlsChecker.calls
+	deps.tlsChecker.mu.Unlock()
+
+	if tlsCalls == 0 {
+		t.Error("expected TLS checker to be called for domain")
+	}
+}
+
 func TestNSChangeDetection(t *testing.T) {
 	t.Parallel()
 
@@ -342,6 +414,12 @@ func TestNSChangeDetection(t *testing.T) {
 		"ns1.example.com.",
 		"ns2.example.com.",
 	}
+	deps.resolver.allRecords["example.com"] = map[string]map[string][]string{
+		"ns1.example.com.": {"A": {"1.2.3.4"}},
+		"ns2.example.com.": {"A": {"1.2.3.4"}},
+	}
+	deps.portChecker.results["1.2.3.4:80"] = false
+	deps.portChecker.results["1.2.3.4:443"] = false
 
 	ctx := t.Context()
 	w.RunOnce(ctx)
@@ -351,6 +429,10 @@ func TestNSChangeDetection(t *testing.T) {
 		"ns1.example.com.",
 		"ns3.example.com.",
 	}
+	deps.resolver.allRecords["example.com"] = map[string]map[string][]string{
+		"ns1.example.com.": {"A": {"1.2.3.4"}},
+		"ns3.example.com.": {"A": {"1.2.3.4"}},
+	}
 	deps.resolver.mu.Unlock()
 
 	w.RunOnce(ctx)
@@ -506,6 +588,61 @@ func TestTLSExpiryWarning(t *testing.T) {
 	}
 }
 
+func TestTLSExpiryWarningDedup(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Hostnames = []string{"www.example.com"}
+	cfg.TLSInterval = 24 * time.Hour
+
+	w, deps := newTestWatcher(t, cfg)
+
+	deps.resolver.allRecords["www.example.com"] = map[string]map[string][]string{
+		"ns1.example.com.": {"A": {"1.2.3.4"}},
+	}
+	deps.resolver.ipAddresses["www.example.com"] = []string{
+		"1.2.3.4",
+	}
+	deps.portChecker.results["1.2.3.4:80"] = true
+	deps.portChecker.results["1.2.3.4:443"] = true
+	deps.tlsChecker.certs["1.2.3.4:www.example.com"] = &tlscheck.CertificateInfo{
+		CommonName: "www.example.com",
+		Issuer:     "DigiCert",
+		NotAfter:   time.Now().Add(3 * 24 * time.Hour),
+		SubjectAlternativeNames: []string{
+			"www.example.com",
+		},
+	}
+
+	ctx := t.Context()
+
+	// First run = baseline, no notifications
+	w.RunOnce(ctx)
+
+	// Second run should fire one expiry warning
+	w.RunOnce(ctx)
+
+	// Third run should NOT fire another warning (dedup)
+	w.RunOnce(ctx)
+
+	notifications := deps.notifier.getNotifications()
+
+	expiryCount := 0
+
+	for _, n := range notifications {
+		if n.Title == "TLS Expiry Warning: www.example.com" {
+			expiryCount++
+		}
+	}
+
+	if expiryCount != 1 {
+		t.Errorf(
+			"expected exactly 1 expiry warning (dedup), got %d",
+			expiryCount,
+		)
+	}
+}
+
 func TestGracefulShutdown(t *testing.T) {
 	t.Parallel()
 
@@ -519,6 +656,11 @@ func TestGracefulShutdown(t *testing.T) {
 	deps.resolver.nsRecords["example.com"] = []string{
 		"ns1.example.com.",
 	}
+	deps.resolver.allRecords["example.com"] = map[string]map[string][]string{
+		"ns1.example.com.": {"A": {"1.2.3.4"}},
+	}
+	deps.portChecker.results["1.2.3.4:80"] = false
+	deps.portChecker.results["1.2.3.4:443"] = false
 
 	ctx, cancel := context.WithCancel(t.Context())