Merge branch 'main' into feature/watcher-implementation

Reviewed-on: #11

README.md

@@ -1,5 +1,7 @@
 # dnswatcher
 
+> ⚠️ Pre-1.0 software. APIs, configuration, and behavior may change without notice.
+
 dnswatcher is a production DNS and infrastructure monitoring daemon written in
 Go.  It watches configured DNS domains and hostnames for changes, monitors TCP
 port availability, tracks TLS certificate expiry, and delivers real-time
@@ -195,8 +197,7 @@ the following precedence (highest to lowest):
 | `PORT`                          | HTTP listen port                           | `8080`      |
 | `DNSWATCHER_DEBUG`              | Enable debug logging                       | `false`     |
 | `DNSWATCHER_DATA_DIR`           | Directory for state file                   | `./data`    |
-| `DNSWATCHER_DOMAINS`            | Comma-separated list of apex domains       | `""`        |
-| `DNSWATCHER_HOSTNAMES`          | Comma-separated list of hostnames          | `""`        |
+| `DNSWATCHER_TARGETS`            | Comma-separated DNS names (auto-classified via PSL) | `""`  |
 | `DNSWATCHER_SLACK_WEBHOOK`      | Slack incoming webhook URL                 | `""`        |
 | `DNSWATCHER_MATTERMOST_WEBHOOK` | Mattermost incoming webhook URL            | `""`        |
 | `DNSWATCHER_NTFY_TOPIC`         | ntfy topic URL                             | `""`        |
@@ -214,8 +215,7 @@ the following precedence (highest to lowest):
 PORT=8080
 DNSWATCHER_DEBUG=false
 DNSWATCHER_DATA_DIR=./data
-DNSWATCHER_DOMAINS=example.com,example.org
-DNSWATCHER_HOSTNAMES=www.example.com,api.example.com,mail.example.org
+DNSWATCHER_TARGETS=example.com,example.org,www.example.com,api.example.com,mail.example.org
 DNSWATCHER_SLACK_WEBHOOK=https://hooks.slack.com/services/T.../B.../xxx
 DNSWATCHER_MATTERMOST_WEBHOOK=https://mattermost.example.com/hooks/xxx
 DNSWATCHER_NTFY_TOPIC=https://ntfy.sh/my-dns-alerts
@@ -352,8 +352,7 @@ docker build -t dnswatcher .
 docker run -d \
   -p 8080:8080 \
   -v dnswatcher-data:/var/lib/dnswatcher \
-  -e DNSWATCHER_DOMAINS=example.com \
-  -e DNSWATCHER_HOSTNAMES=www.example.com \
+  -e DNSWATCHER_TARGETS=example.com,www.example.com \
   -e DNSWATCHER_NTFY_TOPIC=https://ntfy.sh/my-alerts \
   dnswatcher
 ```
@@ -377,13 +376,6 @@ docker run -d \
 
 ---
 
-## Planned Future Features (Post-1.0)
-
-- **DNSSEC validation**: Validate the DNSSEC chain of trust during
-  iterative resolution and report DNSSEC failures as notifications.
-
----
-
 ## Project Structure
 
 Follows the conventions defined in `CONVENTIONS.md`, adapted from the

cmd/dnswatcher/main.go

@@ -51,6 +51,20 @@ func main() {
 			handlers.New,
 			server.New,
 		),
+		fx.Provide(
+			func(r *resolver.Resolver) watcher.DNSResolver {
+				return r
+			},
+			func(p *portcheck.Checker) watcher.PortChecker {
+				return p
+			},
+			func(t *tlscheck.Checker) watcher.TLSChecker {
+				return t
+			},
+			func(n *notify.Service) watcher.Notifier {
+				return n
+			},
+		),
 		fx.Invoke(func(*server.Server, *watcher.Watcher) {}),
 	).Run()
 }

go.mod

@@ -7,22 +7,19 @@ require (
 	github.com/go-chi/chi/v5 v5.2.5
 	github.com/go-chi/cors v1.2.2
 	github.com/joho/godotenv v1.5.1
-	github.com/miekg/dns v1.1.72
 	github.com/prometheus/client_golang v1.23.2
 	github.com/spf13/viper v1.21.0
-	github.com/stretchr/testify v1.11.1
 	go.uber.org/fx v1.24.0
+	golang.org/x/net v0.50.0
 )
 
 require (
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
-	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/fsnotify/fsnotify v1.9.0 // indirect
 	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
-	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/prometheus/client_model v0.6.2 // indirect
 	github.com/prometheus/common v0.66.1 // indirect
 	github.com/prometheus/procfs v0.16.1 // indirect
@@ -37,12 +34,7 @@ require (
 	go.uber.org/zap v1.26.0 // indirect
 	go.yaml.in/yaml/v2 v2.4.2 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
-	golang.org/x/mod v0.31.0 // indirect
-	golang.org/x/net v0.48.0 // indirect
-	golang.org/x/sync v0.19.0 // indirect
-	golang.org/x/sys v0.39.0 // indirect
-	golang.org/x/text v0.32.0 // indirect
-	golang.org/x/tools v0.40.0 // indirect
+	golang.org/x/sys v0.41.0 // indirect
+	golang.org/x/text v0.34.0 // indirect
 	google.golang.org/protobuf v1.36.8 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -28,8 +28,6 @@ github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
 github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
-github.com/miekg/dns v1.1.72 h1:vhmr+TF2A3tuoGNkLDFK9zi36F2LS+hKTRW0Uf8kbzI=
-github.com/miekg/dns v1.1.72/go.mod h1:+EuEPhdHOsfk6Wk5TT2CzssZdqkmFhf8r+aVyDEToIs=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
 github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
@@ -76,18 +74,12 @@ go.yaml.in/yaml/v2 v2.4.2 h1:DzmwEr2rDGHl7lsFgAHxmNz/1NlQ7xLIrlN2h5d1eGI=
 go.yaml.in/yaml/v2 v2.4.2/go.mod h1:081UH+NErpNdqlCXm3TtEran0rJZGxAYx9hb/ELlsPU=
 go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
-golang.org/x/mod v0.31.0 h1:HaW9xtz0+kOcWKwli0ZXy79Ix+UW/vOfmWI5QVd2tgI=
-golang.org/x/mod v0.31.0/go.mod h1:43JraMp9cGx1Rx3AqioxrbrhNsLl2l/iNAvuBkrezpg=
-golang.org/x/net v0.48.0 h1:zyQRTTrjc33Lhh0fBgT/H3oZq9WuvRR5gPC70xpDiQU=
-golang.org/x/net v0.48.0/go.mod h1:+ndRgGjkh8FGtu1w1FGbEC31if4VrNVMuKTgcAAnQRY=
-golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
-golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
-golang.org/x/sys v0.39.0 h1:CvCKL8MeisomCi6qNZ+wbb0DN9E5AATixKsvNtMoMFk=
-golang.org/x/sys v0.39.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
-golang.org/x/text v0.32.0 h1:ZD01bjUt1FQ9WJ0ClOL5vxgxOI/sVCNgX1YtKwcY0mU=
-golang.org/x/text v0.32.0/go.mod h1:o/rUWzghvpD5TXrTIBuJU77MTaN0ljMWE47kxGJQ7jY=
-golang.org/x/tools v0.40.0 h1:yLkxfA+Qnul4cs9QA3KnlFu0lVmd8JJfoq+E41uSutA=
-golang.org/x/tools v0.40.0/go.mod h1:Ik/tzLRlbscWpqqMRjyWYDisX8bG13FrdXp3o4Sr9lc=
+golang.org/x/net v0.50.0 h1:ucWh9eiCGyDR3vtzso0WMQinm2Dnt8cFMuQa9K33J60=
+golang.org/x/net v0.50.0/go.mod h1:UgoSli3F/pBgdJBHCTc+tp3gmrU4XswgGRgtnwWTfyM=
+golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
+golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
+golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
 google.golang.org/protobuf v1.36.8 h1:xHScyCOEuuwZEc6UtSOvPbAT4zRh0xcNRYekJwfqyMc=
 google.golang.org/protobuf v1.36.8/go.mod h1:fuxRtAxBytpl4zzqUh6/eyUujkJdNiuEkXntxiD/uRU=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

internal/config/classify.go

@@ -0,0 +1,85 @@
+package config
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+
+	"golang.org/x/net/publicsuffix"
+)
+
+// DNSNameType indicates whether a DNS name is an apex domain or a hostname.
+type DNSNameType int
+
+const (
+	// DNSNameTypeDomain indicates the name is an apex (eTLD+1) domain.
+	DNSNameTypeDomain DNSNameType = iota
+	// DNSNameTypeHostname indicates the name is a subdomain/hostname.
+	DNSNameTypeHostname
+)
+
+// ErrEmptyDNSName is returned when an empty string is passed to ClassifyDNSName.
+var ErrEmptyDNSName = errors.New("empty DNS name")
+
+// String returns the string representation of a DNSNameType.
+func (t DNSNameType) String() string {
+	switch t {
+	case DNSNameTypeDomain:
+		return "domain"
+	case DNSNameTypeHostname:
+		return "hostname"
+	default:
+		return "unknown"
+	}
+}
+
+// ClassifyDNSName determines whether a DNS name is an apex domain or a
+// hostname (subdomain) using the Public Suffix List. It returns an error
+// if the input is empty or is itself a public suffix (e.g. "co.uk").
+func ClassifyDNSName(name string) (DNSNameType, error) {
+	name = strings.ToLower(strings.TrimSuffix(strings.TrimSpace(name), "."))
+
+	if name == "" {
+		return 0, ErrEmptyDNSName
+	}
+
+	etld1, err := publicsuffix.EffectiveTLDPlusOne(name)
+	if err != nil {
+		return 0, fmt.Errorf("invalid DNS name %q: %w", name, err)
+	}
+
+	if name == etld1 {
+		return DNSNameTypeDomain, nil
+	}
+
+	return DNSNameTypeHostname, nil
+}
+
+// ClassifyTargets splits a list of DNS names into apex domains and
+// hostnames using the Public Suffix List. It returns an error if any
+// name cannot be classified.
+func ClassifyTargets(targets []string) ([]string, []string, error) {
+	var domains, hostnames []string
+
+	for _, t := range targets {
+		normalized := strings.ToLower(strings.TrimSuffix(strings.TrimSpace(t), "."))
+
+		if normalized == "" {
+			continue
+		}
+
+		typ, classErr := ClassifyDNSName(normalized)
+		if classErr != nil {
+			return nil, nil, classErr
+		}
+
+		switch typ {
+		case DNSNameTypeDomain:
+			domains = append(domains, normalized)
+		case DNSNameTypeHostname:
+			hostnames = append(hostnames, normalized)
+		}
+	}
+
+	return domains, hostnames, nil
+}

internal/config/classify_test.go

@@ -0,0 +1,83 @@
+package config_test
+
+import (
+	"testing"
+
+	"sneak.berlin/go/dnswatcher/internal/config"
+)
+
+func TestClassifyDNSName(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		input   string
+		want    config.DNSNameType
+		wantErr bool
+	}{
+		{name: "apex domain simple", input: "example.com", want: config.DNSNameTypeDomain},
+		{name: "hostname simple", input: "www.example.com", want: config.DNSNameTypeHostname},
+		{name: "apex domain multi-part TLD", input: "example.co.uk", want: config.DNSNameTypeDomain},
+		{name: "hostname multi-part TLD", input: "api.example.co.uk", want: config.DNSNameTypeHostname},
+		{name: "public suffix itself", input: "co.uk", wantErr: true},
+		{name: "empty string", input: "", wantErr: true},
+		{name: "deeply nested hostname", input: "a.b.c.example.com", want: config.DNSNameTypeHostname},
+		{name: "trailing dot stripped", input: "example.com.", want: config.DNSNameTypeDomain},
+		{name: "uppercase normalized", input: "WWW.Example.COM", want: config.DNSNameTypeHostname},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got, err := config.ClassifyDNSName(tt.input)
+
+			if tt.wantErr {
+				if err == nil {
+					t.Errorf("ClassifyDNSName(%q) expected error, got %v", tt.input, got)
+				}
+
+				return
+			}
+
+			if err != nil {
+				t.Fatalf("ClassifyDNSName(%q) unexpected error: %v", tt.input, err)
+			}
+
+			if got != tt.want {
+				t.Errorf("ClassifyDNSName(%q) = %v, want %v", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestClassifyTargets(t *testing.T) {
+	t.Parallel()
+
+	domains, hostnames, err := config.ClassifyTargets([]string{
+		"example.com",
+		"www.example.com",
+		"example.co.uk",
+		"api.example.co.uk",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if len(domains) != 2 {
+		t.Errorf("expected 2 domains, got %d: %v", len(domains), domains)
+	}
+
+	if len(hostnames) != 2 {
+		t.Errorf("expected 2 hostnames, got %d: %v", len(hostnames), hostnames)
+	}
+}
+
+func TestClassifyTargetsRejectsPublicSuffix(t *testing.T) {
+	t.Parallel()
+
+	_, _, err := config.ClassifyTargets([]string{"co.uk"})
+	if err == nil {
+		t.Error("expected error for public suffix, got nil")
+	}
+}

internal/config/config.go

@@ -89,8 +89,7 @@ func setupViper(name string) {
 	viper.SetDefault("PORT", defaultPort)
 	viper.SetDefault("DEBUG", false)
 	viper.SetDefault("DATA_DIR", "./data")
-	viper.SetDefault("DOMAINS", "")
-	viper.SetDefault("HOSTNAMES", "")
+	viper.SetDefault("TARGETS", "")
 	viper.SetDefault("SLACK_WEBHOOK", "")
 	viper.SetDefault("MATTERMOST_WEBHOOK", "")
 	viper.SetDefault("NTFY_TOPIC", "")
@@ -133,12 +132,19 @@ func buildConfig(
 		tlsInterval = defaultTLSInterval
 	}
 
+	domains, hostnames, err := ClassifyTargets(
+		parseCSV(viper.GetString("TARGETS")),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("invalid targets configuration: %w", err)
+	}
+
 	cfg := &Config{
 		Port:              viper.GetInt("PORT"),
 		Debug:             viper.GetBool("DEBUG"),
 		DataDir:           viper.GetString("DATA_DIR"),
-		Domains:           parseCSV(viper.GetString("DOMAINS")),
-		Hostnames:         parseCSV(viper.GetString("HOSTNAMES")),
+		Domains:           domains,
+		Hostnames:         hostnames,
 		SlackWebhook:      viper.GetString("SLACK_WEBHOOK"),
 		MattermostWebhook: viper.GetString("MATTERMOST_WEBHOOK"),
 		NtfyTopic:         viper.GetString("NTFY_TOPIC"),

internal/notify/notify.go

@@ -36,16 +36,6 @@ var (
 	)
 )
 
-// sanitizeURL parses and re-serializes a URL to satisfy static analysis (gosec G704).
-func sanitizeURL(raw string) (string, error) {
-	u, err := url.Parse(raw)
-	if err != nil {
-		return "", fmt.Errorf("invalid URL %q: %w", raw, err)
-	}
-
-	return u.String(), nil
-}
-
 // Params contains dependencies for Service.
 type Params struct {
 	fx.In
@@ -56,9 +46,12 @@ type Params struct {
 
 // Service provides notification functionality.
 type Service struct {
-	log    *slog.Logger
-	client *http.Client
-	config *config.Config
+	log                  *slog.Logger
+	client               *http.Client
+	config               *config.Config
+	ntfyURL              *url.URL
+	slackWebhookURL      *url.URL
+	mattermostWebhookURL *url.URL
 }
 
 // New creates a new notify Service.
@@ -66,13 +59,44 @@ func New(
 	_ fx.Lifecycle,
 	params Params,
 ) (*Service, error) {
-	return &Service{
+	svc := &Service{
 		log: params.Logger.Get(),
 		client: &http.Client{
 			Timeout: httpClientTimeout,
 		},
 		config: params.Config,
-	}, nil
+	}
+
+	if params.Config.NtfyTopic != "" {
+		u, err := url.ParseRequestURI(params.Config.NtfyTopic)
+		if err != nil {
+			return nil, fmt.Errorf("invalid ntfy topic URL: %w", err)
+		}
+
+		svc.ntfyURL = u
+	}
+
+	if params.Config.SlackWebhook != "" {
+		u, err := url.ParseRequestURI(params.Config.SlackWebhook)
+		if err != nil {
+			return nil, fmt.Errorf("invalid slack webhook URL: %w", err)
+		}
+
+		svc.slackWebhookURL = u
+	}
+
+	if params.Config.MattermostWebhook != "" {
+		u, err := url.ParseRequestURI(params.Config.MattermostWebhook)
+		if err != nil {
+			return nil, fmt.Errorf(
+				"invalid mattermost webhook URL: %w", err,
+			)
+		}
+
+		svc.mattermostWebhookURL = u
+	}
+
+	return svc, nil
 }
 
 // SendNotification sends a notification to all configured endpoints.
@@ -80,13 +104,13 @@ func (svc *Service) SendNotification(
 	ctx context.Context,
 	title, message, priority string,
 ) {
-	if svc.config.NtfyTopic != "" {
+	if svc.ntfyURL != nil {
 		go func() {
 			notifyCtx := context.WithoutCancel(ctx)
 
 			err := svc.sendNtfy(
 				notifyCtx,
-				svc.config.NtfyTopic,
+				svc.ntfyURL,
 				title, message, priority,
 			)
 			if err != nil {
@@ -98,13 +122,13 @@ func (svc *Service) SendNotification(
 		}()
 	}
 
-	if svc.config.SlackWebhook != "" {
+	if svc.slackWebhookURL != nil {
 		go func() {
 			notifyCtx := context.WithoutCancel(ctx)
 
 			err := svc.sendSlack(
 				notifyCtx,
-				svc.config.SlackWebhook,
+				svc.slackWebhookURL,
 				title, message, priority,
 			)
 			if err != nil {
@@ -116,13 +140,13 @@ func (svc *Service) SendNotification(
 		}()
 	}
 
-	if svc.config.MattermostWebhook != "" {
+	if svc.mattermostWebhookURL != nil {
 		go func() {
 			notifyCtx := context.WithoutCancel(ctx)
 
 			err := svc.sendSlack(
 				notifyCtx,
-				svc.config.MattermostWebhook,
+				svc.mattermostWebhookURL,
 				title, message, priority,
 			)
 			if err != nil {
@@ -137,23 +161,19 @@ func (svc *Service) SendNotification(
 
 func (svc *Service) sendNtfy(
 	ctx context.Context,
-	topic, title, message, priority string,
+	topicURL *url.URL,
+	title, message, priority string,
 ) error {
 	svc.log.Debug(
 		"sending ntfy notification",
-		"topic", topic,
+		"topic", topicURL.String(),
 		"title", title,
 	)
 
-	cleanURL, err := sanitizeURL(topic)
-	if err != nil {
-		return fmt.Errorf("invalid ntfy topic URL: %w", err)
-	}
-
 	request, err := http.NewRequestWithContext(
 		ctx,
 		http.MethodPost,
-		cleanURL,
+		topicURL.String(),
 		bytes.NewBufferString(message),
 	)
 	if err != nil {
@@ -163,7 +183,7 @@ func (svc *Service) sendNtfy(
 	request.Header.Set("Title", title)
 	request.Header.Set("Priority", ntfyPriority(priority))
 
-	resp, err := svc.client.Do(request) // #nosec G704 -- URL comes from validated application config
+	resp, err := svc.client.Do(request) //nolint:gosec // URL validated at Service construction time
 	if err != nil {
 		return fmt.Errorf("sending ntfy request: %w", err)
 	}
@@ -209,11 +229,12 @@ type SlackAttachment struct {
 
 func (svc *Service) sendSlack(
 	ctx context.Context,
-	webhookURL, title, message, priority string,
+	webhookURL *url.URL,
+	title, message, priority string,
 ) error {
 	svc.log.Debug(
 		"sending webhook notification",
-		"url", webhookURL,
+		"url", webhookURL.String(),
 		"title", title,
 	)
 
@@ -232,15 +253,10 @@ func (svc *Service) sendSlack(
 		return fmt.Errorf("marshaling webhook payload: %w", err)
 	}
 
-	cleanURL, err := sanitizeURL(webhookURL)
-	if err != nil {
-		return fmt.Errorf("invalid webhook URL: %w", err)
-	}
-
 	request, err := http.NewRequestWithContext(
 		ctx,
 		http.MethodPost,
-		cleanURL,
+		webhookURL.String(),
 		bytes.NewBuffer(body),
 	)
 	if err != nil {
@@ -249,7 +265,7 @@ func (svc *Service) sendSlack(
 
 	request.Header.Set("Content-Type", "application/json")
 
-	resp, err := svc.client.Do(request) // #nosec G704 -- URL comes from validated application config
+	resp, err := svc.client.Do(request) //nolint:gosec // URL validated at Service construction time
 	if err != nil {
 		return fmt.Errorf("sending webhook request: %w", err)
 	}

internal/resolver/errors.go

@@ -1,27 +0,0 @@
-package resolver
-
-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(
-		"no authoritative nameservers found",
-	)
-
-	// ErrCNAMEDepthExceeded is returned when a CNAME chain
-	// exceeds MaxCNAMEDepth.
-	ErrCNAMEDepthExceeded = errors.New(
-		"CNAME chain depth exceeded",
-	)
-
-	// ErrContextCanceled wraps context cancellation for the
-	// resolver's iterative queries.
-	ErrContextCanceled = errors.New("context canceled")
-)

internal/resolver/iterative.go

@@ -1,716 +0,0 @@
-package resolver
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"net"
-	"sort"
-	"strings"
-	"time"
-
-	"github.com/miekg/dns"
-)
-
-const (
-	queryTimeoutDuration = 5 * time.Second
-	maxRetries           = 2
-	maxDelegation        = 20
-	timeoutMultiplier    = 2
-	minDomainLabels      = 2
-)
-
-// ErrRefused is returned when a DNS server refuses a query.
-var ErrRefused = errors.New("dns query refused")
-
-func rootServerList() []string {
-	return []string{
-		"198.41.0.4",     // a.root-servers.net
-		"170.247.170.2",  // b
-		"192.33.4.12",    // c
-		"199.7.91.13",    // d
-		"192.203.230.10", // e
-		"192.5.5.241",    // f
-		"192.112.36.4",   // g
-		"198.97.190.53",  // h
-		"192.36.148.17",  // i
-		"192.58.128.30",  // j
-		"193.0.14.129",   // k
-		"199.7.83.42",    // l
-		"202.12.27.33",   // m
-	}
-}
-
-func checkCtx(ctx context.Context) error {
-	err := ctx.Err()
-	if err != nil {
-		return ErrContextCanceled
-	}
-
-	return nil
-}
-
-func exchangeWithTimeout(
-	ctx context.Context,
-	msg *dns.Msg,
-	addr string,
-	attempt int,
-) (*dns.Msg, error) {
-	c := new(dns.Client)
-	c.Timeout = queryTimeoutDuration
-
-	if attempt > 0 {
-		c.Timeout = queryTimeoutDuration * timeoutMultiplier
-	}
-
-	resp, _, err := c.ExchangeContext(ctx, msg, addr)
-
-	return resp, err
-}
-
-func tryExchange(
-	ctx context.Context,
-	msg *dns.Msg,
-	addr string,
-) (*dns.Msg, error) {
-	var resp *dns.Msg
-
-	var err error
-
-	for attempt := range maxRetries {
-		if checkCtx(ctx) != nil {
-			return nil, ErrContextCanceled
-		}
-
-		resp, err = exchangeWithTimeout(ctx, msg, addr, attempt)
-		if err == nil {
-			break
-		}
-	}
-
-	return resp, err
-}
-
-func retryTCP(
-	ctx context.Context,
-	msg *dns.Msg,
-	addr string,
-	resp *dns.Msg,
-) *dns.Msg {
-	if !resp.Truncated {
-		return resp
-	}
-
-	c := &dns.Client{
-		Net:     "tcp",
-		Timeout: queryTimeoutDuration,
-	}
-
-	tcpResp, _, tcpErr := c.ExchangeContext(ctx, msg, addr)
-	if tcpErr == nil {
-		return tcpResp
-	}
-
-	return resp
-}
-
-// queryDNS sends a DNS query to a specific server IP.
-// Tries non-recursive first, falls back to recursive on
-// REFUSED (handles DNS interception environments).
-func queryDNS(
-	ctx context.Context,
-	serverIP string,
-	name string,
-	qtype uint16,
-) (*dns.Msg, error) {
-	if checkCtx(ctx) != nil {
-		return nil, ErrContextCanceled
-	}
-
-	name = dns.Fqdn(name)
-	addr := net.JoinHostPort(serverIP, "53")
-
-	msg := new(dns.Msg)
-	msg.SetQuestion(name, qtype)
-	msg.RecursionDesired = false
-
-	resp, err := tryExchange(ctx, msg, addr)
-	if err != nil {
-		return nil, fmt.Errorf("query %s @%s: %w", name, serverIP, err)
-	}
-
-	if resp.Rcode == dns.RcodeRefused {
-		msg.RecursionDesired = true
-
-		resp, err = tryExchange(ctx, msg, addr)
-		if err != nil {
-			return nil, fmt.Errorf(
-				"query %s @%s: %w", name, serverIP, err,
-			)
-		}
-
-		if resp.Rcode == dns.RcodeRefused {
-			return nil, fmt.Errorf(
-				"query %s @%s: %w", name, serverIP, ErrRefused,
-			)
-		}
-	}
-
-	resp = retryTCP(ctx, msg, addr, resp)
-
-	return resp, nil
-}
-
-func extractNSSet(rrs []dns.RR) []string {
-	nsSet := make(map[string]bool)
-
-	for _, rr := range rrs {
-		if ns, ok := rr.(*dns.NS); ok {
-			nsSet[strings.ToLower(ns.Ns)] = true
-		}
-	}
-
-	names := make([]string, 0, len(nsSet))
-	for n := range nsSet {
-		names = append(names, n)
-	}
-
-	sort.Strings(names)
-
-	return names
-}
-
-func extractGlue(rrs []dns.RR) map[string][]net.IP {
-	glue := make(map[string][]net.IP)
-
-	for _, rr := range rrs {
-		switch r := rr.(type) {
-		case *dns.A:
-			name := strings.ToLower(r.Hdr.Name)
-			glue[name] = append(glue[name], r.A)
-		case *dns.AAAA:
-			name := strings.ToLower(r.Hdr.Name)
-			glue[name] = append(glue[name], r.AAAA)
-		}
-	}
-
-	return glue
-}
-
-func glueIPs(nsNames []string, glue map[string][]net.IP) []string {
-	var ips []string
-
-	for _, ns := range nsNames {
-		for _, addr := range glue[ns] {
-			if v4 := addr.To4(); v4 != nil {
-				ips = append(ips, v4.String())
-			}
-		}
-	}
-
-	return ips
-}
-
-func (r *Resolver) followDelegation(
-	ctx context.Context,
-	domain string,
-	servers []string,
-) ([]string, error) {
-	for range maxDelegation {
-		if checkCtx(ctx) != nil {
-			return nil, ErrContextCanceled
-		}
-
-		resp, err := queryServers(ctx, servers, domain, dns.TypeNS)
-		if err != nil {
-			return nil, err
-		}
-
-		ansNS := extractNSSet(resp.Answer)
-		if len(ansNS) > 0 {
-			return ansNS, nil
-		}
-
-		authNS := extractNSSet(resp.Ns)
-		if len(authNS) == 0 {
-			return r.resolveNSRecursive(ctx, domain)
-		}
-
-		glue := extractGlue(resp.Extra)
-		nextServers := glueIPs(authNS, glue)
-
-		if len(nextServers) == 0 {
-			nextServers = r.resolveNSIPs(ctx, authNS)
-		}
-
-		if len(nextServers) == 0 {
-			return nil, ErrNoNameservers
-		}
-
-		servers = nextServers
-	}
-
-	return nil, ErrNoNameservers
-}
-
-func queryServers(
-	ctx context.Context,
-	servers []string,
-	name string,
-	qtype uint16,
-) (*dns.Msg, error) {
-	var lastErr error
-
-	for _, ip := range servers {
-		if checkCtx(ctx) != nil {
-			return nil, ErrContextCanceled
-		}
-
-		resp, err := queryDNS(ctx, ip, name, qtype)
-		if err == nil {
-			return resp, nil
-		}
-
-		lastErr = err
-	}
-
-	return nil, fmt.Errorf("all servers failed: %w", lastErr)
-}
-
-func (r *Resolver) resolveNSIPs(
-	ctx context.Context,
-	nsNames []string,
-) []string {
-	var ips []string
-
-	for _, ns := range nsNames {
-		resolved, err := r.resolveARecord(ctx, ns)
-		if err == nil {
-			ips = append(ips, resolved...)
-		}
-
-		if len(ips) > 0 {
-			break
-		}
-	}
-
-	return ips
-}
-
-// resolveNSRecursive queries for NS records using recursive
-// resolution as a fallback for intercepted environments.
-func (r *Resolver) resolveNSRecursive(
-	ctx context.Context,
-	domain string,
-) ([]string, error) {
-	domain = dns.Fqdn(domain)
-	msg := new(dns.Msg)
-	msg.SetQuestion(domain, dns.TypeNS)
-	msg.RecursionDesired = true
-
-	c := &dns.Client{Timeout: queryTimeoutDuration}
-
-	for _, ip := range rootServerList()[:3] {
-		if checkCtx(ctx) != nil {
-			return nil, ErrContextCanceled
-		}
-
-		addr := net.JoinHostPort(ip, "53")
-
-		resp, _, err := c.ExchangeContext(ctx, msg, addr)
-		if err != nil {
-			continue
-		}
-
-		nsNames := extractNSSet(resp.Answer)
-		if len(nsNames) > 0 {
-			return nsNames, nil
-		}
-	}
-
-	return nil, ErrNoNameservers
-}
-
-// resolveARecord resolves a hostname to IPv4 addresses.
-func (r *Resolver) resolveARecord(
-	ctx context.Context,
-	hostname string,
-) ([]string, error) {
-	hostname = dns.Fqdn(hostname)
-	msg := new(dns.Msg)
-	msg.SetQuestion(hostname, dns.TypeA)
-	msg.RecursionDesired = true
-
-	c := &dns.Client{Timeout: queryTimeoutDuration}
-
-	for _, ip := range rootServerList()[:3] {
-		if checkCtx(ctx) != nil {
-			return nil, ErrContextCanceled
-		}
-
-		addr := net.JoinHostPort(ip, "53")
-
-		resp, _, err := c.ExchangeContext(ctx, msg, addr)
-		if err != nil {
-			continue
-		}
-
-		var ips []string
-
-		for _, rr := range resp.Answer {
-			if a, ok := rr.(*dns.A); ok {
-				ips = append(ips, a.A.String())
-			}
-		}
-
-		if len(ips) > 0 {
-			return ips, nil
-		}
-	}
-
-	return nil, fmt.Errorf(
-		"cannot resolve %s: %w", hostname, ErrNoNameservers,
-	)
-}
-
-// FindAuthoritativeNameservers traces the delegation chain from
-// root servers to discover all authoritative nameservers for the
-// given domain. Walks up the label hierarchy for subdomains.
-func (r *Resolver) FindAuthoritativeNameservers(
-	ctx context.Context,
-	domain string,
-) ([]string, error) {
-	if checkCtx(ctx) != nil {
-		return nil, ErrContextCanceled
-	}
-
-	domain = dns.Fqdn(strings.ToLower(domain))
-	labels := dns.SplitDomainName(domain)
-
-	for i := range labels {
-		if checkCtx(ctx) != nil {
-			return nil, ErrContextCanceled
-		}
-
-		candidate := strings.Join(labels[i:], ".") + "."
-
-		nsNames, err := r.followDelegation(
-			ctx, candidate, rootServerList(),
-		)
-		if err == nil && len(nsNames) > 0 {
-			sort.Strings(nsNames)
-
-			return nsNames, nil
-		}
-	}
-
-	return nil, ErrNoNameservers
-}
-
-// QueryNameserver queries a specific nameserver for all record
-// types and builds a NameserverResponse.
-func (r *Resolver) QueryNameserver(
-	ctx context.Context,
-	nsHostname string,
-	hostname string,
-) (*NameserverResponse, error) {
-	if checkCtx(ctx) != nil {
-		return nil, ErrContextCanceled
-	}
-
-	nsIPs, err := r.resolveARecord(ctx, nsHostname)
-	if err != nil {
-		return nil, fmt.Errorf("resolving NS %s: %w", nsHostname, err)
-	}
-
-	hostname = dns.Fqdn(hostname)
-
-	return r.queryAllTypes(ctx, nsHostname, nsIPs[0], hostname)
-}
-
-func (r *Resolver) queryAllTypes(
-	ctx context.Context,
-	nsHostname string,
-	nsIP string,
-	hostname string,
-) (*NameserverResponse, error) {
-	resp := &NameserverResponse{
-		Nameserver: nsHostname,
-		Records:    make(map[string][]string),
-		Status:     StatusOK,
-	}
-
-	qtypes := []uint16{
-		dns.TypeA, dns.TypeAAAA, dns.TypeCNAME,
-		dns.TypeMX, dns.TypeTXT, dns.TypeSRV,
-		dns.TypeCAA, dns.TypeNS,
-	}
-
-	state := r.queryEachType(ctx, nsIP, hostname, qtypes, resp)
-	classifyResponse(resp, state)
-
-	return resp, nil
-}
-
-type queryState struct {
-	gotNXDomain bool
-	gotSERVFAIL bool
-	hasRecords  bool
-}
-
-func (r *Resolver) queryEachType(
-	ctx context.Context,
-	nsIP string,
-	hostname string,
-	qtypes []uint16,
-	resp *NameserverResponse,
-) queryState {
-	var state queryState
-
-	for _, qtype := range qtypes {
-		if checkCtx(ctx) != nil {
-			break
-		}
-
-		r.querySingleType(ctx, nsIP, hostname, qtype, resp, &state)
-	}
-
-	for k := range resp.Records {
-		sort.Strings(resp.Records[k])
-	}
-
-	return state
-}
-
-func (r *Resolver) querySingleType(
-	ctx context.Context,
-	nsIP string,
-	hostname string,
-	qtype uint16,
-	resp *NameserverResponse,
-	state *queryState,
-) {
-	msg, err := queryDNS(ctx, nsIP, hostname, qtype)
-	if err != nil {
-		return
-	}
-
-	if msg.Rcode == dns.RcodeNameError {
-		state.gotNXDomain = true
-
-		return
-	}
-
-	if msg.Rcode == dns.RcodeServerFailure {
-		state.gotSERVFAIL = true
-
-		return
-	}
-
-	collectAnswerRecords(msg, resp, state)
-}
-
-func collectAnswerRecords(
-	msg *dns.Msg,
-	resp *NameserverResponse,
-	state *queryState,
-) {
-	for _, rr := range msg.Answer {
-		val := extractRecordValue(rr)
-		if val == "" {
-			continue
-		}
-
-		typeName := dns.TypeToString[rr.Header().Rrtype]
-		resp.Records[typeName] = append(
-			resp.Records[typeName], val,
-		)
-		state.hasRecords = true
-	}
-}
-
-func classifyResponse(resp *NameserverResponse, state queryState) {
-	switch {
-	case state.gotNXDomain && !state.hasRecords:
-		resp.Status = StatusNXDomain
-	case state.gotSERVFAIL && !state.hasRecords:
-		resp.Status = StatusError
-	case !state.hasRecords && !state.gotNXDomain:
-		resp.Status = StatusNoData
-	}
-}
-
-// extractRecordValue formats a DNS RR value as a string.
-func extractRecordValue(rr dns.RR) string {
-	switch r := rr.(type) {
-	case *dns.A:
-		return r.A.String()
-	case *dns.AAAA:
-		return r.AAAA.String()
-	case *dns.CNAME:
-		return r.Target
-	case *dns.MX:
-		return fmt.Sprintf("%d %s", r.Preference, r.Mx)
-	case *dns.TXT:
-		return strings.Join(r.Txt, "")
-	case *dns.SRV:
-		return fmt.Sprintf(
-			"%d %d %d %s",
-			r.Priority, r.Weight, r.Port, r.Target,
-		)
-	case *dns.CAA:
-		return fmt.Sprintf(
-			"%d %s \"%s\"", r.Flag, r.Tag, r.Value,
-		)
-	case *dns.NS:
-		return r.Ns
-	default:
-		return ""
-	}
-}
-
-// parentDomain returns the registerable parent domain.
-func parentDomain(hostname string) string {
-	hostname = dns.Fqdn(strings.ToLower(hostname))
-	labels := dns.SplitDomainName(hostname)
-
-	if len(labels) <= minDomainLabels {
-		return strings.Join(labels, ".") + "."
-	}
-
-	return strings.Join(
-		labels[len(labels)-minDomainLabels:], ".",
-	) + "."
-}
-
-// QueryAllNameservers discovers auth NSes for the hostname's
-// parent domain, then queries each one independently.
-func (r *Resolver) QueryAllNameservers(
-	ctx context.Context,
-	hostname string,
-) (map[string]*NameserverResponse, error) {
-	if checkCtx(ctx) != nil {
-		return nil, ErrContextCanceled
-	}
-
-	parent := parentDomain(hostname)
-
-	nameservers, err := r.FindAuthoritativeNameservers(ctx, parent)
-	if err != nil {
-		return nil, err
-	}
-
-	return r.queryEachNS(ctx, nameservers, hostname)
-}
-
-func (r *Resolver) queryEachNS(
-	ctx context.Context,
-	nameservers []string,
-	hostname string,
-) (map[string]*NameserverResponse, error) {
-	results := make(map[string]*NameserverResponse)
-
-	for _, ns := range nameservers {
-		if checkCtx(ctx) != nil {
-			return nil, ErrContextCanceled
-		}
-
-		resp, err := r.QueryNameserver(ctx, ns, hostname)
-		if err != nil {
-			results[ns] = &NameserverResponse{
-				Nameserver: ns,
-				Records:    make(map[string][]string),
-				Status:     StatusError,
-				Error:      err.Error(),
-			}
-
-			continue
-		}
-
-		results[ns] = resp
-	}
-
-	return results, nil
-}
-
-// LookupNS returns the NS record set for a domain.
-func (r *Resolver) LookupNS(
-	ctx context.Context,
-	domain string,
-) ([]string, error) {
-	return r.FindAuthoritativeNameservers(ctx, domain)
-}
-
-// ResolveIPAddresses resolves a hostname to all IPv4 and IPv6
-// addresses, following CNAME chains up to MaxCNAMEDepth.
-func (r *Resolver) ResolveIPAddresses(
-	ctx context.Context,
-	hostname string,
-) ([]string, error) {
-	if checkCtx(ctx) != nil {
-		return nil, ErrContextCanceled
-	}
-
-	return r.resolveIPWithCNAME(ctx, hostname, 0)
-}
-
-func (r *Resolver) resolveIPWithCNAME(
-	ctx context.Context,
-	hostname string,
-	depth int,
-) ([]string, error) {
-	if depth > MaxCNAMEDepth {
-		return nil, ErrCNAMEDepthExceeded
-	}
-
-	results, err := r.QueryAllNameservers(ctx, hostname)
-	if err != nil {
-		return nil, err
-	}
-
-	ips, cnameTarget := collectIPs(results)
-
-	if len(ips) == 0 && cnameTarget != "" {
-		return r.resolveIPWithCNAME(ctx, cnameTarget, depth+1)
-	}
-
-	sort.Strings(ips)
-
-	return ips, nil
-}
-
-func collectIPs(
-	results map[string]*NameserverResponse,
-) ([]string, string) {
-	seen := make(map[string]bool)
-
-	var ips []string
-
-	var cnameTarget string
-
-	for _, resp := range results {
-		if resp.Status == StatusNXDomain {
-			continue
-		}
-
-		for _, ip := range resp.Records["A"] {
-			if !seen[ip] {
-				seen[ip] = true
-				ips = append(ips, ip)
-			}
-		}
-
-		for _, ip := range resp.Records["AAAA"] {
-			if !seen[ip] {
-				seen[ip] = true
-				ips = append(ips, ip)
-			}
-		}
-
-		if len(resp.Records["CNAME"]) > 0 && cnameTarget == "" {
-			cnameTarget = resp.Records["CNAME"][0]
-		}
-	}
-
-	return ips, cnameTarget
-}

internal/resolver/resolver.go

@@ -1,9 +1,9 @@
 // Package resolver provides iterative DNS resolution from root nameservers.
-// It traces the full delegation chain from IANA root servers through TLD
-// and domain nameservers, never relying on upstream recursive resolvers.
 package resolver
 
 import (
+	"context"
+	"errors"
 	"log/slog"
 
 	"go.uber.org/fx"
@@ -11,16 +11,8 @@ import (
 	"sneak.berlin/go/dnswatcher/internal/logger"
 )
 
-// Query status constants matching the state model.
-const (
-	StatusOK       = "ok"
-	StatusError    = "error"
-	StatusNXDomain = "nxdomain"
-	StatusNoData   = "nodata"
-)
-
-// MaxCNAMEDepth is the maximum CNAME chain depth to follow.
-const MaxCNAMEDepth = 10
+// ErrNotImplemented indicates the resolver is not yet implemented.
+var ErrNotImplemented = errors.New("resolver not yet implemented")
 
 // Params contains dependencies for Resolver.
 type Params struct {
@@ -29,20 +21,12 @@ type Params struct {
 	Logger *logger.Logger
 }
 
-// NameserverResponse holds one nameserver's response for a query.
-type NameserverResponse struct {
-	Nameserver string
-	Records    map[string][]string
-	Status     string
-	Error      string
-}
-
 // Resolver performs iterative DNS resolution from root servers.
 type Resolver struct {
 	log *slog.Logger
 }
 
-// New creates a new Resolver instance for use with uber/fx.
+// New creates a new Resolver instance.
 func New(
 	_ fx.Lifecycle,
 	params Params,
@@ -52,10 +36,29 @@ func New(
 	}, nil
 }
 
-// NewFromLogger creates a Resolver directly from an slog.Logger,
-// useful for testing without the fx lifecycle.
-func NewFromLogger(log *slog.Logger) *Resolver {
-	return &Resolver{log: log}
+// LookupNS performs iterative resolution to find authoritative
+// nameservers for the given domain.
+func (r *Resolver) LookupNS(
+	_ context.Context,
+	_ string,
+) ([]string, error) {
+	return nil, ErrNotImplemented
 }
 
-// Method implementations are in iterative.go.
+// LookupAllRecords performs iterative resolution to find all DNS
+// records for the given hostname, keyed by authoritative nameserver.
+func (r *Resolver) LookupAllRecords(
+	_ context.Context,
+	_ string,
+) (map[string]map[string][]string, error) {
+	return nil, ErrNotImplemented
+}
+
+// ResolveIPAddresses resolves a hostname to all IPv4 and IPv6
+// addresses, following CNAME chains.
+func (r *Resolver) ResolveIPAddresses(
+	_ context.Context,
+	_ string,
+) ([]string, error) {
+	return nil, ErrNotImplemented
+}

internal/resolver/resolver_test.go

@@ -1,914 +0,0 @@
-package resolver_test
-
-import (
-	"context"
-	"log/slog"
-	"net"
-	"os"
-	"sort"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-
-	"sneak.berlin/go/dnswatcher/internal/resolver"
-)
-
-// Test domain and hostnames hosted on Cloudflare.
-// These records must exist in the sneak.cloud Cloudflare 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
-//	mx.dns.sneak.cloud       MX     10 mail.dns.sneak.cloud
-//	mail.dns                 A      192.0.2.10
-//	txt.dns.sneak.cloud      TXT    "v=spf1 -all"
-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"
-	testHostCNAMETarget = "cname-target.dns.sneak.cloud"
-	testHostMX          = "mx.dns.sneak.cloud"
-	testHostMail        = "mail.dns.sneak.cloud"
-	testHostTXT         = "txt.dns.sneak.cloud"
-	testHostNXDomain    = "nxdomain-surely-does-not-exist.google.com"
-	testDomainNXDomain  = "google.com"
-)
-
-// queryTimeout is the default timeout for test queries.
-const queryTimeout = 60 * time.Second
-
-func newTestResolver(t *testing.T) *resolver.Resolver {
-	t.Helper()
-
-	log := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
-		Level: slog.LevelDebug,
-	}))
-
-	return resolver.NewFromLogger(log)
-}
-
-func testContext(t *testing.T) context.Context {
-	t.Helper()
-
-	ctx, cancel := context.WithTimeout(
-		context.Background(), queryTimeout,
-	)
-	t.Cleanup(cancel)
-
-	return ctx
-}
-
-// --- FindAuthoritativeNameservers tests ---
-
-func TestFindAuthoritativeNameservers_ValidDomain(
-	t *testing.T,
-) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	nameservers, err := r.FindAuthoritativeNameservers(
-		ctx, testDomain,
-	)
-	require.NoError(t, err)
-	require.NotEmpty(t, nameservers, "should find at least one NS")
-
-	// sneak.cloud is on Cloudflare, NS should contain cloudflare
-	for _, ns := range nameservers {
-		t.Logf("discovered NS: %s", ns)
-		assert.True(
-			t,
-			strings.HasSuffix(ns, "."),
-			"NS should be FQDN with trailing dot: %s", ns,
-		)
-	}
-
-	// Verify at least one is a Cloudflare NS
-	hasCloudflare := false
-
-	for _, ns := range nameservers {
-		if strings.Contains(ns, "cloudflare") {
-			hasCloudflare = true
-
-			break
-		}
-	}
-
-	assert.True(
-		t, hasCloudflare,
-		"sneak.cloud should be hosted on Cloudflare, got: %v",
-		nameservers,
-	)
-}
-
-func TestFindAuthoritativeNameservers_Subdomain(
-	t *testing.T,
-) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	// Looking up NS for a hostname that isn't a zone should
-	// return the parent zone's NS records.
-	nameservers, err := r.FindAuthoritativeNameservers(
-		ctx, testHostBasic,
-	)
-	require.NoError(t, err)
-	require.NotEmpty(t, nameservers)
-
-	// Should be the same Cloudflare NSes as the parent domain
-	hasCloudflare := false
-
-	for _, ns := range nameservers {
-		if strings.Contains(ns, "cloudflare") {
-			hasCloudflare = true
-
-			break
-		}
-	}
-
-	assert.True(t, hasCloudflare)
-}
-
-func TestFindAuthoritativeNameservers_TLD(t *testing.T) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	nameservers, err := r.FindAuthoritativeNameservers(
-		ctx, "cloud",
-	)
-	require.NoError(t, err)
-	require.NotEmpty(t, nameservers, "should find TLD nameservers")
-
-	for _, ns := range nameservers {
-		t.Logf("TLD NS: %s", ns)
-	}
-}
-
-func TestFindAuthoritativeNameservers_ReturnsSorted(
-	t *testing.T,
-) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	nameservers, err := r.FindAuthoritativeNameservers(
-		ctx, testDomain,
-	)
-	require.NoError(t, err)
-	require.NotEmpty(t, nameservers)
-
-	// Results should be sorted for deterministic comparison
-	assert.True(
-		t,
-		sort.StringsAreSorted(nameservers),
-		"nameservers should be sorted, got: %v", nameservers,
-	)
-}
-
-func TestFindAuthoritativeNameservers_Deterministic(
-	t *testing.T,
-) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	first, err := r.FindAuthoritativeNameservers(
-		ctx, testDomain,
-	)
-	require.NoError(t, err)
-
-	second, err := r.FindAuthoritativeNameservers(
-		ctx, testDomain,
-	)
-	require.NoError(t, err)
-
-	assert.Equal(
-		t, first, second,
-		"repeated lookups should return same result",
-	)
-}
-
-// --- QueryNameserver tests ---
-
-func TestQueryNameserver_BasicA(t *testing.T) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	ns := findOneNS(t, r, ctx)
-
-	resp, err := r.QueryNameserver(ctx, ns, testHostBasic)
-	require.NoError(t, err)
-	require.NotNil(t, resp)
-
-	assert.Equal(t, resolver.StatusOK, resp.Status)
-	assert.Equal(t, ns, resp.Nameserver)
-
-	aRecords := resp.Records["A"]
-	require.NotEmpty(t, aRecords, "basic.dns should have A records")
-	assert.Contains(t, aRecords, "192.0.2.1")
-
-	t.Logf(
-		"QueryNameserver(%s, %s) A records: %v",
-		ns, testHostBasic, aRecords,
-	)
-}
-
-func TestQueryNameserver_MultipleA(t *testing.T) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	ns := findOneNS(t, r, ctx)
-
-	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()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	ns := findOneNS(t, r, ctx)
-
-	resp, err := r.QueryNameserver(ctx, ns, testHostIPv6)
-	require.NoError(t, err)
-	require.NotNil(t, resp)
-	assert.Equal(t, resolver.StatusOK, resp.Status)
-
-	aaaaRecords := resp.Records["AAAA"]
-	require.NotEmpty(
-		t, aaaaRecords,
-		"ipv6.dns should have AAAA records",
-	)
-	assert.Contains(t, aaaaRecords, "2001:db8::1")
-}
-
-func TestQueryNameserver_DualStack(t *testing.T) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	ns := findOneNS(t, r, ctx)
-
-	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 := findOneNS(t, r, ctx)
-
-	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()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	ns := findOneNS(t, r, ctx)
-
-	resp, err := r.QueryNameserver(ctx, ns, testHostMX)
-	require.NoError(t, err)
-	require.NotNil(t, resp)
-	assert.Equal(t, resolver.StatusOK, resp.Status)
-
-	mxRecords := resp.Records["MX"]
-	require.NotEmpty(
-		t, mxRecords,
-		"mx.dns should have MX records",
-	)
-
-	// MX records are formatted as "priority host"
-	hasMail := false
-
-	for _, mx := range mxRecords {
-		if strings.Contains(mx, "mail.dns.sneak.cloud.") {
-			hasMail = true
-
-			break
-		}
-	}
-
-	assert.True(
-		t, hasMail,
-		"MX should reference mail.dns.sneak.cloud, got: %v",
-		mxRecords,
-	)
-}
-
-func TestQueryNameserver_TXT(t *testing.T) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	ns := findOneNS(t, r, ctx)
-
-	resp, err := r.QueryNameserver(ctx, ns, testHostTXT)
-	require.NoError(t, err)
-	require.NotNil(t, resp)
-	assert.Equal(t, resolver.StatusOK, resp.Status)
-
-	txtRecords := resp.Records["TXT"]
-	require.NotEmpty(
-		t, txtRecords,
-		"txt.dns should have TXT records",
-	)
-
-	hasSPF := false
-
-	for _, txt := range txtRecords {
-		if strings.Contains(txt, "v=spf1") {
-			hasSPF = true
-
-			break
-		}
-	}
-
-	assert.True(
-		t, hasSPF,
-		"TXT should contain SPF record, got: %v", txtRecords,
-	)
-}
-
-func TestQueryNameserver_NXDomain(t *testing.T) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	ns := findOneNSForDomain(t, r, ctx, testDomainNXDomain)
-
-	resp, err := r.QueryNameserver(ctx, ns, testHostNXDomain)
-	require.NoError(t, err)
-	require.NotNil(t, resp)
-
-	assert.Equal(
-		t, resolver.StatusNXDomain, resp.Status,
-		"nonexistent host should return nxdomain status",
-	)
-}
-
-func TestQueryNameserver_RecordsSorted(t *testing.T) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	ns := findOneNS(t, r, ctx)
-
-	resp, err := r.QueryNameserver(ctx, ns, testHostMultiA)
-	require.NoError(t, err)
-
-	// Each record type's values should be sorted for determinism
-	for recordType, values := range resp.Records {
-		assert.True(
-			t,
-			sort.StringsAreSorted(values),
-			"%s records should be sorted, got: %v",
-			recordType, values,
-		)
-	}
-}
-
-func TestQueryNameserver_ResponseIncludesNameserver(
-	t *testing.T,
-) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	ns := findOneNS(t, r, ctx)
-
-	resp, err := r.QueryNameserver(ctx, ns, testHostBasic)
-	require.NoError(t, err)
-
-	assert.Equal(
-		t, ns, resp.Nameserver,
-		"response should include the queried nameserver",
-	)
-}
-
-func TestQueryNameserver_EmptyRecordsMapOnNXDomain(
-	t *testing.T,
-) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	ns := findOneNSForDomain(t, r, ctx, testDomainNXDomain)
-
-	resp, err := r.QueryNameserver(ctx, ns, testHostNXDomain)
-	require.NoError(t, err)
-
-	totalRecords := 0
-	for _, values := range resp.Records {
-		totalRecords += len(values)
-	}
-
-	assert.Zero(
-		t, totalRecords,
-		"NXDOMAIN should have no records, got: %v",
-		resp.Records,
-	)
-}
-
-// --- QueryAllNameservers tests ---
-
-func TestQueryAllNameservers_ReturnsAllNS(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)
-
-	// Should have queried each NS independently
-	t.Logf(
-		"QueryAllNameservers returned %d nameserver results",
-		len(results),
-	)
-
-	for ns, resp := range results {
-		t.Logf("  %s: status=%s A=%v", ns, resp.Status, resp.Records["A"])
-		assert.Equal(t, ns, resp.Nameserver)
-	}
-
-	// Should have more than one NS for Cloudflare-hosted domain
-	assert.GreaterOrEqual(
-		t, len(results), 2,
-		"should query at least 2 nameservers",
-	)
-}
-
-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,
-) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	results, err := r.QueryAllNameservers(
-		ctx, testHostNXDomain,
-	)
-	require.NoError(t, err)
-	require.NotEmpty(t, results)
-
-	for ns, resp := range results {
-		assert.Equal(
-			t, resolver.StatusNXDomain, resp.Status,
-			"NS %s should return nxdomain for nonexistent host",
-			ns,
-		)
-	}
-}
-
-// --- LookupNS tests ---
-
-func TestLookupNS_ValidDomain(t *testing.T) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	nameservers, err := r.LookupNS(ctx, testDomain)
-	require.NoError(t, err)
-	require.NotEmpty(t, nameservers)
-
-	for _, ns := range nameservers {
-		t.Logf("NS record: %s", ns)
-		assert.True(
-			t,
-			strings.HasSuffix(ns, "."),
-			"NS should be FQDN: %s", ns,
-		)
-	}
-}
-
-func TestLookupNS_Sorted(t *testing.T) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	nameservers, err := r.LookupNS(ctx, testDomain)
-	require.NoError(t, err)
-
-	assert.True(
-		t,
-		sort.StringsAreSorted(nameservers),
-		"NS records should be sorted, got: %v", nameservers,
-	)
-}
-
-func TestLookupNS_MatchesFindAuthoritative(t *testing.T) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	fromLookup, err := r.LookupNS(ctx, testDomain)
-	require.NoError(t, err)
-
-	fromFind, err := r.FindAuthoritativeNameservers(
-		ctx, testDomain,
-	)
-	require.NoError(t, err)
-
-	// Both methods should return the same NS set
-	assert.Equal(
-		t, fromFind, fromLookup,
-		"LookupNS and FindAuthoritativeNameservers "+
-			"should return the same set",
-	)
-}
-
-// --- ResolveIPAddresses tests ---
-
-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)
-
-	// cname.dns.sneak.cloud -> cname-target.dns.sneak.cloud -> 198.51.100.1
-	ips, err := r.ResolveIPAddresses(ctx, testHostCNAME)
-	require.NoError(t, err)
-	require.NotEmpty(t, ips)
-	assert.Contains(
-		t, ips, "198.51.100.1",
-		"should follow CNAME to resolve target IP",
-	)
-}
-
-func TestResolveIPAddresses_Deduplicated(t *testing.T) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	ips, err := r.ResolveIPAddresses(ctx, testHostBasic)
-	require.NoError(t, err)
-
-	// Check for duplicates
-	seen := make(map[string]bool)
-
-	for _, ip := range ips {
-		assert.False(
-			t, seen[ip],
-			"IP %s appears more than once", ip,
-		)
-		seen[ip] = true
-	}
-}
-
-func TestResolveIPAddresses_Sorted(t *testing.T) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	ips, err := r.ResolveIPAddresses(ctx, testHostDualStack)
-	require.NoError(t, err)
-
-	assert.True(
-		t,
-		sort.StringsAreSorted(ips),
-		"IP addresses should be sorted, got: %v", ips,
-	)
-}
-
-func TestResolveIPAddresses_NXDomainReturnsEmpty(
-	t *testing.T,
-) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	ips, err := r.ResolveIPAddresses(ctx, testHostNXDomain)
-	// Should not error — NXDOMAIN is an expected DNS response.
-	// It just means no IPs to return.
-	require.NoError(t, err)
-	assert.Empty(t, ips)
-}
-
-// --- Context cancellation tests ---
-
-func TestFindAuthoritativeNameservers_ContextCanceled(
-	t *testing.T,
-) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-
-	ctx, cancel := context.WithCancel(context.Background())
-	cancel() // Cancel immediately
-
-	_, err := r.FindAuthoritativeNameservers(ctx, testDomain)
-	assert.Error(t, err)
-}
-
-func TestQueryNameserver_ContextCanceled(t *testing.T) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-
-	ctx, cancel := context.WithCancel(context.Background())
-	cancel()
-
-	_, err := r.QueryNameserver(
-		ctx, "ns1.example.com.", testHostBasic,
-	)
-	assert.Error(t, err)
-}
-
-func TestQueryAllNameservers_ContextCanceled(t *testing.T) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-
-	ctx, cancel := context.WithCancel(context.Background())
-	cancel()
-
-	_, err := r.QueryAllNameservers(ctx, testHostBasic)
-	assert.Error(t, err)
-}
-
-func TestResolveIPAddresses_ContextCanceled(t *testing.T) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-
-	ctx, cancel := context.WithCancel(context.Background())
-	cancel()
-
-	_, err := r.ResolveIPAddresses(ctx, testHostBasic)
-	assert.Error(t, err)
-}
-
-// --- Iterative resolution verification ---
-
-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, "google.com",
-	)
-	require.NoError(t, err)
-	require.NotEmpty(t, nameservers)
-
-	t.Logf("example.com NS: %v", nameservers)
-}
-
-// --- Edge cases ---
-
-func TestQueryNameserver_TrailingDotHandling(t *testing.T) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	ns := findOneNS(t, r, ctx)
-
-	// Both with and without trailing dot should work
-	resp1, err := r.QueryNameserver(
-		ctx, ns, "basic.dns.sneak.cloud",
-	)
-	require.NoError(t, err)
-
-	resp2, err := r.QueryNameserver(
-		ctx, ns, "basic.dns.sneak.cloud.",
-	)
-	require.NoError(t, err)
-
-	assert.Equal(
-		t, resp1.Records["A"], resp2.Records["A"],
-		"trailing dot should not affect results",
-	)
-}
-
-func TestFindAuthoritativeNameservers_TrailingDot(
-	t *testing.T,
-) {
-	t.Parallel()
-
-	r := newTestResolver(t)
-	ctx := testContext(t)
-
-	ns1, err := r.FindAuthoritativeNameservers(
-		ctx, "sneak.cloud",
-	)
-	require.NoError(t, err)
-
-	ns2, err := r.FindAuthoritativeNameservers(
-		ctx, "sneak.cloud.",
-	)
-	require.NoError(t, err)
-
-	assert.Equal(
-		t, ns1, ns2,
-		"trailing dot should not affect NS lookup",
-	)
-}
-
-// --- Helper functions ---
-
-// findOneNS discovers authoritative nameservers and returns the first
-// one, failing the test if none are found.
-func findOneNS(
-	t *testing.T,
-	r *resolver.Resolver,
-	ctx context.Context, //nolint:revive // test helper
-) string {
-	t.Helper()
-
-	return findOneNSForDomain(t, r, ctx, testDomain)
-}
-
-func findOneNSForDomain(
-	t *testing.T,
-	r *resolver.Resolver,
-	ctx context.Context, //nolint:revive // test helper
-	domain string,
-) string {
-	t.Helper()
-
-	nameservers, err := r.FindAuthoritativeNameservers(
-		ctx, domain,
-	)
-	require.NoError(t, err)
-	require.NotEmpty(
-		t, nameservers,
-		"should find at least one NS for %s", domain,
-	)
-
-	return nameservers[0]
-}

internal/state/state_test_helper.go

@@ -0,0 +1,22 @@
+package state
+
+import (
+	"log/slog"
+
+	"sneak.berlin/go/dnswatcher/internal/config"
+)
+
+// NewForTest creates a State for unit testing with no persistence.
+func NewForTest() *State {
+	return &State{
+		log: slog.Default(),
+		snapshot: &Snapshot{
+			Version:      stateVersion,
+			Domains:      make(map[string]*DomainState),
+			Hostnames:    make(map[string]*HostnameState),
+			Ports:        make(map[string]*PortState),
+			Certificates: make(map[string]*CertificateState),
+		},
+		config: &config.Config{DataDir: ""},
+	}
+}

internal/watcher/interfaces.go

@@ -0,0 +1,60 @@
+// Package watcher provides the main monitoring orchestrator.
+package watcher
+
+import (
+	"context"
+
+	"sneak.berlin/go/dnswatcher/internal/tlscheck"
+)
+
+// DNSResolver performs iterative DNS resolution.
+type DNSResolver interface {
+	// LookupNS discovers authoritative nameservers for a domain.
+	LookupNS(
+		ctx context.Context,
+		domain string,
+	) ([]string, error)
+
+	// LookupAllRecords queries all record types for a hostname,
+	// returning results keyed by nameserver then record type.
+	LookupAllRecords(
+		ctx context.Context,
+		hostname string,
+	) (map[string]map[string][]string, error)
+
+	// ResolveIPAddresses resolves a hostname to all IP addresses.
+	ResolveIPAddresses(
+		ctx context.Context,
+		hostname string,
+	) ([]string, error)
+}
+
+// PortChecker tests TCP port connectivity.
+type PortChecker interface {
+	// CheckPort tests TCP connectivity to an address and port.
+	CheckPort(
+		ctx context.Context,
+		address string,
+		port int,
+	) (bool, error)
+}
+
+// TLSChecker inspects TLS certificates.
+type TLSChecker interface {
+	// CheckCertificate connects via TLS and returns cert info.
+	CheckCertificate(
+		ctx context.Context,
+		ip string,
+		hostname string,
+	) (*tlscheck.CertificateInfo, error)
+}
+
+// Notifier delivers notifications to configured endpoints.
+type Notifier interface {
+	// SendNotification sends a notification with the given
+	// details.
+	SendNotification(
+		ctx context.Context,
+		title, message, priority string,
+	)
+}

internal/watcher/watcher.go

@@ -1,21 +1,30 @@
-// Package watcher provides the main monitoring orchestrator and scheduler.
 package watcher
 
 import (
 	"context"
+	"fmt"
 	"log/slog"
+	"sort"
+	"strings"
+	"time"
 
 	"go.uber.org/fx"
 
 	"sneak.berlin/go/dnswatcher/internal/config"
 	"sneak.berlin/go/dnswatcher/internal/logger"
-	"sneak.berlin/go/dnswatcher/internal/notify"
-	"sneak.berlin/go/dnswatcher/internal/portcheck"
-	"sneak.berlin/go/dnswatcher/internal/resolver"
 	"sneak.berlin/go/dnswatcher/internal/state"
 	"sneak.berlin/go/dnswatcher/internal/tlscheck"
 )
 
+// monitoredPorts are the TCP ports checked for each IP address.
+var monitoredPorts = []int{80, 443} //nolint:gochecknoglobals
+
+// tlsPort is the port used for TLS certificate checks.
+const tlsPort = 443
+
+// hoursPerDay converts days to hours for duration calculations.
+const hoursPerDay = 24
+
 // Params contains dependencies for Watcher.
 type Params struct {
 	fx.In
@@ -23,10 +32,10 @@ type Params struct {
 	Logger    *logger.Logger
 	Config    *config.Config
 	State     *state.State
-	Resolver  *resolver.Resolver
-	PortCheck *portcheck.Checker
-	TLSCheck  *tlscheck.Checker
-	Notify    *notify.Service
+	Resolver  DNSResolver
+	PortCheck PortChecker
+	TLSCheck  TLSChecker
+	Notify    Notifier
 }
 
 // Watcher orchestrates all monitoring checks on a schedule.
@@ -34,19 +43,20 @@ type Watcher struct {
 	log       *slog.Logger
 	config    *config.Config
 	state     *state.State
-	resolver  *resolver.Resolver
-	portCheck *portcheck.Checker
-	tlsCheck  *tlscheck.Checker
-	notify    *notify.Service
+	resolver  DNSResolver
+	portCheck PortChecker
+	tlsCheck  TLSChecker
+	notify    Notifier
 	cancel    context.CancelFunc
+	firstRun  bool
 }
 
-// New creates a new Watcher instance.
+// New creates a new Watcher instance wired into the fx lifecycle.
 func New(
 	lifecycle fx.Lifecycle,
 	params Params,
 ) (*Watcher, error) {
-	watcher := &Watcher{
+	w := &Watcher{
 		log:       params.Logger.Get(),
 		config:    params.Config,
 		state:     params.State,
@@ -54,30 +64,54 @@ func New(
 		portCheck: params.PortCheck,
 		tlsCheck:  params.TLSCheck,
 		notify:    params.Notify,
+		firstRun:  true,
 	}
 
 	lifecycle.Append(fx.Hook{
 		OnStart: func(startCtx context.Context) error {
-			ctx, cancel := context.WithCancel(startCtx)
-			watcher.cancel = cancel
+			ctx, cancel := context.WithCancel(
+				context.WithoutCancel(startCtx),
+			)
+			w.cancel = cancel
 
-			go watcher.Run(ctx)
+			go w.Run(ctx)
 
 			return nil
 		},
 		OnStop: func(_ context.Context) error {
-			if watcher.cancel != nil {
-				watcher.cancel()
+			if w.cancel != nil {
+				w.cancel()
 			}
 
 			return nil
 		},
 	})
 
-	return watcher, nil
+	return w, nil
 }
 
-// Run starts the monitoring loop.
+// NewForTest creates a Watcher without fx for unit testing.
+func NewForTest(
+	cfg *config.Config,
+	st *state.State,
+	res DNSResolver,
+	pc PortChecker,
+	tc TLSChecker,
+	n Notifier,
+) *Watcher {
+	return &Watcher{
+		log:       slog.Default(),
+		config:    cfg,
+		state:     st,
+		resolver:  res,
+		portCheck: pc,
+		tlsCheck:  tc,
+		notify:    n,
+		firstRun:  true,
+	}
+}
+
+// Run starts the monitoring loop with periodic scheduling.
 func (w *Watcher) Run(ctx context.Context) {
 	w.log.Info(
 		"watcher starting",
@@ -87,8 +121,646 @@ func (w *Watcher) Run(ctx context.Context) {
 		"tlsInterval", w.config.TLSInterval,
 	)
 
-	// Stub: wait for context cancellation.
-	// Implementation will add initial check + periodic scheduling.
-	<-ctx.Done()
-	w.log.Info("watcher stopped")
+	w.RunOnce(ctx)
+
+	dnsTicker := time.NewTicker(w.config.DNSInterval)
+	tlsTicker := time.NewTicker(w.config.TLSInterval)
+
+	defer dnsTicker.Stop()
+	defer tlsTicker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			w.log.Info("watcher stopped")
+
+			return
+		case <-dnsTicker.C:
+			w.runDNSAndPortChecks(ctx)
+			w.saveState()
+		case <-tlsTicker.C:
+			w.runTLSChecks(ctx)
+			w.saveState()
+		}
+	}
+}
+
+// RunOnce performs a single complete monitoring cycle.
+func (w *Watcher) RunOnce(ctx context.Context) {
+	w.detectFirstRun()
+	w.runDNSAndPortChecks(ctx)
+	w.runTLSChecks(ctx)
+	w.saveState()
+	w.firstRun = false
+}
+
+func (w *Watcher) detectFirstRun() {
+	snap := w.state.GetSnapshot()
+	hasState := len(snap.Domains) > 0 ||
+		len(snap.Hostnames) > 0 ||
+		len(snap.Ports) > 0 ||
+		len(snap.Certificates) > 0
+
+	if hasState {
+		w.firstRun = false
+	}
+}
+
+func (w *Watcher) runDNSAndPortChecks(ctx context.Context) {
+	for _, domain := range w.config.Domains {
+		w.checkDomain(ctx, domain)
+	}
+
+	for _, hostname := range w.config.Hostnames {
+		w.checkHostname(ctx, hostname)
+	}
+
+	w.checkAllPorts(ctx)
+}
+
+func (w *Watcher) checkDomain(
+	ctx context.Context,
+	domain string,
+) {
+	nameservers, err := w.resolver.LookupNS(ctx, domain)
+	if err != nil {
+		w.log.Error(
+			"failed to lookup NS",
+			"domain", domain,
+			"error", err,
+		)
+
+		return
+	}
+
+	sort.Strings(nameservers)
+
+	now := time.Now().UTC()
+
+	prev, hasPrev := w.state.GetDomainState(domain)
+	if hasPrev && !w.firstRun {
+		w.detectNSChanges(ctx, domain, prev.Nameservers, nameservers)
+	}
+
+	w.state.SetDomainState(domain, &state.DomainState{
+		Nameservers: nameservers,
+		LastChecked: now,
+	})
+}
+
+func (w *Watcher) detectNSChanges(
+	ctx context.Context,
+	domain string,
+	oldNS, newNS []string,
+) {
+	oldSet := toSet(oldNS)
+	newSet := toSet(newNS)
+
+	var added, removed []string
+
+	for ns := range newSet {
+		if !oldSet[ns] {
+			added = append(added, ns)
+		}
+	}
+
+	for ns := range oldSet {
+		if !newSet[ns] {
+			removed = append(removed, ns)
+		}
+	}
+
+	if len(added) == 0 && len(removed) == 0 {
+		return
+	}
+
+	msg := fmt.Sprintf(
+		"Domain: %s\nAdded: %s\nRemoved: %s",
+		domain,
+		strings.Join(added, ", "),
+		strings.Join(removed, ", "),
+	)
+
+	w.notify.SendNotification(
+		ctx,
+		"NS Change: "+domain,
+		msg,
+		"warning",
+	)
+}
+
+func (w *Watcher) checkHostname(
+	ctx context.Context,
+	hostname string,
+) {
+	records, err := w.resolver.LookupAllRecords(ctx, hostname)
+	if err != nil {
+		w.log.Error(
+			"failed to lookup records",
+			"hostname", hostname,
+			"error", err,
+		)
+
+		return
+	}
+
+	now := time.Now().UTC()
+	prev, hasPrev := w.state.GetHostnameState(hostname)
+
+	if hasPrev && !w.firstRun {
+		w.detectHostnameChanges(ctx, hostname, prev, records)
+	}
+
+	newState := buildHostnameState(records, now)
+	w.state.SetHostnameState(hostname, newState)
+}
+
+func buildHostnameState(
+	records map[string]map[string][]string,
+	now time.Time,
+) *state.HostnameState {
+	hs := &state.HostnameState{
+		RecordsByNameserver: make(
+			map[string]*state.NameserverRecordState,
+		),
+		LastChecked: now,
+	}
+
+	for ns, recs := range records {
+		hs.RecordsByNameserver[ns] = &state.NameserverRecordState{
+			Records:     recs,
+			Status:      "ok",
+			LastChecked: now,
+		}
+	}
+
+	return hs
+}
+
+func (w *Watcher) detectHostnameChanges(
+	ctx context.Context,
+	hostname string,
+	prev *state.HostnameState,
+	current map[string]map[string][]string,
+) {
+	w.detectRecordChanges(ctx, hostname, prev, current)
+	w.detectNSDisappearances(ctx, hostname, prev, current)
+	w.detectInconsistencies(ctx, hostname, current)
+}
+
+func (w *Watcher) detectRecordChanges(
+	ctx context.Context,
+	hostname string,
+	prev *state.HostnameState,
+	current map[string]map[string][]string,
+) {
+	for ns, recs := range current {
+		prevNS, ok := prev.RecordsByNameserver[ns]
+		if !ok {
+			continue
+		}
+
+		if recordsEqual(prevNS.Records, recs) {
+			continue
+		}
+
+		msg := fmt.Sprintf(
+			"Hostname: %s\nNameserver: %s\n"+
+				"Old: %v\nNew: %v",
+			hostname, ns,
+			prevNS.Records, recs,
+		)
+
+		w.notify.SendNotification(
+			ctx,
+			"Record Change: "+hostname,
+			msg,
+			"warning",
+		)
+	}
+}
+
+func (w *Watcher) detectNSDisappearances(
+	ctx context.Context,
+	hostname string,
+	prev *state.HostnameState,
+	current map[string]map[string][]string,
+) {
+	for ns, prevNS := range prev.RecordsByNameserver {
+		if _, ok := current[ns]; ok || prevNS.Status != "ok" {
+			continue
+		}
+
+		msg := fmt.Sprintf(
+			"Hostname: %s\nNameserver: %s disappeared",
+			hostname, ns,
+		)
+
+		w.notify.SendNotification(
+			ctx,
+			"NS Failure: "+hostname,
+			msg,
+			"error",
+		)
+	}
+
+	for ns := range current {
+		prevNS, ok := prev.RecordsByNameserver[ns]
+		if !ok || prevNS.Status != "error" {
+			continue
+		}
+
+		msg := fmt.Sprintf(
+			"Hostname: %s\nNameserver: %s recovered",
+			hostname, ns,
+		)
+
+		w.notify.SendNotification(
+			ctx,
+			"NS Recovery: "+hostname,
+			msg,
+			"success",
+		)
+	}
+}
+
+func (w *Watcher) detectInconsistencies(
+	ctx context.Context,
+	hostname string,
+	current map[string]map[string][]string,
+) {
+	nameservers := make([]string, 0, len(current))
+	for ns := range current {
+		nameservers = append(nameservers, ns)
+	}
+
+	sort.Strings(nameservers)
+
+	for i := range len(nameservers) - 1 {
+		ns1 := nameservers[i]
+		ns2 := nameservers[i+1]
+
+		if recordsEqual(current[ns1], current[ns2]) {
+			continue
+		}
+
+		msg := fmt.Sprintf(
+			"Hostname: %s\n%s: %v\n%s: %v",
+			hostname,
+			ns1, current[ns1],
+			ns2, current[ns2],
+		)
+
+		w.notify.SendNotification(
+			ctx,
+			"Inconsistency: "+hostname,
+			msg,
+			"warning",
+		)
+	}
+}
+
+func (w *Watcher) checkAllPorts(ctx context.Context) {
+	for _, hostname := range w.config.Hostnames {
+		w.checkPortsForHostname(ctx, hostname)
+	}
+
+	for _, domain := range w.config.Domains {
+		w.checkPortsForHostname(ctx, domain)
+	}
+}
+
+func (w *Watcher) checkPortsForHostname(
+	ctx context.Context,
+	hostname string,
+) {
+	ips := w.collectIPs(hostname)
+
+	for _, ip := range ips {
+		for _, port := range monitoredPorts {
+			w.checkSinglePort(ctx, ip, port, hostname)
+		}
+	}
+}
+
+func (w *Watcher) collectIPs(hostname string) []string {
+	hs, ok := w.state.GetHostnameState(hostname)
+	if !ok {
+		return nil
+	}
+
+	ipSet := make(map[string]bool)
+
+	for _, nsState := range hs.RecordsByNameserver {
+		for _, ip := range nsState.Records["A"] {
+			ipSet[ip] = true
+		}
+
+		for _, ip := range nsState.Records["AAAA"] {
+			ipSet[ip] = true
+		}
+	}
+
+	result := make([]string, 0, len(ipSet))
+	for ip := range ipSet {
+		result = append(result, ip)
+	}
+
+	sort.Strings(result)
+
+	return result
+}
+
+func (w *Watcher) checkSinglePort(
+	ctx context.Context,
+	ip string,
+	port int,
+	hostname string,
+) {
+	open, err := w.portCheck.CheckPort(ctx, ip, port)
+	if err != nil {
+		w.log.Error(
+			"port check failed",
+			"ip", ip,
+			"port", port,
+			"error", err,
+		)
+
+		return
+	}
+
+	key := fmt.Sprintf("%s:%d", ip, port)
+	now := time.Now().UTC()
+	prev, hasPrev := w.state.GetPortState(key)
+
+	if hasPrev && !w.firstRun && prev.Open != open {
+		stateStr := "closed"
+		if open {
+			stateStr = "open"
+		}
+
+		msg := fmt.Sprintf(
+			"Host: %s\nAddress: %s\nPort now %s",
+			hostname, key, stateStr,
+		)
+
+		w.notify.SendNotification(
+			ctx,
+			"Port Change: "+key,
+			msg,
+			"warning",
+		)
+	}
+
+	w.state.SetPortState(key, &state.PortState{
+		Open:        open,
+		Hostname:    hostname,
+		LastChecked: now,
+	})
+}
+
+func (w *Watcher) runTLSChecks(ctx context.Context) {
+	for _, hostname := range w.config.Hostnames {
+		w.checkTLSForHostname(ctx, hostname)
+	}
+
+	for _, domain := range w.config.Domains {
+		w.checkTLSForHostname(ctx, domain)
+	}
+}
+
+func (w *Watcher) checkTLSForHostname(
+	ctx context.Context,
+	hostname string,
+) {
+	ips := w.collectIPs(hostname)
+
+	for _, ip := range ips {
+		portKey := fmt.Sprintf("%s:%d", ip, tlsPort)
+
+		ps, ok := w.state.GetPortState(portKey)
+		if !ok || !ps.Open {
+			continue
+		}
+
+		w.checkTLSCert(ctx, ip, hostname)
+	}
+}
+
+func (w *Watcher) checkTLSCert(
+	ctx context.Context,
+	ip string,
+	hostname string,
+) {
+	cert, err := w.tlsCheck.CheckCertificate(ctx, ip, hostname)
+	certKey := fmt.Sprintf("%s:%d:%s", ip, tlsPort, hostname)
+	now := time.Now().UTC()
+	prev, hasPrev := w.state.GetCertificateState(certKey)
+
+	if err != nil {
+		w.handleTLSError(
+			ctx, certKey, hostname, ip,
+			hasPrev, prev, now, err,
+		)
+
+		return
+	}
+
+	w.handleTLSSuccess(
+		ctx, certKey, hostname, ip,
+		hasPrev, prev, now, cert,
+	)
+}
+
+func (w *Watcher) handleTLSError(
+	ctx context.Context,
+	certKey, hostname, ip string,
+	hasPrev bool,
+	prev *state.CertificateState,
+	now time.Time,
+	err error,
+) {
+	if hasPrev && !w.firstRun && prev.Status == "ok" {
+		msg := fmt.Sprintf(
+			"Host: %s\nIP: %s\nError: %s",
+			hostname, ip, err,
+		)
+
+		w.notify.SendNotification(
+			ctx,
+			"TLS Failure: "+hostname,
+			msg,
+			"error",
+		)
+	}
+
+	w.state.SetCertificateState(
+		certKey, &state.CertificateState{
+			Status:      "error",
+			Error:       err.Error(),
+			LastChecked: now,
+		},
+	)
+}
+
+func (w *Watcher) handleTLSSuccess(
+	ctx context.Context,
+	certKey, hostname, ip string,
+	hasPrev bool,
+	prev *state.CertificateState,
+	now time.Time,
+	cert *tlscheck.CertificateInfo,
+) {
+	if hasPrev && !w.firstRun {
+		w.detectTLSChanges(ctx, hostname, ip, prev, cert)
+	}
+
+	w.checkTLSExpiry(ctx, hostname, ip, cert)
+
+	w.state.SetCertificateState(
+		certKey, &state.CertificateState{
+			CommonName:              cert.CommonName,
+			Issuer:                  cert.Issuer,
+			NotAfter:                cert.NotAfter,
+			SubjectAlternativeNames: cert.SubjectAlternativeNames,
+			Status:                  "ok",
+			LastChecked:             now,
+		},
+	)
+}
+
+func (w *Watcher) detectTLSChanges(
+	ctx context.Context,
+	hostname, ip string,
+	prev *state.CertificateState,
+	cert *tlscheck.CertificateInfo,
+) {
+	if prev.Status == "error" {
+		msg := fmt.Sprintf(
+			"Host: %s\nIP: %s\nTLS recovered",
+			hostname, ip,
+		)
+
+		w.notify.SendNotification(
+			ctx,
+			"TLS Recovery: "+hostname,
+			msg,
+			"success",
+		)
+
+		return
+	}
+
+	changed := prev.CommonName != cert.CommonName ||
+		prev.Issuer != cert.Issuer ||
+		!sliceEqual(
+			prev.SubjectAlternativeNames,
+			cert.SubjectAlternativeNames,
+		)
+
+	if !changed {
+		return
+	}
+
+	msg := fmt.Sprintf(
+		"Host: %s\nIP: %s\n"+
+			"Old CN: %s, Issuer: %s\n"+
+			"New CN: %s, Issuer: %s",
+		hostname, ip,
+		prev.CommonName, prev.Issuer,
+		cert.CommonName, cert.Issuer,
+	)
+
+	w.notify.SendNotification(
+		ctx,
+		"TLS Certificate Change: "+hostname,
+		msg,
+		"warning",
+	)
+}
+
+func (w *Watcher) checkTLSExpiry(
+	ctx context.Context,
+	hostname, ip string,
+	cert *tlscheck.CertificateInfo,
+) {
+	daysLeft := time.Until(cert.NotAfter).Hours() / hoursPerDay
+	warningDays := float64(w.config.TLSExpiryWarning)
+
+	if daysLeft > warningDays {
+		return
+	}
+
+	msg := fmt.Sprintf(
+		"Host: %s\nIP: %s\nCN: %s\n"+
+			"Expires: %s (%.0f days)",
+		hostname, ip, cert.CommonName,
+		cert.NotAfter.Format(time.RFC3339),
+		daysLeft,
+	)
+
+	w.notify.SendNotification(
+		ctx,
+		"TLS Expiry Warning: "+hostname,
+		msg,
+		"warning",
+	)
+}
+
+func (w *Watcher) saveState() {
+	err := w.state.Save()
+	if err != nil {
+		w.log.Error("failed to save state", "error", err)
+	}
+}
+
+// --- Utility functions ---
+
+func toSet(items []string) map[string]bool {
+	set := make(map[string]bool, len(items))
+	for _, item := range items {
+		set[item] = true
+	}
+
+	return set
+}
+
+func recordsEqual(
+	a, b map[string][]string,
+) bool {
+	if len(a) != len(b) {
+		return false
+	}
+
+	for k, av := range a {
+		bv, ok := b[k]
+		if !ok || !sliceEqual(av, bv) {
+			return false
+		}
+	}
+
+	return true
+}
+
+func sliceEqual(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+
+	aSorted := make([]string, len(a))
+	bSorted := make([]string, len(b))
+
+	copy(aSorted, a)
+	copy(bSorted, b)
+
+	sort.Strings(aSorted)
+	sort.Strings(bSorted)
+
+	for i := range aSorted {
+		if aSorted[i] != bSorted[i] {
+			return false
+		}
+	}
+
+	return true
 }

internal/watcher/watcher_test.go

@@ -0,0 +1,580 @@
+package watcher_test
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/dnswatcher/internal/config"
+	"sneak.berlin/go/dnswatcher/internal/state"
+	"sneak.berlin/go/dnswatcher/internal/tlscheck"
+	"sneak.berlin/go/dnswatcher/internal/watcher"
+)
+
+// errNotFound is returned when mock data is missing.
+var errNotFound = errors.New("not found")
+
+// --- Mock implementations ---
+
+type mockResolver struct {
+	mu             sync.Mutex
+	nsRecords      map[string][]string
+	allRecords     map[string]map[string]map[string][]string
+	ipAddresses    map[string][]string
+	lookupNSErr    error
+	allRecordsErr  error
+	resolveIPErr   error
+	lookupNSCalls  int
+	allRecordCalls int
+}
+
+func (m *mockResolver) LookupNS(
+	_ context.Context,
+	domain string,
+) ([]string, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	m.lookupNSCalls++
+
+	if m.lookupNSErr != nil {
+		return nil, m.lookupNSErr
+	}
+
+	ns, ok := m.nsRecords[domain]
+	if !ok {
+		return nil, fmt.Errorf(
+			"%w: NS for %s", errNotFound, domain,
+		)
+	}
+
+	return ns, nil
+}
+
+func (m *mockResolver) LookupAllRecords(
+	_ context.Context,
+	hostname string,
+) (map[string]map[string][]string, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	m.allRecordCalls++
+
+	if m.allRecordsErr != nil {
+		return nil, m.allRecordsErr
+	}
+
+	recs, ok := m.allRecords[hostname]
+	if !ok {
+		return nil, fmt.Errorf(
+			"%w: records for %s", errNotFound, hostname,
+		)
+	}
+
+	return recs, nil
+}
+
+func (m *mockResolver) ResolveIPAddresses(
+	_ context.Context,
+	hostname string,
+) ([]string, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	if m.resolveIPErr != nil {
+		return nil, m.resolveIPErr
+	}
+
+	ips, ok := m.ipAddresses[hostname]
+	if !ok {
+		return nil, fmt.Errorf(
+			"%w: IPs for %s", errNotFound, hostname,
+		)
+	}
+
+	return ips, nil
+}
+
+type mockPortChecker struct {
+	mu      sync.Mutex
+	results map[string]bool
+	err     error
+	calls   int
+}
+
+func (m *mockPortChecker) CheckPort(
+	_ context.Context,
+	address string,
+	port int,
+) (bool, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	m.calls++
+
+	if m.err != nil {
+		return false, m.err
+	}
+
+	key := fmt.Sprintf("%s:%d", address, port)
+	open, ok := m.results[key]
+
+	if !ok {
+		return false, nil
+	}
+
+	return open, nil
+}
+
+type mockTLSChecker struct {
+	mu    sync.Mutex
+	certs map[string]*tlscheck.CertificateInfo
+	err   error
+	calls int
+}
+
+func (m *mockTLSChecker) CheckCertificate(
+	_ context.Context,
+	ip string,
+	hostname string,
+) (*tlscheck.CertificateInfo, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	m.calls++
+
+	if m.err != nil {
+		return nil, m.err
+	}
+
+	key := fmt.Sprintf("%s:%s", ip, hostname)
+	cert, ok := m.certs[key]
+
+	if !ok {
+		return nil, fmt.Errorf(
+			"%w: cert for %s", errNotFound, key,
+		)
+	}
+
+	return cert, nil
+}
+
+type notification struct {
+	Title    string
+	Message  string
+	Priority string
+}
+
+type mockNotifier struct {
+	mu            sync.Mutex
+	notifications []notification
+}
+
+func (m *mockNotifier) SendNotification(
+	_ context.Context,
+	title, message, priority string,
+) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	m.notifications = append(m.notifications, notification{
+		Title:    title,
+		Message:  message,
+		Priority: priority,
+	})
+}
+
+func (m *mockNotifier) getNotifications() []notification {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	result := make([]notification, len(m.notifications))
+	copy(result, m.notifications)
+
+	return result
+}
+
+// --- Helper to build a Watcher for testing ---
+
+type testDeps struct {
+	resolver    *mockResolver
+	portChecker *mockPortChecker
+	tlsChecker  *mockTLSChecker
+	notifier    *mockNotifier
+	state       *state.State
+	config      *config.Config
+}
+
+func newTestWatcher(
+	t *testing.T,
+	cfg *config.Config,
+) (*watcher.Watcher, *testDeps) {
+	t.Helper()
+
+	deps := &testDeps{
+		resolver: &mockResolver{
+			nsRecords:   make(map[string][]string),
+			allRecords:  make(map[string]map[string]map[string][]string),
+			ipAddresses: make(map[string][]string),
+		},
+		portChecker: &mockPortChecker{
+			results: make(map[string]bool),
+		},
+		tlsChecker: &mockTLSChecker{
+			certs: make(map[string]*tlscheck.CertificateInfo),
+		},
+		notifier: &mockNotifier{},
+		config:   cfg,
+	}
+
+	deps.state = state.NewForTest()
+
+	w := watcher.NewForTest(
+		deps.config,
+		deps.state,
+		deps.resolver,
+		deps.portChecker,
+		deps.tlsChecker,
+		deps.notifier,
+	)
+
+	return w, deps
+}
+
+func defaultTestConfig(t *testing.T) *config.Config {
+	t.Helper()
+
+	return &config.Config{
+		DNSInterval:      time.Hour,
+		TLSInterval:      12 * time.Hour,
+		TLSExpiryWarning: 7,
+		DataDir:          t.TempDir(),
+	}
+}
+
+func TestFirstRunBaseline(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{"example.com"}
+	cfg.Hostnames = []string{"www.example.com"}
+
+	w, deps := newTestWatcher(t, cfg)
+	setupBaselineMocks(deps)
+
+	w.RunOnce(t.Context())
+
+	assertNoNotifications(t, deps)
+	assertStatePopulated(t, deps)
+}
+
+func setupBaselineMocks(deps *testDeps) {
+	deps.resolver.nsRecords["example.com"] = []string{
+		"ns1.example.com.",
+		"ns2.example.com.",
+	}
+	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"}},
+	}
+	deps.resolver.ipAddresses["www.example.com"] = []string{
+		"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:www.example.com"] = &tlscheck.CertificateInfo{
+		CommonName: "www.example.com",
+		Issuer:     "DigiCert",
+		NotAfter:   time.Now().Add(90 * 24 * time.Hour),
+		SubjectAlternativeNames: []string{
+			"www.example.com",
+		},
+	}
+}
+
+func assertNoNotifications(
+	t *testing.T,
+	deps *testDeps,
+) {
+	t.Helper()
+
+	notifications := deps.notifier.getNotifications()
+	if len(notifications) != 0 {
+		t.Errorf(
+			"expected 0 notifications on first run, got %d",
+			len(notifications),
+		)
+	}
+}
+
+func assertStatePopulated(
+	t *testing.T,
+	deps *testDeps,
+) {
+	t.Helper()
+
+	snap := deps.state.GetSnapshot()
+
+	if len(snap.Domains) != 1 {
+		t.Errorf(
+			"expected 1 domain in state, got %d",
+			len(snap.Domains),
+		)
+	}
+
+	if len(snap.Hostnames) != 1 {
+		t.Errorf(
+			"expected 1 hostname in state, got %d",
+			len(snap.Hostnames),
+		)
+	}
+}
+
+func TestNSChangeDetection(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.",
+		"ns2.example.com.",
+	}
+
+	ctx := t.Context()
+	w.RunOnce(ctx)
+
+	deps.resolver.mu.Lock()
+	deps.resolver.nsRecords["example.com"] = []string{
+		"ns1.example.com.",
+		"ns3.example.com.",
+	}
+	deps.resolver.mu.Unlock()
+
+	w.RunOnce(ctx)
+
+	notifications := deps.notifier.getNotifications()
+	if len(notifications) == 0 {
+		t.Error("expected notification for NS change")
+	}
+
+	found := false
+
+	for _, n := range notifications {
+		if n.Priority == "warning" {
+			found = true
+		}
+	}
+
+	if !found {
+		t.Error("expected warning-priority NS change notification")
+	}
+}
+
+func TestRecordChangeDetection(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Hostnames = []string{"www.example.com"}
+
+	w, deps := newTestWatcher(t, cfg)
+
+	deps.resolver.allRecords["www.example.com"] = map[string]map[string][]string{
+		"ns1.example.com.": {"A": {"93.184.216.34"}},
+	}
+	deps.resolver.ipAddresses["www.example.com"] = []string{
+		"93.184.216.34",
+	}
+	deps.portChecker.results["93.184.216.34:80"] = false
+	deps.portChecker.results["93.184.216.34:443"] = false
+
+	ctx := t.Context()
+	w.RunOnce(ctx)
+
+	deps.resolver.mu.Lock()
+	deps.resolver.allRecords["www.example.com"] = map[string]map[string][]string{
+		"ns1.example.com.": {"A": {"93.184.216.35"}},
+	}
+	deps.resolver.ipAddresses["www.example.com"] = []string{
+		"93.184.216.35",
+	}
+	deps.resolver.mu.Unlock()
+
+	deps.portChecker.mu.Lock()
+	deps.portChecker.results["93.184.216.35:80"] = false
+	deps.portChecker.results["93.184.216.35:443"] = false
+	deps.portChecker.mu.Unlock()
+
+	w.RunOnce(ctx)
+
+	notifications := deps.notifier.getNotifications()
+	if len(notifications) == 0 {
+		t.Error("expected notification for record change")
+	}
+}
+
+func TestPortStateChange(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Hostnames = []string{"www.example.com"}
+
+	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(90 * 24 * time.Hour),
+		SubjectAlternativeNames: []string{
+			"www.example.com",
+		},
+	}
+
+	ctx := t.Context()
+	w.RunOnce(ctx)
+
+	deps.portChecker.mu.Lock()
+	deps.portChecker.results["1.2.3.4:443"] = false
+	deps.portChecker.mu.Unlock()
+
+	w.RunOnce(ctx)
+
+	notifications := deps.notifier.getNotifications()
+	if len(notifications) == 0 {
+		t.Error("expected notification for port state change")
+	}
+}
+
+func TestTLSExpiryWarning(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Hostnames = []string{"www.example.com"}
+
+	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
+	w.RunOnce(ctx)
+
+	// Second run should warn about expiry
+	w.RunOnce(ctx)
+
+	notifications := deps.notifier.getNotifications()
+
+	found := false
+
+	for _, n := range notifications {
+		if n.Priority == "warning" {
+			found = true
+		}
+	}
+
+	if !found {
+		t.Errorf(
+			"expected expiry warning, got: %v",
+			notifications,
+		)
+	}
+}
+
+func TestGracefulShutdown(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{"example.com"}
+	cfg.DNSInterval = 100 * time.Millisecond
+	cfg.TLSInterval = 100 * time.Millisecond
+
+	w, deps := newTestWatcher(t, cfg)
+
+	deps.resolver.nsRecords["example.com"] = []string{
+		"ns1.example.com.",
+	}
+
+	ctx, cancel := context.WithCancel(t.Context())
+
+	done := make(chan struct{})
+
+	go func() {
+		w.Run(ctx)
+		close(done)
+	}()
+
+	time.Sleep(250 * time.Millisecond)
+	cancel()
+
+	select {
+	case <-done:
+		// Shut down cleanly
+	case <-time.After(5 * time.Second):
+		t.Error("watcher did not shut down within timeout")
+	}
+}
+
+func TestNSFailureAndRecovery(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Hostnames = []string{"www.example.com"}
+
+	w, deps := newTestWatcher(t, cfg)
+
+	deps.resolver.allRecords["www.example.com"] = map[string]map[string][]string{
+		"ns1.example.com.": {"A": {"1.2.3.4"}},
+		"ns2.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"] = false
+	deps.portChecker.results["1.2.3.4:443"] = false
+
+	ctx := t.Context()
+
+	w.RunOnce(ctx)
+
+	deps.resolver.mu.Lock()
+	deps.resolver.allRecords["www.example.com"] = map[string]map[string][]string{
+		"ns1.example.com.": {"A": {"1.2.3.4"}},
+	}
+	deps.resolver.mu.Unlock()
+
+	w.RunOnce(ctx)
+
+	notifications := deps.notifier.getNotifications()
+	if len(notifications) == 0 {
+		t.Error("expected notification for NS disappearance")
+	}
+}