watcher: a hostname whose zone's nameservers all stop answering gets NS Failure (closes #284)

When none of the nameservers of a hostname's zone answered, the walk to
them failed and the check was only logged. The walk now returns a
NoAnswerError naming the nameservers of the zone it reached through a
referral when none of them answers. When those are the nameservers the
previous check saved for the name, each is saved as failed with the
reason, so it gets an NS Failure and later an NS Recovery. A domain with
no delegation of its own, whose NS lookup is that same walk, gets the
same. A walk that fails before that zone, as when the host loses its
network, is still only logged.

Model: opus-5-5

.dockerignore

@@ -1,6 +1,75 @@
-.git/
+# .dockerignore does NOT use .gitignore semantics. Docker matches with
-bin/
+# moby/patternmatcher: filepath.Match plus `**`, so `*` does not cross
-*.md
+# `/` and an unprefixed pattern is anchored at the context root. Every
-LICENSE
+# depth-independent pattern therefore needs `**/`, or `config/.env` and
-.editorconfig
+# `certs/server.key` still ship while this file reads as solved. Only
-.gitignore
+# genuinely root-anchored entries go unprefixed. Never transplant these
+# into .gitignore, where `**/` is wrong.
+#
+# Matching is case-sensitive, so secrets use character ranges rather
+# than an ALL-CAPS twin, which would still miss `Server.Key`.
+#
+# Extend with this repo's own host-built artifacts, written anchored:
+# `/myapp`, never `**/myapp`, which also matches `cmd/myapp/` and
+# deletes the package directory from the context.
+
+# .git is sent without its config. Without a VERSION build argument the
+# stage that compiles runs `git describe --tags --always` on .git, which
+# does not need .git/config; that file can hold a credential, such as a
+# password in a remote URL or the token the CI checkout step stores there.
+# Each submodule keeps a config with the same exposure in its git directory
+# under .git/modules/, nested again for a submodule's own submodules, or in
+# its own .git directory when it keeps one.
+# KNOWN GAP: a submodule whose name has a `config` segment (`config`,
+# `deploy/config`, `config/lib`) loses its whole git directory, because
+# `**/.git/modules/**/config` also matches that segment's directory
+# under .git/modules/. Go's version stamping then fails the build;
+# nothing leaks. Name such a submodule without that segment:
+# `git submodule add --name`.
+**/.git/config
+**/.git/modules/**/config
+
+# Agent scratch: one full checkout of the repo per in-flight agent.
+# Anchored because it occurs once where agents run at the repo root.
+# KNOWN GAP: a repo running agents in subdirectories still ships
+# `services/api/.claude/` and must add its own anchored entry.
+.claude
+
+# Environment files. `*.env` covers bare `.env` and the `prod.env`
+# convention. Re-include a committed template with a negation if the
+# build needs one: `!docs/example.env`.
+**/*.[eE][nN][vV]
+**/.[eE][nN][vV].*
+**/.[eE][nN][vV][rR][cC]
+
+# Private keys and the bundles carrying them. Public certificates
+# (*.crt, *.cer) are deliberately absent: they are legitimate inputs.
+**/*.[pP][eE][mM]
+**/*.[kK][eE][yY]
+**/*.[pP]12
+**/*.[pP][fF][xX]
+**/[iI][dD]_[rR][sS][aA]
+**/[iI][dD]_[dD][sS][aA]
+**/[iI][dD]_[eE][cC][dD][sS][aA]
+**/[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK]
+**/[iI][dD]_[eE][dD]25519
+**/[iI][dD]_[eE][dD]25519_[sS][kK]
+
+# Dependencies: restored inside the image, never copied in.
+**/node_modules
+
+# OS metadata.
+**/.DS_Store
+**/Thumbs.db
+
+# Editor state: never a build input, and it churns COPY.
+**/*.swp
+**/*.swo
+**/*~
+**/*.bak
+**/.idea
+**/.vscode
+**/*.sublime-*
+
+# This repository's host-built artifacts: `make build` writes bin/.
+/bin

.editorconfig

@@ -10,3 +10,6 @@ insert_final_newline = true
 
 [Makefile]
 indent_style = tab
+
+[*.go]
+indent_style = tab

.gitea/workflows/check.yml

@@ -1,9 +1,17 @@
 name: check
 on: [push]
+# A new push to a branch cancels that branch's older run, queued or running;
+# runs on other branches, `next` and `main` among them, are left alone.
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
 jobs:
     check:
         runs-on: ubuntu-latest
         steps:
-            # actions/checkout v4.2.2, 2026-02-28
+            # actions/checkout v4.2.2, 2026-02-22
             - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+              # script/cibuild needs no token, so none is left in .git/config.
+              with:
+                  persist-credentials: false
             - run: script/cibuild

.gitignore

@@ -1,6 +1,57 @@
+# OS
+.DS_Store
+Thumbs.db
+
+# Editors
+*.swp
+*.swo
+*~
+*.bak
+.idea/
+.vscode/
+*.sublime-*
+
+# Agent scratch (worktrees of this repo, created and destroyed by
+# in-flight tooling). Unanchored: .gitignore patterns already match at
+# every depth, so no prefix is wanted here. This is not a .dockerignore
+# entry and must not be given a `**/` prefix on the way into one.
+.claude/
+
+# Node
+node_modules/
+
+# Secrets. Unanchored like every entry above, so each matches at every
+# depth. Matching is case-sensitive on Linux, so names use character
+# ranges rather than a lowercase form that misses `Server.Key`.
+
+# Environment files. `*.env` covers bare `.env` and the `prod.env`
+# convention. Only the templates `example.env` and `sample.env` are
+# re-included below. A repository that commits any other template adds
+# its own negation after these lines, for example `!.env.example`.
+*.[eE][nN][vV]
+.[eE][nN][vV].*
+.[eE][nN][vV][rR][cC]
+!example.env
+!sample.env
+
+# Private keys and the bundles carrying them.
+*.[pP][eE][mM]
+*.[kK][eE][yY]
+*.[pP]12
+*.[pP][fF][xX]
+[iI][dD]_[rR][sS][aA]
+[iI][dD]_[dD][sS][aA]
+[iI][dD]_[eE][cC][dD][sS][aA]
+[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK]
+[iI][dD]_[eE][dD]25519
+[iI][dD]_[eE][dD]25519_[sS][kK]
+
+# This repository's own entries, kept after the canonical content above.
+*.log
+*.out
+*.test
 bin/
 vendor/
 data/
-.env
 *.exe
 /dnswatcher

.golangci.yml

@@ -17,6 +17,7 @@ linters:
   disable:
     # Genuinely incompatible with project patterns
     - exhaustruct      # Requires all struct fields
+    - exhaustruct_v5   # Requires all struct fields (successor to exhaustruct)
     - godot            # Requires comments to end with periods
     - wrapcheck        # Too verbose for internal packages
     - varnamelen       # Short names like db, id are idiomatic Go

.prettierignore

@@ -0,0 +1,2 @@
+node_modules/
+yarn.lock

.prettierrc

@@ -0,0 +1,4 @@
+{
+    "tabWidth": 4,
+    "proseWrap": "always"
+}

Dockerfile

@@ -1,46 +1,102 @@
-# Lint stage - fast feedback on lint issues, before the build starts.
+# Lint phase, built alone by script/lint. The linter is invoked directly
-# The linter is invoked directly rather than through `make lint`: that
+# rather than through `make lint`, which is itself a docker build and
-# target shells out to `docker build -f Dockerfile.lint`, and there is
+# would recurse into a daemon that does not exist in a build step.
-# no docker daemon inside a docker build.
+# golangci/golangci-lint:v2.14.0 (Debian-based), 2026-10-06
-# script/cibuild and script/docker name this stage in --no-cache-filter.
+FROM golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f AS lint
-# golangci/golangci-lint:v2.12.2 (Debian-based), 2026-08-10
-FROM golangci/golangci-lint:v2.12.2@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240 AS lint
-
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
-
 COPY . .
-
-RUN make fmt-check
 RUN golangci-lint run --config .golangci.yml ./...
 
-# Build stage
+# Test phase, built alone by script/test. -race needs cgo and so a C
-# script/cibuild and script/docker name this stage in --no-cache-filter.
+# compiler, which the Debian Go image ships and the alpine one does not.
-# golang 1.25-alpine, 2026-02-28
+# The tests query live DNS (TESTING.md), so this step needs the network.
-FROM golang@sha256:f6751d823c26342f9506c03797d2527668d095b0a15f1862cddb4d927a7a4ced AS builder
+# -count=1 keeps Go's test result cache out of both runs, as TESTING.md
-
+# requires. -timeout 90s is a backstop above the 60-second cap on the
-RUN apk add --no-cache git make gcc musl-dev binutils-gold
+# suite. The rerun with -v only shows details: the build fails however
-
+# it ends, because the first run already failed.
-# Force BuildKit to run the lint stage before proceeding
+# golang 1.25.7-trixie, 2026-10-06
-COPY --from=lint /src/go.sum /dev/null
+FROM golang@sha256:2b174ffcf56c7ad0c47d30d2630693265639ddf2a5141149c2da34db921791b4 AS test
-
+# The file permission tests skip themselves as root, so the tests run as
+# an ordinary user, whose home directory holds Go's build cache.
+RUN useradd --create-home tester
+USER tester
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
+COPY . .
+RUN go test -count=1 -race -timeout 90s -cover ./... || \
+    { echo "--- Rerunning with -v for details ---"; \
+      go test -count=1 -race -timeout 90s -v ./...; exit 1; }
 
+# Markdown formatting with prettier, at the version package.json and
+# yarn.lock pin, so it is never installed on the host. script/fmt-check
+# builds the fmt-check stage and script/fmt the fmt-out stage; the image
+# does not depend on any of these stages, so a plain `docker build .`
+# skips them.
+# node:22-bookworm-slim, 2026-09-05
+FROM node@sha256:83f487e0a63425e5b4d146fb5e5be574bcbe1b7b843d3ebafdd95eaf7767a7e5 AS nodedeps
+# prettier lives outside /src, so the COPY of the repo cannot overwrite
+# it and node_modules is not in the tree prettier walks.
+WORKDIR /tools
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile --non-interactive --no-progress
+ENV PATH="/tools/node_modules/.bin:${PATH}"
+WORKDIR /src
+
+# --config rather than discovery: a missing .prettierrc is then an error
+# instead of prettier's defaults, under which every wrap passes.
+# --no-editorconfig so .prettierrc alone sets the style.
+FROM nodedeps AS fmt-check
+COPY . .
+RUN prettier --config .prettierrc --no-editorconfig --check "**/*.md"
+
+# Only the markdown is copied out, with its paths, so the export cannot
+# put anything else back over the working tree.
+FROM nodedeps AS fmt
+COPY . .
+RUN prettier --config .prettierrc --no-editorconfig --write "**/*.md" && \
+    mkdir -p /out && \
+    find . -name '*.md' -type f -exec cp --parents '{}' /out/ ';'
+
+FROM scratch AS fmt-out
+COPY --from=fmt /out/ /
+
+# Build stage. Nothing is wanted from the lint and test phases; the
+# copies are what make BuildKit build them first, so this stage cannot
+# run unless lint and test passed.
+# golang 1.25-alpine, 2026-02-28
+FROM golang@sha256:f6751d823c26342f9506c03797d2527668d095b0a15f1862cddb4d927a7a4ced AS builder
+COPY --from=lint /src/go.sum /dev/null
+COPY --from=test /src/go.sum /dev/null
+RUN apk add --no-cache git
+# A tar-stream context keeps the sender's file owners, which git refuses.
+RUN git config --system --add safe.directory /src
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
 COPY . .
 
-# Run the tests - build fails if any test fails
+# The VERSION build arg when one is given (script/docker and
-RUN make test
+# script/cibuild pass one), otherwise `git describe --tags --always` on
+# the .git in the build context. With .git present, a version that is
+# still empty, dev or unknown fails the build: git is missing or could
+# not read the checkout.
+ARG VERSION
+RUN VERSION="${VERSION:-$(git describe --tags --always)}"; \
+    if [ -e .git ]; then \
+        case "$VERSION" in ""|dev|unknown) \
+            echo "version is '$VERSION' although .git is present" >&2; \
+            exit 1 ;; \
+        esac; \
+    fi; \
+    CGO_ENABLED=0 go build -trimpath \
+        -ldflags="-s -w -X main.Version=${VERSION}" \
+        -o /src/bin/dnswatcher ./cmd/dnswatcher/
 
-# Build the binary. .dockerignore leaves out .git, so `git describe` in
+# Runtime stage, and the last one: a plain `docker build .` builds this
-# the Makefile cannot find the version here: script/docker passes it as
+# stage's chain and nothing else.
-# --build-arg VERSION, and a build that passes none reports `dev`.
-ARG VERSION=dev
-RUN make build VERSION="${VERSION}"
-
-# Runtime stage
 # alpine 3.21, 2026-02-28
 FROM alpine@sha256:c3f8e73fdb79deaebaa2037150150191b9dcbfba68b4a46d70103204c53f4709
 

Dockerfile.lint

@@ -1,29 +0,0 @@
-# Lint-only image: used by script/lint. golangci-lint is never run on
-# the host — the repo is COPYed into the build context and the linter
-# runs as a build step, so a successful build IS a clean lint. This
-# also works where the docker daemon is remote and bind mounts are
-# impossible.
-#
-# `golangci-lint config verify` is deliberately NOT run here: it
-# fetches its JSON schema over a live, unpinned HTTPS call, which would
-# make linting network-dependent and defeat hash-pinning. The cost of
-# that: unknown top-level keys in .golangci.yml are silently ignored,
-# so a mistyped or wrong-schema key lints clean while applying nothing.
-#
-# golangci/golangci-lint:v2.12.2 (Debian-based), 2026-08-10
-FROM golangci/golangci-lint:v2.12.2@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240 AS deps
-
-WORKDIR /src
-
-# Dependencies first, so this stage stays cached across lint runs.
-COPY go.mod go.sum ./
-RUN go mod download
-
-# Everything below is invalidated on every run by the
-# --no-cache-filter=lint that script/lint passes: caching is explicitly
-# waived for linting, and a cached build lints nothing.
-FROM deps AS lint
-
-COPY . .
-
-RUN golangci-lint run --config .golangci.yml ./...

Makefile

@@ -1,9 +1,13 @@
-.PHONY: all bootstrap setup build lint fmt fmt-check test check clean hooks docker
+.PHONY: all bootstrap setup build version lint fmt fmt-check test check clean hooks docker
 
 BINARY := dnswatcher
-# `make build VERSION=...` overrides this; the Dockerfile does so, as the
+# VERSION given on the command line (`make build VERSION=...`) or in the
-# image has no .git to describe.
+# environment wins over what `git describe` says of this checkout. An
-VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
+# empty one counts as not given; `override` is what replaces an empty
+# command-line value.
+ifeq ($(VERSION),)
+override VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
+endif
 LDFLAGS := -X main.Version=$(VERSION)
 
 # Standard targets are thin shims; the implementations live in script/
@@ -21,6 +25,10 @@ setup:
 build:
 	go build -ldflags "$(LDFLAGS)" -o bin/$(BINARY) ./cmd/dnswatcher
 
+# Prints the version `make build` stamps.
+version:
+	@echo "$(VERSION)"
+
 test:
 	@script/test
 

REPO_POLICIES.md

@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-08-07
+last_modified: 2026-10-04
 ---
 
 This document covers repository structure, tooling, and workflow standards. Code
@@ -60,17 +60,28 @@ style conventions are in separate documents:
   prerequisite since nvm requires bash. yarn is then pinned via
   `corepack prepare yarn@<version> --activate`. Never install "latest" or "lts";
   always exact versions. `script/cibuild` runs the CI build: it changes to the
-  repo root and runs `docker build .`; the Gitea workflow calls it. Four further
+  repo root, runs `script/bootstrap`, runs `script/check`, and builds the image
-  scripts are our own extensions to the standard: `script/check` runs
+  with the version; the Gitea workflow calls it. **`script/cibuild` runs
-  `script/test`, `script/lint`, and `script/fmt-check`; `script/precommit` is
+  `script/bootstrap` first**, because the workflow checks out the repo and runs
-  what the git pre-commit hook runs, and it calls `script/check`;
+  nothing else, while `script/fmt-check` runs the formatter on the host: on a
-  `script/install-precommit` installs the git pre-commit hook (the `make hooks`
+  pristine checkout with nothing installed the run dies there, after the
-  target shims to it); and `script/projectname` (literally that filename) simply
+  containerised gates have passed. **The bootstrap alone is not enough**:
-  outputs the project's name. Scripts that need the name call
+  `script/bootstrap` installs node and yarn under nvm and leaves neither on the
-  `script/projectname` — e.g. `script/docker` assembles its image tag from it —
+  `PATH` of the shell that called it, so a bare `yarn` still exits 127. The host
-  so those scripts stay byte-identical across all repos. Repo-type-specific
+  entrypoints that need yarn — `script/fmt` and `script/fmt-check` — therefore
-  pre-commit extras (e.g. `go mod tidy` verification in Go repos) belong in
+  source nvm for the pinned node version before invoking it, exactly as
-  `script/precommit`, not in the hook itself. Model scripts are at
+  `script/bootstrap`'s own install step does. A runner carrying nothing but
+  docker and git then gets through `script/check`. Four further scripts are our
+  own extensions to the standard: `script/check` runs `script/test`,
+  `script/lint` and `script/fmt-check`; `script/precommit` is what the git
+  pre-commit hook runs, and it calls `script/check`; `script/install-precommit`
+  installs the git pre-commit hook (the `make hooks` target shims to it); and
+  `script/projectname` (literally that filename) simply outputs the project's
+  name. Scripts that need the name call `script/projectname` — e.g.
+  `script/docker` assembles its image tag from it — so those scripts stay
+  byte-identical across all repos. Repo-type-specific pre-commit extras (e.g.
+  `go mod tidy` verification in Go repos) belong in `script/precommit`, not in
+  the hook itself. Model scripts are at
   `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`. The README
   must document the provided scripts in an **Entrypoints** section (see the
   README requirements below).
@@ -89,87 +100,198 @@ style conventions are in separate documents:
   contributor should be able to understand the entire development workflow by
   reading the Makefile.
 
-- Every repo should have a `Dockerfile`. All Dockerfiles must run `make check`
+- Every repo should have a `Dockerfile`, and it carries the repo's gates: a
-  as a build step so the build fails if the branch is not green. For non-server
+  `lint` phase and a `test` phase, with the final stage depending on both so the
-  repos, the Dockerfile should bring up a development environment and run
+  image cannot be built unless they pass. For non-server repos the final stage
-  `make check`. For server repos, `make check` should run as an early build
+  brings up a development environment; for server repos it is the runtime image.
-  stage before the final image is assembled. Dockerfiles install development
+  The gate phases and the build stage start from their pinned base images and
-  prerequisites by running `script/bootstrap` rather than duplicating installs
+  install what those images lack either inline, as the canonical Go `Dockerfile`
-  inline; COPY `script/` and the dependency manifests (`package.json` +
+  below does for `git`, or by running `script/bootstrap`, as the `prompts`
-  `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it so the bootstrap
+  repo's own `Dockerfile` does for its yarn packages. The development
-  layer stays cached until dependencies change.
+  environment stage installs development prerequisites by running
+  `script/bootstrap` rather than duplicating its installs inline. A stage that
+  runs `script/bootstrap` COPYs `script/` and the dependency manifests
+  (`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it.
 
-- **Dockerfiles must use a separate lint stage for fail-fast feedback.** Go
+- **Linting and testing run in Docker, as phases of the `Dockerfile`.** There is
-  repos use a multistage build where linting runs in an independent stage based
+  no separate lint file. `script/lint` and `script/test` each build one phase
-  on the `golangci/golangci-lint` image (pinned by hash). This stage runs
+  and nothing else:
-  `make fmt-check` and `make lint` before the full build begins. The build stage
-  then declares an explicit dependency on the lint stage via
-  `COPY --from=lint /src/go.sum /dev/null`, which forces BuildKit to complete
-  linting before proceeding to compilation and tests. This ensures lint failures
-  surface in seconds rather than minutes, without blocking on dependency
-  download or compilation in the build stage.
 
-    The standard pattern for a Go repo Dockerfile is:
+    ```sh
+    docker build --no-cache --target lint -t "$(script/projectname)-lint" .
+    docker build --no-cache --target test -t "$(script/projectname)-test" .
+    ```
+
+    **A stage that is not the last one in the file is built only when the final
+    stage's chain depends on it, or when `--target` names it.** That is why the
+    two gates are always invoked by name here, and why the final stage carries a
+    `COPY --from=` of a harmless file from each of them: without that edge a
+    plain `docker build .` builds the last stage alone and exits 0 having linted
+    and tested nothing.
+
+    **Every `docker build` in `script/` is tagged**, here and in
+    `script/cibuild` and `script/docker`. An untagged build leaves a dangling
+    image behind on every invocation, on every developer host and every CI
+    runner; a tagged one replaces the previous image.
+
+    Inside a phase the tool is invoked directly — `golangci-lint`, `go test`,
+    `eslint`, `prettier` — never through `make lint` or `script/test`, which are
+    themselves a `docker build` and would recurse into a daemon that does not
+    exist in a build step. Formatting is the exception and stays on the host:
+    `script/fmt` writes the working tree, and `script/fmt-check` is its
+    read-only twin.
+
+    **No lint verdict may come from a host invocation of the linter.** On a
+    shared host golangci-lint reads a result cache keyed on file content rather
+    than location, so a second checkout of the same content is served the first
+    one's findings, and a host-global lock in `$TMPDIR` makes concurrent runs
+    exit non-zero with `parallel golangci-lint is running` — a status a caller
+    cannot tell from real findings. Both have produced wrong verdicts in this
+    org, in both directions. A container has its own cache, its own `TMPDIR` and
+    a digest-pinned binary, so neither is reachable.
+
+- **Any build that runs checks is built with `--no-cache`.** Docker invalidates
+  a `COPY` layer only when the copied content changes, so on an unchanged tree
+  the check `RUN` is served from cache, nothing executes, and the build still
+  exits 0. Every `docker build` in `script/` therefore passes `--no-cache`:
+  `script/lint`, `script/test`, `script/cibuild` and `script/docker` are the
+  four, and there is no fifth — `script/check` runs the two gate phases and
+  `script/fmt-check`, and builds no image of its own. A bare `docker build .` is
+  not evidence that anything ran: a sub-second build reporting success is a
+  cache hit, not a result. Never invalidate by pruning — `docker builder prune`
+  and friends destroy a build cache shared with every other build on the host.
+  When a check is added or changed, prove it works by planting a defect it must
+  catch and watching the run fail on it, then revert the defect. A green run
+  alone shows neither that the check ran nor that it covers what it should.
+
+- **The gate phases are separate stages, and the build stage depends on both.**
+  The lint phase is based on the `golangci/golangci-lint` image (pinned by
+  hash), so lint failures surface in seconds rather than after a full compile,
+  and the test phase is based on the Debian Go image. The canonical Go repo
+  `Dockerfile`:
 
     ```dockerfile
-    # Lint stage — fast feedback on formatting and lint issues
+    # Lint phase
     # golangci/golangci-lint:v2.x.x, YYYY-MM-DD
     FROM golangci/golangci-lint@sha256:... AS lint
     WORKDIR /src
     COPY go.mod go.sum ./
     RUN go mod download
     COPY . .
-    RUN make fmt-check
+    RUN golangci-lint run --config .golangci.yml ./...
-    RUN make lint
 
-    # Build stage
+    # Test phase. -race needs cgo and so a C compiler, which the Debian Go
-    # golang:1.x-alpine, YYYY-MM-DD
+    # image ships and the alpine one does not.
-    FROM golang@sha256:... AS builder
+    # golang:1.x, YYYY-MM-DD
+    FROM golang@sha256:... AS test
     WORKDIR /src
-
-    # Force BuildKit to run the lint stage before proceeding
-    COPY --from=lint /src/go.sum /dev/null
-
     COPY go.mod go.sum ./
     RUN go mod download
     COPY . .
-    RUN make test
+    RUN go test -timeout 90s -race -cover ./... || \
+        { echo "--- Rerunning with -v for details ---"; \
+          go test -timeout 90s -race -v ./...; exit 1; }
 
-    ARG VERSION=dev
+    # Build stage. Nothing is wanted from either phase above; the copies
-    RUN CGO_ENABLED=0 go build -trimpath \
+    # are what make BuildKit build them first, so this stage cannot run
-        -ldflags="-s -w -X main.Version=${VERSION}" \
+    # unless lint and test passed.
-        -o /app ./cmd/app/
+    # golang:1.x-alpine, YYYY-MM-DD
+    FROM golang@sha256:... AS builder
+    COPY --from=lint /src/go.sum /dev/null
+    COPY --from=test /src/go.sum /dev/null
+    RUN apk add --no-cache git
+    # A tar-stream context keeps the sender's file owners, which git refuses.
+    RUN git config --system --add safe.directory /src
+    WORKDIR /src
+    COPY go.mod go.sum ./
+    RUN go mod download
+    COPY . .
 
-    # Runtime stage
+    # The VERSION build arg when one is given, otherwise
+    # `git describe --tags --always` on the .git in the build context. With
+    # .git present, a version that is still empty, dev or unknown fails the
+    # build: git is missing or could not read the checkout.
+    ARG VERSION
+    RUN VERSION="${VERSION:-$(git describe --tags --always)}"; \
+        if [ -e .git ]; then \
+            case "$VERSION" in ""|dev|unknown) \
+                echo "version is '$VERSION' although .git is present" >&2; \
+                exit 1 ;; \
+            esac; \
+        fi; \
+        CGO_ENABLED=0 go build -trimpath \
+            -ldflags="-s -w -X main.Version=${VERSION}" \
+            -o /app ./cmd/app/
+
+    # Runtime stage, and the last one
     FROM alpine@sha256:...
     COPY --from=builder /app /usr/local/bin/app
     ENTRYPOINT ["app"]
     ```
 
     Key points:
-    - The lint stage uses the `golangci/golangci-lint` image directly (it
+    - The lint phase uses the `golangci/golangci-lint` image directly (it has
-      includes both Go and the linter), so there is no need to install the
+      both Go and the linter), so nothing needs installing.
-      linter separately.
+    - `COPY --from=<phase> /src/go.sum /dev/null` is a no-op copy whose only
-    - `COPY --from=lint /src/go.sum /dev/null` is a no-op file copy that creates
+      purpose is the ordering edge. BuildKit runs stages in parallel by default,
-      a stage dependency. BuildKit runs stages in parallel by default; without
+      and a stage nothing depends on is not built at all, so without these two
-      this line, the build stage would not wait for lint to finish and a lint
+      lines a red gate would not fail the build.
-      failure might not fail the overall build.
+    - Keep the runtime stage last, and if you add a stage after it, give it the
+      same two copies. A plain `docker build .` builds the last stage's chain
+      and nothing else.
     - If the project uses `//go:embed` directives that reference build artifacts
-      (e.g. a web frontend compiled in a separate stage), the lint stage must
+      (e.g. a web frontend compiled in a separate stage), the lint phase must
       create placeholder files so the embed directives resolve. Example:
       `RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css`.
-      The lint stage should not depend on the actual build output — it exists to
+    - If the project requires CGO or system libraries for linting, install them
-      fail fast.
+      in the lint phase. The `golangci/golangci-lint` image is Debian-based and
-    - If the project requires CGO or system libraries for linting (e.g.
+      has no `apk`, so install with `apt-get` under the Debian package name
-      `vips-dev`), install them in the lint stage with `apk add`.
+      (`libvips-dev`, where alpine says `vips-dev`), and delete the package
-    - The build stage runs `make test` after compilation setup. Tests run in the
+      lists in the same `RUN`, so the layer does not keep them:
-      build stage, not the lint stage, because they may require compiled
+
-      artifacts or heavier dependencies.
+        ```dockerfile
+        RUN apt-get update \
+            && apt-get install -y --no-install-recommends libvips-dev \
+            && rm -rf /var/lib/apt/lists/*
+        ```
+
+    - `.dockerignore` lets `.git` into the build context. It keeps out every git
+      `config` at any depth (`**/.git/config`, `**/.git/modules/**/config`): the
+      repository's own, each submodule's under `.git/modules/`, and that of a
+      submodule keeping its own `.git` directory. `git describe` does not need
+      them, and each can hold a credential: a password in a remote URL, or the
+      token the CI checkout step stores there. A submodule whose name has a
+      `config` segment (`config`, `deploy/config`, `config/lib`) loses its whole
+      git directory to `**/.git/modules/**/config`, and Go's version stamping
+      then fails the build: give it a name without that segment
+      (`git submodule add --name`). The stage that compiles has `git` (the
+      Debian Go image has it; an alpine one needs `apk add --no-cache git`) and
+      takes the version from the `VERSION` build argument when one is given,
+      otherwise from `git describe --tags --always`. That gives the tag on a
+      tagged commit; on a later commit, the tag, the number of commits since it
+      and the short commit (`v1.2.3-4-gabc1234`); and the short commit when no
+      tag is reachable. The stage that compiles also marks its working directory
+      safe for git (`git config --system --add safe.directory /src`): a context
+      sent as a tar stream keeps the sender's file owners, and git refuses a
+      checkout owned by another user, so the version would come out empty.
+      `ARG VERSION` has no default, and the build fails if the context carries
+      `.git` and the version still comes out empty, `dev` or `unknown`. A plain
+      `docker build .` with no build arguments must succeed; a Dockerfile that
+      refuses an empty build argument drops that refusal and keeps the argument.
 
 - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
-  runs `script/cibuild` (which runs `docker build .`) on push. Since the
+  runs `script/cibuild` on push, and checks out the repo as its only other step.
-  Dockerfile already runs `make check`, a successful build implies all checks
+  That script bootstraps, runs the gate phases, and then builds the image, so a
-  pass.
+  successful run means every check passed; a bare `docker build .` does not
+  carry the same guarantee, because its gate phases may come from the cache. The
+  image build is uncached and so runs the gate phases a second time. That is the
+  price of the rule above, and it is worth paying: the image that ships is built
+  from a run of its own gates rather than from a cache entry. A separate
+  workflow limited to `main` by a `branches` list under `on: push` cannot be
+  checked by review: to try a change to it, add the feature branch to that list
+  and push, then remove the branch from the list again before merging. Keep any
+  job in it that publishes behind `if: github.ref_name == 'main'`, so the run
+  from the feature branch publishes nothing.
 
 - Use platform-standard formatters: `black` for Python, `prettier` for
   JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
@@ -193,15 +315,17 @@ style conventions are in separate documents:
   suite that exceeds it fails. Under 20 seconds is the target. A suite between
   20 and 60 seconds is still green, but the overage must be filed as an
   improvement bug against that repo. Add a 90-second timeout to the test
-  invocation in the Makefile (`go test -timeout 90s`). The backstop deliberately
+  invocation (`go test -timeout 90s`). The backstop deliberately sits above the
-  sits above the hard cap so that it catches a genuinely hung test rather than a
+  hard cap so that it catches a genuinely hung test rather than a merely slow
-  merely slow one.
+  one.
 
-- **`make test` should use the conditional verbose rerun pattern.** Run tests
+- **The test command should use the conditional verbose rerun pattern.** Run
-  without `-v` (verbose) first. If tests fail, automatically rerun with `-v` to
+  tests without `-v` (verbose) first. If tests fail, automatically rerun with
-  show full output. This keeps CI logs and `docker build` output clean on
+  `-v` to show full output. This keeps CI logs and `docker build` output clean
-  success (just package/suite summaries) while providing full diagnostic detail
+  on success (just package/suite summaries) while providing full diagnostic
-  on failure (every test case, every assertion). The general shell pattern:
+  detail on failure (every test case, every assertion). The command lives in the
+  `test` phase of the `Dockerfile`, since `script/test` builds that phase; the
+  Makefile form below is the same pattern for any repo-local invocation:
 
     ```makefile
     test:
@@ -214,11 +338,26 @@ style conventions are in separate documents:
 
     ```makefile
     test:
-    	@go test -timeout 90s -race -cover ./... || \
+    	@go test -count=1 -timeout 90s -race -cover ./... || \
     		{ echo "--- Rerunning with -v for details ---"; \
-    		  go test -timeout 90s -race -v ./...; exit 1; }
+    		  go test -count=1 -timeout 90s -race -v ./...; exit 1; }
     ```
 
+    `-count=1` is required on both invocations: it defeats Go's test _result_
+    cache, so neither run can report a stored pass in place of running the
+    tests. It leaves the build cache alone, so it costs the runtime of the suite
+    and no recompilation.
+
+    That cache is Go's own, separate from Docker's layer cache. Go stores a
+    passing result in its cache directory (`GOCACHE`), and when the same tests
+    run again on unchanged code it prints that result, marked `(cached)`,
+    without running them. That matters on a developer's machine, where this
+    target runs and the directory lasts from one run to the next. The `test`
+    phase of the `Dockerfile` needs no `-count=1`: its base image holds no
+    result for this repo's tests and nothing before its `go test` step runs a
+    test, so there is nothing to replay. `--no-cache` (above) is what makes that
+    step run on an unchanged tree.
+
     Python example:
 
     ```makefile
@@ -244,10 +383,84 @@ style conventions are in separate documents:
   must be in `.gitignore`. No exceptions.
 
 - `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
-  editor files (`.swp`, `*~`), language build artifacts, and `node_modules/`.
+  editor files (`.swp`, `*~`), in-repo agent scratch directories (`.claude/`),
-  Fetch the standard `.gitignore` from
+  language build artifacts, and `node_modules/`. Fetch the standard `.gitignore`
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
+  from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when
-  a new repo.
+  setting up a new repo. These patterns are written to `.gitignore`'s own
+  semantics, in which an unanchored pattern already matches at every depth; they
+  are not a `.dockerignore` and must not be transplanted into one unmodified.
+
+- **`.dockerignore` does not use `.gitignore` semantics, and copying patterns
+  across unmodified leaves secrets in the build context.** Docker matches with
+  `moby/patternmatcher`: `filepath.Match` semantics plus a `**` extension, so
+  `*` does not cross `/` and a pattern without a leading `**/` is anchored at
+  the build-context root. A `.dockerignore` listing `.env`, `*.pem` and `*.key`
+  therefore excludes only the copies at the repository root, while `config/.env`
+  and `certs/server.key` still reach the context and can land in an image layer
+  — which is more dangerous than a short file with no secret patterns at all,
+  because it reads as solved and stops anyone looking. Give every
+  depth-independent pattern the `**/` prefix and leave only genuinely
+  root-anchored entries unprefixed: `.claude`, and the repo's own host-built
+  binary, written `/myapp` and never `**/myapp`, which would also match
+  `cmd/myapp/` and delete the package directory from the context. Matching is
+  case-sensitive, and an ALL-CAPS twin per pattern still misses `Server.Key`, so
+  secret names use character ranges — `**/*.[kK][eE][yY]`, `**/*.[pP][eE][mM]`,
+  and likewise for `.envrc` and the extensionless SSH keys. Where such a pattern
+  also catches something the build needs, re-include it with a negation
+  (`!docs/example.env`); deleting the pattern reopens the exposure for every
+  other file it covers. Fetch the standard `.dockerignore` from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` and extend
+  it with the repo's own artifacts.
+
+- **In-repo agent scratch belongs in both files, written to each file's own
+  semantics.** `.claude/` holds one worktree per in-flight agent — an entire
+  additional checkout of the repo — so under `COPY . .` the build context
+  inflates by a multiple of the repo and another session's unreviewed work can
+  be copied into an image layer. In `.gitignore` the entry is `.claude/`,
+  unanchored. In `.dockerignore` it is `.claude`, anchored and with **no** `**/`
+  prefix, because the prefixed form would also delete any nested directory of
+  that name from the build. Anchoring carries a known gap that the canonical
+  `.dockerignore` states in its own comment, since consuming repos receive the
+  file and not the tracker: the directory is created in the agent's working
+  directory, so a repo running agents in subdirectories still ships
+  `services/api/.claude/` and must add its own anchored entry there.
+
+- **A plain `docker build .` of a clone stamps the version that
+  `git describe --tags --always` gives**, derived from the `.git` in the build
+  context as the canonical `Dockerfile` above shows. Without its failure check,
+  a missing `git` or an unreadable checkout would leave `-X main.Version=` empty
+  and the build would still exit 0. `script/docker` and `script/cibuild` pass
+  the version they compute on the host; it takes precedence. They do this
+  byte-identically across repos:
+
+    ```sh
+    # Own line: a failing command substitution inside an argument does not
+    # trip `set -e`, so the inline form degrades to an empty constant.
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    [ -n "$version" ] || version="unknown"
+    docker build --no-cache \
+        --build-arg VERSION="$version" \
+        -t "$(script/projectname)" .
+    ```
+
+    `--always` makes an untagged repo yield an abbreviated commit hash rather
+    than failing, and the `[ -n "$version" ]` line is the single place the
+    fallback is applied — a live check that fires on a build from an export with
+    no `.git` and on a repository with no commits yet. Do not fold it into the
+    substitution as `|| echo unknown`, which makes the guard unreachable. The
+    Dockerfile's side is `ARG VERSION` in the stage that compiles, declared
+    there because `ARG` is stage-scoped; passing `VERSION` to a repo whose
+    Dockerfile declares no such `ARG` is ignored and costs nothing, which is why
+    the scripts stay byte-identical. One consequence for CI: the standard
+    checkout action clones shallow and fetches no tags, so a repo that embeds a
+    tag-derived version must set `fetch-depth: 0` on its checkout step.
+
+- **Verify `.dockerignore` by enumerating the image, not by reading the
+  patterns.** Plant files at the root _and_ at least two directories deep, build
+  a probe image that does `COPY . .`, and list what actually landed
+  (`docker run --rm --entrypoint find IMAGE /app`). The `transferring context`
+  size is not a substitute: a nested secret is a few bytes, and BuildKit
+  transfers only the delta from the previous build.
 
 - **No build artifacts in version control.** Code-derived data (compiled
   bundles, minified output, generated assets) must never be committed to the
@@ -263,12 +476,56 @@ style conventions are in separate documents:
 - Make all changes on a feature branch. You can do whatever you want on a
   feature branch.
 
-- `.golangci.yml` is standardized and must _NEVER_ be modified by an agent, only
+- `.golangci.yml` is standardized. The vendored copy in a consuming repo must
-  manually by the user. Fetch from
+  _NEVER_ be modified by an agent: fetch it from
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`. The
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml` and keep it
-  canonical golangci-lint version is v2.12.2 (released 2026-05-06), installed
+  byte-identical, so that no repo can quietly loosen its own linting. Linter
-  commit-pinned via
+  configuration changes are made to the canonical copy in the `prompts` repo and
-  `go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@c0d3ddc9cf3faa61a4e378e879ece580256d76e5`.
+  reach consuming repos by re-vendoring; an agent may open a PR against
+  canonical, which only the user merges. One list is exempt from byte-identity,
+  because it cannot be written once for every repo: the `deny` list of the
+  `test-support` depguard rule, where a repo names its own test-support packages
+  by full import path. A repo adds entries there and changes nothing else, and a
+  re-vendor carries its entries forward. The canonical golangci-lint version is
+  v2.14.0 (released 2026-09-24), pinned as the digest of the lint phase's base
+  image
+  (`golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f`,
+  which reports `2.14.0 built with go1.27.0 from 114493f9`). A module's `go`
+  directive must not name a newer Go minor version than the one golangci-lint
+  was built with, or golangci-lint refuses to lint it: this release lints
+  `go 1.27.1` but not `go 1.28`. That digest is the only pin, since no repo
+  installs golangci-lint on the host. A repo sets the lint phase digest to the
+  one named here and re-vendors `.golangci.yml` in the same commit, whichever of
+  the two prompted the change: the canonical copy can name linters that an older
+  golangci-lint rejects, and a newer golangci-lint can add linters that
+  `default: all` switches on until the canonical copy disables them.
+
+- **`script/bootstrap` installs a pinned tool by comparing versions, never by
+  testing presence.** An `if ! command -v <tool>; then install; fi` guard tests
+  `PATH` only, so on an already-provisioned machine the pin is inert and a
+  version bump is a silent no-op — while the Dockerfile, installing into a clean
+  image, gets the pinned version, so a local `make check` and `make docker` can
+  disagree about what the tool even is. The canonical form:
+    - compares the installed version against the pin over the **whole** version
+      token; a parser that stops at the first `-` reports `2.12.2` for a host
+      running `2.12.2-rc1` and skips the install;
+    - treats absent, non-zero, empty or unrecognised `--version` output as a
+      mismatch, so the failure direction is a redundant install and never a
+      skipped one;
+    - after installing, re-resolves the binary the way callers do — `hash -r`,
+      then through `PATH`, not through the directory the installer wrote to —
+      and fails naming the resolved path, since an install that a shadowing
+      binary hides succeeds while changing nothing any caller sees;
+    - is actually called, and prints the version on both success paths: a
+      function defined and never invoked has the same exit status and the same
+      empty output as one that worked.
+
+    Keep it POSIX sh: no arrays, no `[[`, no `grep -P`.
+
+    A Go tool a repo needs on the host is installed with `go install` pinned to
+    a commit hash (`go install <package>@<commit hash>`). It is never tracked as
+    a `go.mod` tool dependency or through a `tools.go` file, either of which
+    pulls the tool's own dependencies into the repo's `go.mod` and `go.sum`.
 
 - When pinning images or packages by hash, add a comment above the reference
   with the version and date (YYYY-MM-DD).
@@ -382,12 +639,14 @@ style conventions are in separate documents:
   settings.
 
 - Avoid putting files in the repo root unless necessary. Root should contain
-  only project-level config files (`README.md`, `Makefile`, `Dockerfile`,
+  only project-level config files (`README.md`, `AGENTS.md`, `Makefile`,
-  `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and
+  `Dockerfile`, `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`,
-  language-specific config). Everything else goes in a subdirectory. Canonical
+  and language-specific config). Everything else goes in a subdirectory.
-  subdirectory names:
+  Canonical subdirectory names:
     - `bin/` — executable scripts and tools
-    - `cmd/` — Go command entrypoints
+    - `cmd/` — Go command entrypoints; thin only: one `main.go` per binary whose
+      body is a single call into `internal/` or `pkg/`, no project logic in
+      `cmd/`
     - `configs/` — configuration templates and examples
     - `deploy/` — deployment manifests (k8s, compose, terraform)
     - `docs/` — documentation and markdown (README.md stays in root)
@@ -414,3 +673,7 @@ style conventions are in separate documents:
     - Go: `go.mod`, `go.sum`, `.golangci.yml`
     - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
     - Python: `pyproject.toml`
+
+- Guidance for coding agents lives in one `AGENTS.md` at the repository root. It
+  is never committed under a file or directory named after one agent tool, such
+  as `CLAUDE.md` or `.claude/`, and never split into separate memory files.

TESTING.md

@@ -2,44 +2,43 @@
 
 ## DNS Resolution Tests
 
-DNS is never mocked in this project, not in tests and not anywhere
+DNS is never mocked in this project, not in tests and not anywhere else; see the
-else; see the README section "No DNS mocking. Ever." Every test that
+README section "No DNS mocking. Ever." Every test that looks something up in DNS
-looks something up in DNS **MUST** query live DNS servers, never a
+**MUST** query live DNS servers, never a stand-in. Logic that works on record
-stand-in. Logic that works on record data, such as comparing or
+data, such as comparing or formatting records, may be tested on that data
-formatting records, may be tested on that data directly with no
+directly with no lookup.
-lookup.
 
 ### Rationale
 
-The resolver performs iterative resolution from root nameservers through
+The resolver performs iterative resolution from root nameservers through the
-the full delegation chain. Mocked responses cannot faithfully represent
+full delegation chain. Mocked responses cannot faithfully represent the variety
-the variety of real-world DNS behavior (truncation, referrals, glue
+of real-world DNS behavior (truncation, referrals, glue records, DNSSEC, varied
-records, DNSSEC, varied response times, EDNS, etc.). Testing against
+response times, EDNS, etc.). Testing against real servers ensures the resolver
-real servers ensures the resolver works correctly in production.
+works correctly in production.
 
 ### Constraints
 
 - Tests hit real DNS infrastructure and require network access
-- Test duration depends on network conditions; timeout tuning keeps
+- Test duration depends on network conditions; timeout tuning keeps the suite
-  the suite within the 60-second target
+  within the 60-second target
-- Query timeout is calibrated to 3× maximum antipodal RTT (~300ms)
+- Query timeout is calibrated to 3× maximum antipodal RTT (~300ms) plus
-  plus processing margin
+  processing margin
 - Root server fan-out is limited to reduce parallel query load
-- Live lookups that expect an answer go through `internal/livednstest`,
+- Live lookups that expect an answer go through `internal/livednstest`, which
-  which limits how many run at once in a test binary and retries a
+  limits how many run at once in a test binary and retries a lookup that got
-  lookup that got none
+  none
-- Flaky failures from transient network issues are acceptable and
+- Flaky failures from transient network issues are acceptable and should be
-  should be investigated as potential resolver bugs, not papered over
+  investigated as potential resolver bugs, not papered over with mocks or skip
-  with mocks or skip flags
+  flags
 
 ### What NOT to do
 
-- **Do not mock, fake or stub DNS** anywhere: no stand-in `DNSClient`,
+- **Do not mock, fake or stub DNS** anywhere: no stand-in `DNSClient`, no
-  no stand-in for the watcher's `DNSResolver`, no fake DNS server, no
+  stand-in for the watcher's `DNSResolver`, no fake DNS server, no canned
-  canned responses
+  responses
 - **Do not add `-short` flags** to skip slow tests
 - **Do not increase `-timeout`** to hide hanging queries
-- **Do not remove `-count=1` from `script/test`** — Go's test cache
+- **Do not remove `-count=1` from the test phase of the `Dockerfile`** — Go's
-  replays a previous run's output without querying anything, so a
+  test cache replays a previous run's output without querying anything, so a
   cached pass is not evidence that live resolution works
 - **Do not modify linter configuration** to suppress findings

TODO.md

@@ -1,24 +1,126 @@
 # Workflow
 
-* branch (from `next`)
+- branch (from `next`)
-* do the work in Next Step
+- do the work in Next Step
-* move Next Step to the top of Completed Steps
+- move Next Step to the top of Completed Steps
-* move the top item of Future Steps into Next Step
+- move the top item of Future Steps into Next Step
-* commit (`TODO.md` changes in the same commit as the work)
+- commit (`TODO.md` changes in the same commit as the work)
-* push
+- push
-* open a PR against `next`
+- open a PR against `next`
 
 # Status
 
-pre-1.0. No git tags. Work lands on `next` by PR. Open work for 1.0 is tracked
+pre-1.0. Work lands on `next` by PR. Open work for 1.0 is tracked on the 1.0
-on the 1.0 milestone: https://git.eeqj.de/sneak/dnswatcher/milestone/7
+milestone: https://git.eeqj.de/sneak/dnswatcher/milestone/7
 
 # Next Step
 
-nameserver IP address changes: https://git.eeqj.de/sneak/dnswatcher/issues/105
+1.0 tracking issue: https://git.eeqj.de/sneak/dnswatcher/issues/66
 
 # Completed Steps
 
+- 2026-10-13: a hostname or a domain whose zone's nameservers all stop answering
+  gets an NS Failure for each, then an NS Recovery (closes #284).
+- 2026-10-13: an IPv6 address is written in brackets before its port, as in
+  `[2001:db8::1]:443`, in keys and Port Change notifications (closes #270).
+- 2026-10-13: `TODO.md` names only open issues as next and future steps, and its
+  Status says nothing about git tags (closes #281).
+- 2026-10-13: a port check that finds port 443 closed removes that address's
+  certificate entries, so none is left shown as `ok` (closes #265).
+- 2026-10-13: a state file holding `{}`, or leaving out a section, loads with
+  that section empty; the first check no longer crashes on it (closes #267).
+- 2026-10-13: a stop before the first scan completes sends no startup
+  notification; a scan that ran to the end still sends it (closes #271).
+- 2026-10-13: a nameserver leaving a domain's delegation sends only NS Change;
+  one leaving a hostname's zone sends NS Change, not NS Failure (closes #262).
+- 2026-10-13: `DNSWATCHER_METRICS_USERNAME` set without
+  `DNSWATCHER_METRICS_PASSWORD` stops startup (closes #268).
+- 2026-10-13: a save syncs the state file to disk before renaming it into place,
+  so a crash cannot leave it empty and stop the next start (closes #264).
+- 2026-10-13: a `PORT` that cannot be bound stops startup with an error naming
+  the address, instead of running without the HTTP server (closes #266).
+- 2026-10-13: a bad `PORT`, `DNSWATCHER_TLS_EXPIRY_WARNING` or true/false
+  setting stops startup instead of being read as 0 or false (closes #269).
+- 2026-10-13: a check saving the state while the dashboard or `/api/v1/status`
+  is read cannot crash the process (closes #261).
+- 2026-10-06: canonical files re-fetched from `sneak/prompts` at `dd4027b`; lint
+  and test are phases of the `Dockerfile`, every scripted build uncached (closes
+  #257).
+- 2026-10-05: a name listed in `DNSWATCHER_SKIP_RECORD_NOTIFICATIONS` gets no
+  Record Change or Inconsistency notification; a name listed there that is not
+  in `DNSWATCHER_TARGETS` stops startup (closes #255).
+- 2026-10-02: a nameserver whose query for one record type failed while the
+  others answered with no records is `ok`, not `nodata` (closes #253).
+- 2026-10-02: a domain that does not exist is shown so, with no nameservers; no
+  name gets a parent's nameservers when its own did not answer (closes #222).
+- 2026-10-02: the refused-query test sends one query to four operators' public
+  resolvers in turn until one replies, not eight to one operator (closes #251).
+- 2026-10-02: a name removed from `DNSWATCHER_TARGETS` leaves the state, and so
+  the dashboard and API, at startup, before the first check (closes #223).
+- 2026-10-02: a record type whose query to a nameserver fails keeps its previous
+  records and alerts nothing; the other types are still saved (closes #231).
+- 2026-10-02: a Port Change notification lists the port's domains on a
+  `Domains:` line and its hostnames on a `Hostnames:` line (closes #248).
+- 2026-10-02: the dashboard's Ports table and `/api/v1/status` port entries list
+  a port's domains apart from its hostnames (closes #245).
+- 2026-10-02: nameservers a referral names without addresses are looked up,
+  three deep at most; `pool.ntp.org`'s nameservers resolve (closes #221).
+- 2026-10-02: an apex domain is not counted or listed as a hostname; its records
+  show under Domains, and notifications about them say `Domain:` (closes #224).
+- 2026-10-02: the dashboard lists each nameserver's record types in one fixed
+  order, the README's, then any other type, not a random one (closes #226).
+- 2026-10-02: the dashboard and `/api/v1/status` show why a nameserver query or
+  a certificate check failed, which only the state file showed (closes #225).
+- 2026-10-02: a name's CNAME is stored once per nameserver, not once per record
+  type asked for; a state file with repeats loads each value once (closes #220).
+- 2026-10-02: a DNS lookup that shutdown cuts short logs no error; one that
+  fails otherwise, or runs out of time, still does (closes #229).
+- 2026-10-02: Record Change and Inconsistency notifications list only the record
+  types that differ, each with its values as plain text (closes #219).
+- 2026-10-02: the startup notification no longer says every notification
+  endpoint works; it says it is a test sent to each of them (closes #230).
+- 2026-10-02: a Mattermost webhook that answers an HTTP error is logged as
+  `mattermost notification failed`, not as a Slack failure (closes #227).
+- 2026-10-02: durations in the log are written as text such as `2m0s`, not as a
+  bare count of nanoseconds (closes #228).
+- 2026-10-02: a watched name whose nameservers answer with a CNAME and no
+  address gets port and TLS checks at the end of its CNAME chain (closes #203).
+- 2026-10-02: a resolver test that reads one record type from a nameserver's
+  answer asks again when that type is missing from it (closes #218).
+- 2026-10-02: a plain `docker build .` of a clone stamps its tag or short
+  commit, not `dev`: the build context now carries `.git` (closes #210).
+- 2026-10-02: a query a server refuses is not resent asking for recursion, and
+  every root server refusing is reported as DNS interception (closes #206).
+- 2026-10-02: a push to a branch cancels that branch's older CI run, and the
+  checkout leaves no token in `.git/config` (closes #216).
+- 2026-10-02: watcher tests send far fewer queries and a live attempt may take
+  18s; nameserver addresses are asked only for A, AAAA, CNAME (closes #214).
+- 2026-10-02: the resolver tries root servers, and every other server list it
+  walks, in a random order each time, not always from the top (closes #138).
+- 2026-10-02: a name listed more than once in `DNSWATCHER_TARGETS`, in any
+  letter case or with a trailing dot, is watched once (closes #207).
+- 2026-10-01: README checked against the code and corrected: metrics, CORS,
+  notification retries, CNAMEs, state file fields, Design tree (closes #108).
+- 2026-10-01: a certificate within the expiry warning period is warned about on
+  every TLS check, where some checks used to skip it at random (closes #204).
+- 2026-10-01: a domain's NS set is its delegation from the parent zone's
+  servers, not whichever of its own servers answered first (closes #200).
+- 2026-10-01: README has Getting Started, Rationale and TODO sections, and its
+  Architecture section is now Design, in the order policy sets (closes #173).
+- 2026-10-01: a zone's server that answers SERVFAIL or a referral leading no
+  closer is passed over for the next, as one that times out is (closes #197).
+- 2026-10-01: when none of a configured name's nameservers answered, the port
+  state saved for its addresses is kept, not removed (closes #193).
+- 2026-10-01: `ResolveIPAddresses` returns an error, not no addresses, when no
+  nameserver of the name's zone answered (closes #190).
+- 2026-10-01: `make fmt` and `make fmt-check` cover Markdown with prettier, run
+  in Docker at the version pinned by `yarn.lock` (closes #119).
+- 2026-10-01: `make fmt-check` fails on a file `goimports` would change; both
+  format scripts run `goimports` at its pinned commit, not from `PATH` (#119).
+- 2026-10-01: a hostname is queried at the servers of the zone it is in, found
+  by following delegations for the name, not its last two labels (closes #189).
+- 2026-10-01: each nameserver's addresses are saved with its domain, and a
+  change while it stays in the delegation is notified (closes #105).
 - 2026-10-01: the watcher saves state when it stops, and shutdown waits for that
   save, so it no longer relies on the state's own stop hook (closes #114).
 - 2026-10-01: `DNSWATCHER_SENTRY_DSN` reports panics in HTTP handlers to Sentry,
@@ -105,14 +207,4 @@ nameserver IP address changes: https://git.eeqj.de/sneak/dnswatcher/issues/105
 
 # Future Steps
 
-- trial run of the finished image:
+- DNSSEC validation, after 1.0: https://git.eeqj.de/sneak/dnswatcher/issues/59
-  https://git.eeqj.de/sneak/dnswatcher/issues/149
-- 1.0 readiness: run it with a real config and read the logs:
-  https://git.eeqj.de/sneak/dnswatcher/issues/66
-- `goimports` in `make fmt-check`, Markdown formatting:
-  https://git.eeqj.de/sneak/dnswatcher/issues/119
-- README accuracy sweep: https://git.eeqj.de/sneak/dnswatcher/issues/108
-- README sections required by policy:
-  https://git.eeqj.de/sneak/dnswatcher/issues/173
-- fixed root server order: https://git.eeqj.de/sneak/dnswatcher/issues/138
-- review toward 1.0: https://git.eeqj.de/sneak/dnswatcher/issues/144

internal/config/classify.go

@@ -57,17 +57,22 @@ func ClassifyDNSName(name string) (DNSNameType, error) {
 
 // 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.
+// name cannot be classified. A name given more than once, in any letter
+// case or with a trailing dot, is kept once.
 func ClassifyTargets(targets []string) ([]string, []string, error) {
 	var domains, hostnames []string
 
+	seen := make(map[string]bool)
+
 	for _, t := range targets {
 		normalized := strings.ToLower(strings.TrimSuffix(strings.TrimSpace(t), "."))
 
-		if normalized == "" {
+		if normalized == "" || seen[normalized] {
 			continue
 		}
 
+		seen[normalized] = true
+
 		typ, classErr := ClassifyDNSName(normalized)
 		if classErr != nil {
 			return nil, nil, classErr

internal/config/classify_test.go

@@ -1,6 +1,7 @@
 package config_test
 
 import (
+	"slices"
 	"testing"
 
 	"sneak.berlin/go/dnswatcher/internal/config"
@@ -93,6 +94,29 @@ func TestClassifyTargets(t *testing.T) {
 	}
 }
 
+func TestClassifyTargetsKeepsEachNameOnce(t *testing.T) {
+	t.Parallel()
+
+	domains, hostnames, err := config.ClassifyTargets([]string{
+		"example.org",
+		"Example.org.",
+		"www.example.org",
+		"EXAMPLE.ORG",
+		"WWW.Example.org.",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if !slices.Equal(domains, []string{"example.org"}) {
+		t.Errorf("domains = %v, want [example.org]", domains)
+	}
+
+	if !slices.Equal(hostnames, []string{"www.example.org"}) {
+		t.Errorf("hostnames = %v, want [www.example.org]", hostnames)
+	}
+}
+
 func TestClassifyTargetsRejectsPublicSuffix(t *testing.T) {
 	t.Parallel()
 

internal/config/config.go

@@ -5,6 +5,8 @@ import (
 	"errors"
 	"fmt"
 	"log/slog"
+	"slices"
+	"strconv"
 	"strings"
 	"time"
 
@@ -23,6 +25,9 @@ const (
 	defaultTLSExpiryWarning = 7
 )
 
+// maxPort is the highest TCP port number.
+const maxPort = 65535
+
 // ErrNoTargets is returned when no monitoring targets are configured.
 var ErrNoTargets = errors.New(
 	"no monitoring targets configured: set DNSWATCHER_TARGETS environment variable",
@@ -35,6 +40,34 @@ var ErrInvalidInterval = errors.New(
 	"interval must be a positive duration such as 30m or 1h",
 )
 
+// ErrNotInTargets is returned when DNSWATCHER_SKIP_RECORD_NOTIFICATIONS
+// lists a name that is not in DNSWATCHER_TARGETS.
+var ErrNotInTargets = errors.New("name is not in DNSWATCHER_TARGETS")
+
+// ErrInvalidPort is returned when PORT is set but is not a whole number
+// from 1 to 65535. An empty value counts as unset and means the default.
+var ErrInvalidPort = errors.New("port must be a whole number from 1 to 65535")
+
+// ErrInvalidTLSExpiryWarning is returned when DNSWATCHER_TLS_EXPIRY_WARNING
+// is set but is not a whole number, 1 or more. An empty value counts as unset
+// and means the default.
+var ErrInvalidTLSExpiryWarning = errors.New(
+	"TLS expiry warning must be a whole number of days, 1 or more",
+)
+
+// ErrInvalidBool is returned when DNSWATCHER_DEBUG,
+// DNSWATCHER_MAINTENANCE_MODE or DNSWATCHER_SEND_TEST_NOTIFICATION is set
+// but is not a value strconv.ParseBool accepts. An empty value counts as
+// unset and means the default.
+var ErrInvalidBool = errors.New("value must be true or false")
+
+// ErrNoMetricsPassword is returned when DNSWATCHER_METRICS_USERNAME is set and
+// DNSWATCHER_METRICS_PASSWORD is empty. Basic Auth on /metrics would otherwise
+// let in anyone who sends the username with an empty password.
+var ErrNoMetricsPassword = errors.New(
+	"DNSWATCHER_METRICS_PASSWORD must be set when DNSWATCHER_METRICS_USERNAME is set",
+)
+
 // Params contains dependencies for Config.
 type Params struct {
 	fx.In
@@ -45,24 +78,25 @@ type Params struct {
 
 // Config holds application configuration.
 type Config struct {
-	Port                 int
+	Port                    int
-	Debug                bool
+	Debug                   bool
-	DataDir              string
+	DataDir                 string
-	Domains              []string
+	Domains                 []string
-	Hostnames            []string
+	Hostnames               []string
-	SlackWebhook         string
+	SkipRecordNotifications []string
-	MattermostWebhook    string
+	SlackWebhook            string
-	NtfyTopic            string
+	MattermostWebhook       string
-	DNSInterval          time.Duration
+	NtfyTopic               string
-	TLSInterval          time.Duration
+	DNSInterval             time.Duration
-	TLSExpiryWarning     int
+	TLSInterval             time.Duration
-	SentryDSN            string
+	TLSExpiryWarning        int
-	MaintenanceMode      bool
+	SentryDSN               string
-	MetricsUsername      string
+	MaintenanceMode         bool
-	MetricsPassword      string
+	MetricsUsername         string
-	SendTestNotification bool
+	MetricsPassword         string
-	params               *Params
+	SendTestNotification    bool
-	log                  *slog.Logger
+	params                  *Params
+	log                     *slog.Logger
 }
 
 // New creates a new Config instance from environment and config files.
@@ -81,6 +115,10 @@ func New(_ fx.Lifecycle, params Params) (*Config, error) {
 		return nil, err
 	}
 
+	if cfg.MetricsUsername != "" && cfg.MetricsPassword == "" {
+		return nil, ErrNoMetricsPassword
+	}
+
 	configureDebugLogging(cfg, params)
 
 	return cfg, nil
@@ -103,6 +141,7 @@ func setupViper(name string) {
 	viper.SetDefault("DEBUG", false)
 	viper.SetDefault("DATA_DIR", "/var/lib/"+name)
 	viper.SetDefault("TARGETS", "")
+	viper.SetDefault("SKIP_RECORD_NOTIFICATIONS", "")
 	viper.SetDefault("SLACK_WEBHOOK", "")
 	viper.SetDefault("MATTERMOST_WEBHOOK", "")
 	viper.SetDefault("NTFY_TOPIC", "")
@@ -120,16 +159,9 @@ func buildConfig(
 	log *slog.Logger,
 	params *Params,
 ) (*Config, error) {
-	err := viper.ReadInConfig()
+	err := readConfigFile(log)
 	if err != nil {
-		var notFound viper.ConfigFileNotFoundError
+		return nil, err
-		if !errors.As(err, &notFound) {
-			log.Error("config file malformed", "error", err)
-
-			return nil, fmt.Errorf(
-				"config file malformed: %w", err,
-			)
-		}
 	}
 
 	dnsInterval, err := parseInterval("DNS_INTERVAL")
@@ -147,30 +179,78 @@ func buildConfig(
 		return nil, err
 	}
 
+	skipRecordNotifications, err := parseSkipRecordNotifications(
+		domains, hostnames,
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	port, err := parsePort()
+	if err != nil {
+		return nil, err
+	}
+
+	tlsExpiryWarning, err := parseTLSExpiryWarning()
+	if err != nil {
+		return nil, err
+	}
+
+	debug, err := parseBool("DEBUG")
+	if err != nil {
+		return nil, err
+	}
+
+	maintenanceMode, err := parseBool("MAINTENANCE_MODE")
+	if err != nil {
+		return nil, err
+	}
+
+	sendTestNotification, err := parseBool("SEND_TEST_NOTIFICATION")
+	if err != nil {
+		return nil, err
+	}
+
 	cfg := &Config{
-		Port:                 viper.GetInt("PORT"),
+		Port:                    port,
-		Debug:                viper.GetBool("DEBUG"),
+		Debug:                   debug,
-		DataDir:              viper.GetString("DATA_DIR"),
+		DataDir:                 viper.GetString("DATA_DIR"),
-		Domains:              domains,
+		Domains:                 domains,
-		Hostnames:            hostnames,
+		Hostnames:               hostnames,
-		SlackWebhook:         viper.GetString("SLACK_WEBHOOK"),
+		SkipRecordNotifications: skipRecordNotifications,
-		MattermostWebhook:    viper.GetString("MATTERMOST_WEBHOOK"),
+		SlackWebhook:            viper.GetString("SLACK_WEBHOOK"),
-		NtfyTopic:            viper.GetString("NTFY_TOPIC"),
+		MattermostWebhook:       viper.GetString("MATTERMOST_WEBHOOK"),
-		DNSInterval:          dnsInterval,
+		NtfyTopic:               viper.GetString("NTFY_TOPIC"),
-		TLSInterval:          tlsInterval,
+		DNSInterval:             dnsInterval,
-		TLSExpiryWarning:     viper.GetInt("TLS_EXPIRY_WARNING"),
+		TLSInterval:             tlsInterval,
-		SentryDSN:            viper.GetString("SENTRY_DSN"),
+		TLSExpiryWarning:        tlsExpiryWarning,
-		MaintenanceMode:      viper.GetBool("MAINTENANCE_MODE"),
+		SentryDSN:               viper.GetString("SENTRY_DSN"),
-		MetricsUsername:      viper.GetString("METRICS_USERNAME"),
+		MaintenanceMode:         maintenanceMode,
-		MetricsPassword:      viper.GetString("METRICS_PASSWORD"),
+		MetricsUsername:         viper.GetString("METRICS_USERNAME"),
-		SendTestNotification: viper.GetBool("SEND_TEST_NOTIFICATION"),
+		MetricsPassword:         viper.GetString("METRICS_PASSWORD"),
-		params:               params,
+		SendTestNotification:    sendTestNotification,
-		log:                  log,
+		params:                  params,
+		log:                     log,
 	}
 
 	return cfg, nil
 }
 
+// readConfigFile reads the config file, if there is one.
+func readConfigFile(log *slog.Logger) error {
+	err := viper.ReadInConfig()
+	if err != nil {
+		var notFound viper.ConfigFileNotFoundError
+		if !errors.As(err, &notFound) {
+			log.Error("config file malformed", "error", err)
+
+			return fmt.Errorf("config file malformed: %w", err)
+		}
+	}
+
+	return nil
+}
+
 // parseInterval reads the DNSWATCHER_-prefixed setting key as a duration. A
 // value that does not parse, or is zero or negative, is an error naming the
 // variable and the value; an unset variable has its default from setupViper.
@@ -187,6 +267,53 @@ func parseInterval(key string) (time.Duration, error) {
 	return interval, nil
 }
 
+// parsePort reads PORT, which has no DNSWATCHER_ prefix, as a port number. A
+// value that is not a whole number from 1 to 65535 is an error naming the
+// variable and the value; an unset variable has its default from setupViper.
+func parsePort() (int, error) {
+	value := viper.GetString("PORT")
+
+	port, err := strconv.Atoi(value)
+	if err != nil || port < 1 || port > maxPort {
+		return 0, fmt.Errorf("invalid PORT %q: %w", value, ErrInvalidPort)
+	}
+
+	return port, nil
+}
+
+// parseTLSExpiryWarning reads DNSWATCHER_TLS_EXPIRY_WARNING as a number of
+// days. A value that is not a whole number, 1 or more, is an error naming the
+// variable and the value; an unset variable has its default from setupViper.
+func parseTLSExpiryWarning() (int, error) {
+	value := viper.GetString("TLS_EXPIRY_WARNING")
+
+	days, err := strconv.Atoi(value)
+	if err != nil || days < 1 {
+		return 0, fmt.Errorf(
+			"invalid DNSWATCHER_TLS_EXPIRY_WARNING %q: %w",
+			value, ErrInvalidTLSExpiryWarning,
+		)
+	}
+
+	return days, nil
+}
+
+// parseBool reads the DNSWATCHER_-prefixed setting key as true or false. A
+// value strconv.ParseBool does not accept is an error naming the variable and
+// the value; an unset variable has its default from setupViper.
+func parseBool(key string) (bool, error) {
+	value := viper.GetString(key)
+
+	result, err := strconv.ParseBool(value)
+	if err != nil {
+		return false, fmt.Errorf(
+			"invalid DNSWATCHER_%s %q: %w", key, value, ErrInvalidBool,
+		)
+	}
+
+	return result, nil
+}
+
 func parseAndValidateTargets() ([]string, []string, error) {
 	domains, hostnames, err := ClassifyTargets(
 		parseCSV(viper.GetString("TARGETS")),
@@ -204,6 +331,36 @@ func parseAndValidateTargets() ([]string, []string, error) {
 	return domains, hostnames, nil
 }
 
+// parseSkipRecordNotifications reads DNSWATCHER_SKIP_RECORD_NOTIFICATIONS,
+// a comma-separated list of names from the targets. Each name is written
+// as ClassifyTargets writes a target, in lower case without a trailing
+// dot, and a name listed more than once is kept once. A name that is
+// not one of domains or hostnames is an error naming it.
+func parseSkipRecordNotifications(
+	domains, hostnames []string,
+) ([]string, error) {
+	value := viper.GetString("SKIP_RECORD_NOTIFICATIONS")
+
+	var names []string
+
+	for _, listed := range parseCSV(value) {
+		name := strings.ToLower(strings.TrimSuffix(listed, "."))
+
+		if !slices.Contains(domains, name) && !slices.Contains(hostnames, name) {
+			return nil, fmt.Errorf(
+				"invalid DNSWATCHER_SKIP_RECORD_NOTIFICATIONS %q: %w",
+				listed, ErrNotInTargets,
+			)
+		}
+
+		if !slices.Contains(names, name) {
+			names = append(names, name)
+		}
+	}
+
+	return names, nil
+}
+
 func parseCSV(input string) []string {
 	if input == "" {
 		return nil

internal/config/config_test.go

@@ -57,6 +57,7 @@ func TestNew_DefaultValues(t *testing.T) {
 	assert.Empty(t, cfg.MetricsUsername)
 	assert.Empty(t, cfg.MetricsPassword)
 	assert.False(t, cfg.SendTestNotification)
+	assert.Empty(t, cfg.SkipRecordNotifications)
 }
 
 func TestNew_EnvironmentOverrides(t *testing.T) {
@@ -115,7 +116,7 @@ func TestNew_OnlyEmptyCSVSegments(t *testing.T) {
 }
 
 // TestNew_InvalidIntervalStopsStartup checks values that must stop startup;
-// TestNew_DefaultValues and TestNew_EmptyIntervalMeansDefault check that an
+// TestNew_DefaultValues and TestNew_EmptyValueMeansDefault check that an
 // unset or empty interval means the default.
 func TestNew_InvalidIntervalStopsStartup(t *testing.T) {
 	variables := []string{"DNSWATCHER_DNS_INTERVAL", "DNSWATCHER_TLS_INTERVAL"}
@@ -143,16 +144,107 @@ func TestNew_InvalidIntervalStopsStartup(t *testing.T) {
 	}
 }
 
-func TestNew_EmptyIntervalMeansDefault(t *testing.T) {
+func TestNew_EmptyValueMeansDefault(t *testing.T) {
 	viper.Reset()
 	t.Setenv("DNSWATCHER_TARGETS", "example.com")
 	t.Setenv("DNSWATCHER_DNS_INTERVAL", "")
 	t.Setenv("DNSWATCHER_TLS_INTERVAL", "")
+	t.Setenv("PORT", "")
+	t.Setenv("DNSWATCHER_TLS_EXPIRY_WARNING", "")
+	t.Setenv("DNSWATCHER_DEBUG", "")
+	t.Setenv("DNSWATCHER_MAINTENANCE_MODE", "")
+	t.Setenv("DNSWATCHER_SEND_TEST_NOTIFICATION", "")
 
 	cfg, err := config.New(nil, newTestParams(t))
 	require.NoError(t, err)
 	assert.Equal(t, time.Hour, cfg.DNSInterval)
 	assert.Equal(t, 12*time.Hour, cfg.TLSInterval)
+	assert.Equal(t, 8080, cfg.Port)
+	assert.Equal(t, 7, cfg.TLSExpiryWarning)
+	assert.False(t, cfg.Debug)
+	assert.False(t, cfg.MaintenanceMode)
+	assert.False(t, cfg.SendTestNotification)
+}
+
+// TestNew_InvalidNumberOrBoolStopsStartup checks values that must stop
+// startup; TestNew_EnvironmentOverrides, the two tests after this one and
+// TestNew_EmptyValueMeansDefault check values that must not.
+func TestNew_InvalidNumberOrBoolStopsStartup(t *testing.T) {
+	notBools := []string{"yes", "on", "2", "tRUE"}
+	tests := []struct {
+		variable string
+		values   []string
+		want     error
+	}{
+		{
+			variable: "PORT",
+			values:   []string{"notaport", "0", "-1", "65536", "8080.5"},
+			want:     config.ErrInvalidPort,
+		},
+		{
+			variable: "DNSWATCHER_TLS_EXPIRY_WARNING",
+			values:   []string{"abc", "7d", "0", "-5"},
+			want:     config.ErrInvalidTLSExpiryWarning,
+		},
+		{
+			variable: "DNSWATCHER_DEBUG",
+			values:   notBools,
+			want:     config.ErrInvalidBool,
+		},
+		{
+			variable: "DNSWATCHER_MAINTENANCE_MODE",
+			values:   notBools,
+			want:     config.ErrInvalidBool,
+		},
+		{
+			variable: "DNSWATCHER_SEND_TEST_NOTIFICATION",
+			values:   notBools,
+			want:     config.ErrInvalidBool,
+		},
+	}
+
+	for _, tt := range tests {
+		for _, value := range tt.values {
+			t.Run(tt.variable+"="+value, func(t *testing.T) {
+				viper.Reset()
+				t.Setenv("DNSWATCHER_TARGETS", "example.com")
+				t.Setenv(tt.variable, value)
+
+				_, err := config.New(nil, newTestParams(t))
+				require.ErrorIs(t, err, tt.want)
+				require.ErrorContains(t, err, tt.variable)
+				require.ErrorContains(t, err, strconv.Quote(value))
+			})
+		}
+	}
+}
+
+func TestNew_LowestNumbersAndOtherSpellingsOfTrue(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "example.com")
+	t.Setenv("PORT", "1")
+	t.Setenv("DNSWATCHER_TLS_EXPIRY_WARNING", "1")
+	t.Setenv("DNSWATCHER_DEBUG", "1")
+	t.Setenv("DNSWATCHER_MAINTENANCE_MODE", "T")
+	t.Setenv("DNSWATCHER_SEND_TEST_NOTIFICATION", "True")
+
+	cfg, err := config.New(nil, newTestParams(t))
+	require.NoError(t, err)
+	assert.Equal(t, 1, cfg.Port)
+	assert.Equal(t, 1, cfg.TLSExpiryWarning)
+	assert.True(t, cfg.Debug)
+	assert.True(t, cfg.MaintenanceMode)
+	assert.True(t, cfg.SendTestNotification)
+}
+
+func TestNew_HighestPort(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "example.com")
+	t.Setenv("PORT", "65535")
+
+	cfg, err := config.New(nil, newTestParams(t))
+	require.NoError(t, err)
+	assert.Equal(t, 65535, cfg.Port)
 }
 
 func TestNew_DebugEnablesDebugLogging(t *testing.T) {
@@ -235,6 +327,51 @@ func TestNew_TargetsWithTrailingComma(t *testing.T) {
 		"trailing comma should be ignored")
 }
 
+func TestNew_SkipRecordNotifications(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "example.net,www.example.net,example.org")
+	t.Setenv("DNSWATCHER_SKIP_RECORD_NOTIFICATIONS",
+		" WWW.Example.net. , example.net,www.example.net")
+
+	cfg, err := config.New(nil, newTestParams(t))
+	require.NoError(t, err)
+	assert.Equal(t,
+		[]string{"www.example.net", "example.net"},
+		cfg.SkipRecordNotifications,
+		"names are written as targets are, each once",
+	)
+}
+
+func TestNew_SkipRecordNotificationsNotInTargetsStopsStartup(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "example.net")
+	t.Setenv("DNSWATCHER_SKIP_RECORD_NOTIFICATIONS",
+		"example.net,www.example.net")
+
+	_, err := config.New(nil, newTestParams(t))
+	require.ErrorIs(t, err, config.ErrNotInTargets)
+	require.ErrorContains(t, err, "DNSWATCHER_SKIP_RECORD_NOTIFICATIONS")
+	require.ErrorContains(t, err, `"www.example.net"`)
+}
+
+// TestNew_MetricsUsernameWithoutPasswordStopsStartup checks an unset and an
+// empty password; TestNew_EnvironmentOverrides checks a username with one.
+func TestNew_MetricsUsernameWithoutPasswordStopsStartup(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "example.com")
+	t.Setenv("DNSWATCHER_METRICS_USERNAME", "prom")
+
+	_, err := config.New(nil, newTestParams(t))
+	require.ErrorIs(t, err, config.ErrNoMetricsPassword, "password unset")
+	require.ErrorContains(t, err, "DNSWATCHER_METRICS_PASSWORD")
+
+	viper.Reset()
+	t.Setenv("DNSWATCHER_METRICS_PASSWORD", "")
+
+	_, err = config.New(nil, newTestParams(t))
+	require.ErrorIs(t, err, config.ErrNoMetricsPassword, "password empty")
+}
+
 func TestNew_CustomDNSIntervalDuration(t *testing.T) {
 	viper.Reset()
 	t.Setenv("DNSWATCHER_TARGETS", "example.com")

internal/handlers/dashboard.go

@@ -1,11 +1,14 @@
 package handlers
 
 import (
+	"cmp"
 	"embed"
 	"fmt"
 	"html/template"
+	"maps"
 	"math"
 	"net/http"
+	"slices"
 	"strings"
 	"time"
 
@@ -40,12 +43,19 @@ func newDashboardTemplate() *template.Template {
 	)
 }
 
-// dashboardData is the data passed to the dashboard template.
+// dashboardData is the data passed to the dashboard template. Hostnames
+// and DomainRecords split the records in Snapshot.Hostnames, which also
+// holds the apex domains' own (see splitHostnames). Ports holds
+// Snapshot.Ports with each port's names split into domains and
+// hostnames, as /api/v1/status gives them (see buildPorts).
 type dashboardData struct {
-	Snapshot    state.Snapshot
+	Snapshot      state.Snapshot
-	Alerts      []notify.AlertEntry
+	Hostnames     map[string]*state.HostnameState
-	StateAge    string
+	DomainRecords map[string]*state.HostnameState
-	GeneratedAt string
+	Ports         map[string]*statusPortInfo
+	Alerts        []notify.AlertEntry
+	StateAge      string
+	GeneratedAt   string
 }
 
 // HandleDashboard returns the dashboard page handler.
@@ -58,12 +68,16 @@ func (h *Handlers) HandleDashboard() http.HandlerFunc {
 	) {
 		snap := h.state.GetSnapshot()
 		alerts := h.notifyHistory.Recent()
+		hostnames, domainRecords := splitHostnames(snap)
 
 		data := dashboardData{
-			Snapshot:    snap,
+			Snapshot:      snap,
-			Alerts:      alerts,
+			Hostnames:     hostnames,
-			StateAge:    relTime(snap.LastUpdated),
+			DomainRecords: domainRecords,
-			GeneratedAt: time.Now().UTC().Format("2006-01-02 15:04:05"),
+			Ports:         buildPorts(snap),
+			Alerts:        alerts,
+			StateAge:      relTime(snap.LastUpdated),
+			GeneratedAt:   time.Now().UTC().Format("2006-01-02 15:04:05"),
 		}
 
 		writer.Header().Set(
@@ -122,16 +136,37 @@ func joinStrings(items []string, sep string) string {
 }
 
 // formatRecords formats a map of record type → values into a
-// compact display string.
+// compact display string. Record types are listed in the order the
+// README lists them, any other type after them in alphabetical order,
+// so rows of nameservers with the same records read the same.
 func formatRecords(records map[string][]string) string {
 	if len(records) == 0 {
 		return "-"
 	}
 
+	order := []string{"A", "AAAA", "CNAME", "MX", "TXT", "SRV", "CAA", "NS"}
+
+	position := func(rtype string) int {
+		i := slices.Index(order, rtype)
+		if i < 0 {
+			return len(order)
+		}
+
+		return i
+	}
+
+	rtypes := slices.Collect(maps.Keys(records))
+	slices.SortFunc(rtypes, func(a, b string) int {
+		return cmp.Or(
+			cmp.Compare(position(a), position(b)),
+			strings.Compare(a, b),
+		)
+	})
+
 	var parts []string
 
-	for rtype, values := range records {
+	for _, rtype := range rtypes {
-		for _, v := range values {
+		for _, v := range records[rtype] {
 			parts = append(parts, rtype+": "+v)
 		}
 	}

internal/handlers/dashboard_test.go

@@ -1,6 +1,8 @@
 package handlers_test
 
 import (
+	"regexp"
+	"strings"
 	"testing"
 	"time"
 
@@ -78,3 +80,194 @@ func TestFormatRecords(t *testing.T) {
 		t.Errorf("unexpected format: %q", got)
 	}
 }
+
+// TestFormatRecordsTypeOrder checks that record types are listed in
+// the README's order (A, AAAA, CNAME, MX, TXT, SRV, CAA, NS), with
+// any other type after them in alphabetical order.
+func TestFormatRecordsTypeOrder(t *testing.T) {
+	t.Parallel()
+
+	got := handlers.FormatRecords(map[string][]string{
+		"SOA":   {"ns1.example.com. hostmaster.example.com. 1 2 3 4 5"},
+		"NS":    {"ns1.example.com.", "ns2.example.com."},
+		"CAA":   {`0 issue "letsencrypt.org"`},
+		"DNAME": {"example.net."},
+		"TXT":   {"v=spf1 -all"},
+		"SRV":   {"10 5 443 www.example.com."},
+		"MX":    {"10 mail.example.com."},
+		"CNAME": {"www.example.com."},
+		"AAAA":  {"2001:db8::1"},
+		"A":     {"192.0.2.1"},
+	})
+
+	want := strings.Join([]string{
+		"A: 192.0.2.1",
+		"AAAA: 2001:db8::1",
+		"CNAME: www.example.com.",
+		"MX: 10 mail.example.com.",
+		"TXT: v=spf1 -all",
+		"SRV: 10 5 443 www.example.com.",
+		`CAA: 0 issue "letsencrypt.org"`,
+		"NS: ns1.example.com.",
+		"NS: ns2.example.com.",
+		"DNAME: example.net.",
+		"SOA: ns1.example.com. hostmaster.example.com. 1 2 3 4 5",
+	}, ", ")
+
+	if got != want {
+		t.Errorf("FormatRecords lists types out of order:\n got %q\nwant %q",
+			got, want)
+	}
+}
+
+// dashboardRow returns the table row of page that contains name.
+func dashboardRow(t *testing.T, page string, name string) string {
+	t.Helper()
+
+	for row := range strings.SplitSeq(page, "<tr") {
+		if strings.Contains(row, name) {
+			return row
+		}
+	}
+
+	t.Fatalf("dashboard has no row containing %q", name)
+
+	return ""
+}
+
+// TestDashboardShowsFailureReasons checks that the dashboard shows the
+// reason in the row of a failed nameserver and of a failed certificate,
+// and not in the row of a nameserver that answered.
+func TestDashboardShowsFailureReasons(t *testing.T) {
+	t.Parallel()
+
+	page := get(t, newHandlersWithFailures(t).HandleDashboard())
+
+	if !strings.Contains(dashboardRow(t, page, failedNS), nsFailureReason) {
+		t.Errorf("row of %s does not show %q", failedNS, nsFailureReason)
+	}
+
+	if strings.Contains(dashboardRow(t, page, answeringNS), nsFailureReason) {
+		t.Errorf("row of %s shows %q", answeringNS, nsFailureReason)
+	}
+
+	if !strings.Contains(dashboardRow(t, page, certKey), certFailedReason) {
+		t.Errorf("row of %s does not show %q", certKey, certFailedReason)
+	}
+}
+
+// dashboardSection returns the section of page under heading.
+func dashboardSection(t *testing.T, page string, heading string) string {
+	t.Helper()
+
+	for section := range strings.SplitSeq(page, "<section") {
+		words := strings.Join(strings.Fields(section), " ")
+		if strings.Contains(words, "> "+heading+" </h2>") {
+			return section
+		}
+	}
+
+	t.Fatalf("dashboard has no section headed %q", heading)
+
+	return ""
+}
+
+// TestDashboardShowsDomainRecordsUnderDomains checks that the dashboard
+// shows an apex domain's own records in the Domains section, and
+// neither lists nor counts the domain as a hostname.
+func TestDashboardShowsDomainRecordsUnderDomains(t *testing.T) {
+	t.Parallel()
+
+	page := get(t, newHandlersWithFailures(t).HandleDashboard())
+
+	domains := dashboardSection(t, page, "Domains")
+	if !strings.Contains(dashboardRow(t, domains, domainAddress), testDomain) {
+		t.Errorf("row of %s does not name %s", domainAddress, testDomain)
+	}
+
+	if strings.Contains(dashboardSection(t, page, "Hostnames"), testDomain) {
+		t.Errorf("Hostnames section lists the domain %s", testDomain)
+	}
+
+	words := strings.Join(strings.Fields(page), " ")
+
+	footer := "monitoring 2 domains + 1 hostnames"
+	if !strings.Contains(words, footer) {
+		t.Errorf("dashboard does not say %q", footer)
+	}
+
+	// With the tags taken out, the summary bar starts "Domains 2
+	// Hostnames 1".
+	text := regexp.MustCompile(`<[^>]*>`).ReplaceAllString(page, " ")
+	summary := "Domains 2 Hostnames 1"
+
+	if !strings.Contains(strings.Join(strings.Fields(text), " "), summary) {
+		t.Errorf("summary bar does not say %q", summary)
+	}
+}
+
+// TestDashboardMarksDomainThatDoesNotExist checks that the Domains
+// section says a domain that does not exist does not exist, and does
+// not say so of a domain that exists.
+func TestDashboardMarksDomainThatDoesNotExist(t *testing.T) {
+	t.Parallel()
+
+	page := get(t, newHandlersWithFailures(t).HandleDashboard())
+	domains := dashboardSection(t, page, "Domains")
+
+	if !strings.Contains(dashboardRow(t, domains, missingDomain), "does not exist") {
+		t.Errorf("row of %s does not say it does not exist", missingDomain)
+	}
+
+	if strings.Contains(dashboardRow(t, domains, testDomain), "does not exist") {
+		t.Errorf("row of %s says it does not exist", testDomain)
+	}
+}
+
+// rowCells returns the text of each cell of a dashboard table row
+// whose cells start with tag, "<th" or "<td".
+func rowCells(row string, tag string) []string {
+	tags := regexp.MustCompile(`<[^>]*>`)
+	parts := strings.Split(row, tag)[1:]
+	cells := make([]string, 0, len(parts))
+
+	for _, cell := range parts {
+		text := tags.ReplaceAllString(tag+cell, " ")
+		cells = append(cells, strings.Join(strings.Fields(text), " "))
+	}
+
+	return cells
+}
+
+// TestDashboardPortsTellDomainsFromHostnames checks that the Ports
+// table lists an apex domain under Domains and a hostname under
+// Hostnames when both resolve to the port's address.
+func TestDashboardPortsTellDomainsFromHostnames(t *testing.T) {
+	t.Parallel()
+
+	page := get(t, newHandlersWithFailures(t).HandleDashboard())
+	ports := dashboardSection(t, page, "Ports")
+
+	headings := rowCells(dashboardRow(t, ports, "Address</th>"), "<th")
+	cells := rowCells(dashboardRow(t, ports, sharedPort), "<td")
+
+	if len(cells) != len(headings) {
+		t.Fatalf("row of %s has cells %q under headings %q",
+			sharedPort, cells, headings)
+	}
+
+	under := make(map[string]string)
+	for i, heading := range headings {
+		under[heading] = cells[i]
+	}
+
+	if under["Domains"] != testDomain {
+		t.Errorf("row of %s lists %q under Domains, want %q",
+			sharedPort, under["Domains"], testDomain)
+	}
+
+	if under["Hostnames"] != testHostname {
+		t.Errorf("row of %s lists %q under Hostnames, want %q",
+			sharedPort, under["Hostnames"], testHostname)
+	}
+}

internal/handlers/status.go

@@ -9,15 +9,21 @@ import (
 )
 
 // statusDomainInfo holds status information for a monitored domain.
+// RecordsByNameserver holds the domain's own records, in the form a
+// hostname's Nameservers holds the hostname's. NXDomain is true when
+// the domain's parent zone's servers answered that it does not exist.
 type statusDomainInfo struct {
-	Nameservers []string  `json:"nameservers"`
+	Nameservers         []string                         `json:"nameservers"`
-	LastChecked time.Time `json:"lastChecked"`
+	RecordsByNameserver map[string]*statusHostnameNSInfo `json:"recordsByNameserver"`
+	NXDomain            bool                             `json:"nxdomain"`
+	LastChecked         time.Time                        `json:"lastChecked"`
 }
 
 // statusHostnameNSInfo holds per-nameserver status for a hostname.
 type statusHostnameNSInfo struct {
 	Records     map[string][]string `json:"records"`
 	Status      string              `json:"status"`
+	Error       string              `json:"error,omitempty"`
 	LastChecked time.Time           `json:"lastChecked"`
 }
 
@@ -28,8 +34,11 @@ type statusHostnameInfo struct {
 }
 
 // statusPortInfo holds status information for a monitored port.
+// Domains and Hostnames list the apex domains and the hostnames that
+// resolve to its address.
 type statusPortInfo struct {
 	Open        bool      `json:"open"`
+	Domains     []string  `json:"domains"`
 	Hostnames   []string  `json:"hostnames"`
 	LastChecked time.Time `json:"lastChecked"`
 }
@@ -41,6 +50,7 @@ type statusCertificateInfo struct {
 	NotAfter                time.Time `json:"notAfter"`
 	SubjectAlternativeNames []string  `json:"subjectAlternativeNames"`
 	Status                  string    `json:"status"`
+	Error                   string    `json:"error,omitempty"`
 	LastChecked             time.Time `json:"lastChecked"`
 }
 
@@ -94,21 +104,44 @@ func buildStatusResponse(
 		LastUpdated:  snap.LastUpdated,
 		Domains:      make(map[string]*statusDomainInfo),
 		Hostnames:    make(map[string]*statusHostnameInfo),
-		Ports:        make(map[string]*statusPortInfo),
 		Certificates: make(map[string]*statusCertificateInfo),
 	}
 
-	buildDomains(snap, resp)
+	hostnames, domainRecords := splitHostnames(snap)
-	buildHostnames(snap, resp)
+
-	buildPorts(snap, resp)
+	buildDomains(snap, domainRecords, resp)
+	buildHostnames(hostnames, resp)
+	resp.Ports = buildPorts(snap)
 	buildCertificates(snap, resp)
 	buildCounts(resp)
 
 	return resp
 }
 
+// splitHostnames returns the records saved in snap.Hostnames in two
+// maps: the hostnames' and the apex domains' own. The watcher saves a
+// domain's own records there under the domain's name, which has an
+// entry in snap.Domains too.
+func splitHostnames(
+	snap state.Snapshot,
+) (map[string]*state.HostnameState, map[string]*state.HostnameState) {
+	hostnames := make(map[string]*state.HostnameState)
+	domainRecords := make(map[string]*state.HostnameState)
+
+	for name, hs := range snap.Hostnames {
+		if _, isDomain := snap.Domains[name]; isDomain {
+			domainRecords[name] = hs
+		} else {
+			hostnames[name] = hs
+		}
+	}
+
+	return hostnames, domainRecords
+}
+
 func buildDomains(
 	snap state.Snapshot,
+	domainRecords map[string]*state.HostnameState,
 	resp *statusResponse,
 ) {
 	for name, ds := range snap.Domains {
@@ -116,57 +149,87 @@ func buildDomains(
 		copy(ns, ds.Nameservers)
 		sort.Strings(ns)
 
+		records := make(map[string]*statusHostnameNSInfo)
+		if hs, ok := domainRecords[name]; ok {
+			records = nameserverInfo(hs)
+		}
+
 		resp.Domains[name] = &statusDomainInfo{
-			Nameservers: ns,
+			Nameservers:         ns,
-			LastChecked: ds.LastChecked,
+			RecordsByNameserver: records,
+			NXDomain:            ds.NXDomain,
+			LastChecked:         ds.LastChecked,
 		}
 	}
 }
 
 func buildHostnames(
-	snap state.Snapshot,
+	hostnames map[string]*state.HostnameState,
 	resp *statusResponse,
 ) {
-	for name, hs := range snap.Hostnames {
+	for name, hs := range hostnames {
-		info := &statusHostnameInfo{
+		resp.Hostnames[name] = &statusHostnameInfo{
-			Nameservers: make(map[string]*statusHostnameNSInfo),
+			Nameservers: nameserverInfo(hs),
 			LastChecked: hs.LastChecked,
 		}
-
-		for ns, nsState := range hs.RecordsByNameserver {
-			recs := make(map[string][]string, len(nsState.Records))
-			for rtype, vals := range nsState.Records {
-				copied := make([]string, len(vals))
-				copy(copied, vals)
-				recs[rtype] = copied
-			}
-
-			info.Nameservers[ns] = &statusHostnameNSInfo{
-				Records:     recs,
-				Status:      nsState.Status,
-				LastChecked: nsState.LastChecked,
-			}
-		}
-
-		resp.Hostnames[name] = info
 	}
 }
 
-func buildPorts(
+// nameserverInfo copies each nameserver's answer saved in hs.
-	snap state.Snapshot,
+func nameserverInfo(
-	resp *statusResponse,
+	hs *state.HostnameState,
-) {
+) map[string]*statusHostnameNSInfo {
+	info := make(map[string]*statusHostnameNSInfo)
+
+	for ns, nsState := range hs.RecordsByNameserver {
+		recs := make(map[string][]string, len(nsState.Records))
+		for rtype, vals := range nsState.Records {
+			copied := make([]string, len(vals))
+			copy(copied, vals)
+			recs[rtype] = copied
+		}
+
+		info[ns] = &statusHostnameNSInfo{
+			Records:     recs,
+			Status:      nsState.Status,
+			Error:       nsState.Error,
+			LastChecked: nsState.LastChecked,
+		}
+	}
+
+	return info
+}
+
+// buildPorts returns the port entries saved in snap. A port entry
+// saves apex domains with its hostnames; they are told apart as in
+// splitHostnames, by a domain entry in snap.Domains.
+func buildPorts(snap state.Snapshot) map[string]*statusPortInfo {
+	ports := make(map[string]*statusPortInfo, len(snap.Ports))
+
 	for key, ps := range snap.Ports {
-		hostnames := make([]string, len(ps.Hostnames))
+		domains := []string{}
-		copy(hostnames, ps.Hostnames)
+		hostnames := []string{}
+
+		for _, name := range ps.Hostnames {
+			if _, isDomain := snap.Domains[name]; isDomain {
+				domains = append(domains, name)
+			} else {
+				hostnames = append(hostnames, name)
+			}
+		}
+
+		sort.Strings(domains)
 		sort.Strings(hostnames)
 
-		resp.Ports[key] = &statusPortInfo{
+		ports[key] = &statusPortInfo{
 			Open:        ps.Open,
+			Domains:     domains,
 			Hostnames:   hostnames,
 			LastChecked: ps.LastChecked,
 		}
 	}
+
+	return ports
 }
 
 func buildCertificates(
@@ -183,6 +246,7 @@ func buildCertificates(
 			NotAfter:                cs.NotAfter,
 			SubjectAlternativeNames: sans,
 			Status:                  cs.Status,
+			Error:                   cs.Error,
 			LastChecked:             cs.LastChecked,
 		}
 	}

internal/handlers/status_test.go

@@ -0,0 +1,309 @@
+package handlers_test
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"slices"
+	"testing"
+	"time"
+
+	"go.uber.org/fx/fxtest"
+
+	"sneak.berlin/go/dnswatcher/internal/config"
+	"sneak.berlin/go/dnswatcher/internal/globals"
+	"sneak.berlin/go/dnswatcher/internal/handlers"
+	"sneak.berlin/go/dnswatcher/internal/logger"
+	"sneak.berlin/go/dnswatcher/internal/notify"
+	"sneak.berlin/go/dnswatcher/internal/state"
+)
+
+// The state the handler tests serve: www.example.com has one nameserver
+// that answered and one whose query failed, and its certificate check
+// failed. example.net is an apex domain, whose own records are saved
+// with the hostnames' records, as the watcher saves them. Both names
+// resolve to domainAddress, whose port 443 entry lists them.
+// missingDomain is an apex domain whose parent zone's servers answered
+// that it does not exist, saved with no nameservers and no records.
+const (
+	missingDomain    = "does-not-exist.example"
+	testHostname     = "www.example.com"
+	answeringNS      = "ns1.example.com."
+	failedNS         = "ns2.example.com."
+	nsFailureReason  = "server returned a referral"
+	certKey          = "192.0.2.1:443:www.example.com"
+	certFailedReason = "x509: certificate has expired or is not yet valid"
+	testDomain       = "example.net"
+	domainNS         = "a.iana-servers.net."
+	domainAddress    = "192.0.2.2"
+	sharedPort       = domainAddress + ":443"
+)
+
+// newHandlersWithFailures builds real Handlers whose state holds the
+// entries described above.
+func newHandlersWithFailures(t *testing.T) *handlers.Handlers {
+	t.Helper()
+
+	glob, err := globals.New(nil)
+	if err != nil {
+		t.Fatalf("globals.New: %v", err)
+	}
+
+	log, err := logger.New(nil, logger.Params{Globals: glob})
+	if err != nil {
+		t.Fatalf("logger.New: %v", err)
+	}
+
+	notifier, err := notify.New(fxtest.NewLifecycle(t), notify.Params{
+		Logger: log,
+		Config: &config.Config{},
+	})
+	if err != nil {
+		t.Fatalf("notify.New: %v", err)
+	}
+
+	st, err := state.New(fxtest.NewLifecycle(t), state.Params{
+		Logger: log,
+		Config: &config.Config{DataDir: t.TempDir()},
+	})
+	if err != nil {
+		t.Fatalf("state.New: %v", err)
+	}
+
+	setTestState(st)
+
+	hnd, err := handlers.New(nil, handlers.Params{
+		Logger:  log,
+		Globals: glob,
+		State:   st,
+		Notify:  notifier,
+	})
+	if err != nil {
+		t.Fatalf("handlers.New: %v", err)
+	}
+
+	return hnd
+}
+
+// setTestState sets the entries described above in st.
+func setTestState(st *state.State) {
+	now := time.Now()
+
+	st.SetHostnameState(testHostname, &state.HostnameState{
+		RecordsByNameserver: map[string]*state.NameserverRecordState{
+			answeringNS: {
+				Records: map[string][]string{
+					"A": {"192.0.2.1", domainAddress},
+				},
+				Status:      "ok",
+				LastChecked: now,
+			},
+			failedNS: {
+				Records:     map[string][]string{},
+				Status:      "error",
+				Error:       nsFailureReason,
+				LastChecked: now,
+			},
+		},
+		LastChecked: now,
+	})
+
+	st.SetCertificateState(certKey, &state.CertificateState{
+		Status:      "error",
+		Error:       certFailedReason,
+		LastChecked: now,
+	})
+
+	st.SetDomainState(testDomain, &state.DomainState{
+		Nameservers: []string{domainNS},
+		LastChecked: now,
+	})
+
+	st.SetHostnameState(testDomain, &state.HostnameState{
+		RecordsByNameserver: map[string]*state.NameserverRecordState{
+			domainNS: {
+				Records:     map[string][]string{"A": {domainAddress}},
+				Status:      "ok",
+				LastChecked: now,
+			},
+		},
+		LastChecked: now,
+	})
+
+	st.SetPortState(sharedPort, &state.PortState{
+		Open:        true,
+		Hostnames:   []string{testDomain, testHostname},
+		LastChecked: now,
+	})
+
+	st.SetDomainState(missingDomain, &state.DomainState{
+		Nameservers: []string{},
+		NXDomain:    true,
+		LastChecked: now,
+	})
+}
+
+// get serves one GET request to handler and returns the response body.
+func get(t *testing.T, handler http.HandlerFunc) string {
+	t.Helper()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(
+		t.Context(), http.MethodGet, "/", nil,
+	)
+
+	handler(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", rec.Code)
+	}
+
+	return rec.Body.String()
+}
+
+// TestStatusGivesFailureReasons checks that /api/v1/status gives the
+// reason for a failed nameserver entry and a failed certificate entry,
+// and no error for a nameserver that answered.
+func TestStatusGivesFailureReasons(t *testing.T) {
+	t.Parallel()
+
+	body := get(t, newHandlersWithFailures(t).HandleStatus())
+
+	var resp struct {
+		Hostnames map[string]struct {
+			Nameservers map[string]map[string]any `json:"nameservers"`
+		} `json:"hostnames"`
+		Certificates map[string]map[string]any `json:"certificates"`
+	}
+
+	err := json.Unmarshal([]byte(body), &resp)
+	if err != nil {
+		t.Fatalf("decoding response: %v", err)
+	}
+
+	nameservers := resp.Hostnames[testHostname].Nameservers
+
+	got := nameservers[failedNS]["error"]
+	if got != nsFailureReason {
+		t.Errorf("failed nameserver error = %v, want %q",
+			got, nsFailureReason)
+	}
+
+	_, has := nameservers[answeringNS]["error"]
+	if has {
+		t.Errorf("answering nameserver has an error field: %v",
+			nameservers[answeringNS])
+	}
+
+	got = resp.Certificates[certKey]["error"]
+	if got != certFailedReason {
+		t.Errorf("failed certificate error = %v, want %q",
+			got, certFailedReason)
+	}
+}
+
+// TestStatusGivesDomainRecordsUnderTheDomain checks that /api/v1/status
+// gives an apex domain's own records in its domain entry, and neither
+// lists nor counts the domain as a hostname.
+func TestStatusGivesDomainRecordsUnderTheDomain(t *testing.T) {
+	t.Parallel()
+
+	body := get(t, newHandlersWithFailures(t).HandleStatus())
+
+	var resp struct {
+		Counts struct {
+			Hostnames int `json:"hostnames"`
+		} `json:"counts"`
+		Domains map[string]struct {
+			RecordsByNameserver map[string]struct {
+				Records map[string][]string `json:"records"`
+			} `json:"recordsByNameserver"`
+		} `json:"domains"`
+		Hostnames map[string]any `json:"hostnames"`
+	}
+
+	err := json.Unmarshal([]byte(body), &resp)
+	if err != nil {
+		t.Fatalf("decoding response: %v", err)
+	}
+
+	if resp.Counts.Hostnames != 1 {
+		t.Errorf("counts.hostnames = %d, want 1", resp.Counts.Hostnames)
+	}
+
+	if _, listed := resp.Hostnames[testDomain]; listed {
+		t.Errorf("hostnames lists the domain %s", testDomain)
+	}
+
+	records := resp.Domains[testDomain].RecordsByNameserver[domainNS].Records
+	if !slices.Equal(records["A"], []string{domainAddress}) {
+		t.Errorf("domain %s records at %s = %v, want A %s",
+			testDomain, domainNS, records, domainAddress)
+	}
+}
+
+// TestStatusMarksDomainThatDoesNotExist checks that /api/v1/status sets
+// nxdomain for a domain that does not exist, with no nameservers or
+// records, and not for a domain that exists.
+func TestStatusMarksDomainThatDoesNotExist(t *testing.T) {
+	t.Parallel()
+
+	body := get(t, newHandlersWithFailures(t).HandleStatus())
+
+	var resp struct {
+		Domains map[string]struct {
+			Nameservers         []string       `json:"nameservers"`
+			RecordsByNameserver map[string]any `json:"recordsByNameserver"`
+			NXDomain            bool           `json:"nxdomain"`
+		} `json:"domains"`
+	}
+
+	err := json.Unmarshal([]byte(body), &resp)
+	if err != nil {
+		t.Fatalf("decoding response: %v", err)
+	}
+
+	missing := resp.Domains[missingDomain]
+	if !missing.NXDomain || len(missing.Nameservers) != 0 ||
+		len(missing.RecordsByNameserver) != 0 {
+		t.Errorf("domain %s = %+v, want nxdomain and nothing else",
+			missingDomain, missing)
+	}
+
+	if resp.Domains[testDomain].NXDomain {
+		t.Errorf("domain %s has nxdomain set", testDomain)
+	}
+}
+
+// TestStatusPortsTellDomainsFromHostnames checks that a port entry in
+// /api/v1/status lists an apex domain in domains and a hostname in
+// hostnames when both resolve to its address.
+func TestStatusPortsTellDomainsFromHostnames(t *testing.T) {
+	t.Parallel()
+
+	body := get(t, newHandlersWithFailures(t).HandleStatus())
+
+	var resp struct {
+		Ports map[string]struct {
+			Domains   []string `json:"domains"`
+			Hostnames []string `json:"hostnames"`
+		} `json:"ports"`
+	}
+
+	err := json.Unmarshal([]byte(body), &resp)
+	if err != nil {
+		t.Fatalf("decoding response: %v", err)
+	}
+
+	port := resp.Ports[sharedPort]
+
+	if !slices.Equal(port.Domains, []string{testDomain}) {
+		t.Errorf("port %s domains = %v, want [%s]",
+			sharedPort, port.Domains, testDomain)
+	}
+
+	if !slices.Equal(port.Hostnames, []string{testHostname}) {
+		t.Errorf("port %s hostnames = %v, want [%s]",
+			sharedPort, port.Hostnames, testHostname)
+	}
+}

internal/handlers/templates/dashboard.html

@@ -39,7 +39,7 @@
             Hostnames
           </div>
           <div class="text-2xl font-bold text-teal-400 mt-1">
-            {{ len .Snapshot.Hostnames }}
+            {{ len .Hostnames }}
           </div>
         </div>
         <div class="bg-surface-800 border border-slate-700/50 rounded-lg p-4">
@@ -84,7 +84,11 @@
                   {{ $name }}
                 </td>
                 <td class="py-2 px-3 text-slate-400 break-all">
+                  {{ if $ds.NXDomain }}
+                  <span class="text-red-400">does not exist</span>
+                  {{ else }}
                   {{ joinStrings $ds.Nameservers ", " }}
+                  {{ end }}
                 </td>
                 <td class="py-2 px-3 text-slate-500 whitespace-nowrap">
                   {{ relTime $ds.LastChecked }}
@@ -94,6 +98,24 @@
             </tbody>
           </table>
         </div>
+        {{ if .DomainRecords }}
+        <div class="overflow-x-auto mt-4">
+          <table class="w-full text-left text-xs">
+            <thead>
+              <tr class="text-slate-500 uppercase tracking-wider">
+                <th class="py-2 px-3">Domain</th>
+                <th class="py-2 px-3">NS</th>
+                <th class="py-2 px-3">Status</th>
+                <th class="py-2 px-3">Records</th>
+                <th class="py-2 px-3">Checked</th>
+              </tr>
+            </thead>
+            <tbody class="divide-y divide-slate-800">
+              {{ template "records" .DomainRecords }}
+            </tbody>
+          </table>
+        </div>
+        {{ end }}
         {{ else }}
         <p class="text-slate-600 italic text-xs">
           No domains configured.
@@ -108,7 +130,7 @@
         >
           Hostnames
         </h2>
-        {{ if .Snapshot.Hostnames }}
+        {{ if .Hostnames }}
         <div class="overflow-x-auto">
           <table class="w-full text-left text-xs">
             <thead>
@@ -121,39 +143,7 @@
               </tr>
             </thead>
             <tbody class="divide-y divide-slate-800">
-              {{ range $name, $hs := .Snapshot.Hostnames }}
+              {{ template "records" .Hostnames }}
-              {{ range $ns, $nsr := $hs.RecordsByNameserver }}
-              <tr class="hover:bg-surface-800/50">
-                <td class="py-2 px-3 text-slate-200 font-medium">
-                  {{ $name }}
-                </td>
-                <td class="py-2 px-3 text-slate-400 break-all">
-                  {{ $ns }}
-                </td>
-                <td class="py-2 px-3">
-                  {{ if eq $nsr.Status "ok" }}
-                  <span
-                    class="inline-block px-1.5 py-0.5 rounded text-[10px] font-bold uppercase bg-teal-900/50 text-teal-400 border border-teal-700/30"
-                    >ok</span
-                  >
-                  {{ else }}
-                  <span
-                    class="inline-block px-1.5 py-0.5 rounded text-[10px] font-bold uppercase bg-red-900/50 text-red-400 border border-red-700/30"
-                    >{{ $nsr.Status }}</span
-                  >
-                  {{ end }}
-                </td>
-                <td
-                  class="py-2 px-3 text-slate-400 break-all max-w-xs"
-                >
-                  {{ formatRecords $nsr.Records }}
-                </td>
-                <td class="py-2 px-3 text-slate-500 whitespace-nowrap">
-                  {{ relTime $nsr.LastChecked }}
-                </td>
-              </tr>
-              {{ end }}
-              {{ end }}
             </tbody>
           </table>
         </div>
@@ -171,19 +161,20 @@
         >
           Ports
         </h2>
-        {{ if .Snapshot.Ports }}
+        {{ if .Ports }}
         <div class="overflow-x-auto">
           <table class="w-full text-left text-xs">
             <thead>
               <tr class="text-slate-500 uppercase tracking-wider">
                 <th class="py-2 px-3">Address</th>
                 <th class="py-2 px-3">State</th>
+                <th class="py-2 px-3">Domains</th>
                 <th class="py-2 px-3">Hostnames</th>
                 <th class="py-2 px-3">Checked</th>
               </tr>
             </thead>
             <tbody class="divide-y divide-slate-800">
-              {{ range $key, $ps := .Snapshot.Ports }}
+              {{ range $key, $ps := .Ports }}
               <tr class="hover:bg-surface-800/50">
                 <td class="py-2 px-3 text-slate-200 font-medium">
                   {{ $key }}
@@ -201,6 +192,9 @@
                   >
                   {{ end }}
                 </td>
+                <td class="py-2 px-3 text-slate-400 break-all">
+                  {{ joinStrings $ps.Domains ", " }}
+                </td>
                 <td class="py-2 px-3 text-slate-400 break-all">
                   {{ joinStrings $ps.Hostnames ", " }}
                 </td>
@@ -258,6 +252,11 @@
                   >
                   {{ end }}
                 </td>
+                {{ if $cs.Error }}
+                <td colspan="3" class="py-2 px-3 text-red-400 break-all">
+                  <div class="max-w-xs">{{ $cs.Error }}</div>
+                </td>
+                {{ else }}
                 <td class="py-2 px-3 text-slate-200">
                   {{ $cs.CommonName }}
                 </td>
@@ -285,6 +284,7 @@
                     {{ end }}
                   {{ end }}
                 </td>
+                {{ end }}
                 <td class="py-2 px-3 text-slate-500 whitespace-nowrap">
                   {{ relTime $cs.LastChecked }}
                 </td>
@@ -363,8 +363,48 @@
         class="text-[11px] text-slate-700 border-t border-slate-800 pt-4 mt-8"
       >
         dnswatcher &middot; monitoring {{ len .Snapshot.Domains }} domains +
-        {{ len .Snapshot.Hostnames }} hostnames
+        {{ len .Hostnames }} hostnames
       </div>
     </div>
   </body>
 </html>
+{{/* ---- One row per nameserver of each name in the map it is given ---- */}}
+{{ define "records" }}
+{{ range $name, $hs := . }}
+{{ range $ns, $nsr := $hs.RecordsByNameserver }}
+<tr class="hover:bg-surface-800/50">
+  <td class="py-2 px-3 text-slate-200 font-medium">
+    {{ $name }}
+  </td>
+  <td class="py-2 px-3 text-slate-400 break-all">
+    {{ $ns }}
+  </td>
+  <td class="py-2 px-3">
+    {{ if eq $nsr.Status "ok" }}
+    <span
+      class="inline-block px-1.5 py-0.5 rounded text-[10px] font-bold uppercase bg-teal-900/50 text-teal-400 border border-teal-700/30"
+      >ok</span
+    >
+    {{ else }}
+    <span
+      class="inline-block px-1.5 py-0.5 rounded text-[10px] font-bold uppercase bg-red-900/50 text-red-400 border border-red-700/30"
+      >{{ $nsr.Status }}</span
+    >
+    {{ end }}
+  </td>
+  <td
+    class="py-2 px-3 text-slate-400 break-all max-w-xs"
+  >
+    {{ if $nsr.Error }}
+    <span class="text-red-400">{{ $nsr.Error }}</span>
+    {{ else }}
+    {{ formatRecords $nsr.Records }}
+    {{ end }}
+  </td>
+  <td class="py-2 px-3 text-slate-500 whitespace-nowrap">
+    {{ relTime $nsr.LastChecked }}
+  </td>
+</tr>
+{{ end }}
+{{ end }}
+{{ end }}

internal/livednstest/livednstest.go

@@ -9,11 +9,11 @@
 //
 //  1. Bounded concurrency. Tests run in parallel and the build hosts
 //     have many cores, so without a limit every test starts its own
-//     iterative resolution at the same instant and they all hit the
+//     iterative resolution at the same instant and they all send their
-//     first root server within a few milliseconds of each other. Root
+//     first queries to the root servers within a few milliseconds of
-//     servers rate-limit that, which shows up as a different arbitrary
+//     each other. Root servers rate-limit that, which shows up as a
-//     subset of tests failing on each run. Run caps how many live
+//     different arbitrary subset of tests failing on each run. Run caps
-//     operations are in flight at once in one test binary.
+//     how many live operations are in flight at once in one test binary.
 //
 //  2. Retry with exponential backoff. Each live operation gets several
 //     attempts with its own timeout. An attempt is retried when it
@@ -36,11 +36,18 @@ const (
 	// before the test fails.
 	attempts = 3
 
-	// AttemptTimeout bounds one attempt. Worst case for an operation
+	// AttemptTimeout bounds one attempt. It must fit the longest
-	// is attempts * AttemptTimeout plus the backoff — about 26
+	// operation, a watcher check, which sends over a hundred queries one
-	// seconds, well inside the 90-second `go test -timeout` backstop
+	// after another and on a slow build host takes several times as long
-	// even when several operations exhaust their attempts.
+	// as the few seconds it takes on a fast one. An operation whose
-	AttemptTimeout = 8 * time.Second
+	// every attempt fails takes attempts * AttemptTimeout plus the
+	// backoff, about 56 seconds, after it waits for one of the
+	// Concurrency slots that every live operation in the test binary
+	// shares. So when live DNS does not answer at all, a test binary
+	// with more live operations than slots runs into the 90-second
+	// `go test -timeout` backstop instead of each test failing on its
+	// own.
+	AttemptTimeout = 18 * time.Second
 
 	// backoffBase is the delay after the first failed attempt; it is
 	// multiplied by backoffFactor each time.

internal/notify/delivery_test.go

@@ -6,9 +6,11 @@ import (
 	"encoding/json"
 	"errors"
 	"io"
+	"maps"
 	"net/http"
 	"net/http/httptest"
 	"net/url"
+	"strings"
 	"sync"
 	"testing"
 	"time"
@@ -413,7 +415,8 @@ func sendSlackInfo(
 	svc *notify.Service, target *url.URL,
 ) error {
 	return svc.SendSlack(
-		context.Background(), target, "t", "m", prioInfo,
+		context.Background(), target, notify.ErrSlackFailed,
+		"t", "m", prioInfo,
 	)
 }
 
@@ -506,6 +509,7 @@ func TestSendSlackPayloadFields(t *testing.T) {
 	err := svc.SendSlack(
 		context.Background(),
 		webhookURL,
+		notify.ErrSlackFailed,
 		"Alert Title",
 		"Alert body text",
 		"warning",
@@ -608,7 +612,8 @@ func TestSendSlackAllColors(t *testing.T) {
 
 			err := svc.SendSlack(
 				context.Background(),
-				webhookURL, "t", "m", tc.priority,
+				webhookURL, notify.ErrSlackFailed,
+				"t", "m", tc.priority,
 			)
 			if err != nil {
 				t.Fatalf("SendSlack error: %v", err)
@@ -659,7 +664,8 @@ func TestSendSlackNetworkError(t *testing.T) {
 	)
 
 	err := svc.SendSlack(
-		context.Background(), webhookURL, "t", "m", "info",
+		context.Background(), webhookURL, notify.ErrSlackFailed,
+		"t", "m", "info",
 	)
 	if err == nil {
 		t.Fatal("expected error for network failure")
@@ -1028,6 +1034,66 @@ func TestSendNotificationMattermostError(t *testing.T) {
 	)
 }
 
+// TestSendNotificationErrorNamesEndpoint verifies that, with both
+// Slack and Mattermost set, a failed delivery's logged error names
+// the endpoint that failed. Both are sent by the Slack sender.
+func TestSendNotificationErrorNamesEndpoint(t *testing.T) {
+	t.Parallel()
+
+	srv := httptest.NewServer(
+		http.HandlerFunc(
+			func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusServiceUnavailable)
+			}),
+	)
+	defer srv.Close()
+
+	target, _ := url.Parse(srv.URL)
+
+	svc, logs := newLoggingService(http.DefaultTransport)
+	svc.SetSlackWebhookURL(target)
+	svc.SetMattermostWebhookURL(target)
+	svc.SetSleepFunc(instantSleep)
+	svc.SetRetryConfig(notify.RetryConfig{
+		MaxRetries: 1,
+		BaseDelay:  time.Millisecond,
+		MaxDelay:   time.Millisecond,
+	})
+
+	svc.SendNotification(
+		context.Background(), "t", "m", prioError,
+	)
+
+	waitForCondition(t, func() bool {
+		return svc.OutstandingDeliveries() == 0
+	})
+
+	got := map[string]string{}
+
+	for line := range strings.Lines(logs.String()) {
+		var record struct {
+			Msg      string `json:"msg"`
+			Endpoint string `json:"endpoint"`
+			Error    string `json:"error"`
+		}
+
+		_ = json.Unmarshal([]byte(line), &record)
+
+		if record.Msg == "failed to send notification after retries" {
+			got[record.Endpoint] = record.Error
+		}
+	}
+
+	want := map[string]string{
+		"slack":      "slack notification failed: status 503",
+		"mattermost": "mattermost notification failed: status 503",
+	}
+
+	if !maps.Equal(got, want) {
+		t.Errorf("logged errors = %v, want %v", got, want)
+	}
+}
+
 // ── SlackPayload JSON marshaling ──────────────────────────
 
 func TestSlackPayloadJSON(t *testing.T) {

internal/notify/export_test.go

@@ -85,10 +85,11 @@ func (svc *Service) SendNtfy(
 func (svc *Service) SendSlack(
 	ctx context.Context,
 	webhookURL *url.URL,
+	failed error,
 	title, message, priority string,
 ) error {
 	return svc.sendSlack(
-		ctx, webhookURL, title, message, priority,
+		ctx, webhookURL, failed, title, message, priority,
 	)
 }
 

internal/notify/notify.go

@@ -277,7 +277,8 @@ func (svc *Service) dispatchSlack(
 
 	svc.dispatch(ctx, "slack", func(c context.Context) error {
 		return svc.sendSlack(
-			c, svc.slackWebhookURL, title, message, priority,
+			c, svc.slackWebhookURL, ErrSlackFailed,
+			title, message, priority,
 		)
 	})
 }
@@ -294,7 +295,7 @@ func (svc *Service) dispatchMattermost(
 		ctx, "mattermost",
 		func(c context.Context) error {
 			return svc.sendSlack(
-				c, svc.mattermostWebhookURL,
+				c, svc.mattermostWebhookURL, ErrMattermostFailed,
 				title, message, priority,
 			)
 		},
@@ -370,9 +371,14 @@ type SlackAttachment struct {
 	Text  string `json:"text"`
 }
 
+// sendSlack posts to a Slack or Mattermost incoming webhook, which
+// take the same payload. An HTTP error status is returned wrapped in
+// failed, ErrSlackFailed or ErrMattermostFailed, so the error names
+// the endpoint.
 func (svc *Service) sendSlack(
 	ctx context.Context,
 	webhookURL *url.URL,
+	failed error,
 	title, message, priority string,
 ) error {
 	ctx, cancel := context.WithTimeout(
@@ -420,7 +426,7 @@ func (svc *Service) sendSlack(
 	if resp.StatusCode >= httpStatusClientError {
 		return fmt.Errorf(
 			"%w: status %d",
-			ErrSlackFailed, resp.StatusCode,
+			failed, resp.StatusCode,
 		)
 	}
 

internal/notify/retry.go

@@ -115,7 +115,9 @@ func (svc *Service) deliverWithRetry(
 			"endpoint", endpoint,
 			"attempt", attempt+1,
 			"maxAttempts", cfg.MaxRetries+1,
-			"retryIn", delay,
+			// As text: the JSON log writes a time.Duration as
+			// bare nanoseconds.
+			"retryIn", delay.String(),
 			"error", lastErr,
 		)
 

internal/notify/retry_test.go

@@ -2,6 +2,7 @@ package notify_test
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"net/http"
 	"net/http/httptest"
@@ -189,6 +190,50 @@ func TestDeliverWithRetryExhaustsAttempts(t *testing.T) {
 	}
 }
 
+// TestDeliverWithRetryLogsRetryInAsText checks that the wait
+// before a retry is logged as text such as "1.02s", not as a
+// count of nanoseconds.
+func TestDeliverWithRetryLogsRetryInAsText(t *testing.T) {
+	t.Parallel()
+
+	svc, logs := newLoggingService(http.DefaultTransport)
+	svc.SetRetryConfig(notify.RetryConfig{
+		MaxRetries: 1,
+		BaseDelay:  time.Second,
+		MaxDelay:   time.Second,
+	})
+
+	var waited time.Duration
+
+	svc.SetSleepFunc(func(d time.Duration) <-chan time.Time {
+		waited = d
+
+		return instantSleep(d)
+	})
+
+	_ = svc.DeliverWithRetry(
+		context.Background(), "test",
+		func(_ context.Context) error {
+			return errFail
+		},
+	)
+
+	// With one retry, only the first failure is logged.
+	var record map[string]any
+
+	err := json.Unmarshal([]byte(logs.String()), &record)
+	if err != nil {
+		t.Fatalf("log is not one JSON record: %v\n%s", err, logs)
+	}
+
+	if record["retryIn"] != waited.String() {
+		t.Errorf(
+			"retryIn logged as %v, want %q",
+			record["retryIn"], waited.String(),
+		)
+	}
+}
+
 func TestDeliverWithRetryRespectsContextCancellation(
 	t *testing.T,
 ) {

internal/portcheck/portcheck.go

@@ -193,7 +193,9 @@ func (c *Checker) checkConnection(
 	c.log.Debug(
 		"port check succeeded",
 		"target", target,
-		"latency", latency,
+		// As text: the JSON log writes a time.Duration as bare
+		// nanoseconds.
+		"latency", latency.String(),
 	)
 
 	return &PortResult{

internal/resolver/errors.go

@@ -2,6 +2,23 @@ package resolver
 
 import "errors"
 
+// NoAnswerError is returned when the walk to a name's nameservers
+// reached a zone through a referral and none of that zone's
+// nameservers, Nameservers as the referral names them, answered. Err
+// says why they did not.
+type NoAnswerError struct {
+	Nameservers []string
+	Err         error
+}
+
+func (e *NoAnswerError) Error() string {
+	return e.Err.Error()
+}
+
+func (e *NoAnswerError) Unwrap() error {
+	return e.Err
+}
+
 // Sentinel errors returned by the resolver.
 var (
 	// ErrNoNameservers is returned when no authoritative NS
@@ -10,12 +27,46 @@ var (
 		"no authoritative nameservers found",
 	)
 
+	// ErrNXDomain is returned when the servers of the zone a domain
+	// is in answer NXDOMAIN: the domain does not exist.
+	ErrNXDomain = errors.New("domain does not exist")
+
+	// ErrNoNameserverAnswered is returned when every nameserver
+	// asked about a name timed out, failed or returned a referral,
+	// so whether the name has addresses is unknown.
+	ErrNoNameserverAnswered = errors.New("no nameserver answered")
+
+	// ErrUnusableReply is returned when a server replied with an
+	// error such as SERVFAIL, or with a referral that leads no
+	// closer to the name asked about.
+	ErrUnusableReply = errors.New(
+		"reply is an error or a referral that leads no closer",
+	)
+
+	// ErrTruncated is the reason given for a reply too large for UDP
+	// whose retry over TCP failed.
+	ErrTruncated = errors.New(
+		"reply truncated and its retry over TCP failed",
+	)
+
+	// ErrIntercepted is returned when every root server refused a
+	// query. Root servers refuse no query, so the refusals came from
+	// something on the network answering in their place.
+	ErrIntercepted = errors.New("this network intercepts DNS queries")
+
 	// ErrCNAMEDepthExceeded is returned when a CNAME chain
 	// exceeds MaxCNAMEDepth.
 	ErrCNAMEDepthExceeded = errors.New(
 		"CNAME chain depth exceeded",
 	)
 
+	// ErrLookupDepthExceeded is returned when nameserver addresses
+	// were not looked up because lookups were already maxLookupDepth
+	// deep, one inside another.
+	ErrLookupDepthExceeded = errors.New(
+		"lookups of nameserver addresses go too deep",
+	)
+
 	// ErrContextCanceled wraps context cancellation for the
 	// resolver's iterative queries.
 	ErrContextCanceled = errors.New("context canceled")

internal/resolver/export_test.go

@@ -2,20 +2,147 @@ package resolver
 
 import (
 	"context"
+	"log/slog"
+	"time"
 
 	"github.com/miekg/dns"
 )
 
+// NewWithFailingTCP returns a Resolver whose TCP client gives up before
+// it can connect, so the retry over TCP of every truncated reply fails.
+func NewWithFailingTCP(log *slog.Logger) *Resolver {
+	r := NewFromLogger(log)
+	r.tcp = &tcpClient{timeout: time.Nanosecond}
+
+	return r
+}
+
+// NewWithQueryTimeout returns a Resolver whose queries over UDP give up
+// after timeout, so a test that asks an address where nothing answers
+// does not wait out the usual timeout.
+func NewWithQueryTimeout(log *slog.Logger, timeout time.Duration) *Resolver {
+	r := NewFromLogger(log)
+	r.client = &udpClient{timeout: timeout}
+
+	return r
+}
+
+// FollowDelegation exports followDelegation for testing.
+func (r *Resolver) FollowDelegation(
+	ctx context.Context,
+	domain string,
+	zone string,
+	nameservers []string,
+	servers []string,
+) ([]string, error) {
+	return r.followDelegation(ctx, domain, zone, nameservers, servers)
+}
+
+// FindAuthoritativeNameserversFrom exports findAuthoritativeNameservers
+// for testing.
+func (r *Resolver) FindAuthoritativeNameserversFrom(
+	ctx context.Context,
+	domain string,
+	servers []string,
+) ([]string, error) {
+	return r.findAuthoritativeNameservers(ctx, domain, servers)
+}
+
+// ResolveNSIterative exports resolveNSIterative for testing.
+func (r *Resolver) ResolveNSIterative(
+	ctx context.Context,
+	domain string,
+) ([]string, error) {
+	return r.resolveNSIterative(ctx, domain)
+}
+
 // ExtractRecordValue exports extractRecordValue for testing.
 func ExtractRecordValue(rr dns.RR) string {
 	return extractRecordValue(rr)
 }
 
+// CollectAnswerRecords exports collectAnswerRecords for testing.
+func CollectAnswerRecords(msg *dns.Msg, resp *NameserverResponse) {
+	var state queryState
+
+	collectAnswerRecords(msg, resp, &state)
+}
+
+// UsableReply exports usableReply for testing.
+func UsableReply(resp *dns.Msg, zone string, name string) bool {
+	return usableReply(resp, zone, name)
+}
+
+// NSSetFrom exports nsSetFrom for testing.
+func NSSetFrom(resp *dns.Msg, domain string) []string {
+	return nsSetFrom(resp, domain)
+}
+
+// CollectIPs exports collectIPs for testing.
+func CollectIPs(
+	results map[string]*NameserverResponse,
+) ([]string, string, error) {
+	return collectIPs(results)
+}
+
+// QueryServers exports queryServers for testing.
+func (r *Resolver) QueryServers(
+	ctx context.Context,
+	servers []string,
+	zone string,
+	name string,
+	qtype uint16,
+) (*dns.Msg, error) {
+	return r.queryServers(ctx, servers, zone, name, qtype)
+}
+
 // QueryEachNS exports queryEachNS for testing.
 func (r *Resolver) QueryEachNS(
 	ctx context.Context,
 	nameservers []string,
 	hostname string,
 ) (map[string]*NameserverResponse, error) {
-	return r.queryEachNS(ctx, nameservers, hostname)
+	return r.queryEachNS(ctx, nameservers, hostname, recordTypes())
+}
+
+// ResolveNSIPs exports resolveNSIPs for testing, looking each name up
+// as a lookup that no other lookup started.
+func (r *Resolver) ResolveNSIPs(
+	ctx context.Context,
+	nsNames []string,
+) []string {
+	ips, _ := r.resolveNSIPs(ctx, nsNames, 1)
+
+	return ips
+}
+
+// MaxLookupDepth exports maxLookupDepth for testing.
+const MaxLookupDepth = maxLookupDepth
+
+// QueryZone exports queryZone for testing.
+func (r *Resolver) QueryZone(
+	ctx context.Context,
+	given []string,
+	withoutAddresses []string,
+	zone string,
+	name string,
+	qtype uint16,
+	depth int,
+) (*dns.Msg, error) {
+	return r.queryZone(
+		ctx, given, withoutAddresses, zone, name, qtype, depth,
+	)
+}
+
+// RootServerList exports rootServerList for testing.
+func RootServerList() []string {
+	return rootServerList()
+}
+
+// Shuffled exports shuffled for testing.
+func Shuffled(
+	servers []string,
+	shuffle func(n int, swap func(i, j int)),
+) []string {
+	return shuffled(servers, shuffle)
 }

internal/resolver/iterative_internal_test.go

@@ -0,0 +1,149 @@
+package resolver
+
+import (
+	"strconv"
+	"syscall"
+	"testing"
+
+	"github.com/miekg/dns"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestClassifyResponse sets a nameserver's status from the results of
+// its queries and the record types whose query failed, built here. One
+// that answered some record types, even with no records, has not failed
+// when its query for another type got no usable reply, whatever the
+// reason, and is ok, not nodata: that type may have records. One whose
+// every query got none has failed. Only one whose every type answered
+// with no records is nodata.
+func TestClassifyResponse(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		results     queryState
+		failedTypes []string
+		wantStatus  string
+		wantError   string
+	}{
+		{
+			"every type answered with no records",
+			queryState{answered: true},
+			nil,
+			StatusNoData, "",
+		},
+		{
+			"some types answered with no records, another timed out",
+			queryState{answered: true, gotTimeout: true},
+			[]string{"A"},
+			StatusOK, "",
+		},
+		{
+			"some types answered with no records, another got SERVFAIL",
+			queryState{
+				answered: true, gotErrorReply: true, errorReply: "SERVFAIL",
+			},
+			[]string{"A"},
+			StatusOK, "",
+		},
+		{
+			"some types answered with no records, another was refused",
+			queryState{answered: true, gotRefused: true},
+			[]string{"A"},
+			StatusOK, "",
+		},
+		{
+			"some types answered with no records, another got a network error",
+			queryState{answered: true, netErr: syscall.ECONNREFUSED},
+			[]string{"A"},
+			StatusOK, "",
+		},
+		{
+			"some types answered with no records, another's reply was " +
+				"truncated and its retry over TCP failed",
+			queryState{answered: true, netErr: ErrTruncated},
+			[]string{"TXT"},
+			StatusOK, "",
+		},
+		{
+			"some types answered with no records, another got a referral",
+			queryState{answered: true, gotReferral: true},
+			[]string{"A"},
+			StatusOK, "",
+		},
+		{
+			"every query timed out",
+			queryState{gotTimeout: true},
+			[]string{"A", "AAAA", "CNAME"},
+			StatusTimeout, "all queries timed out",
+		},
+		{
+			"every query got NOTIMP",
+			queryState{gotErrorReply: true, errorReply: "NOTIMP"},
+			[]string{"A", "AAAA", "CNAME"},
+			StatusError, "server returned NOTIMP",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			resp := &NameserverResponse{Status: StatusOK, FailedTypes: tt.failedTypes}
+			classifyResponse(resp, tt.results)
+
+			assert.Equal(t, tt.wantStatus, resp.Status)
+			assert.Equal(t, tt.wantError, resp.Error)
+			assert.Equal(t, tt.failedTypes, resp.FailedTypes)
+		})
+	}
+}
+
+// TestReadReply checks which replies to a query about one record type,
+// built here, are an answer: one with the code NOERROR or NXDOMAIN. A
+// reply with any other code is not, and the type's query has failed; a
+// nameserver whose only reply it is has failed, and Error gives the
+// code, or its number when the code has no name.
+func TestReadReply(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		rcode      int
+		wantStatus string
+		wantError  string
+	}{
+		{dns.RcodeSuccess, StatusNoData, ""},
+		{dns.RcodeNameError, StatusNXDomain, ""},
+		{dns.RcodeServerFailure, StatusError, "server returned SERVFAIL"},
+		{dns.RcodeNotImplemented, StatusError, "server returned NOTIMP"},
+		{dns.RcodeFormatError, StatusError, "server returned FORMERR"},
+		{12, StatusError, "server returned 12"}, // unassigned, no name
+	}
+
+	for _, tt := range tests {
+		t.Run(strconv.Itoa(tt.rcode), func(t *testing.T) {
+			t.Parallel()
+
+			msg := new(dns.Msg)
+			msg.Authoritative = true
+			msg.Rcode = tt.rcode
+
+			resp := &NameserverResponse{Records: map[string][]string{}}
+
+			var state queryState
+
+			err := readReply(msg, resp, &state)
+			classifyResponse(resp, state)
+
+			if tt.wantStatus == StatusError {
+				require.ErrorIs(t, err, ErrUnusableReply)
+			} else {
+				require.NoError(t, err)
+			}
+
+			assert.Equal(t, tt.wantStatus, resp.Status)
+			assert.Equal(t, tt.wantError, resp.Error)
+		})
+	}
+}

internal/resolver/iterative_test.go

@@ -1,14 +1,210 @@
 package resolver_test
 
 import (
+	"math/rand/v2"
+	"slices"
 	"testing"
 
 	"github.com/miekg/dns"
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 
 	"sneak.berlin/go/dnswatcher/internal/resolver"
 )
 
+// TestCollectIPs_OneAnswerIsEnough checks that one nameserver answering
+// NXDOMAIN says the name has no addresses, though the other timed out.
+func TestCollectIPs_OneAnswerIsEnough(t *testing.T) {
+	t.Parallel()
+
+	ips, _, err := resolver.CollectIPs(
+		map[string]*resolver.NameserverResponse{
+			"ns1.example.": {Status: resolver.StatusTimeout},
+			"ns2.example.": {Status: resolver.StatusNXDomain},
+		},
+	)
+	require.NoError(t, err)
+	assert.Empty(t, ips)
+}
+
+// TestCollectIPs_FailedIsNoAnswer checks that nameservers that all have
+// status error, from a refusal, a server failure, a network error or a
+// referral, are no answer rather than a name with no addresses.
+func TestCollectIPs_FailedIsNoAnswer(t *testing.T) {
+	t.Parallel()
+
+	ips, _, err := resolver.CollectIPs(
+		map[string]*resolver.NameserverResponse{
+			"ns1.example.": {Status: resolver.StatusError},
+			"ns2.example.": {Status: resolver.StatusError},
+		},
+	)
+	require.ErrorIs(t, err, resolver.ErrNoNameserverAnswered)
+	assert.Empty(t, ips)
+}
+
+// TestCollectIPs_FailedTypeIsNoAnswer checks that a nameserver whose
+// query for one of the types failed is no answer: its addresses are
+// only part of them.
+func TestCollectIPs_FailedTypeIsNoAnswer(t *testing.T) {
+	t.Parallel()
+
+	ips, _, err := resolver.CollectIPs(
+		map[string]*resolver.NameserverResponse{
+			nsExample1: {
+				Records:     map[string][]string{"A": {"192.0.2.1"}},
+				FailedTypes: []string{"AAAA"},
+				Status:      resolver.StatusOK,
+			},
+		},
+	)
+	require.ErrorIs(t, err, resolver.ErrNoNameserverAnswered)
+	assert.Empty(t, ips)
+}
+
+const (
+	// exampleCom is the zone most cases of TestUsableReply and
+	// TestNSSetFrom are about, and wwwExampleCom a name in it.
+	exampleCom    = "example.com."
+	wwwExampleCom = "www.example.com."
+
+	// exampleNS is the server the NS records nsRecord builds name.
+	exampleNS = "ns1.example.net."
+)
+
+// nsRecord builds an NS record that names a server of zone.
+func nsRecord(zone string) *dns.NS {
+	return &dns.NS{
+		Hdr: dns.RR_Header{
+			Name: zone, Rrtype: dns.TypeNS, Class: dns.ClassINET,
+		},
+		Ns: exampleNS,
+	}
+}
+
+// referralTo builds a reply that refers the query to the servers of
+// zone.
+func referralTo(zone string) *dns.Msg {
+	msg := new(dns.Msg)
+	msg.Ns = []dns.RR{nsRecord(zone)}
+
+	return msg
+}
+
+// TestUsableReply checks which replies from one of a zone's servers are
+// used. A reply that is not usable moves the query on to the zone's
+// next server.
+func TestUsableReply(t *testing.T) {
+	t.Parallel()
+
+	servfail := new(dns.Msg)
+	servfail.Rcode = dns.RcodeServerFailure
+
+	answer := new(dns.Msg)
+	answer.Authoritative = true
+	answer.Answer = []dns.RR{nsRecord(exampleCom)}
+
+	nxdomain := new(dns.Msg)
+	nxdomain.Authoritative = true
+	nxdomain.Rcode = dns.RcodeNameError
+
+	tests := []struct {
+		name  string
+		resp  *dns.Msg
+		zone  string
+		query string
+		want  bool
+	}{
+		{
+			name: "SERVFAIL", resp: servfail,
+			zone: exampleCom, query: exampleCom, want: false,
+		},
+		{
+			name: "answer", resp: answer,
+			zone: exampleCom, query: exampleCom, want: true,
+		},
+		{
+			name: "NXDOMAIN", resp: nxdomain,
+			zone: ".", query: exampleCom, want: true,
+		},
+		{
+			name: "root refers to com", resp: referralTo("com."),
+			zone: ".", query: exampleCom, want: true,
+		},
+		{
+			name: "com refers to example.com", resp: referralTo(exampleCom),
+			zone: "com.", query: wwwExampleCom, want: true,
+		},
+		{
+			name: "referral back to the zone", resp: referralTo(exampleCom),
+			zone: exampleCom, query: exampleCom, want: false,
+		},
+		{
+			name: "referral up to the root", resp: referralTo("."),
+			zone: exampleCom, query: exampleCom, want: false,
+		},
+		{
+			name: "referral sideways", resp: referralTo("net."),
+			zone: ".", query: exampleCom, want: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			assert.Equal(t, tt.want,
+				resolver.UsableReply(tt.resp, tt.zone, tt.query),
+			)
+		})
+	}
+}
+
+// TestNSSetFrom checks which NS set a reply gives for a domain; a set
+// that is not empty ends the walk. The referral to example.com that
+// com's servers all send alike gives its delegation, so the set is the
+// same whichever of them answered, and example.com's own servers, which
+// can disagree, are not asked.
+func TestNSSetFrom(t *testing.T) {
+	t.Parallel()
+
+	answer := new(dns.Msg)
+	answer.Authoritative = true
+	answer.Answer = []dns.RR{nsRecord(exampleCom)}
+
+	tests := []struct {
+		name   string
+		resp   *dns.Msg
+		domain string
+		want   []string
+	}{
+		{
+			name: "com refers to example.com", resp: referralTo(exampleCom),
+			domain: exampleCom, want: []string{exampleNS},
+		},
+		{
+			name: "com refers on, for www.example.com",
+			resp: referralTo(exampleCom), domain: wwwExampleCom,
+			want: nil,
+		},
+		{
+			name: "answer from a server that holds example.com",
+			resp: answer, domain: exampleCom,
+			want: []string{exampleNS},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			assert.ElementsMatch(t, tt.want,
+				resolver.NSSetFrom(tt.resp, tt.domain),
+			)
+		})
+	}
+}
+
 func TestExtractRecordValue_LetterCase(t *testing.T) {
 	t.Parallel()
 
@@ -60,3 +256,62 @@ func TestExtractRecordValue_LetterCase(t *testing.T) {
 		})
 	}
 }
+
+// TestCollectAnswerRecords_CNAMEOnce collects the answers a nameserver
+// gives for a name with a CNAME, one for each record type a check asks
+// for. Each answer holds the CNAME, which must be stored once.
+func TestCollectAnswerRecords_CNAMEOnce(t *testing.T) {
+	t.Parallel()
+
+	cname := &dns.CNAME{
+		Hdr: dns.RR_Header{
+			Name: "git.eeqj.de.", Rrtype: dns.TypeCNAME, Class: dns.ClassINET,
+		},
+		Target: "fsn1app1.datavi.be.",
+	}
+
+	resp := &resolver.NameserverResponse{Records: map[string][]string{}}
+
+	for _, qtype := range []uint16{
+		dns.TypeA, dns.TypeAAAA, dns.TypeCNAME, dns.TypeMX,
+		dns.TypeTXT, dns.TypeSRV, dns.TypeCAA, dns.TypeNS,
+	} {
+		msg := new(dns.Msg)
+		msg.SetQuestion("git.eeqj.de.", qtype)
+		msg.Answer = []dns.RR{cname}
+
+		resolver.CollectAnswerRecords(msg, resp)
+	}
+
+	assert.Equal(t,
+		map[string][]string{"CNAME": {"fsn1app1.datavi.be."}},
+		resp.Records,
+	)
+}
+
+// TestShuffled shuffles the root servers with many seeds. Every order
+// must hold each root server once, so each is tried before a
+// resolution fails; each root server must come first for some seed, so
+// no one root server gets every first query; and the list passed in
+// must be left as it was.
+func TestShuffled(t *testing.T) {
+	t.Parallel()
+
+	const seeds = 1000
+
+	roots := resolver.RootServerList()
+	before := slices.Clone(roots)
+	first := make(map[string]bool)
+
+	for seed := range uint64(seeds) {
+		rng := rand.New(rand.NewPCG(seed, 0)) //nolint:gosec // seeded on purpose
+		order := resolver.Shuffled(roots, rng.Shuffle)
+
+		assert.ElementsMatch(t, roots, order)
+
+		first[order[0]] = true
+	}
+
+	assert.Len(t, first, len(roots))
+	assert.Equal(t, before, roots)
+}

internal/resolver/livedns_test.go

@@ -187,8 +187,8 @@ func liveFindAuthoritative(
 	return out
 }
 
-// liveLookupNS is liveFindAuthoritative through the LookupNS entry
+// liveLookupNS looks up the NS record set of domain, a domain that has
-// point, so that both entry points stay independently exercised.
+// one, retrying until the delegation chain can be walked.
 func liveLookupNS(
 	t *testing.T,
 	r *resolver.Resolver,
@@ -226,11 +226,17 @@ func liveLookupNS(
 // liveQueryNameserver queries one nameserver, retrying while that
 // nameserver fails to answer. NXDOMAIN and NODATA are answers and
 // are returned to the caller to assert on.
+//
+// QueryNameserver sends one query per record type, so one lost query
+// leaves its type out of an answer that is otherwise fine. A test names
+// in types the record types it reads; an answer holding records of none
+// of them is retried too.
 func liveQueryNameserver(
 	t *testing.T,
 	r *resolver.Resolver,
 	nameserver string,
 	hostname string,
+	types ...string,
 ) *resolver.NameserverResponse {
 	t.Helper()
 
@@ -260,6 +266,18 @@ func liveQueryNameserver(
 				)
 			}
 
+			hasRecords := func(recordType string) bool {
+				return len(resp.Records[recordType]) > 0
+			}
+
+			if len(types) > 0 && !slices.ContainsFunc(types, hasRecords) {
+				return fmt.Errorf(
+					"%w: %s returned no %s records",
+					livednstest.ErrNoAnswer, nameserver,
+					strings.Join(types, " or "),
+				)
+			}
+
 			out = resp
 
 			return nil
@@ -383,3 +401,37 @@ func liveResolveIPsAllowingEmpty(
 
 	return out
 }
+
+// liveResolveNSIPs looks up the addresses of the nameservers named
+// names, retrying until there are at least atLeast of them: a name
+// whose lookup got no reply is left out of the result, not an error.
+func liveResolveNSIPs(
+	t *testing.T,
+	r *resolver.Resolver,
+	names []string,
+	atLeast int,
+) []string {
+	t.Helper()
+
+	var out []string
+
+	livednstest.Retry(
+		t,
+		"ResolveNSIPs("+strings.Join(names, ", ")+")",
+		func(ctx context.Context) error {
+			ips := r.ResolveNSIPs(ctx, names)
+			if len(ips) < atLeast {
+				return fmt.Errorf(
+					"%w: %d addresses, expected at least %d",
+					livednstest.ErrNoAnswer, len(ips), atLeast,
+				)
+			}
+
+			out = ips
+
+			return nil
+		},
+	)
+
+	return out
+}

internal/resolver/resolver.go

@@ -31,11 +31,15 @@ type Params struct {
 }
 
 // NameserverResponse holds one nameserver's response for a query.
+// FailedTypes lists the record types whose query got no usable reply,
+// and Records holds nothing for them: their records are not known. When
+// no record type got one, Status and Error say the nameserver failed.
 type NameserverResponse struct {
-	Nameserver string
+	Nameserver  string
-	Records    map[string][]string
+	Records     map[string][]string
-	Status     string
+	FailedTypes []string
-	Error      string
+	Status      string
+	Error       string
 }
 
 // Resolver performs iterative DNS resolution from root servers.

internal/resolver/resolver_test.go

@@ -1,7 +1,9 @@
 package resolver_test
 
 import (
+	"bytes"
 	"context"
+	"errors"
 	"fmt"
 	"log/slog"
 	"net"
@@ -11,6 +13,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/miekg/dns"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
@@ -22,6 +25,13 @@ import (
 // Test helpers
 // ----------------------------------------------------------------
 
+// nonexistentDomain is a .com domain that does not exist.
+const nonexistentDomain = "dnswatcher-test-does-not-exist.com"
+
+// noAnswerAddress is 192.0.2.1, a documentation address: nothing
+// answers there.
+const noAnswerAddress = "192.0.2.1"
+
 func newTestResolver(t *testing.T) *resolver.Resolver {
 	t.Helper()
 
@@ -79,9 +89,56 @@ func TestFindAuthoritativeNameservers_Subdomain(
 	t.Parallel()
 
 	r := newTestResolver(t)
-	nameservers := liveFindAuthoritative(t, r, "www.google.com")
+	fromHost := liveFindAuthoritative(t, r, "www.google.com")
+	fromZone := liveFindAuthoritative(t, r, "google.com")
 
-	assert.NotEmpty(t, nameservers)
+	assert.Equal(t, fromZone, fromHost)
+}
+
+// TestFindAuthoritativeNameservers_DelegatedSubdomain looks up the
+// nameservers of www.cs.cmu.edu, a name in cs.cmu.edu, a zone that
+// cmu.edu delegates to other servers. The servers of cs.cmu.edu answer
+// that the name has no delegation of its own, so it gets their names,
+// not those of the cmu.edu servers. Every referral on the way gives the
+// nameservers' addresses, so the walk sends few queries.
+func TestFindAuthoritativeNameservers_DelegatedSubdomain(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	fromHost := liveFindAuthoritative(t, r, "www.cs.cmu.edu")
+	fromZone := liveLookupNS(t, r, "cs.cmu.edu")
+	fromParent := liveLookupNS(t, r, "cmu.edu")
+
+	assert.Equal(t, fromZone, fromHost)
+	assert.NotEqual(t, fromParent, fromHost)
+}
+
+// TestFindAuthoritativeNameservers_NoAnswer starts each walk for
+// www.google.com at 192.0.2.1, a documentation address where nothing
+// answers. A walk that got no answer does not say that the name has no
+// delegation of its own, so the lookup returns that walk's error, about
+// www.google.com, and tries no parent name: trying google.com and com
+// would end in ErrNoNameservers, or in the error of a walk for one of
+// them. The servers that did not answer are those the walk started at,
+// which no referral named, so the error is no NoAnswerError, as when
+// the host running dnswatcher has lost its network.
+func TestFindAuthoritativeNameservers_NoAnswer(t *testing.T) {
+	t.Parallel()
+
+	r := resolver.NewWithQueryTimeout(slog.Default(), 100*time.Millisecond)
+
+	nameservers, err := r.FindAuthoritativeNameserversFrom(
+		t.Context(), "www.google.com", []string{noAnswerAddress},
+	)
+	require.Error(t, err)
+	require.NotErrorIs(t, err, resolver.ErrNoNameservers)
+	assert.Contains(t, err.Error(), "query www.google.com. @"+noAnswerAddress)
+	assert.Empty(t, nameservers)
+
+	var noAnswer *resolver.NoAnswerError
+	assert.NotErrorAs(t, err, &noAnswer)
 }
 
 func TestFindAuthoritativeNameservers_ReturnsSorted(
@@ -138,6 +195,134 @@ func TestFindAuthoritativeNameservers_CloudflareDomain(
 	}
 }
 
+// TestResolveNSIPs_EveryNameserver looks up the addresses of two of
+// google.com's nameservers together, as the walk does when a referral
+// names a zone's nameservers without their addresses, and compares them
+// with each looked up alone. Together they must give the addresses of
+// both, not only of the first that resolves, so that when one gives no
+// usable reply the walk goes on to the other.
+func TestResolveNSIPs_EveryNameserver(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	names := []string{"ns3.google.com.", "ns4.google.com."}
+	want := make([]string, 0, len(names))
+
+	for _, name := range names {
+		want = append(want, liveResolveNSIPs(t, r, []string{name}, 1)...)
+	}
+
+	got := liveResolveNSIPs(t, r, names, len(want))
+
+	assert.ElementsMatch(t, want, got)
+}
+
+// TestResolveNSIPs_ZoneDelegatedWithoutAddresses looks up the address
+// of a.ntpns.org, a nameserver of pool.ntp.org. The org servers delegate
+// ntpns.org to nameservers in other zones and give none of their
+// addresses, so those are looked up on the way.
+func TestResolveNSIPs_ZoneDelegatedWithoutAddresses(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ips := liveResolveNSIPs(t, r, []string{"a.ntpns.org."}, 1)
+
+	for _, ip := range ips {
+		assert.NotNil(t, net.ParseIP(ip), "should be valid IP: %s", ip)
+	}
+}
+
+// TestQueryZone_GivenAddressesFail asks the servers of ntp.org about
+// pool.ntp.org, as the walk to a name under ntp.org does after the org
+// servers' referral. That referral names four nameservers and gives an
+// address for ns1.everett.org alone; here the given address is
+// 192.0.2.1, where nothing answers, so the other three must be looked
+// up and asked.
+func TestQueryZone_GivenAddressesFail(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+
+	var resp *dns.Msg
+
+	livednstest.Retry(
+		t,
+		"QueryZone(192.0.2.1 and three ntp.org nameservers, pool.ntp.org)",
+		func(ctx context.Context) error {
+			var err error
+
+			resp, err = r.QueryZone(
+				ctx, []string{"192.0.2.1"},
+				[]string{"anyns.pch.net.", "dns1.udel.edu.", "dns2.udel.edu."},
+				"ntp.org.", "pool.ntp.org.", dns.TypeNS, 0,
+			)
+
+			return err
+		},
+	)
+
+	assert.NotEmpty(t, resolver.NSSetFrom(resp, "pool.ntp.org."))
+}
+
+// TestQueryZone_LookupDepth asks the servers of g.ntpns.org, a
+// nameserver of pool.ntp.org, for its address, as looking that address
+// up does when anyns.pch.net, one of the servers of ntpns.org, gives the
+// referral to g.ntpns.org without addresses. Their addresses are looked
+// up (here only a.ntpns.org's), and that needs a bitnames.com
+// nameserver's address, as the org servers delegate ntpns.org without
+// addresses. From depth 1, where looking up g.ntpns.org's address
+// starts, that makes three lookups and the address is found. From one
+// below maxLookupDepth, the bitnames.com lookup would be past the limit,
+// so nothing can be asked, and the error says the limit is why.
+func TestQueryZone_LookupDepth(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	withoutAddresses := []string{"a.ntpns.org."}
+
+	var resp *dns.Msg
+
+	livednstest.Retry(
+		t,
+		"QueryZone(a.ntpns.org without its address, g.ntpns.org)",
+		func(ctx context.Context) error {
+			var err error
+
+			resp, err = r.QueryZone(
+				ctx, nil, withoutAddresses, "g.ntpns.org.", "g.ntpns.org.",
+				dns.TypeA, 1,
+			)
+
+			return err
+		},
+	)
+
+	assert.NotEmpty(t, resp.Answer)
+
+	var limitErr error
+
+	// Any other error is live DNS not answering, and is retried.
+	livednstest.Retry(
+		t,
+		"QueryZone(a.ntpns.org without its address, g.ntpns.org, "+
+			"one below the limit)",
+		func(ctx context.Context) error {
+			_, limitErr = r.QueryZone(
+				ctx, nil, withoutAddresses, "g.ntpns.org.", "g.ntpns.org.",
+				dns.TypeA, resolver.MaxLookupDepth-1,
+			)
+			if limitErr == nil ||
+				errors.Is(limitErr, resolver.ErrLookupDepthExceeded) {
+				return nil
+			}
+
+			return limitErr
+		},
+	)
+
+	require.ErrorIs(t, limitErr, resolver.ErrLookupDepthExceeded)
+}
+
 // ----------------------------------------------------------------
 // QueryNameserver tests
 // ----------------------------------------------------------------
@@ -147,7 +332,7 @@ func TestQueryNameserver_BasicA(t *testing.T) {
 
 	r := newTestResolver(t)
 	ns := findOneNSForDomain(t, r, "google.com")
-	resp := liveQueryNameserver(t, r, ns, "www.google.com")
+	resp := liveQueryNameserver(t, r, ns, "www.google.com", "A", "CNAME")
 
 	require.NotNil(t, resp)
 
@@ -161,12 +346,26 @@ func TestQueryNameserver_BasicA(t *testing.T) {
 	)
 }
 
+// TestQueryNameserver_ZoneDelegatedWithoutAddresses asks a.ntpns.org, a
+// nameserver of pool.ntp.org, about pool.ntp.org, as the watcher does.
+// The org servers delegate ntpns.org without the addresses of its
+// nameservers, so finding a.ntpns.org's address needs a lookup inside
+// the one QueryNameserver starts.
+func TestQueryNameserver_ZoneDelegatedWithoutAddresses(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	resp := liveQueryNameserver(t, r, "a.ntpns.org.", "pool.ntp.org", "A")
+
+	assert.Equal(t, resolver.StatusOK, resp.Status)
+}
+
 func TestQueryNameserver_AAAA(t *testing.T) {
 	t.Parallel()
 
 	r := newTestResolver(t)
 	ns := findOneNSForDomain(t, r, "cloudflare.com")
-	resp := liveQueryNameserver(t, r, ns, "cloudflare.com")
+	resp := liveQueryNameserver(t, r, ns, "cloudflare.com", "AAAA")
 
 	aaaaRecords := resp.Records["AAAA"]
 	require.NotEmpty(t, aaaaRecords,
@@ -186,7 +385,7 @@ func TestQueryNameserver_MX(t *testing.T) {
 
 	r := newTestResolver(t)
 	ns := findOneNSForDomain(t, r, "google.com")
-	resp := liveQueryNameserver(t, r, ns, "google.com")
+	resp := liveQueryNameserver(t, r, ns, "google.com", "MX")
 
 	mxRecords := resp.Records["MX"]
 	require.NotEmpty(t, mxRecords,
@@ -199,7 +398,7 @@ func TestQueryNameserver_TXT(t *testing.T) {
 
 	r := newTestResolver(t)
 	ns := findOneNSForDomain(t, r, "google.com")
-	resp := liveQueryNameserver(t, r, ns, "google.com")
+	resp := liveQueryNameserver(t, r, ns, "google.com", "TXT")
 
 	txtRecords := resp.Records["TXT"]
 	require.NotEmpty(t, txtRecords,
@@ -221,6 +420,30 @@ func TestQueryNameserver_TXT(t *testing.T) {
 	)
 }
 
+// TestQueryNameserver_TruncatedReplyWhoseTCPRetryFails asks a google.com
+// nameserver about google.com with a resolver whose retries over TCP
+// fail. google.com's TXT records do not fit in a reply over UDP, so TXT
+// is reported as failed, holding none of the records that fit, and
+// logged with the reason, while the nameserver, which answered the other
+// types, is ok.
+func TestQueryNameserver_TruncatedReplyWhoseTCPRetryFails(t *testing.T) {
+	t.Parallel()
+
+	ns := findOneNSForDomain(t, newTestResolver(t), "google.com")
+
+	var logs bytes.Buffer
+
+	r := resolver.NewWithFailingTCP(slog.New(slog.NewTextHandler(&logs, nil)))
+	resp := liveQueryNameserver(t, r, ns, "google.com")
+
+	assert.Equal(t, resolver.StatusOK, resp.Status)
+	assert.Contains(t, resp.FailedTypes, "TXT")
+	assert.NotContains(t, resp.Records, "TXT")
+	assert.Contains(t, logs.String(),
+		"hostname=google.com. nameserver="+ns+" type=TXT error=",
+	)
+}
+
 func TestQueryNameserver_NXDomain(t *testing.T) {
 	t.Parallel()
 
@@ -272,6 +495,184 @@ func TestQueryNameserver_Refused(t *testing.T) {
 	assert.Equal(t, "server returned REFUSED", resp.Error)
 }
 
+// TestQueryServers_RecursiveResolverRefused passes a public recursive
+// resolver to QueryServers as the server of google.com. These resolvers
+// refuse a query that does not ask for recursion and answer one that
+// does. The resolver never asks for recursion, so the query must be
+// reported as refused, never answered. Each resolver is run by a
+// different operator, and they are asked in turn until one replies, so
+// one operator not answering does not fail the test.
+func TestQueryServers_RecursiveResolverRefused(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	resolvers := []string{
+		"64.6.64.6", "185.222.222.222", "4.2.2.1", "9.9.9.9",
+	}
+
+	var err error
+
+	livednstest.Retry(
+		t,
+		"QueryServers(public recursive resolvers, google.com)",
+		func(ctx context.Context) error {
+			for _, ip := range resolvers {
+				_, err = r.QueryServers(
+					ctx, []string{ip}, "google.com.", "google.com.",
+					dns.TypeA,
+				)
+
+				// A refusal or an answer is a reply; anything else may
+				// be no reply at all, so the next resolver is asked.
+				if err == nil || errors.Is(err, resolver.ErrRefused) {
+					return nil
+				}
+			}
+
+			return fmt.Errorf("%w: %w", livednstest.ErrNoAnswer, err)
+		},
+	)
+
+	require.ErrorIs(t, err, resolver.ErrRefused)
+}
+
+// googleNameserverIPv4s returns the IPv4 addresses of google.com's
+// nameservers, the only addresses the resolver asks servers at.
+func googleNameserverIPv4s(t *testing.T, r *resolver.Resolver) []string {
+	t.Helper()
+
+	names := liveFindAuthoritative(t, r, "google.com")
+
+	return liveResolveNSIPs(t, r, names, len(names))
+}
+
+// TestQueryServers_EveryServerRefused asks all of google.com's
+// nameservers about cloudflare.com, a zone they do not serve, which
+// they all refuse. The error says every server refused; it is not
+// ErrIntercepted, which only the root servers refusing shows.
+func TestQueryServers_EveryServerRefused(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	servers := googleNameserverIPv4s(t, r)
+
+	var err error
+
+	livednstest.Retry(
+		t,
+		"QueryServers(google.com servers, cloudflare.com)",
+		func(ctx context.Context) error {
+			_, err = r.QueryServers(
+				ctx, servers, "google.com.", "cloudflare.com.",
+				dns.TypeNS,
+			)
+
+			// When not every server refused, one may have given no
+			// reply at all, so the attempt is tried again.
+			if err != nil &&
+				!strings.HasPrefix(err.Error(), "every server of") {
+				return fmt.Errorf(
+					"%w: %w", livednstest.ErrNoAnswer, err,
+				)
+			}
+
+			return nil
+		},
+	)
+
+	require.ErrorIs(t, err, resolver.ErrRefused)
+	require.NotErrorIs(t, err, resolver.ErrIntercepted)
+	require.EqualError(
+		t, err,
+		"every server of google.com. refused a query for "+
+			"cloudflare.com.: dns query refused",
+	)
+}
+
+// TestQueryServers_EveryRootServerRefused passes google.com's
+// nameservers to QueryServers as the servers of the root zone. They
+// refuse a query about cloudflare.com, as root servers would if
+// something on the network answered in their place, so the error is
+// ErrIntercepted.
+func TestQueryServers_EveryRootServerRefused(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	servers := googleNameserverIPv4s(t, r)
+
+	var err error
+
+	livednstest.Retry(
+		t,
+		"QueryServers(google.com servers as root servers, cloudflare.com)",
+		func(ctx context.Context) error {
+			_, err = r.QueryServers(
+				ctx, servers, ".", "cloudflare.com.", dns.TypeNS,
+			)
+
+			// When not every server refused, one may have given no
+			// reply at all, so the attempt is tried again. Both errors
+			// for every server refusing say "refused a query for".
+			if err != nil &&
+				!strings.Contains(err.Error(), "refused a query for") {
+				return fmt.Errorf(
+					"%w: %w", livednstest.ErrNoAnswer, err,
+				)
+			}
+
+			return nil
+		},
+	)
+
+	require.ErrorIs(t, err, resolver.ErrIntercepted)
+	require.EqualError(
+		t, err,
+		"every root server refused a query for cloudflare.com.: "+
+			"this network intercepts DNS queries",
+	)
+}
+
+// TestQueryServers_NotEveryRootServerRefused passes google.com's
+// nameservers and 192.0.2.1 to QueryServers as the servers of the root
+// zone. The google.com nameservers refuse a query about cloudflare.com,
+// but nothing answers at 192.0.2.1, a documentation address, so not
+// every server refused, wherever 192.0.2.1 falls in the random order:
+// the error is not ErrIntercepted and does not say every server refused.
+func TestQueryServers_NotEveryRootServerRefused(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	servers := googleNameserverIPv4s(t, r)
+	servers = append(servers, "192.0.2.1")
+
+	var err error
+
+	livednstest.Retry(
+		t,
+		"QueryServers(google.com servers and 192.0.2.1, cloudflare.com)",
+		func(ctx context.Context) error {
+			_, err = r.QueryServers(
+				ctx, servers, ".", "cloudflare.com.", dns.TypeNS,
+			)
+
+			// An attempt that ran out of time may not have asked every
+			// server, so it is tried again.
+			if ctx.Err() != nil {
+				return fmt.Errorf(
+					"%w: %w", livednstest.ErrNoAnswer, err,
+				)
+			}
+
+			return nil
+		},
+	)
+
+	require.Error(t, err)
+	require.NotErrorIs(t, err, resolver.ErrIntercepted)
+	// Both errors for every server refusing say "refused a query for".
+	require.NotContains(t, err.Error(), "refused a query for")
+}
+
 func TestQueryNameserver_RecordsSorted(t *testing.T) {
 	t.Parallel()
 
@@ -350,37 +751,58 @@ func TestQueryAllNameservers_ReturnsAllNS(t *testing.T) {
 func TestQueryAllNameservers_AllReturnOK(t *testing.T) {
 	t.Parallel()
 
-	r := newTestResolver(t)
+	// The last two names are in zones other than their last two
-	results := liveQueryAllNameservers(t, r, "google.com")
+	// labels: google.co.uk, under the two-label suffix co.uk, and
+	// compute-1.amazonaws.com, which amazonaws.com delegates to other
+	// servers and which has a host name for each of its addresses.
+	// Servers above a name's zone only refer onward, which gives
+	// nodata, so ok shows the name was asked at its own zone's
+	// servers.
+	hostnames := []string{
+		"google.com",
+		"www.google.co.uk",
+		"ec2-3-80-0-1.compute-1.amazonaws.com",
+	}
 
-	// A quorum, not unanimity: one authoritative server being
+	for _, hostname := range hostnames {
-	// slow or rate-limiting us is a property of the live
+		t.Run(hostname, func(t *testing.T) {
-	// internet, not a resolver defect.
+			t.Parallel()
-	assert.GreaterOrEqual(
-		t,
-		countStatus(results, resolver.StatusOK),
-		liveQuorum(len(results)),
-		"a quorum of nameservers should answer OK: %s",
-		describeStatuses(results),
-	)
 
-	// Quorum tolerates SILENCE only. Every individual result must
+			r := newTestResolver(t)
-	// be either the expected answer or a non-answer: ok, timeout
+			results := liveQueryAllNameservers(t, r, hostname)
-	// or error, and nothing else. Stated as a closed allowlist so
+
-	// that a wrong answer no one thought to ban — nxdomain and
+			// A quorum, not unanimity: one authoritative server
-	// nodata today, any status added later — fails here rather
+			// being slow or rate-limiting us is a property of the
-	// than sliding through under the quorum.
+			// live internet, not a resolver defect.
-	assert.Empty(
+			assert.GreaterOrEqual(
-		t,
+				t,
-		unsanctionedStatuses(
+				countStatus(results, resolver.StatusOK),
-			results,
+				liveQuorum(len(results)),
-			resolver.StatusOK,
+				"a quorum of nameservers should answer OK: %s",
-			resolver.StatusTimeout,
+				describeStatuses(results),
-			resolver.StatusError,
+			)
-		),
+
-		"every nameserver must answer OK or not answer at all: %s",
+			// Quorum tolerates SILENCE only. Every individual
-		describeStatuses(results),
+			// result must be either the expected answer or a
-	)
+			// non-answer: ok, timeout or error, and nothing else.
+			// Stated as a closed allowlist so that a wrong answer
+			// no one thought to ban — nxdomain and nodata today,
+			// any status added later — fails here rather than
+			// sliding through under the quorum.
+			assert.Empty(
+				t,
+				unsanctionedStatuses(
+					results,
+					resolver.StatusOK,
+					resolver.StatusTimeout,
+					resolver.StatusError,
+				),
+				"every nameserver must answer OK or not answer "+
+					"at all: %s",
+				describeStatuses(results),
+			)
+		})
+	}
 }
 
 func TestQueryAllNameservers_NXDomainFromAllNS(
@@ -455,6 +877,167 @@ func TestLookupNS_MatchesFindAuthoritative(t *testing.T) {
 	assert.Equal(t, fromFind, fromLookup)
 }
 
+// TestLookupNS_ParentZoneDelegatedWithoutAddresses looks up the
+// nameservers of g.ntpns.org. The org servers delegate its parent zone,
+// ntpns.org, without the addresses of its nameservers, so the walk has
+// to look them up to ask them. If it did not, the walk for g.ntpns.org
+// would fail.
+func TestLookupNS_ParentZoneDelegatedWithoutAddresses(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	nameservers := liveLookupNS(t, r, "g.ntpns.org")
+
+	assert.Contains(t, nameservers, "a.ntpns.org.")
+}
+
+// TestLookupNS_DomainThatDoesNotExist looks up the nameservers of a .com
+// domain that does not exist. The .com servers answer NXDOMAIN, so the
+// error is ErrNXDomain, and the domain does not get their names.
+func TestLookupNS_DomainThatDoesNotExist(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+
+	var (
+		nameservers []string
+		err         error
+	)
+
+	livednstest.Retry(
+		t,
+		"LookupNS("+nonexistentDomain+")",
+		func(ctx context.Context) error {
+			nameservers, err = r.LookupNS(ctx, nonexistentDomain)
+			if errors.Is(err, resolver.ErrNXDomain) {
+				return nil
+			}
+
+			return err
+		},
+	)
+
+	require.ErrorIs(t, err, resolver.ErrNXDomain)
+	assert.Empty(t, nameservers)
+}
+
+// TestLookupNS_NoDelegationOfItsOwn looks up the nameservers of
+// www.google.com, a name in the google.com zone with no delegation of
+// its own, as a domain such as octocat.github.io is. The google.com
+// servers answer with no NS records for it: the set is empty, and it is
+// not ErrNXDomain.
+func TestLookupNS_NoDelegationOfItsOwn(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+
+	var nameservers []string
+
+	livednstest.Retry(
+		t,
+		"LookupNS(www.google.com)",
+		func(ctx context.Context) error {
+			var err error
+
+			nameservers, err = r.LookupNS(ctx, "www.google.com")
+
+			return err
+		},
+	)
+
+	assert.Empty(t, nameservers)
+}
+
+// TestFollowDelegation_NoAnswer starts the walk LookupNS uses, for
+// google.com, at 192.0.2.1, a documentation address where nothing
+// answers. A walk that got no answer is an error, not an empty set,
+// which the watcher would report as an NS Change with every nameserver
+// removed.
+func TestFollowDelegation_NoAnswer(t *testing.T) {
+	t.Parallel()
+
+	r := resolver.NewWithQueryTimeout(slog.Default(), 100*time.Millisecond)
+
+	nameservers, err := r.FollowDelegation(
+		t.Context(), "google.com.", ".", nil, []string{noAnswerAddress},
+	)
+	require.Error(t, err)
+	assert.Empty(t, nameservers)
+}
+
+// TestFollowDelegation_NoAnswerAfterReferral starts the walk for
+// www.example.net at the servers of example.net as a referral names
+// them, ns1.example.net and ns2.example.net, at 192.0.2.1, where nothing
+// answers. The error is a NoAnswerError naming them, which the watcher
+// compares with the nameservers it saved for the name.
+func TestFollowDelegation_NoAnswerAfterReferral(t *testing.T) {
+	t.Parallel()
+
+	r := resolver.NewWithQueryTimeout(slog.Default(), 100*time.Millisecond)
+	nameservers := []string{"ns1.example.net.", "ns2.example.net."}
+
+	_, err := r.FollowDelegation(
+		t.Context(), "www.example.net.", "example.net.", nameservers,
+		[]string{noAnswerAddress},
+	)
+
+	var noAnswer *resolver.NoAnswerError
+	require.ErrorAs(t, err, &noAnswer)
+	assert.Equal(t, nameservers, noAnswer.Nameservers)
+	assert.Contains(t, err.Error(), "query www.example.net. @"+noAnswerAddress)
+}
+
+// TestResolveNSIterative_NoDelegationOfItsOwn walks to the nameservers
+// of www.google.com as the fallback walk does. As in
+// TestLookupNS_NoDelegationOfItsOwn, the set is empty, with no error.
+func TestResolveNSIterative_NoDelegationOfItsOwn(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+
+	var nameservers []string
+
+	livednstest.Retry(
+		t,
+		"ResolveNSIterative(www.google.com)",
+		func(ctx context.Context) error {
+			var err error
+
+			nameservers, err = r.ResolveNSIterative(ctx, "www.google.com")
+
+			return err
+		},
+	)
+
+	assert.Empty(t, nameservers)
+}
+
+// TestResolveNSIterative_DomainThatDoesNotExist walks to the nameservers
+// of a .com domain that does not exist as the fallback walk does. As in
+// TestLookupNS_DomainThatDoesNotExist, the error is ErrNXDomain.
+func TestResolveNSIterative_DomainThatDoesNotExist(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+
+	var err error
+
+	livednstest.Retry(
+		t,
+		"ResolveNSIterative("+nonexistentDomain+")",
+		func(ctx context.Context) error {
+			_, err = r.ResolveNSIterative(ctx, nonexistentDomain)
+			if errors.Is(err, resolver.ErrNXDomain) {
+				return nil
+			}
+
+			return err
+		},
+	)
+
+	require.ErrorIs(t, err, resolver.ErrNXDomain)
+}
+
 // ----------------------------------------------------------------
 // ResolveIPAddresses tests
 // ----------------------------------------------------------------
@@ -518,6 +1101,34 @@ func TestResolveIPAddresses_CloudflareDomain(t *testing.T) {
 	assert.NotEmpty(t, ips)
 }
 
+// TestResolveIPAddresses_NameserverIPv4AndIPv6 looks up the addresses of
+// one of cloudflare.com's nameservers, as a domain check does for each
+// nameserver. That name has A and AAAA records, so both kinds of address
+// come back.
+func TestResolveIPAddresses_NameserverIPv4AndIPv6(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ns := findOneNSForDomain(t, r, "cloudflare.com")
+	ips := liveResolveIPs(t, r, ns)
+
+	var ipv4, ipv6 int
+
+	for _, ip := range ips {
+		parsed := net.ParseIP(ip)
+		require.NotNil(t, parsed, "should be valid IP: %s", ip)
+
+		if parsed.To4() != nil {
+			ipv4++
+		} else {
+			ipv6++
+		}
+	}
+
+	assert.Positive(t, ipv4, "no IPv4 address for %s: %v", ns, ips)
+	assert.Positive(t, ipv6, "no IPv6 address for %s: %v", ns, ips)
+}
+
 // ----------------------------------------------------------------
 // Context cancellation tests
 // ----------------------------------------------------------------
@@ -611,6 +1222,105 @@ func TestQueryNameserverIP_Timeout(t *testing.T) {
 	assert.NotEmpty(t, resp.Error)
 }
 
+// TestQueryNameserverIP_CancelledLogsNothing cancels the context while
+// a query to 192.0.2.1, where nothing answers, is waiting for a reply,
+// as shutdown does. The query was cut short, not failed, so nothing is
+// logged.
+func TestQueryNameserverIP_CancelledLogsNothing(t *testing.T) {
+	t.Parallel()
+
+	var logs bytes.Buffer
+
+	r := resolver.NewFromLogger(slog.New(slog.NewTextHandler(&logs, nil)))
+
+	ctx, cancel := context.WithCancel(context.Background())
+	t.Cleanup(cancel)
+	time.AfterFunc(100*time.Millisecond, cancel)
+
+	_, err := r.QueryNameserverIP(
+		ctx, "unreachable.test.", "192.0.2.1", "example.com",
+	)
+	require.NoError(t, err)
+
+	assert.Empty(t, logs.String())
+}
+
+// TestCollectIPs_NoNameserverAnswered takes the response of a
+// nameserver at 192.0.2.1, where nothing answers, as
+// TestQueryNameserverIP_Timeout does. Addresses collected from
+// nameservers that all failed to answer are an error, not none.
+func TestCollectIPs_NoNameserverAnswered(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+
+	// The deadline outlasts the first try, as in
+	// TestQueryNameserverIP_Timeout.
+	ctx, cancel := context.WithTimeout(
+		context.Background(), 3*time.Second,
+	)
+	t.Cleanup(cancel)
+
+	resp, err := r.QueryNameserverIP(
+		ctx, "unreachable.test.", "192.0.2.1",
+		"example.com",
+	)
+	require.NoError(t, err)
+
+	ips, _, err := resolver.CollectIPs(
+		map[string]*resolver.NameserverResponse{resp.Nameserver: resp},
+	)
+	require.ErrorIs(t, err, resolver.ErrNoNameserverAnswered)
+	assert.Empty(t, ips)
+}
+
+// TestCollectIPs_ReferralIsNoAnswer asks a root server about
+// example.com, which the root zone does not hold, so it only refers the
+// query to the com servers. That reply is no answer, as is a parent
+// zone's when every server of the name's own zone failed.
+func TestCollectIPs_ReferralIsNoAnswer(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+
+	var resp *resolver.NameserverResponse
+
+	livednstest.Retry(
+		t,
+		"QueryNameserverIP(a.root-servers.net, example.com)",
+		func(ctx context.Context) error {
+			var err error
+
+			resp, err = r.QueryNameserverIP(
+				ctx, "a.root-servers.net.", "198.41.0.4",
+				"example.com",
+			)
+			if err != nil {
+				return err
+			}
+
+			// A timeout or a network error is no reply at all.
+			if resp.Status == resolver.StatusTimeout ||
+				strings.HasPrefix(resp.Error, "network error") {
+				return fmt.Errorf(
+					"%w: %s", livednstest.ErrNoAnswer, resp.Error,
+				)
+			}
+
+			return nil
+		},
+	)
+
+	assert.Equal(t, resolver.StatusError, resp.Status)
+	assert.Equal(t, "server returned a referral", resp.Error)
+
+	ips, _, err := resolver.CollectIPs(
+		map[string]*resolver.NameserverResponse{resp.Nameserver: resp},
+	)
+	require.ErrorIs(t, err, resolver.ErrNoNameserverAnswered)
+	assert.Empty(t, ips)
+}
+
 func TestResolveIPAddresses_ContextCanceled(t *testing.T) {
 	t.Parallel()
 

internal/server/export_test.go

@@ -13,8 +13,8 @@ import (
 const RequestTimeout time.Duration = requestTimeout
 
 // SetListenPort overrides the port Run binds. A test uses it to hand
-// Run an unbindable port so ListenAndServe fails immediately and Run
+// Run an unbindable port, so that Run stores its http.Server and then
-// returns after storing its http.Server.
+// returns an error without listening.
 func SetListenPort(s *Server, port int) {
 	s.port = port
 }

internal/server/server.go

@@ -6,6 +6,7 @@ import (
 	"errors"
 	"fmt"
 	"log/slog"
+	"net"
 	"net/http"
 	"time"
 
@@ -112,7 +113,7 @@ func New(
 	}
 
 	lifecycle.Append(fx.Hook{
-		OnStart: func(_ context.Context) error {
+		OnStart: func(ctx context.Context) error {
 			srv.startupTime = time.Now()
 
 			err := srv.enableSentry()
@@ -120,9 +121,7 @@ func New(
 				return err
 			}
 
-			go srv.Run()
+			return srv.Run(ctx)
-
-			return nil
 		},
 		OnStop: func(ctx context.Context) error {
 			return srv.Shutdown(ctx)
@@ -149,8 +148,10 @@ func newHTTPServer(
 	}
 }
 
-// Run starts the HTTP server.
+// Run binds the listen port, then serves HTTP on it in a new goroutine
-func (s *Server) Run() {
+// and returns. A port that cannot be bound is returned as an error, so
+// that startup stops instead of running without the HTTP server.
+func (s *Server) Run(ctx context.Context) error {
 	s.SetupRoutes()
 
 	listenAddr := fmt.Sprintf(":%d", s.port)
@@ -158,10 +159,21 @@ func (s *Server) Run() {
 
 	s.log.Info("http server starting", "addr", listenAddr)
 
-	err := s.httpServer.ListenAndServe()
+	lc := &net.ListenConfig{}
-	if err != nil && !errors.Is(err, http.ErrServerClosed) {
+
-		s.log.Error("http server error", "error", err)
+	listener, err := lc.Listen(ctx, "tcp", listenAddr)
+	if err != nil {
+		return fmt.Errorf("starting http server: %w", err)
 	}
+
+	go func() {
+		err := s.httpServer.Serve(listener)
+		if err != nil && !errors.Is(err, http.ErrServerClosed) {
+			s.log.Error("http server error", "error", err)
+		}
+	}()
+
+	return nil
 }
 
 // Shutdown gracefully shuts down the server, then sends the error

internal/server/server_test.go

@@ -1,6 +1,8 @@
 package server_test
 
 import (
+	"net"
+	"strings"
 	"testing"
 
 	"github.com/spf13/viper"
@@ -58,15 +60,13 @@ func buildServer(t *testing.T) *server.Server {
 }
 
 // TestRunWiresSocketTimeouts pins that the http.Server the running
-// server actually serves — the one Run builds and hands to
+// server actually serves — the one Run builds and serves on the port
-// ListenAndServe — carries every socket-level timeout, plus the two
+// it binds — carries every socket-level timeout, plus the two
 // relationships the values must satisfy.
 //
-// Run is driven to completion with an unbindable port: it builds and
+// Run is given an unbindable port: it builds and stores s.httpServer,
-// stores s.httpServer, then ListenAndServe fails at once and Run
+// then the bind fails and Run returns the error without ever
-// returns without ever listening. The assertions run in the same
+// listening. Nothing here measures elapsed time.
-// goroutine after Run returns, so reading s.httpServer is free of any
-// data race. Nothing here measures elapsed time.
 //
 // ReadTimeout must be at least ReadHeaderTimeout. net/http reads the
 // headers under ReadHeaderTimeout, then sets the read deadline for the
@@ -84,7 +84,10 @@ func TestRunWiresSocketTimeouts(t *testing.T) {
 	srv := buildServer(t)
 	server.SetListenPort(srv, -1)
 
-	srv.Run()
+	err := srv.Run(t.Context())
+	if err == nil {
+		t.Fatal("Run bound port -1")
+	}
 
 	hs := server.HTTPServerOf(srv)
 	if hs == nil {
@@ -133,3 +136,38 @@ func TestRunWiresSocketTimeouts(t *testing.T) {
 		)
 	}
 }
+
+func TestPortInUseStopsStartup(t *testing.T) {
+	// Bound on every address, as Run binds, so that Run's bind fails.
+	lc := &net.ListenConfig{}
+
+	taken, err := lc.Listen(t.Context(), "tcp", ":0")
+	if err != nil {
+		t.Fatalf("binding a port for the test: %v", err)
+	}
+
+	defer func() { _ = taken.Close() }()
+
+	_, port, err := net.SplitHostPort(taken.Addr().String())
+	if err != nil {
+		t.Fatalf("reading the bound port: %v", err)
+	}
+
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "example.com")
+	t.Setenv("DNSWATCHER_DATA_DIR", t.TempDir())
+	t.Setenv("PORT", port)
+
+	app := newServerApp(fx.Invoke(func(*server.Server) {}))
+
+	err = app.Start(t.Context())
+	if err == nil {
+		_ = app.Stop(t.Context())
+
+		t.Fatal("startup succeeded on a port that is already bound")
+	}
+
+	if !strings.Contains(err.Error(), ":"+port) {
+		t.Errorf("startup error does not name port %s: %v", port, err)
+	}
+}

internal/state/state.go

@@ -4,10 +4,13 @@ package state
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"log/slog"
+	"maps"
 	"os"
 	"path/filepath"
+	"slices"
 	"sync"
 	"time"
 
@@ -35,22 +38,41 @@ type Params struct {
 }
 
 // DomainState holds the monitoring state for an apex domain.
+// NameserverAddresses holds the sorted addresses each nameserver's name
+// resolves to, by nameserver name. A state file written before it
+// existed loads with it nil. NXDomain is true when the domain's parent
+// zone's servers answered that it does not exist; it then has no
+// nameservers.
 type DomainState struct {
-	Nameservers []string  `json:"nameservers"`
+	Nameservers         []string            `json:"nameservers"`
-	LastChecked time.Time `json:"lastChecked"`
+	NameserverAddresses map[string][]string `json:"nameserverAddresses"`
+	NXDomain            bool                `json:"nxdomain,omitempty"`
+	LastChecked         time.Time           `json:"lastChecked"`
 }
 
 // NameserverRecordState holds one NS's response for a hostname.
+// FailedTypes lists the record types whose query to the nameserver
+// failed on this check: Records holds for them the records saved by the
+// previous check, which are kept. UnknownTypes lists those of them whose
+// records the previous check did not know either, as when the
+// nameserver was new or failing then: Records holds nothing for them.
 type NameserverRecordState struct {
-	Records     map[string][]string `json:"records"`
+	Records      map[string][]string `json:"records"`
-	Status      string              `json:"status"`
+	FailedTypes  []string            `json:"failedTypes,omitempty"`
-	Error       string              `json:"error,omitempty"`
+	UnknownTypes []string            `json:"unknownTypes,omitempty"`
-	LastChecked time.Time           `json:"lastChecked"`
+	Status       string              `json:"status"`
+	Error        string              `json:"error,omitempty"`
+	LastChecked  time.Time           `json:"lastChecked"`
 }
 
 // HostnameState holds per-nameserver monitoring state for a hostname.
+// CNAMEAddresses holds the sorted addresses at the end of the name's
+// CNAME chain, found when its nameservers answered with a CNAME and no
+// address; it is empty otherwise. It is nil when they are not known: a
+// state file written before it existed loads with it nil.
 type HostnameState struct {
 	RecordsByNameserver map[string]*NameserverRecordState `json:"recordsByNameserver"`
+	CNAMEAddresses      []string                          `json:"cnameAddresses"`
 	LastChecked         time.Time                         `json:"lastChecked"`
 }
 
@@ -112,6 +134,8 @@ type CertificateState struct {
 }
 
 // Snapshot is the complete monitoring state persisted to disk.
+// Hostnames also holds each apex domain's own records, under the
+// domain's name, which has an entry in Domains too.
 type Snapshot struct {
 	Version      int                          `json:"version"`
 	LastUpdated  time.Time                    `json:"lastUpdated"`
@@ -192,6 +216,37 @@ func (s *State) Load() error {
 		return fmt.Errorf("parsing state file: %w", err)
 	}
 
+	// A section the file leaves out, or holds as null, loads empty: the
+	// setters write into these maps, and writing into a nil map panics.
+	if snapshot.Domains == nil {
+		snapshot.Domains = make(map[string]*DomainState)
+	}
+
+	if snapshot.Hostnames == nil {
+		snapshot.Hostnames = make(map[string]*HostnameState)
+	}
+
+	if snapshot.Ports == nil {
+		snapshot.Ports = make(map[string]*PortState)
+	}
+
+	if snapshot.Certificates == nil {
+		snapshot.Certificates = make(map[string]*CertificateState)
+	}
+
+	// A state file saved before each record value was stored once can
+	// hold a hostname's CNAME once for every record type asked for.
+	// Each value is kept once, so the first check does not see a
+	// record change.
+	for _, hs := range snapshot.Hostnames {
+		for _, ns := range hs.RecordsByNameserver {
+			for recordType, values := range ns.Records {
+				slices.Sort(values)
+				ns.Records[recordType] = slices.Compact(values)
+			}
+		}
+	}
+
 	s.snapshot = &snapshot
 	s.log.Info("loaded state from disk", "path", path)
 
@@ -217,10 +272,20 @@ func (s *State) Save() error {
 		return fmt.Errorf("creating data directory: %w", err)
 	}
 
-	// Atomic write: write to temp file, then rename
+	// Atomic write: write to temp file, then rename. The temp file is
+	// synced before the rename and the directory after it, or a crash
+	// can leave the renamed state file empty.
 	tmpPath := path + ".tmp"
 
-	err = os.WriteFile(tmpPath, data, filePermissions)
+	//nolint:gosec // path is from trusted config
+	tmpFile, err := os.OpenFile(
+		tmpPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, filePermissions,
+	)
+	if err == nil {
+		_, err = tmpFile.Write(data)
+		err = errors.Join(err, tmpFile.Sync(), tmpFile.Close())
+	}
+
 	if err != nil {
 		return fmt.Errorf("writing temp state file: %w", err)
 	}
@@ -230,17 +295,35 @@ func (s *State) Save() error {
 		return fmt.Errorf("renaming state file: %w", err)
 	}
 
+	dir, err := os.Open(filepath.Dir(path))
+	if err == nil {
+		err = errors.Join(dir.Sync(), dir.Close())
+	}
+
+	if err != nil {
+		return fmt.Errorf("syncing data directory: %w", err)
+	}
+
 	s.log.Debug("state saved to disk", "path", path)
 
 	return nil
 }
 
-// GetSnapshot returns a copy of the current snapshot.
+// GetSnapshot returns a copy of the current snapshot, with copies of
+// its maps, so that a caller can range over them while the state is
+// written. The entries in the maps are not copied: an entry saved in the
+// state must be replaced, never changed in place.
 func (s *State) GetSnapshot() Snapshot {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
 
-	return *s.snapshot
+	snap := *s.snapshot
+	snap.Domains = maps.Clone(snap.Domains)
+	snap.Hostnames = maps.Clone(snap.Hostnames)
+	snap.Ports = maps.Clone(snap.Ports)
+	snap.Certificates = maps.Clone(snap.Certificates)
+
+	return snap
 }
 
 // SetDomainState updates the state for a domain.
@@ -266,6 +349,27 @@ func (s *State) GetDomainState(
 	return ds, ok
 }
 
+// DeleteDomainState removes a domain state entry.
+func (s *State) DeleteDomainState(domain string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	delete(s.snapshot.Domains, domain)
+}
+
+// GetAllDomainNames returns the names of all domain state entries.
+func (s *State) GetAllDomainNames() []string {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	names := make([]string, 0, len(s.snapshot.Domains))
+	for name := range s.snapshot.Domains {
+		names = append(names, name)
+	}
+
+	return names
+}
+
 // SetHostnameState updates the state for a hostname.
 func (s *State) SetHostnameState(
 	hostname string,
@@ -289,6 +393,28 @@ func (s *State) GetHostnameState(
 	return hs, ok
 }
 
+// DeleteHostnameState removes a hostname state entry.
+func (s *State) DeleteHostnameState(hostname string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	delete(s.snapshot.Hostnames, hostname)
+}
+
+// GetAllHostnames returns the names of all hostname state entries,
+// which include each apex domain's own records.
+func (s *State) GetAllHostnames() []string {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	names := make([]string, 0, len(s.snapshot.Hostnames))
+	for name := range s.snapshot.Hostnames {
+		names = append(names, name)
+	}
+
+	return names
+}
+
 // SetPortState updates the state for a port.
 func (s *State) SetPortState(key string, ps *PortState) {
 	s.mu.Lock()
@@ -351,6 +477,27 @@ func (s *State) GetCertificateState(
 	return cs, ok
 }
 
+// DeleteCertificateState removes a certificate state entry.
+func (s *State) DeleteCertificateState(key string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	delete(s.snapshot.Certificates, key)
+}
+
+// GetAllCertificateKeys returns all certificate state keys.
+func (s *State) GetAllCertificateKeys() []string {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	keys := make([]string, 0, len(s.snapshot.Certificates))
+	for k := range s.snapshot.Certificates {
+		keys = append(keys, k)
+	}
+
+	return keys
+}
+
 // checkDataDirWritable creates the data directory if needed, then writes
 // and removes the temp file that Save uses. It runs at startup so that an
 // unwritable directory stops the process, instead of the process running

internal/state/state_test.go

@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"os"
 	"path/filepath"
+	"reflect"
 	"strings"
 	"sync"
 	"testing"
@@ -37,6 +38,10 @@ func populateState(t *testing.T, s *state.State) {
 
 	s.SetDomainState("example.com", &state.DomainState{
 		Nameservers: []string{testNS1, testNS2},
+		NameserverAddresses: map[string][]string{
+			testNS1: {testIP, testIPv4},
+			testNS2: {testIPv4},
+		},
 		LastChecked: now,
 	})
 
@@ -123,6 +128,261 @@ func TestSaveLoadRoundTrip_Domains(t *testing.T) {
 	if len(dom.Nameservers) != 2 {
 		t.Errorf("expected 2 nameservers, got %d", len(dom.Nameservers))
 	}
+
+	want := map[string][]string{
+		testNS1: {testIP, testIPv4},
+		testNS2: {testIPv4},
+	}
+	if !reflect.DeepEqual(dom.NameserverAddresses, want) {
+		t.Errorf(
+			"nameserver addresses: got %v, want %v",
+			dom.NameserverAddresses, want,
+		)
+	}
+}
+
+// TestLoadStateFromBeforeNameserverAddresses loads a state file written
+// before nameserver addresses were saved.
+func TestLoadStateFromBeforeNameserverAddresses(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+
+	data := []byte(`{
+		"version": 1,
+		"lastUpdated": "2026-02-19T12:00:00Z",
+		"domains": {
+			"example.com": {
+				"nameservers": ["ns1.example.com.", "ns2.example.com."],
+				"lastChecked": "2026-02-19T12:00:00Z"
+			}
+		}
+	}`)
+
+	err := os.WriteFile(filepath.Join(dir, "state.json"), data, 0o600)
+	if err != nil {
+		t.Fatalf("writing state file: %v", err)
+	}
+
+	s := state.NewForTestWithDataDir(dir)
+
+	err = s.Load()
+	if err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+
+	dom, ok := s.GetDomainState("example.com")
+	if !ok {
+		t.Fatal("missing domain example.com")
+	}
+
+	if !reflect.DeepEqual(dom.Nameservers, []string{testNS1, testNS2}) {
+		t.Errorf("nameservers: got %v", dom.Nameservers)
+	}
+
+	if dom.NameserverAddresses != nil {
+		t.Errorf(
+			"nameserver addresses: got %v, want none",
+			dom.NameserverAddresses,
+		)
+	}
+}
+
+// TestSaveLoadRoundTrip_CNAMEAddresses checks that no addresses at the
+// end of a hostname's CNAME chain load as an empty list, and addresses
+// that are not known load as nil: the watcher tells the two apart.
+func TestSaveLoadRoundTrip_CNAMEAddresses(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	s := state.NewForTestWithDataDir(dir)
+
+	want := map[string][]string{
+		"cname.example.com":     {testIP},
+		"none.example.com":      {},
+		"not-known.example.com": nil,
+	}
+
+	for name, addresses := range want {
+		s.SetHostnameState(name, &state.HostnameState{
+			CNAMEAddresses: addresses,
+		})
+	}
+
+	err := s.Save()
+	if err != nil {
+		t.Fatalf("Save() error: %v", err)
+	}
+
+	loaded := state.NewForTestWithDataDir(dir)
+
+	err = loaded.Load()
+	if err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+
+	for name, addresses := range want {
+		hs, ok := loaded.GetHostnameState(name)
+		if !ok {
+			t.Fatalf("missing hostname %s", name)
+		}
+
+		if !reflect.DeepEqual(hs.CNAMEAddresses, addresses) {
+			t.Errorf(
+				"%s: loaded %#v, want %#v",
+				name, hs.CNAMEAddresses, addresses,
+			)
+		}
+	}
+}
+
+// TestSaveLoadRoundTrip_FailedTypes checks that a nameserver's
+// failedTypes and unknownTypes survive a save and load. Without
+// unknownTypes, a type whose records were not known would load as one
+// with no records.
+func TestSaveLoadRoundTrip_FailedTypes(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	s := state.NewForTestWithDataDir(dir)
+
+	failed := []string{"TXT", "CAA"}
+	unknown := []string{"CAA"}
+
+	s.SetHostnameState(testHostname, &state.HostnameState{
+		RecordsByNameserver: map[string]*state.NameserverRecordState{
+			testNS1: {
+				Records:      map[string][]string{"TXT": {"v=spf1 -all"}},
+				FailedTypes:  failed,
+				UnknownTypes: unknown,
+				Status:       "ok",
+			},
+		},
+	})
+
+	err := s.Save()
+	if err != nil {
+		t.Fatalf("Save() error: %v", err)
+	}
+
+	loaded := state.NewForTestWithDataDir(dir)
+
+	err = loaded.Load()
+	if err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+
+	hs, ok := loaded.GetHostnameState(testHostname)
+	if !ok {
+		t.Fatal("missing hostname " + testHostname)
+	}
+
+	ns1 := hs.RecordsByNameserver[testNS1]
+	if ns1 == nil {
+		t.Fatal("missing nameserver " + testNS1)
+	}
+
+	if !reflect.DeepEqual(ns1.FailedTypes, failed) {
+		t.Errorf("failedTypes: got %#v", ns1.FailedTypes)
+	}
+
+	if !reflect.DeepEqual(ns1.UnknownTypes, unknown) {
+		t.Errorf("unknownTypes: got %#v", ns1.UnknownTypes)
+	}
+}
+
+// TestLoadStateFromBeforeCNAMEAddresses loads a state file written
+// before the addresses at the end of a hostname's CNAME chain were
+// saved. They load as not known (nil), not as none.
+func TestLoadStateFromBeforeCNAMEAddresses(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+
+	data := []byte(`{
+		"version": 1,
+		"lastUpdated": "2026-02-19T12:00:00Z",
+		"hostnames": {
+			"www.example.com": {
+				"recordsByNameserver": {},
+				"lastChecked": "2026-02-19T12:00:00Z"
+			}
+		}
+	}`)
+
+	err := os.WriteFile(filepath.Join(dir, "state.json"), data, 0o600)
+	if err != nil {
+		t.Fatalf("writing state file: %v", err)
+	}
+
+	s := state.NewForTestWithDataDir(dir)
+
+	err = s.Load()
+	if err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+
+	hs, ok := s.GetHostnameState(testHostname)
+	if !ok {
+		t.Fatal("missing hostname " + testHostname)
+	}
+
+	if hs.CNAMEAddresses != nil {
+		t.Errorf("CNAME addresses: got %#v, want nil", hs.CNAMEAddresses)
+	}
+}
+
+// TestLoadStateWithRepeatedValues loads a state file saved when a
+// hostname's CNAME was stored once for every record type asked for.
+// Each value must load once, and every different value must load.
+func TestLoadStateWithRepeatedValues(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+
+	data := []byte(`{
+		"version": 1,
+		"hostnames": {
+			"www.example.com": {
+				"recordsByNameserver": {
+					"ns1.example.com.": {
+						"records": {
+							"A": ["192.0.2.2", "192.0.2.1", "192.0.2.2", "192.0.2.1"],
+							"CNAME": ["a.example.net.", "a.example.net.", "a.example.net."]
+						},
+						"status": "ok"
+					}
+				}
+			}
+		}
+	}`)
+
+	err := os.WriteFile(filepath.Join(dir, "state.json"), data, 0o600)
+	if err != nil {
+		t.Fatalf("writing state file: %v", err)
+	}
+
+	s := state.NewForTestWithDataDir(dir)
+
+	err = s.Load()
+	if err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+
+	hs, ok := s.GetHostnameState(testHostname)
+	if !ok {
+		t.Fatal("missing hostname " + testHostname)
+	}
+
+	want := map[string][]string{
+		"A":     {"192.0.2.1", "192.0.2.2"},
+		"CNAME": {"a.example.net."},
+	}
+
+	got := hs.RecordsByNameserver[testNS1].Records
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("records: got %v, want %v", got, want)
+	}
 }
 
 // TestSaveLoadRoundTrip_Hostnames verifies hostname data survives a save/load cycle.
@@ -358,6 +618,53 @@ func TestSaveAtomicWrite(t *testing.T) {
 	}
 }
 
+// TestSaveOverLeftoverTempFile verifies that a temp file left by a
+// crash, longer than the state Save writes, leaves nothing of itself in
+// the state file, and that no temp file remains after Save.
+func TestSaveOverLeftoverTempFile(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	statePath := filepath.Join(dir, "state.json")
+	tmpPath := statePath + ".tmp"
+
+	err := os.WriteFile(tmpPath, []byte(strings.Repeat("x", 64*1024)), 0o600)
+	if err != nil {
+		t.Fatalf("writing leftover temp file: %v", err)
+	}
+
+	s := state.NewForTestWithDataDir(dir)
+
+	populateState(t, s)
+
+	err = s.Save()
+	if err != nil {
+		t.Fatalf("Save() error: %v", err)
+	}
+
+	//nolint:gosec // test file with known path
+	data, err := os.ReadFile(statePath)
+	if err != nil {
+		t.Fatalf("reading state file: %v", err)
+	}
+
+	var snap state.Snapshot
+
+	err = json.Unmarshal(data, &snap)
+	if err != nil {
+		t.Fatalf("state file is not complete JSON: %v", err)
+	}
+
+	if len(snap.Domains) != 2 {
+		t.Errorf("state file has %d domains, want 2", len(snap.Domains))
+	}
+
+	_, err = os.Stat(tmpPath)
+	if !os.IsNotExist(err) {
+		t.Error("temp file should not exist after save")
+	}
+}
+
 // TestLoadMissingFile verifies that loading a nonexistent file is not an error.
 func TestLoadMissingFile(t *testing.T) {
 	t.Parallel()
@@ -388,6 +695,58 @@ func TestLoadMissingFile(t *testing.T) {
 	}
 }
 
+// TestLoadFileWithoutSections loads a state file holding {}, and files
+// that each leave out one section. Every section loads as an empty map.
+// TestFirstCheckAfterLoadingFileWithoutSections in the watcher tests
+// runs the first check after such a load.
+func TestLoadFileWithoutSections(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		file string
+	}{
+		{"no sections", `{}`},
+		{"no domains", `{"hostnames": {}, "ports": {}, "certificates": {}}`},
+		{"no hostnames", `{"domains": {}, "ports": {}, "certificates": {}}`},
+		{"no ports", `{"domains": {}, "hostnames": {}, "certificates": {}}`},
+		{"no certificates", `{"domains": {}, "hostnames": {}, "ports": {}}`},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			dir := t.TempDir()
+
+			err := os.WriteFile(
+				filepath.Join(dir, "state.json"), []byte(tt.file), 0o600,
+			)
+			if err != nil {
+				t.Fatalf("writing state file: %v", err)
+			}
+
+			s := state.NewForTestWithDataDir(dir)
+
+			err = s.Load()
+			if err != nil {
+				t.Fatalf("Load() error: %v", err)
+			}
+
+			want := state.Snapshot{
+				Domains:      map[string]*state.DomainState{},
+				Hostnames:    map[string]*state.HostnameState{},
+				Ports:        map[string]*state.PortState{},
+				Certificates: map[string]*state.CertificateState{},
+			}
+
+			if got := s.GetSnapshot(); !reflect.DeepEqual(got, want) {
+				t.Errorf("loaded %#v, want %#v", got, want)
+			}
+		})
+	}
+}
+
 // TestLoadCorruptFile verifies that a corrupt state file returns an error.
 func TestLoadCorruptFile(t *testing.T) {
 	t.Parallel()
@@ -735,7 +1094,8 @@ func TestPortStateUnmarshalJSON_BothFormats(t *testing.T) {
 	}
 }
 
-// TestGetSnapshot_ReturnsCopy verifies that GetSnapshot returns a value copy.
+// TestGetSnapshot_ReturnsCopy verifies that the maps in the snapshot
+// GetSnapshot returns are not the state's own.
 func TestGetSnapshot_ReturnsCopy(t *testing.T) {
 	t.Parallel()
 
@@ -745,15 +1105,67 @@ func TestGetSnapshot_ReturnsCopy(t *testing.T) {
 
 	snap := s.GetSnapshot()
 
-	// Mutate the returned snapshot's map.
+	const added = "added.example.com"
-	snap.Domains["mutated.example.com"] = &state.DomainState{
+
-		Nameservers: []string{"ns1.mutated.com."},
+	snap.Domains[added] = &state.DomainState{}
+	snap.Hostnames[added] = &state.HostnameState{}
+	snap.Ports[added] = &state.PortState{}
+	snap.Certificates[added] = &state.CertificateState{}
+
+	if _, ok := s.GetDomainState(added); ok {
+		t.Error("the snapshot's Domains map is the state's own")
 	}
 
-	// The original domain data should still be accessible.
+	if _, ok := s.GetHostnameState(added); ok {
-	_, ok := s.GetDomainState("example.com")
+		t.Error("the snapshot's Hostnames map is the state's own")
-	if !ok {
+	}
-		t.Error("original domain should still exist")
+
+	if _, ok := s.GetPortState(added); ok {
+		t.Error("the snapshot's Ports map is the state's own")
+	}
+
+	if _, ok := s.GetCertificateState(added); ok {
+		t.Error("the snapshot's Certificates map is the state's own")
+	}
+}
+
+// TestGetSnapshot_WhileWritten ranges over snapshots while another
+// goroutine writes the state, as the dashboard does while a check runs.
+// Under -race it fails when a snapshot's maps are the state's own.
+func TestGetSnapshot_WhileWritten(t *testing.T) {
+	t.Parallel()
+
+	s := state.NewForTestWithDataDir(t.TempDir())
+
+	const writes = 1000
+
+	written := make(chan struct{})
+
+	go func() {
+		defer close(written)
+
+		for range writes {
+			s.SetDomainState("example.com", &state.DomainState{})
+			s.SetHostnameState(testHostname, &state.HostnameState{})
+			s.SetPortState(testIPv4+":443", &state.PortState{})
+			s.SetCertificateState(
+				testIPv4+":443:"+testHostname, &state.CertificateState{},
+			)
+		}
+	}()
+
+	for {
+		select {
+		case <-written:
+			return
+		default:
+		}
+
+		// json.Marshal ranges over each of the snapshot's maps.
+		_, err := json.Marshal(s.GetSnapshot())
+		if err != nil {
+			t.Fatal(err)
+		}
 	}
 }
 

internal/watcher/cancelled_test.go

@@ -1,10 +1,13 @@
 package watcher_test
 
 import (
+	"bytes"
 	"context"
 	"log/slog"
 	"reflect"
+	"strings"
 	"testing"
+	"time"
 
 	"sneak.berlin/go/dnswatcher/internal/portcheck"
 	"sneak.berlin/go/dnswatcher/internal/resolver"
@@ -79,3 +82,96 @@ func TestCancelledCheckSavesNothing(t *testing.T) {
 		t.Errorf("sent %v, want no notifications", notifications)
 	}
 }
+
+// TestStopBeforeFirstScanSendsNoStartupNotification runs a watcher with
+// the startup notification on and its context already cancelled, so the
+// first scan is cut short before its lookup is sent. The scan did not
+// complete, so no startup notification may be sent.
+func TestStopBeforeFirstScanSendsNoStartupNotification(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Hostnames = []string{testHost}
+	cfg.SendTestNotification = true
+
+	w, deps := newTestWatcher(t, cfg)
+
+	ctx, cancel := context.WithCancel(t.Context())
+	cancel()
+
+	w.Run(ctx)
+
+	notifications := deps.notifier.getNotifications()
+	if len(notifications) != 0 {
+		t.Errorf("sent %v, want no notifications", notifications)
+	}
+}
+
+// newLoggingWatcher returns a watcher for a domain and a hostname, with
+// the real resolver, that writes what it logs at warning level or above
+// into the returned buffer.
+func newLoggingWatcher(t *testing.T) (*watcher.Watcher, *bytes.Buffer) {
+	t.Helper()
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{testSmallDomain}
+	cfg.Hostnames = []string{host}
+
+	w, _ := newTestWatcher(t, cfg)
+
+	logs := &bytes.Buffer{}
+	w.SetLogger(slog.New(slog.NewJSONHandler(
+		logs, &slog.HandlerOptions{Level: slog.LevelWarn},
+	)))
+
+	return w, logs
+}
+
+// TestLookupCutShortIsNotLogged checks a domain and a hostname, looks
+// up a nameserver's addresses and follows a CNAME, with the context
+// cancelled, as shutdown leaves it. The real resolver fails each lookup
+// without sending a query. Shutdown cutting a lookup short is not a
+// failure, so nothing may be logged at warning level or above.
+func TestLookupCutShortIsNotLogged(t *testing.T) {
+	t.Parallel()
+
+	w, logs := newLoggingWatcher(t)
+
+	ctx, cancel := context.WithCancel(t.Context())
+	cancel()
+
+	w.RunOnce(ctx)
+	w.ResolveNameserverAddresses(ctx, []string{nsA}, nil)
+	w.ResolveCNAMEAddresses(ctx, host, cnameState(), nil)
+
+	if logs.Len() > 0 {
+		t.Errorf("logged at warning level or above:\n%s", logs)
+	}
+}
+
+// TestLookupOutOfTimeIsLoggedAsError does what
+// TestLookupCutShortIsNotLogged does, with the context's deadline passed
+// instead. A lookup that ran out of time did fail, so the domain's NS
+// lookup, the hostname's lookup, the nameserver's address lookup and the
+// CNAME's are each logged as an error.
+func TestLookupOutOfTimeIsLoggedAsError(t *testing.T) {
+	t.Parallel()
+
+	w, logs := newLoggingWatcher(t)
+
+	ctx, cancel := context.WithDeadline(t.Context(), time.Now())
+	t.Cleanup(cancel)
+
+	w.RunOnce(ctx)
+	w.ResolveNameserverAddresses(ctx, []string{nsA}, nil)
+	w.ResolveCNAMEAddresses(ctx, host, cnameState(), nil)
+
+	const want = 4
+
+	lines := strings.Count(logs.String(), "\n")
+	errorLines := strings.Count(logs.String(), `"level":"ERROR"`)
+
+	if lines != want || errorLines != want {
+		t.Errorf("logged:\n%s\nwant %d lines, each at error level", logs, want)
+	}
+}

internal/watcher/cname_test.go

@@ -0,0 +1,372 @@
+package watcher_test
+
+import (
+	"context"
+	"log/slog"
+	"slices"
+	"testing"
+
+	"sneak.berlin/go/dnswatcher/internal/livednstest"
+	"sneak.berlin/go/dnswatcher/internal/resolver"
+	"sneak.berlin/go/dnswatcher/internal/state"
+	"sneak.berlin/go/dnswatcher/internal/watcher"
+)
+
+// TestCNAMEIntoAnotherZonePortAndTLSChecks runs the port and TLS
+// checks on hostname state built here: the name's nameserver answered
+// with a CNAME into another zone, and following it found ip1. Both
+// checks must use ip1. They look nothing up, so the watcher has no
+// resolver.
+func TestCNAMEIntoAnotherZonePortAndTLSChecks(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Hostnames = []string{host}
+
+	deps := newTestDeps(t, cfg)
+	w := watcher.NewForTest(
+		cfg, deps.state, nil,
+		deps.portChecker, deps.tlsChecker, deps.notifier,
+	)
+
+	deps.state.SetHostnameState(host, cnameState(ip1))
+
+	w.CheckAllPorts(t.Context())
+	w.RunTLSChecks(t.Context())
+
+	snap := deps.state.GetSnapshot()
+
+	ps, ok := snap.Ports[ip1+":443"]
+	if !ok || !slices.Contains(ps.Hostnames, host) {
+		t.Errorf("no port state for %s at %s:443", host, ip1)
+	}
+
+	certKey := ip1 + ":443:" + host
+	if _, ok := snap.Certificates[certKey]; !ok {
+		t.Errorf("no certificate state %s", certKey)
+	}
+}
+
+// TestCNAMEThatCannotBeFollowedKeepsPrevious runs a check of a name, not
+// the watcher's first, from the point where its records have been looked
+// up: they hold a CNAME to a target under .invalid, whose lookup fails.
+// The previous check found the same records, and oldIP at the end of the
+// CNAME. The check must keep oldIP and send nothing.
+func TestCNAMEThatCannotBeFollowedKeepsPrevious(t *testing.T) {
+	t.Parallel()
+
+	w, deps := newTestWatcher(t, defaultTestConfig(t))
+	w.SetFirstRun(false)
+
+	records := map[string]map[string][]string{
+		nsA: cnameTo("target.example.invalid."),
+	}
+
+	prev := hostnameState(records)
+	prev.CNAMEAddresses = []string{oldIP}
+	deps.state.SetHostnameState(host, prev)
+
+	// The result is the same whether or not live DNS answers, so the
+	// lookup is not retried.
+	_ = livednstest.Run(func(ctx context.Context) error {
+		w.UpdateHostnameState(ctx, host, hostnameState(records))
+
+		return nil
+	})
+
+	hs, _ := deps.state.GetHostnameState(host)
+	if !slices.Equal(hs.CNAMEAddresses, prev.CNAMEAddresses) {
+		t.Errorf(
+			"saved %v, want %v",
+			hs.CNAMEAddresses, prev.CNAMEAddresses,
+		)
+	}
+
+	notifications := deps.notifier.getNotifications()
+	if len(notifications) != 0 {
+		t.Errorf("sent %v, want no notifications", notifications)
+	}
+}
+
+// followLive follows in live DNS the CNAMEs in a name's records, built
+// from records, and returns the addresses saved for the name. The
+// previous check saved oldIP, which is kept when a target cannot be
+// followed; that is retried. The tests point CNAMEs only at names in
+// zones with two nameservers, to keep queries few (see the top of
+// watcher_test.go).
+func followLive(
+	t *testing.T,
+	records map[string]map[string][]string,
+) []string {
+	t.Helper()
+
+	w := watcher.NewForTest(
+		nil, nil, resolver.NewFromLogger(slog.Default()), nil, nil, nil,
+	)
+	prev := cnameState(oldIP)
+
+	var current *state.HostnameState
+
+	livednstest.Retry(t, "following CNAMEs", func(ctx context.Context) error {
+		current = hostnameState(records)
+
+		w.ResolveCNAMEAddresses(ctx, host, current, prev)
+
+		if slices.Equal(current.CNAMEAddresses, prev.CNAMEAddresses) {
+			return livednstest.ErrNoAnswer
+		}
+
+		return nil
+	})
+
+	return current.CNAMEAddresses
+}
+
+// TestCNAMEAddressesOfEveryTarget gives a name's two nameservers
+// different CNAME targets, as when a secondary still serves an old one.
+// The addresses at the end of both are saved, whichever answer is read
+// first: one.one.one.one has 1.1.1.1, and dns.adguard-dns.com has
+// 94.140.14.14.
+func TestCNAMEAddressesOfEveryTarget(t *testing.T) {
+	t.Parallel()
+
+	found := followLive(t, map[string]map[string][]string{
+		nsA: cnameTo("one.one.one.one."),
+		nsB: cnameTo("dns.adguard-dns.com."),
+	})
+
+	for _, ip := range []string{"1.1.1.1", "94.140.14.14"} {
+		if !slices.Contains(found, ip) {
+			t.Errorf("saved %v, want %s among them", found, ip)
+		}
+	}
+}
+
+// TestCNAMEChainEndingInNoAddressSavesEmptyList follows a CNAME to a
+// name live DNS answers with NXDOMAIN. An empty list is saved, not nil,
+// which would mean the addresses are not known.
+func TestCNAMEChainEndingInNoAddressSavesEmptyList(t *testing.T) {
+	t.Parallel()
+
+	found := followLive(t, map[string]map[string][]string{
+		nsA: cnameTo("this-surely-does-not-exist-xyz.example.org."),
+	})
+
+	if found == nil || len(found) != 0 {
+		t.Errorf("saved %#v, want an empty list", found)
+	}
+}
+
+// TestCNAMEBesideAnAddressNotFollowed gives one nameserver of a name an
+// address and another a CNAME. The CNAME is not followed: an empty list
+// is saved, not nil, and nothing is looked up, the watcher having no
+// resolver.
+func TestCNAMEBesideAnAddressNotFollowed(t *testing.T) {
+	t.Parallel()
+
+	w := watcher.NewForTest(nil, nil, nil, nil, nil, nil)
+
+	current := hostnameState(map[string]map[string][]string{
+		nsA: {"A": {ip1}},
+		nsB: cnameTo("target.example.org."),
+	})
+
+	w.ResolveCNAMEAddresses(t.Context(), host, current, nil)
+
+	if current.CNAMEAddresses == nil || len(current.CNAMEAddresses) != 0 {
+		t.Errorf("saved %#v, want an empty list", current.CNAMEAddresses)
+	}
+}
+
+// TestCNAMEWhoseNameserversAllFailedKeepsPrevious checks a name none of
+// whose nameservers answered. The addresses the previous check saved
+// from following its CNAME are kept, and nothing is looked up: the
+// watcher has no resolver.
+func TestCNAMEWhoseNameserversAllFailedKeepsPrevious(t *testing.T) {
+	t.Parallel()
+
+	w := watcher.NewForTest(nil, nil, nil, nil, nil, nil)
+
+	current := saved(map[string]*state.NameserverRecordState{
+		nsA: failed(), nsB: failed(),
+	})
+	prev := cnameState(oldIP)
+
+	w.ResolveCNAMEAddresses(t.Context(), host, current, prev)
+
+	if !slices.Equal(current.CNAMEAddresses, prev.CNAMEAddresses) {
+		t.Errorf(
+			"saved %v, want %v",
+			current.CNAMEAddresses, prev.CNAMEAddresses,
+		)
+	}
+}
+
+// TestCNAMEWhoseAddressQueryFailedKeepsPrevious checks a name whose
+// nameserver answered, but whose query for A, AAAA or CNAME failed with
+// nothing kept for it. That is not an answer with no address: the
+// addresses the previous check saved from following its CNAME are kept,
+// and nothing is looked up, the watcher having no resolver.
+func TestCNAMEWhoseAddressQueryFailedKeepsPrevious(t *testing.T) {
+	t.Parallel()
+
+	for _, rtype := range []string{"A", "AAAA", "CNAME"} {
+		t.Run(rtype, func(t *testing.T) {
+			t.Parallel()
+
+			w := watcher.NewForTest(nil, nil, nil, nil, nil, nil)
+
+			current := saved(map[string]*state.NameserverRecordState{
+				nsA: {
+					Records:      map[string][]string{},
+					FailedTypes:  []string{rtype},
+					UnknownTypes: []string{rtype},
+					Status:       "ok",
+				},
+			})
+			prev := cnameState(oldIP)
+
+			w.ResolveCNAMEAddresses(t.Context(), host, current, prev)
+
+			if !slices.Equal(current.CNAMEAddresses, prev.CNAMEAddresses) {
+				t.Errorf(
+					"saved %v, want %v",
+					current.CNAMEAddresses, prev.CNAMEAddresses,
+				)
+			}
+		})
+	}
+}
+
+// cnameTo builds the records of a nameserver that answered with a CNAME
+// to target and no address.
+func cnameTo(target string) map[string][]string {
+	return map[string][]string{"CNAME": {target}}
+}
+
+// cnameState builds the state a check leaves behind for a name whose
+// nameserver answered with a CNAME and no address, when following the
+// CNAME found these addresses, which may be none.
+func cnameState(addresses ...string) *state.HostnameState {
+	hs := hostnameState(map[string]map[string][]string{
+		nsA: cnameTo("target.example.org."),
+	})
+
+	hs.CNAMEAddresses = append([]string{}, addresses...)
+
+	return hs
+}
+
+func TestCNAMEAddressChangeAlerts(t *testing.T) {
+	t.Parallel()
+
+	// A state file written before the addresses were saved loads with
+	// them nil.
+	olderStateFile := cnameState()
+	olderStateFile.CNAMEAddresses = nil
+
+	// Each case is the state saved by the previous check and by the
+	// current one. The name's records are the same in both.
+	tests := []struct {
+		name          string
+		prev, current *state.HostnameState
+		want          int
+	}{
+		{
+			"same addresses",
+			cnameState(ip1, ip2), cnameState(ip1, ip2), 0,
+		},
+		{
+			"same addresses in another order",
+			cnameState(ip2, ip1), cnameState(ip1, ip2), 0,
+		},
+		{
+			"address replaced",
+			cnameState(ip1), cnameState(ip2), 1,
+		},
+		{
+			"address added",
+			cnameState(ip1), cnameState(ip1, ip2), 1,
+		},
+		{
+			"no address at the end of the chain now",
+			cnameState(ip1), cnameState(), 1,
+		},
+		{
+			"addresses at the end of the chain again",
+			cnameState(), cnameState(ip1), 1,
+		},
+		{
+			"state file from before addresses were saved",
+			olderStateFile, cnameState(ip1), 0,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			notifier := &mockNotifier{}
+			w := watcher.NewForTest(nil, nil, nil, nil, nil, notifier)
+
+			w.DetectHostnameChanges(t.Context(), host, tt.prev, tt.current)
+
+			got := len(notifier.getNotifications())
+			if got != tt.want {
+				t.Errorf("sent %d notifications, want %d", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestCNAMEAddressChangeAlertNamesHostnameAndAddresses(t *testing.T) {
+	t.Parallel()
+
+	notifier := &mockNotifier{}
+	w := watcher.NewForTest(nil, nil, nil, nil, nil, notifier)
+
+	w.DetectHostnameChanges(
+		t.Context(), host, cnameState(ip1), cnameState(ip2, ip3),
+	)
+
+	want := notification{
+		Title: "CNAME Address Change: " + host,
+		Message: "Hostname: " + host +
+			"\nOld: " + ip1 + "\nNew: " + ip2 + ", " + ip3,
+		Priority: "warning",
+	}
+
+	got := notifier.getNotifications()
+	if len(got) != 1 || got[0] != want {
+		t.Errorf("sent %v, want %v", got, want)
+	}
+}
+
+// TestNameMovedFromARecordsToCNAMEAlerts checks a name that answers
+// with an A record and then with a CNAME whose chain ends in ip2. The
+// second check is notified as a CNAME address change from no addresses,
+// beside the record change. Nothing is looked up: the watcher has no
+// resolver.
+func TestNameMovedFromARecordsToCNAMEAlerts(t *testing.T) {
+	t.Parallel()
+
+	notifier := &mockNotifier{}
+	w := watcher.NewForTest(nil, nil, nil, nil, nil, notifier)
+
+	prev := hostnameState(map[string]map[string][]string{
+		nsA: {"A": {ip1}},
+	})
+	w.ResolveCNAMEAddresses(t.Context(), host, prev, nil)
+
+	w.DetectHostnameChanges(t.Context(), host, prev, cnameState(ip2))
+
+	title := "CNAME Address Change: " + host
+	message := "Hostname: " + host + "\nOld: \nNew: " + ip2
+
+	got := notifier.getNotifications()
+	if !slices.ContainsFunc(got, func(n notification) bool {
+		return n.Title == title && n.Message == message
+	}) {
+		t.Errorf("sent %v, want %q with %q among them", got, title, message)
+	}
+}

internal/watcher/export_test.go

@@ -10,7 +10,8 @@ import (
 	"sneak.berlin/go/dnswatcher/internal/state"
 )
 
-// NewForTest creates a Watcher without fx for unit testing.
+// NewForTest creates a Watcher without fx for unit testing. A nil cfg
+// is an empty configuration.
 func NewForTest(
 	cfg *config.Config,
 	st *state.State,
@@ -19,17 +20,26 @@ func NewForTest(
 	tc TLSChecker,
 	n Notifier,
 ) *Watcher {
-	return &Watcher{
+	if cfg == nil {
-		log:            slog.Default(),
+		cfg = &config.Config{}
-		config:         cfg,
-		state:          st,
-		resolver:       res,
-		portCheck:      pc,
-		tlsCheck:       tc,
-		notify:         n,
-		firstRun:       true,
-		expiryNotified: make(map[string]time.Time),
 	}
+
+	return &Watcher{
+		log:       slog.Default(),
+		config:    cfg,
+		state:     st,
+		resolver:  res,
+		portCheck: pc,
+		tlsCheck:  tc,
+		notify:    n,
+		firstRun:  true,
+	}
+}
+
+// SetLogger replaces the watcher's logger, so a test can read what it
+// logs.
+func (w *Watcher) SetLogger(log *slog.Logger) {
+	w.log = log
 }
 
 // NewlyDisagreeingPairs exports newlyDisagreeingPairs for testing.
@@ -39,6 +49,21 @@ func NewlyDisagreeingPairs(
 	return newlyDisagreeingPairs(prev, current)
 }
 
+// SetFirstRun sets whether the watcher is on its first check, in which
+// nothing is compared with the previous check. NewForTest's watcher is.
+func (w *Watcher) SetFirstRun(firstRun bool) {
+	w.firstRun = firstRun
+}
+
+// UpdateHostnameState exports updateHostnameState for testing.
+func (w *Watcher) UpdateHostnameState(
+	ctx context.Context,
+	hostname string,
+	newState *state.HostnameState,
+) {
+	w.updateHostnameState(ctx, hostname, newState)
+}
+
 // DetectHostnameChanges exports detectHostnameChanges for testing.
 func (w *Watcher) DetectHostnameChanges(
 	ctx context.Context,
@@ -48,10 +73,88 @@ func (w *Watcher) DetectHostnameChanges(
 	w.detectHostnameChanges(ctx, hostname, prev, current)
 }
 
+// ResolveNameserverAddresses exports resolveNameserverAddresses for
+// testing.
+func (w *Watcher) ResolveNameserverAddresses(
+	ctx context.Context,
+	nameservers []string,
+	prev map[string][]string,
+) map[string][]string {
+	return w.resolveNameserverAddresses(ctx, nameservers, prev)
+}
+
+// ResolveCNAMEAddresses exports resolveCNAMEAddresses for testing.
+func (w *Watcher) ResolveCNAMEAddresses(
+	ctx context.Context,
+	hostname string,
+	current, prev *state.HostnameState,
+) {
+	w.resolveCNAMEAddresses(ctx, hostname, current, prev)
+}
+
+// DetectNSAddressChanges exports detectNSAddressChanges for testing.
+func (w *Watcher) DetectNSAddressChanges(
+	ctx context.Context,
+	domain string,
+	prev, current map[string][]string,
+) {
+	w.detectNSAddressChanges(ctx, domain, prev, current)
+}
+
+// MaybeSendTestNotification exports maybeSendTestNotification for
+// testing.
+func (w *Watcher) MaybeSendTestNotification(ctx context.Context) {
+	w.maybeSendTestNotification(ctx)
+}
+
+// CleanupRemovedTargets exports cleanupRemovedTargets for testing.
+func (w *Watcher) CleanupRemovedTargets() {
+	w.cleanupRemovedTargets()
+}
+
+// CheckAllPorts exports checkAllPorts for testing.
+func (w *Watcher) CheckAllPorts(ctx context.Context) {
+	w.checkAllPorts(ctx)
+}
+
+// RunTLSChecks exports runTLSChecks for testing.
+func (w *Watcher) RunTLSChecks(ctx context.Context) {
+	w.runTLSChecks(ctx)
+}
+
+// CheckHostnameResult exports checkHostnameResult for testing.
+func (w *Watcher) CheckHostnameResult(
+	ctx context.Context,
+	hostname string,
+	results map[string]*resolver.NameserverResponse,
+	err error,
+) bool {
+	return w.checkHostnameResult(ctx, hostname, results, err)
+}
+
+// CheckDomainResult exports checkDomainResult for testing.
+func (w *Watcher) CheckDomainResult(
+	ctx context.Context,
+	domain string,
+	nameservers []string,
+	err error,
+) {
+	w.checkDomainResult(ctx, domain, nameservers, err)
+}
+
+// FailedNameservers exports failedNameservers for testing.
+func FailedNameservers(
+	err error,
+	prev *state.HostnameState,
+) map[string]*resolver.NameserverResponse {
+	return failedNameservers(err, prev)
+}
+
 // BuildHostnameState exports buildHostnameState for testing.
 func BuildHostnameState(
 	results map[string]*resolver.NameserverResponse,
+	prev *state.HostnameState,
 	now time.Time,
 ) *state.HostnameState {
-	return buildHostnameState(results, now)
+	return buildHostnameState(results, prev, now)
 }

internal/watcher/failedtype_test.go

@@ -0,0 +1,364 @@
+package watcher_test
+
+import (
+	"maps"
+	"slices"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/dnswatcher/internal/resolver"
+	"sneak.berlin/go/dnswatcher/internal/state"
+	"sneak.berlin/go/dnswatcher/internal/watcher"
+)
+
+const (
+	// txt is the record type whose query fails in these tests.
+	txt  = "TXT"
+	spf1 = "v=spf1 -all"
+	spf2 = "v=spf1 include:example.net -all"
+)
+
+// response is a nameserver's response with these records, whose queries
+// for failedTypes failed.
+func response(
+	records map[string][]string,
+	failedTypes ...string,
+) *resolver.NameserverResponse {
+	return &resolver.NameserverResponse{
+		Records:     records,
+		FailedTypes: failedTypes,
+		Status:      resolver.StatusOK,
+	}
+}
+
+// savedChecks saves the state of each check in turn from the
+// nameservers' responses, each from the state the check before saved.
+func savedChecks(
+	checks ...map[string]*resolver.NameserverResponse,
+) []*state.HostnameState {
+	states := make([]*state.HostnameState, 0, len(checks))
+
+	var prev *state.HostnameState
+
+	for _, results := range checks {
+		prev = watcher.BuildHostnameState(results, prev, time.Now())
+		states = append(states, prev)
+	}
+
+	return states
+}
+
+// TestFailedTypeKeepsPreviousRecords saves a check in which nsA's query
+// for TXT failed, after previous checks of several kinds. TXT is always
+// saved in FailedTypes, and in UnknownTypes when there was nothing to
+// keep.
+func TestFailedTypeKeepsPreviousRecords(t *testing.T) {
+	t.Parallel()
+
+	aOnly := map[string][]string{"A": {ip1}}
+	withTXT := map[string][]string{"A": {ip1}, txt: {spf1}}
+	txtKept := &state.NameserverRecordState{
+		Records: withTXT, FailedTypes: []string{txt}, Status: "ok",
+	}
+	txtNotKnown := &state.NameserverRecordState{
+		Records:      aOnly,
+		FailedTypes:  []string{txt},
+		UnknownTypes: []string{txt},
+		Status:       "ok",
+	}
+
+	tests := []struct {
+		name        string
+		prev        *state.HostnameState
+		wantRecords map[string][]string
+		wantUnknown []string
+	}{
+		{
+			"previous TXT records are kept",
+			saved(map[string]*state.NameserverRecordState{nsA: answered(withTXT)}),
+			withTXT, nil,
+		},
+		{
+			"previous check had no TXT records",
+			saved(map[string]*state.NameserverRecordState{nsA: answered(aOnly)}),
+			aOnly, nil,
+		},
+		{
+			"TXT failed on the previous check, which kept its records",
+			saved(map[string]*state.NameserverRecordState{nsA: txtKept}),
+			withTXT, nil,
+		},
+		{"first check", nil, aOnly, []string{txt}},
+		{
+			"nameserver new on this check",
+			saved(map[string]*state.NameserverRecordState{nsB: answered(withTXT)}),
+			aOnly, []string{txt},
+		},
+		{
+			"nameserver failed on the previous check",
+			saved(map[string]*state.NameserverRecordState{nsA: failed()}),
+			aOnly, []string{txt},
+		},
+		{
+			"TXT failed on the previous check with nothing to keep",
+			saved(map[string]*state.NameserverRecordState{nsA: txtNotKnown}),
+			aOnly, []string{txt},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			hs := watcher.BuildHostnameState(
+				map[string]*resolver.NameserverResponse{
+					nsA: response(map[string][]string{"A": {ip1}}, txt),
+				},
+				tt.prev, time.Now(),
+			)
+
+			got := hs.RecordsByNameserver[nsA]
+			if got.Status != "ok" ||
+				!maps.EqualFunc(got.Records, tt.wantRecords, slices.Equal) ||
+				!slices.Equal(got.FailedTypes, []string{txt}) ||
+				!slices.Equal(got.UnknownTypes, tt.wantUnknown) {
+				t.Errorf(
+					"saved status %q, records %v, failed types %v, "+
+						"unknown types %v; want ok, %v, [%s], %v",
+					got.Status, got.Records, got.FailedTypes,
+					got.UnknownTypes, tt.wantRecords, txt, tt.wantUnknown,
+				)
+			}
+		})
+	}
+}
+
+// TestFailedTypeAlerts saves the checks of each case in turn from the
+// nameservers' responses, the first being the state loaded at startup,
+// and counts the alerts sent. nsB's TXT query fails on one check, and
+// nothing changes.
+func TestFailedTypeAlerts(t *testing.T) {
+	t.Parallel()
+
+	records := map[string][]string{"A": {ip1}, txt: {spf1}}
+	aOnly := map[string][]string{"A": {ip1}}
+
+	bothAnswer := map[string]*resolver.NameserverResponse{
+		nsA: response(records), nsB: response(records),
+	}
+	bTXTFails := map[string]*resolver.NameserverResponse{
+		nsA: response(records), nsB: response(aOnly, txt),
+	}
+	onlyA := map[string]*resolver.NameserverResponse{
+		nsA: response(records),
+	}
+	bFails := map[string]*resolver.NameserverResponse{
+		nsA: response(records),
+		nsB: {
+			Records: map[string][]string{},
+			Status:  resolver.StatusTimeout,
+			Error:   "all queries timed out",
+		},
+	}
+
+	tests := []struct {
+		name   string
+		checks []map[string]*resolver.NameserverResponse
+		want   alertCounts
+	}{
+		{
+			"type failing at one nameserver alerts nothing, nor its next answer",
+			[]map[string]*resolver.NameserverResponse{
+				bothAnswer, bTXTFails, bothAnswer,
+			},
+			alertCounts{},
+		},
+		{
+			"type failing on the first check alerts nothing on the next",
+			[]map[string]*resolver.NameserverResponse{bTXTFails, bothAnswer},
+			alertCounts{},
+		},
+		{
+			"type failing at a nameserver new on that check alerts nothing",
+			[]map[string]*resolver.NameserverResponse{
+				onlyA, bTXTFails, bothAnswer,
+			},
+			alertCounts{},
+		},
+		{
+			"type failing at a recovering nameserver alerts the recovery",
+			[]map[string]*resolver.NameserverResponse{
+				bFails, bTXTFails, bothAnswer,
+			},
+			alertCounts{recoveries: 1},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			states := savedChecks(tt.checks...)
+
+			got := countAlerts(t, states[0], states[1:])
+			if got != tt.want {
+				t.Errorf("sent %+v, want %+v", got, tt.want)
+			}
+		})
+	}
+}
+
+// TestFailedTypeComparedOnceItAnswers saves the checks of each case in
+// turn as TestFailedTypeAlerts does. nsB's TXT query fails on one check,
+// and the TXT record changes: the change is sent as a Record Change for
+// each nameserver on the check where it answers it, and an Inconsistency
+// only when nsB still answers the old record.
+func TestFailedTypeComparedOnceItAnswers(t *testing.T) {
+	t.Parallel()
+
+	records := map[string][]string{"A": {ip1}, txt: {spf1}}
+	changed := map[string][]string{"A": {ip1}, txt: {spf2}}
+	aOnly := map[string][]string{"A": {ip1}}
+
+	bothAnswer := map[string]*resolver.NameserverResponse{
+		nsA: response(records), nsB: response(records),
+	}
+	bTXTFails := map[string]*resolver.NameserverResponse{
+		nsA: response(records), nsB: response(aOnly, txt),
+	}
+	bothChange := map[string]*resolver.NameserverResponse{
+		nsA: response(changed), nsB: response(changed),
+	}
+	aChangesBTXTFails := map[string]*resolver.NameserverResponse{
+		nsA: response(changed), nsB: response(aOnly, txt),
+	}
+	bStillOld := map[string]*resolver.NameserverResponse{
+		nsA: response(changed), nsB: response(records),
+	}
+
+	tests := []struct {
+		name   string
+		checks []map[string]*resolver.NameserverResponse
+		want   alertCounts
+	}{
+		{
+			"change made while the type failed",
+			[]map[string]*resolver.NameserverResponse{
+				bothAnswer, bTXTFails, bothChange,
+			},
+			alertCounts{recordChanges: 2},
+		},
+		{
+			"change seen at one nameserver while the other's type failed",
+			[]map[string]*resolver.NameserverResponse{
+				bothAnswer, aChangesBTXTFails, bothChange,
+			},
+			alertCounts{recordChanges: 2},
+		},
+		{
+			"old record answered after the type failed",
+			[]map[string]*resolver.NameserverResponse{
+				bothAnswer, aChangesBTXTFails, bStillOld,
+			},
+			alertCounts{recordChanges: 1, inconsistencies: 1},
+		},
+		{
+			"change after the type failed on the first check and answered",
+			[]map[string]*resolver.NameserverResponse{
+				bTXTFails, bothAnswer, bothChange,
+			},
+			alertCounts{recordChanges: 2},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			states := savedChecks(tt.checks...)
+
+			got := countAlerts(t, states[0], states[1:])
+			if got != tt.want {
+				t.Errorf("sent %+v, want %+v", got, tt.want)
+			}
+		})
+	}
+}
+
+// TestFailedTypeLeftOutOfMessages checks that a Record Change and an
+// Inconsistency name only the record types they compared. nsB's TXT
+// records are not known on the first check, and on the second either
+// answered or still not known; nsB's A record changes, so both alerts
+// are sent and name the A record alone.
+func TestFailedTypeLeftOutOfMessages(t *testing.T) {
+	t.Parallel()
+
+	withTXT := map[string][]string{"A": {ip1}, txt: {spf1}}
+	txtNotKnown := func(address string) *state.NameserverRecordState {
+		return &state.NameserverRecordState{
+			Records:      map[string][]string{"A": {address}},
+			FailedTypes:  []string{txt},
+			UnknownTypes: []string{txt},
+			Status:       "ok",
+		}
+	}
+
+	before := saved(map[string]*state.NameserverRecordState{
+		nsA: answered(withTXT), nsB: txtNotKnown(ip1),
+	})
+
+	tests := []struct {
+		name  string
+		after *state.HostnameState
+	}{
+		{
+			"TXT answers",
+			saved(map[string]*state.NameserverRecordState{
+				nsA: answered(withTXT),
+				nsB: answered(map[string][]string{"A": {ip2}, txt: {spf1}}),
+			}),
+		},
+		{
+			"TXT still not known",
+			saved(map[string]*state.NameserverRecordState{
+				nsA: answered(withTXT), nsB: txtNotKnown(ip2),
+			}),
+		},
+	}
+
+	want := map[string]string{
+		"Record Change: " + host: "Hostname: " + host +
+			"\nNameserver: " + nsB + "\nType: A\nOld: " + ip1 + "\nNew: " + ip2,
+		"Inconsistency: " + host: "Hostname: " + host +
+			"\nType: A\n" + nsA + ": " + ip1 + "\n" + nsB + ": " + ip2,
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			// The hostname change detection uses only the notifier.
+			notifier := &mockNotifier{}
+			w := watcher.NewForTest(nil, nil, nil, nil, nil, notifier)
+
+			w.DetectHostnameChanges(t.Context(), host, before, tt.after)
+
+			notifications := notifier.getNotifications()
+			if len(notifications) != len(want) {
+				t.Fatalf(
+					"sent %d notifications, want %d: %v",
+					len(notifications), len(want), notifications,
+				)
+			}
+
+			for _, n := range notifications {
+				if n.Message != want[n.Title] {
+					t.Errorf(
+						"%s message:\n%s\nwant:\n%s",
+						n.Title, n.Message, want[n.Title],
+					)
+				}
+			}
+		})
+	}
+}

internal/watcher/inconsistency_test.go

@@ -183,3 +183,58 @@ func TestInconsistencyAlert(t *testing.T) {
 		})
 	}
 }
+
+// TestFirstCheckAfterRepeatedValuesLoaded saves a state file holding a
+// hostname's CNAME once for every record type asked for, as checks did
+// before each value was stored once, and two addresses each repeated,
+// and loads it. A check that then finds each value once at each
+// nameserver must notify nothing.
+func TestFirstCheckAfterRepeatedValuesLoaded(t *testing.T) {
+	t.Parallel()
+
+	const (
+		cnameType = "CNAME"
+		cname     = "c.example.net."
+	)
+
+	cfg := defaultTestConfig(t)
+	repeated := map[string][]string{
+		"A":       {ip2, ip1, ip2, ip1},
+		cnameType: {cname, cname, cname, cname, cname, cname, cname, cname},
+	}
+	once := map[string][]string{"A": {ip1, ip2}, cnameType: {cname}}
+
+	saved := newTestDeps(t, cfg).state
+	saved.SetHostnameState(host, hostnameState(map[string]map[string][]string{
+		nsA: repeated, nsB: repeated,
+	}))
+
+	err := saved.Save()
+	if err != nil {
+		t.Fatalf("saving the state file: %v", err)
+	}
+
+	deps := newTestDeps(t, cfg)
+
+	err = deps.state.Load()
+	if err != nil {
+		t.Fatalf("loading the state file: %v", err)
+	}
+
+	prev, ok := deps.state.GetHostnameState(host)
+	if !ok {
+		t.Fatal("the state file has no state for " + host)
+	}
+
+	current := hostnameState(map[string]map[string][]string{
+		nsA: once, nsB: once,
+	})
+
+	// The hostname change detection uses only the notifier.
+	w := watcher.NewForTest(nil, nil, nil, nil, nil, deps.notifier)
+	w.DetectHostnameChanges(t.Context(), host, prev, current)
+
+	if got := deps.notifier.getNotifications(); len(got) != 0 {
+		t.Errorf("sent %v, want no notification", got)
+	}
+}

internal/watcher/interfaces.go

@@ -11,14 +11,19 @@ import (
 
 // DNSResolver performs iterative DNS resolution.
 type DNSResolver interface {
-	// LookupNS discovers authoritative nameservers for a domain.
+	// LookupNS returns a domain's NS record set, as its parent zone's
+	// servers delegate it: empty when they answer that it has none, and
+	// resolver.ErrNXDomain when they answer that it does not exist.
 	LookupNS(
 		ctx context.Context,
 		domain string,
 	) ([]string, error)
 
 	// LookupAllRecords queries all record types for a hostname,
-	// returning each nameserver's response keyed by nameserver.
+	// returning each nameserver's response keyed by nameserver. When
+	// the walk to the nameservers reached a zone through a referral and
+	// none of that zone's nameservers answered, the error is a
+	// *resolver.NoAnswerError naming them.
 	LookupAllRecords(
 		ctx context.Context,
 		hostname string,

internal/watcher/ipv6_test.go

@@ -0,0 +1,83 @@
+package watcher_test
+
+import (
+	"maps"
+	"slices"
+	"testing"
+
+	"sneak.berlin/go/dnswatcher/internal/state"
+	"sneak.berlin/go/dnswatcher/internal/watcher"
+)
+
+// TestIPv6AddressInBrackets runs the port checks, not the watcher's
+// first, on hostname state built here for a hostname at an IPv6 address
+// whose port 443 the previous check found closed. It is open now. Then
+// it runs the TLS checks and the port checks again. The port and
+// certificate keys and the Port Change notification write the address
+// in brackets, so its last group cannot be read as the port, and the
+// second port checks keep the certificate entry, whose address they read
+// back from its key. When a last port check finds port 443 closed, the
+// certificate entry is removed. Nothing is looked up.
+func TestIPv6AddressInBrackets(t *testing.T) {
+	t.Parallel()
+
+	const aaaaType = "AAAA"
+
+	cfg := defaultTestConfig(t)
+	cfg.Hostnames = []string{host}
+
+	deps := newTestDeps(t, cfg)
+	w := watcher.NewForTest(
+		cfg, deps.state, nil,
+		deps.portChecker, deps.tlsChecker, deps.notifier,
+	)
+	w.SetFirstRun(false)
+
+	deps.state.SetHostnameState(host, saved(
+		map[string]*state.NameserverRecordState{
+			nsA: answered(map[string][]string{aaaaType: {"2001:db8::1"}}),
+		},
+	))
+	deps.state.SetPortState("[2001:db8::1]:443", &state.PortState{
+		Hostnames: []string{host},
+	})
+
+	w.CheckAllPorts(t.Context())
+	w.RunTLSChecks(t.Context())
+	w.CheckAllPorts(t.Context())
+
+	snap := deps.state.GetSnapshot()
+
+	gotPorts := slices.Sorted(maps.Keys(snap.Ports))
+	wantPorts := []string{"[2001:db8::1]:443", "[2001:db8::1]:80"}
+
+	if !slices.Equal(gotPorts, wantPorts) {
+		t.Errorf("port entries %v, want %v", gotPorts, wantPorts)
+	}
+
+	gotCerts := slices.Sorted(maps.Keys(snap.Certificates))
+	wantCerts := []string{"[2001:db8::1]:443:www.example.net"}
+
+	if !slices.Equal(gotCerts, wantCerts) {
+		t.Errorf("certificate entries %v, want %v", gotCerts, wantCerts)
+	}
+
+	title := "Port Change: [2001:db8::1]:443"
+	want := `Hostnames: www.example.net
+Address: [2001:db8::1]:443
+Port now open`
+
+	got := deps.notifier.getNotifications()
+	if len(got) != 1 || got[0].Title != title || got[0].Message != want {
+		t.Errorf("sent %v, want one %q with message:\n%s", got, title, want)
+	}
+
+	deps.portChecker.closed = true
+
+	w.CheckAllPorts(t.Context())
+
+	gotCerts = slices.Sorted(maps.Keys(deps.state.GetSnapshot().Certificates))
+	if len(gotCerts) != 0 {
+		t.Errorf("certificate entries %v with port 443 closed, want none", gotCerts)
+	}
+}

internal/watcher/message_test.go

@@ -0,0 +1,294 @@
+package watcher_test
+
+import (
+	"maps"
+	"strings"
+	"testing"
+
+	"sneak.berlin/go/dnswatcher/internal/state"
+	"sneak.berlin/go/dnswatcher/internal/watcher"
+)
+
+// When one nameserver's A record changes and its TXT record does not,
+// the record change and the inconsistency it starts name the A record
+// alone, with its values written as plain text.
+func TestChangeMessagesNameTheChangedType(t *testing.T) {
+	t.Parallel()
+
+	// A nameserver's records: this A address and the same TXT record.
+	records := func(address string) map[string][]string {
+		return map[string][]string{
+			"A":   {address},
+			"TXT": {"v=spf1 -all"},
+		}
+	}
+
+	before := hostnameState(map[string]map[string][]string{
+		nsA: records(ip1),
+		nsB: records(ip1),
+	})
+	after := hostnameState(map[string]map[string][]string{
+		nsA: records(ip1),
+		nsB: records(ip2),
+	})
+
+	// The hostname change detection uses only the notifier.
+	notifier := &mockNotifier{}
+	w := watcher.NewForTest(nil, nil, nil, nil, nil, notifier)
+
+	w.DetectHostnameChanges(t.Context(), host, before, after)
+
+	want := map[string]string{
+		"Record Change: " + host: `Hostname: www.example.net
+Nameserver: b.ns.example.net.
+Type: A
+Old: 192.0.2.1
+New: 192.0.2.2`,
+		"Inconsistency: " + host: `Hostname: www.example.net
+Type: A
+a.ns.example.net.: 192.0.2.1
+b.ns.example.net.: 192.0.2.2`,
+	}
+
+	notifications := notifier.getNotifications()
+	if len(notifications) != len(want) {
+		t.Fatalf(
+			"sent %d notifications, want %d: %v",
+			len(notifications), len(want), notifications,
+		)
+	}
+
+	for _, n := range notifications {
+		if n.Message != want[n.Title] {
+			t.Errorf(
+				"%s message:\n%s\nwant:\n%s",
+				n.Title, n.Message, want[n.Title],
+			)
+		}
+	}
+}
+
+// Every kind of notification about a configured apex domain's own
+// records names it as a domain.
+func TestDomainRecordNotificationsNameTheDomain(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{domain}
+
+	deps := newTestDeps(t, cfg)
+	w := watcher.NewForTest(cfg, deps.state, nil, nil, nil, deps.notifier)
+
+	// nsA's address changes, which also makes it differ from nsC; nsB
+	// fails; nsC answers again.
+	w.DetectHostnameChanges(t.Context(), domain,
+		saved(map[string]*state.NameserverRecordState{
+			nsA: answered(map[string][]string{"A": {ip1}}),
+			nsB: answered(map[string][]string{"A": {ip1}}),
+			nsC: failed(),
+		}),
+		saved(map[string]*state.NameserverRecordState{
+			nsA: answered(map[string][]string{"A": {ip2}}),
+			nsB: failed(),
+			nsC: answered(map[string][]string{"A": {ip1}}),
+		}),
+	)
+
+	// The address at the end of its CNAME chain changes.
+	w.DetectHostnameChanges(
+		t.Context(), domain, cnameState(ip1), cnameState(ip2),
+	)
+
+	want := map[string]int{
+		"Record Change":        1,
+		"Inconsistency":        1,
+		"NS Failure":           1,
+		"NS Recovery":          1,
+		"CNAME Address Change": 1,
+	}
+
+	sent := make(map[string]int)
+
+	for _, n := range deps.notifier.getNotifications() {
+		kind, _, _ := strings.Cut(n.Title, ":")
+		sent[kind]++
+
+		if !strings.HasPrefix(n.Message, "Domain: "+domain+"\n") {
+			t.Errorf("%s message does not name the domain:\n%s",
+				n.Title, n.Message)
+		}
+	}
+
+	if !maps.Equal(sent, want) {
+		t.Errorf("sent %v, want %v", sent, want)
+	}
+}
+
+// nsB, which answered, and nsC, which did not, are no longer among the
+// nameservers. One NS Change lists both, for the hostname and for the
+// configured apex domain with no delegation of its own. Nothing is sent
+// for the domain whose delegation on the previous check listed them:
+// the check of its delegation sends its NS Change.
+func TestRemovedNameserversAreAnNSChange(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name   string
+		target string
+		// The domain's nameservers saved by the previous check.
+		delegation []string
+		// The NS Change sent, or "" for none.
+		want string
+	}{
+		{
+			name:   "hostname",
+			target: host,
+			want: `Hostname: www.example.net
+Removed: b.ns.example.net., c.ns.example.net.`,
+		},
+		{
+			name:       "domain with no delegation of its own",
+			target:     domain,
+			delegation: []string{},
+			want: `Domain: example.net
+Removed: b.ns.example.net., c.ns.example.net.`,
+		},
+		{
+			name:       "domain whose delegation listed them",
+			target:     domain,
+			delegation: []string{nsA, nsB, nsC},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			cfg := defaultTestConfig(t)
+			cfg.Domains = []string{domain}
+
+			deps := newTestDeps(t, cfg)
+			w := watcher.NewForTest(
+				cfg, deps.state, nil, nil, nil, deps.notifier,
+			)
+
+			deps.state.SetDomainState(domain, &state.DomainState{
+				Nameservers: tt.delegation,
+			})
+
+			prev := saved(map[string]*state.NameserverRecordState{
+				nsA: answered(map[string][]string{"A": {ip1}}),
+				nsB: answered(map[string][]string{"A": {ip1}}),
+				nsC: failed(),
+			})
+			current := saved(map[string]*state.NameserverRecordState{
+				nsA: answered(map[string][]string{"A": {ip1}}),
+			})
+
+			w.DetectHostnameChanges(t.Context(), tt.target, prev, current)
+
+			got := deps.notifier.getNotifications()
+
+			if tt.want == "" {
+				if len(got) != 0 {
+					t.Errorf("sent %v, want nothing", got)
+				}
+
+				return
+			}
+
+			title := "NS Change: " + tt.target
+			if len(got) != 1 || got[0].Title != title ||
+				got[0].Message != tt.want {
+				t.Errorf("sent %v, want one %q with message:\n%s",
+					got, title, tt.want)
+			}
+		})
+	}
+}
+
+// The startup notification counts the configured domains and hostnames,
+// although the state's hostnames also hold the apex domain's own
+// records. Nothing is looked up: the watcher has no resolver.
+func TestStartupNotificationCountsConfiguredNames(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.SendTestNotification = true
+	cfg.Domains = []string{domain}
+	cfg.Hostnames = []string{host}
+
+	deps := newTestDeps(t, cfg)
+	w := watcher.NewForTest(cfg, deps.state, nil, nil, nil, deps.notifier)
+
+	// The state a check of both names saves.
+	deps.state.SetDomainState(domain, &state.DomainState{
+		Nameservers: []string{nsA},
+	})
+
+	for _, name := range []string{domain, host} {
+		deps.state.SetHostnameState(name, saved(
+			map[string]*state.NameserverRecordState{
+				nsA: answered(map[string][]string{"A": {ip1}}),
+			},
+		))
+	}
+
+	w.MaybeSendTestNotification(t.Context())
+
+	notifications := deps.notifier.getNotifications()
+
+	counts := "\nMonitoring 1 domain(s) and 1 hostname(s).\n"
+	if len(notifications) != 1 ||
+		!strings.Contains(notifications[0].Message, counts) {
+		t.Errorf("sent %v, want one message with %q", notifications, counts)
+	}
+}
+
+// A Port Change notification lists the configured apex domain and the
+// hostname that resolve to the port's address on separate lines. The
+// port checks read the saved hostname state and look nothing up, so the
+// watcher has no resolver.
+func TestPortChangeListsDomainsApartFromHostnames(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{domain}
+	cfg.Hostnames = []string{host}
+
+	deps := newTestDeps(t, cfg)
+	w := watcher.NewForTest(
+		cfg, deps.state, nil,
+		deps.portChecker, deps.tlsChecker, deps.notifier,
+	)
+	w.SetFirstRun(false)
+
+	// Both names resolve to ip1, whose port 443 the previous check
+	// found open. It is closed now.
+	for _, name := range []string{domain, host} {
+		deps.state.SetHostnameState(name, saved(
+			map[string]*state.NameserverRecordState{
+				nsA: answered(map[string][]string{"A": {ip1}}),
+			},
+		))
+	}
+
+	key := ip1 + ":443"
+	deps.state.SetPortState(key, &state.PortState{
+		Open: true, Hostnames: []string{domain, host},
+	})
+	deps.portChecker.closed = true
+
+	w.CheckAllPorts(t.Context())
+
+	title := "Port Change: " + key
+	want := `Domains: example.net
+Hostnames: www.example.net
+Address: 192.0.2.1:443
+Port now closed`
+
+	got := deps.notifier.getNotifications()
+	if len(got) != 1 || got[0].Title != title || got[0].Message != want {
+		t.Errorf("sent %v, want one %q with message:\n%s", got, title, want)
+	}
+}

internal/watcher/nsaddress_test.go

@@ -0,0 +1,151 @@
+package watcher_test
+
+import (
+	"context"
+	"log/slog"
+	"reflect"
+	"testing"
+
+	"sneak.berlin/go/dnswatcher/internal/livednstest"
+	"sneak.berlin/go/dnswatcher/internal/resolver"
+	"sneak.berlin/go/dnswatcher/internal/watcher"
+)
+
+const domain = "example.net"
+
+func TestNSAddressChangeAlerts(t *testing.T) {
+	t.Parallel()
+
+	// Each case is the nameserver addresses saved by the previous check
+	// and by the current one.
+	tests := []struct {
+		name          string
+		prev, current map[string][]string
+		want          int
+	}{
+		{
+			"same addresses",
+			map[string][]string{nsA: {ip1, ip2}},
+			map[string][]string{nsA: {ip1, ip2}},
+			0,
+		},
+		{
+			"same addresses in another order",
+			map[string][]string{nsA: {ip2, ip1}},
+			map[string][]string{nsA: {ip1, ip2}},
+			0,
+		},
+		{
+			"address replaced",
+			map[string][]string{nsA: {ip1}},
+			map[string][]string{nsA: {ip2}},
+			1,
+		},
+		{
+			"address added",
+			map[string][]string{nsA: {ip1}},
+			map[string][]string{nsA: {ip1, ip2}},
+			1,
+		},
+		{
+			"two nameservers changed",
+			map[string][]string{nsA: {ip1}, nsB: {ip2}},
+			map[string][]string{nsA: {ip3}, nsB: {ip3}},
+			2,
+		},
+		{
+			"nameserver added",
+			map[string][]string{nsA: {ip1}},
+			map[string][]string{nsA: {ip1}, nsB: {ip2}},
+			0,
+		},
+		{
+			"nameserver removed",
+			map[string][]string{nsA: {ip1}, nsB: {ip2}},
+			map[string][]string{nsA: {ip1}},
+			0,
+		},
+		{
+			"state file from before addresses were saved",
+			nil,
+			map[string][]string{nsA: {ip1}, nsB: {ip2}},
+			0,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			notifier := &mockNotifier{}
+			w := watcher.NewForTest(nil, nil, nil, nil, nil, notifier)
+
+			w.DetectNSAddressChanges(t.Context(), domain, tt.prev, tt.current)
+
+			got := len(notifier.getNotifications())
+			if got != tt.want {
+				t.Errorf("sent %d address changes, want %d", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestNSAddressChangeAlertNamesDomainNameserverAndAddresses(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	notifier := &mockNotifier{}
+	w := watcher.NewForTest(nil, nil, nil, nil, nil, notifier)
+
+	w.DetectNSAddressChanges(
+		t.Context(), domain,
+		map[string][]string{nsA: {ip1}},
+		map[string][]string{nsA: {ip2, ip3}},
+	)
+
+	want := notification{
+		Title: "NS Address Change: " + domain,
+		Message: "Domain: " + domain + "\nNameserver: " + nsA +
+			"\nOld: " + ip1 + "\nNew: " + ip2 + ", " + ip3,
+		Priority: "warning",
+	}
+
+	got := notifier.getNotifications()
+	if len(got) != 1 || got[0] != want {
+		t.Errorf("sent %v, want %v", got, want)
+	}
+}
+
+// TestNameserverWithNoAddressKeepsPrevious looks up nameserver names
+// with no address: two under .invalid, whose lookup fails with an
+// error, and one that does not exist under a real zone, which live DNS
+// answers with no address and no error. Each one with addresses saved
+// by the previous check keeps them; the one without gets none.
+func TestNameserverWithNoAddressKeepsPrevious(t *testing.T) {
+	t.Parallel()
+
+	w := watcher.NewForTest(
+		nil, nil, resolver.NewFromLogger(slog.Default()), nil, nil, nil,
+	)
+
+	nonexistentNS := "this-surely-does-not-exist-xyz." + testSmallDomain + "."
+
+	prev := map[string][]string{oldNS1: {oldIP}, nonexistentNS: {oldIP}}
+
+	var got map[string][]string
+
+	// The result is the same whether or not live DNS answers, so the
+	// lookup is not retried.
+	_ = livednstest.Run(func(ctx context.Context) error {
+		got = w.ResolveNameserverAddresses(
+			ctx, []string{oldNS1, oldNS2, nonexistentNS}, prev,
+		)
+
+		return nil
+	})
+
+	if !reflect.DeepEqual(got, prev) {
+		t.Errorf("saved %v, want %v", got, prev)
+	}
+}

internal/watcher/nsfailure_test.go

@@ -2,6 +2,7 @@ package watcher_test
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"log/slog"
 	"strings"
@@ -14,6 +15,10 @@ import (
 	"sneak.berlin/go/dnswatcher/internal/watcher"
 )
 
+// errNoReply is why a walk that got no reply from a zone's servers
+// failed.
+var errNoReply = errors.New("all servers failed: i/o timeout")
+
 // answered is what a check saves for a nameserver that answered with
 // these records.
 func answered(records map[string][]string) *state.NameserverRecordState {
@@ -183,6 +188,134 @@ func TestNSFailureAlertNamesHostnameNameserverAndReason(t *testing.T) {
 	}
 }
 
+// TestZoneNameserversAllStopAnswering runs three checks of host from
+// the point where its lookup has returned. On the first, nsA and nsB,
+// the nameservers of its zone, answer. On the second, the lookup fails
+// with the error the walk to them returns when neither answers (see
+// the resolver's TestFollowDelegation_NoAnswerAfterReferral), given
+// here because no live zone has nameservers that never answer. For a
+// hostname it is the lookup of its records that fails, and for a domain
+// with no delegation of its own the lookup of its delegation. Both are
+// saved as failed, with the reason, and each gets an NS Failure. On the
+// third, both answer, and each gets an NS Recovery. A domain's records
+// are checked as a hostname's, so its first and third checks are too.
+func TestZoneNameserversAllStopAnswering(t *testing.T) {
+	t.Parallel()
+
+	records := map[string][]string{"A": {ip1}}
+	bothAnswer := map[string]*resolver.NameserverResponse{
+		nsA: response(records), nsB: response(records),
+	}
+	noAnswer := &resolver.NoAnswerError{
+		Nameservers: []string{nsA, nsB}, Err: errNoReply,
+	}
+
+	tests := []struct {
+		name     string
+		isDomain bool
+	}{
+		{"hostname", false},
+		{"domain with no delegation of its own", true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			cfg := defaultTestConfig(t)
+			if tt.isDomain {
+				cfg.Domains = []string{host}
+			} else {
+				cfg.Hostnames = []string{host}
+			}
+
+			// The watcher is given each lookup's result, so it has no
+			// resolver.
+			deps := newTestDeps(t, cfg)
+			w := watcher.NewForTest(
+				cfg, deps.state, nil,
+				deps.portChecker, deps.tlsChecker, deps.notifier,
+			)
+			w.SetFirstRun(false)
+
+			w.CheckHostnameResult(t.Context(), host, bothAnswer, nil)
+
+			if tt.isDomain {
+				w.CheckDomainResult(t.Context(), host, nil, noAnswer)
+			} else {
+				w.CheckHostnameResult(t.Context(), host, nil, noAnswer)
+			}
+
+			current, _ := deps.state.GetHostnameState(host)
+
+			for _, ns := range []string{nsA, nsB} {
+				got := current.RecordsByNameserver[ns]
+				if got.Status != failed().Status || got.Error != errNoReply.Error() {
+					t.Errorf(
+						"%s saved with status %q, error %q; want %q, %q",
+						ns, got.Status, got.Error, failed().Status, errNoReply,
+					)
+				}
+			}
+
+			if n := countNotifications(deps, "NS Failure: "+host); n != 2 {
+				t.Errorf("sent %d NS Failure notifications, want 2", n)
+			}
+
+			w.CheckHostnameResult(t.Context(), host, bothAnswer, nil)
+
+			if n := countNotifications(deps, "NS Recovery: "+host); n != 2 {
+				t.Errorf("sent %d NS Recovery notifications, want 2", n)
+			}
+		})
+	}
+}
+
+// TestFailedNameserversOnlyForThoseOfThePreviousCheck gives
+// FailedNameservers lookup errors after a check in which nsA and nsB
+// answered. Only an error that names both makes them failed.
+func TestFailedNameserversOnlyForThoseOfThePreviousCheck(t *testing.T) {
+	t.Parallel()
+
+	records := map[string][]string{"A": {ip1}}
+	bothAnswered := saved(map[string]*state.NameserverRecordState{
+		nsA: answered(records), nsB: answered(records),
+	})
+	noAnswer := func(nameservers ...string) error {
+		return &resolver.NoAnswerError{Nameservers: nameservers, Err: errNoReply}
+	}
+
+	tests := []struct {
+		name       string
+		err        error
+		prev       *state.HostnameState
+		wantFailed bool
+	}{
+		{"both did not answer", noAnswer(nsA, nsB), bothAnswered, true},
+		{
+			"the servers of a parent zone did not answer",
+			noAnswer(nsC), bothAnswered, false,
+		},
+		{
+			"the zone's delegation lists only nsA now",
+			noAnswer(nsA), bothAnswered, false,
+		},
+		{"no root server answered", errNoReply, bothAnswered, false},
+		{"no previous check", noAnswer(nsA, nsB), nil, false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got := watcher.FailedNameservers(tt.err, tt.prev)
+			if (got != nil) != tt.wantFailed {
+				t.Errorf("returned %v, want failed: %v", got, tt.wantFailed)
+			}
+		})
+	}
+}
+
 // TestNameserverThatNeverAnswers asks a nameserver address where
 // nothing answers, 192.0.2.1, and checks what the watcher saves for it.
 // The deadline outlasts the resolver's first two-second try, as in the
@@ -201,7 +334,7 @@ func TestNameserverThatNeverAnswers(t *testing.T) {
 	}
 
 	hs := watcher.BuildHostnameState(
-		map[string]*resolver.NameserverResponse{nsA: resp}, time.Now(),
+		map[string]*resolver.NameserverResponse{nsA: resp}, nil, time.Now(),
 	)
 
 	got := hs.RecordsByNameserver[nsA]
@@ -256,7 +389,7 @@ func TestNameserverThatAnswersNXDOMAIN(t *testing.T) {
 	}
 
 	hs := watcher.BuildHostnameState(
-		map[string]*resolver.NameserverResponse{ns: resp}, time.Now(),
+		map[string]*resolver.NameserverResponse{ns: resp}, nil, time.Now(),
 	)
 
 	got := hs.RecordsByNameserver[ns]
@@ -320,7 +453,7 @@ func TestNameserverThatRefuses(t *testing.T) {
 	}
 
 	hs := watcher.BuildHostnameState(
-		map[string]*resolver.NameserverResponse{ns: resp}, time.Now(),
+		map[string]*resolver.NameserverResponse{ns: resp}, nil, time.Now(),
 	)
 
 	got := hs.RecordsByNameserver[ns]
@@ -331,3 +464,118 @@ func TestNameserverThatRefuses(t *testing.T) {
 		)
 	}
 }
+
+// TestPortStateWhenNoNameserverAnswered runs the port checks on
+// hostname state built here, which gives the name no address. The port
+// state saved for its old address is kept only when the name is a
+// configured hostname or domain and none of its nameservers answered.
+func TestPortStateWhenNoNameserverAnswered(t *testing.T) {
+	t.Parallel()
+
+	noneAnswered := saved(map[string]*state.NameserverRecordState{
+		nsA: failed(), nsB: failed(),
+	})
+	oneAnsweredNoAddress := saved(map[string]*state.NameserverRecordState{
+		nsA: answered(map[string][]string{}), nsB: failed(),
+	})
+
+	configured := []string{host}
+
+	tests := []struct {
+		name      string
+		hostname  *state.HostnameState
+		hostnames []string
+		domains   []string
+		wantKept  bool
+	}{
+		{"no nameserver answered", noneAnswered, configured, nil, true},
+		{
+			"no nameserver answered, configured as a domain",
+			noneAnswered, nil, configured, true,
+		},
+		{
+			"one answered with no address",
+			oneAnsweredNoAddress, configured, nil, false,
+		},
+		{"no nameserver answered, not configured", noneAnswered, nil, nil, false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			cfg := defaultTestConfig(t)
+			cfg.Hostnames = tt.hostnames
+			cfg.Domains = tt.domains
+
+			// The port checks read the saved hostname state and look
+			// nothing up, so the watcher has no resolver.
+			deps := newTestDeps(t, cfg)
+			w := watcher.NewForTest(
+				cfg, deps.state, nil,
+				deps.portChecker, deps.tlsChecker, deps.notifier,
+			)
+
+			key := ip1 + ":443"
+
+			deps.state.SetHostnameState(host, tt.hostname)
+			deps.state.SetPortState(key, &state.PortState{
+				Open: true, Hostnames: []string{host},
+			})
+
+			w.CheckAllPorts(t.Context())
+
+			_, kept := deps.state.GetPortState(key)
+			if kept != tt.wantKept {
+				t.Errorf("port state %s kept: %v, want %v", key, kept, tt.wantKept)
+			}
+		})
+	}
+}
+
+// TestPortStateWhenNoNameserverAnsweredAndOtherNameMovesAway saves the
+// port state of an address two configured hostnames resolve to. While
+// none of the first one's nameservers answer, the port checks run with
+// the other one still at that address, then after it moved away; the
+// port state is kept both times.
+func TestPortStateWhenNoNameserverAnsweredAndOtherNameMovesAway(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	const other = "mail.example.net"
+
+	cfg := defaultTestConfig(t)
+	cfg.Hostnames = []string{host, other}
+
+	// The port checks read the saved hostname state and look nothing
+	// up, so the watcher has no resolver.
+	deps := newTestDeps(t, cfg)
+	w := watcher.NewForTest(
+		cfg, deps.state, nil,
+		deps.portChecker, deps.tlsChecker, deps.notifier,
+	)
+
+	key := ip1 + ":443"
+
+	deps.state.SetPortState(key, &state.PortState{
+		Open: true, Hostnames: []string{host, other},
+	})
+	deps.state.SetHostnameState(host, saved(
+		map[string]*state.NameserverRecordState{nsA: failed(), nsB: failed()},
+	))
+
+	for _, otherIP := range []string{ip1, ip2} {
+		deps.state.SetHostnameState(other, saved(
+			map[string]*state.NameserverRecordState{
+				nsA: answered(map[string][]string{"A": {otherIP}}),
+			},
+		))
+
+		w.CheckAllPorts(t.Context())
+
+		if _, kept := deps.state.GetPortState(key); !kept {
+			t.Fatalf("port state %s removed with %s at %s", key, other, otherIP)
+		}
+	}
+}

internal/watcher/removed_test.go

@@ -0,0 +1,291 @@
+package watcher_test
+
+import (
+	"maps"
+	"net"
+	"slices"
+	"strings"
+	"testing"
+
+	"sneak.berlin/go/dnswatcher/internal/state"
+	"sneak.berlin/go/dnswatcher/internal/watcher"
+)
+
+// TestRemovedTargetsLeaveTheState loads a state saved while a domain
+// and a hostname now removed from the configuration were still in it,
+// and runs the removal that Run does before the first check. The
+// removed names' domain, hostname and certificate entries are gone,
+// the configured names' are kept, and nothing is notified. Nothing is
+// looked up: the watcher has no resolver.
+func TestRemovedTargetsLeaveTheState(t *testing.T) {
+	t.Parallel()
+
+	const (
+		removedDomain = "example.com"
+		removedHost   = "www.example.com"
+	)
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{domain}
+	cfg.Hostnames = []string{host}
+
+	deps := newTestDeps(t, cfg)
+	w := watcher.NewForTest(
+		cfg, deps.state, nil,
+		deps.portChecker, deps.tlsChecker, deps.notifier,
+	)
+
+	// The state a check of all four names saves, each name at ip1.
+	for _, name := range []string{domain, removedDomain} {
+		deps.state.SetDomainState(name, &state.DomainState{
+			Nameservers: []string{nsA},
+		})
+	}
+
+	for _, name := range []string{domain, host, removedDomain, removedHost} {
+		deps.state.SetHostnameState(name, saved(
+			map[string]*state.NameserverRecordState{
+				nsA: answered(map[string][]string{"A": {ip1}}),
+			},
+		))
+		deps.state.SetCertificateState(
+			ip1+":443:"+name, &state.CertificateState{Status: "ok"},
+		)
+	}
+
+	err := deps.state.Save()
+	if err != nil {
+		t.Fatalf("saving the state: %v", err)
+	}
+
+	err = deps.state.Load()
+	if err != nil {
+		t.Fatalf("loading the state: %v", err)
+	}
+
+	w.CleanupRemovedTargets()
+
+	snap := deps.state.GetSnapshot()
+
+	got := slices.Sorted(maps.Keys(snap.Domains))
+	if want := []string{domain}; !slices.Equal(got, want) {
+		t.Errorf("domain entries %v, want %v", got, want)
+	}
+
+	got = slices.Sorted(maps.Keys(snap.Hostnames))
+	if want := []string{domain, host}; !slices.Equal(got, want) {
+		t.Errorf("hostname entries %v, want %v", got, want)
+	}
+
+	got = slices.Sorted(maps.Keys(snap.Certificates))
+	if want := []string{
+		ip1 + ":443:" + domain, ip1 + ":443:" + host,
+	}; !slices.Equal(got, want) {
+		t.Errorf("certificate entries %v, want %v", got, want)
+	}
+
+	if sent := deps.notifier.getNotifications(); len(sent) != 0 {
+		t.Errorf("sent %v, want nothing", sent)
+	}
+}
+
+// TestRemovedTargetsLeaveThePortEntries loads a state whose port
+// entries name a domain and a hostname now removed from the
+// configuration, and runs the removal that Run does before the first
+// check. The removed names are off each port entry's list of names, the
+// entry only they had is gone, the entry that also names configured
+// names is kept for the port checks, and nothing is notified.
+func TestRemovedTargetsLeaveThePortEntries(t *testing.T) {
+	t.Parallel()
+
+	const (
+		removedDomain = "example.com"
+		removedHost   = "www.example.com"
+	)
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{domain}
+	cfg.Hostnames = []string{host}
+
+	deps := newTestDeps(t, cfg)
+	w := watcher.NewForTest(
+		cfg, deps.state, nil,
+		deps.portChecker, deps.tlsChecker, deps.notifier,
+	)
+
+	// The port 443 entries a check of all four names saves: each name
+	// at ip1, except the removed hostname, at ip2.
+	deps.state.SetPortState(ip1+":443", &state.PortState{
+		Open: true, Hostnames: []string{removedDomain, domain, host},
+	})
+	deps.state.SetPortState(ip2+":443", &state.PortState{
+		Open: true, Hostnames: []string{removedHost},
+	})
+
+	err := deps.state.Save()
+	if err != nil {
+		t.Fatalf("saving the state: %v", err)
+	}
+
+	err = deps.state.Load()
+	if err != nil {
+		t.Fatalf("loading the state: %v", err)
+	}
+
+	w.CleanupRemovedTargets()
+
+	if sent := deps.notifier.getNotifications(); len(sent) != 0 {
+		t.Errorf("sent %v, want nothing", sent)
+	}
+
+	snap := deps.state.GetSnapshot()
+
+	got := slices.Sorted(maps.Keys(snap.Ports))
+	if want := []string{ip1 + ":443"}; !slices.Equal(got, want) {
+		t.Fatalf("port entries %v, want %v", got, want)
+	}
+
+	got = snap.Ports[ip1+":443"].Hostnames
+	if want := []string{domain, host}; !slices.Equal(got, want) {
+		t.Errorf("names of port entry %s:443 %v, want %v", ip1, got, want)
+	}
+}
+
+// TestCertificateStateForAnAddressGone runs the port checks on hostname
+// state built here for a configured hostname, with certificate entries
+// saved for it at ip1, ip2 and an IPv6 address. When its nameservers
+// answered with ip1 and the IPv6 address, the entry for ip2 is removed.
+// When none of them answered, its addresses are not known, and every
+// entry is kept. Nothing is notified, and nothing is looked up.
+func TestCertificateStateForAnAddressGone(t *testing.T) {
+	t.Parallel()
+
+	const ip6 = "2001:db8::1"
+
+	tests := []struct {
+		name     string
+		hostname *state.HostnameState
+		want     []string
+	}{
+		{
+			"answered without ip2",
+			saved(map[string]*state.NameserverRecordState{
+				nsA: answered(map[string][]string{
+					"A": {ip1}, "AAAA": {ip6},
+				}),
+			}),
+			[]string{ip1 + ":443:" + host, "[" + ip6 + "]:443:" + host},
+		},
+		{
+			"no nameserver answered",
+			saved(map[string]*state.NameserverRecordState{
+				nsA: failed(), nsB: failed(),
+			}),
+			[]string{
+				ip1 + ":443:" + host,
+				ip2 + ":443:" + host,
+				"[" + ip6 + "]:443:" + host,
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			cfg := defaultTestConfig(t)
+			cfg.Hostnames = []string{host}
+
+			deps := newTestDeps(t, cfg)
+			w := watcher.NewForTest(
+				cfg, deps.state, nil,
+				deps.portChecker, deps.tlsChecker, deps.notifier,
+			)
+			w.SetFirstRun(false)
+
+			deps.state.SetHostnameState(host, tt.hostname)
+
+			for _, ip := range []string{ip1, ip2, ip6} {
+				deps.state.SetCertificateState(
+					net.JoinHostPort(ip, "443")+":"+host,
+					&state.CertificateState{Status: "ok"},
+				)
+			}
+
+			w.CheckAllPorts(t.Context())
+
+			got := slices.Sorted(maps.Keys(deps.state.GetSnapshot().Certificates))
+			if !slices.Equal(got, tt.want) {
+				t.Errorf("certificate entries %v, want %v", got, tt.want)
+			}
+
+			if sent := deps.notifier.getNotifications(); len(sent) != 0 {
+				t.Errorf("sent %v, want nothing", sent)
+			}
+		})
+	}
+}
+
+// TestCertificateStateForAPortClosed runs the port checks on hostname
+// and port state built here for a configured hostname at ip1, whose
+// port 443 the previous check found open and whose certificate entry
+// is ok. The port is closed now: the certificate entry is removed, and
+// only the Port Change is notified. When the port opens again, the next
+// TLS check saves the certificate as new and notifies nothing about it.
+// Nothing is looked up.
+func TestCertificateStateForAPortClosed(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Hostnames = []string{host}
+
+	deps := newTestDeps(t, cfg)
+	w := watcher.NewForTest(
+		cfg, deps.state, nil,
+		deps.portChecker, deps.tlsChecker, deps.notifier,
+	)
+	w.SetFirstRun(false)
+
+	certKey := ip1 + ":443:" + host
+
+	deps.state.SetHostnameState(host, saved(
+		map[string]*state.NameserverRecordState{
+			nsA: answered(map[string][]string{"A": {ip1}}),
+		},
+	))
+	deps.state.SetPortState(ip1+":443", &state.PortState{
+		Open: true, Hostnames: []string{host},
+	})
+	deps.state.SetCertificateState(certKey, &state.CertificateState{
+		CommonName: host, Status: "ok",
+	})
+	deps.portChecker.closed = true
+
+	w.CheckAllPorts(t.Context())
+
+	if _, ok := deps.state.GetCertificateState(certKey); ok {
+		t.Errorf("certificate entry %s kept with port 443 closed", certKey)
+	}
+
+	sent := deps.notifier.getNotifications()
+	if title := "Port Change: " + ip1 + ":443"; len(sent) != 1 ||
+		sent[0].Title != title {
+		t.Errorf("sent %v, want one %q", sent, title)
+	}
+
+	deps.portChecker.closed = false
+
+	w.CheckAllPorts(t.Context())
+	w.RunTLSChecks(t.Context())
+
+	cert, ok := deps.state.GetCertificateState(certKey)
+	if !ok || cert.Status != "ok" {
+		t.Errorf("certificate entry %s after port 443 opened: %+v", certKey, cert)
+	}
+
+	for _, n := range deps.notifier.getNotifications() {
+		if strings.HasPrefix(n.Title, "TLS") {
+			t.Errorf("sent %v, want no TLS notification", n)
+		}
+	}
+}

internal/watcher/skiprecordnotifications_test.go

@@ -0,0 +1,107 @@
+package watcher_test
+
+import (
+	"slices"
+	"testing"
+
+	"sneak.berlin/go/dnswatcher/internal/config"
+	"sneak.berlin/go/dnswatcher/internal/state"
+	"sneak.berlin/go/dnswatcher/internal/watcher"
+)
+
+// TestSkipRecordNotificationsAlerts runs the hostname change detection
+// for two names on the same check: nsA's address changes, so that nsA
+// now differs from nsB, and nsC stops answering. The name in
+// SkipRecordNotifications gets only the NS Failure; the other name also
+// gets the Record Change and the Inconsistency.
+func TestSkipRecordNotificationsAlerts(t *testing.T) {
+	t.Parallel()
+
+	const skipped = "skipped.example.net"
+
+	prev := saved(map[string]*state.NameserverRecordState{
+		nsA: answered(map[string][]string{"A": {ip1}}),
+		nsB: answered(map[string][]string{"A": {ip1}}),
+		nsC: answered(map[string][]string{"A": {ip1}}),
+	})
+	current := saved(map[string]*state.NameserverRecordState{
+		nsA: answered(map[string][]string{"A": {ip2}}),
+		nsB: answered(map[string][]string{"A": {ip1}}),
+		nsC: failed(),
+	})
+
+	cfg := &config.Config{
+		Hostnames:               []string{host, skipped},
+		SkipRecordNotifications: []string{skipped},
+	}
+
+	// The hostname change detection uses only the configuration and the
+	// notifier.
+	notifier := &mockNotifier{}
+	w := watcher.NewForTest(cfg, nil, nil, nil, nil, notifier)
+
+	w.DetectHostnameChanges(t.Context(), host, prev, current)
+	w.DetectHostnameChanges(t.Context(), skipped, prev, current)
+
+	sent := notifier.getNotifications()
+	titles := make([]string, 0, len(sent))
+
+	for _, n := range sent {
+		titles = append(titles, n.Title)
+	}
+
+	slices.Sort(titles)
+
+	want := []string{
+		"Inconsistency: " + host,
+		"NS Failure: " + skipped,
+		"NS Failure: " + host,
+		"Record Change: " + host,
+	}
+
+	if !slices.Equal(titles, want) {
+		t.Errorf("sent %v, want %v", titles, want)
+	}
+}
+
+// TestSkipRecordNotificationsCheck checks testHost, which is in
+// SkipRecordNotifications, from a saved state in which every nameserver
+// live DNS lists answered with an address live DNS never returns. No
+// Record Change and no Inconsistency is sent, and the check still saves
+// what the nameservers answer.
+func TestSkipRecordNotificationsCheck(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Hostnames = []string{testHost}
+	cfg.SkipRecordNotifications = []string{testHost}
+
+	nameservers := lookupNameservers(t, testHost)
+
+	_, deps := runChecks(t, cfg, func(deps *testDeps) {
+		byNameserver := make(map[string]*state.NameserverRecordState)
+		for _, ns := range nameservers {
+			byNameserver[ns] = answered(map[string][]string{"A": {oldIP}})
+		}
+
+		deps.state.SetHostnameState(testHost, saved(byNameserver))
+	})
+
+	for _, title := range []string{
+		"Record Change: " + testHost,
+		"Inconsistency: " + testHost,
+	} {
+		if n := countNotifications(deps, title); n != 0 {
+			t.Errorf("sent %d %q, want 0", n, title)
+		}
+	}
+
+	// A nameserver whose query for A failed keeps oldIP, so the check
+	// is that some address live DNS gave was saved.
+	hs, _ := deps.state.GetHostnameState(testHost)
+	fromLiveDNS := func(ip string) bool { return ip != oldIP }
+
+	if !slices.ContainsFunc(addresses(hs), fromLiveDNS) {
+		t.Errorf("saved addresses %v, want those live DNS gave", addresses(hs))
+	}
+}

internal/watcher/watcher_test.go

@@ -4,8 +4,10 @@ import (
 	"context"
 	"fmt"
 	"log/slog"
+	"net"
 	"os"
 	"slices"
+	"strings"
 	"sync"
 	"testing"
 	"time"
@@ -25,13 +27,23 @@ import (
 
 // The watcher looks these names up in live DNS with the real resolver,
 // so tests assert on what the watcher does with the answers, never on
-// the records these zones publish. testHost's nameservers and addresses
+// the records these zones publish. The nameservers of testHost and
-// stay the same from one check to the next, which the tests that check
+// testSmallDomain stay the same between a test looking them up and its
-// it twice rely on.
+// check. Every query a check sends is one more that can be lost, so the
+// tests keep them few. A check asks each of a name's nameservers about
+// every record type, and both names have two. A domain check also looks
+// up each nameserver's addresses at every nameserver of the zone that
+// nameserver is in: testSmallDomain's nameservers are in zones with two
+// nameservers, while a domain whose nameservers are in, say,
+// cloudflare.com, which has five, makes each domain check much longer.
+// A test checks a domain only when it is about domains, and checks once,
+// from saved state it builds, rather than twice. The tests that query
+// testDomain's nameservers directly do no domain check.
 const (
-	testDomain = "google.com"
+	testDomain      = "google.com"
-	testHost   = "cloudflare.com"
+	testSmallDomain = "desec.io"
-	testIssuer = "DigiCert"
+	testHost        = "example.org"
+	testIssuer      = "DigiCert"
 )
 
 // Saved-state values that live DNS never returns: nameserver names
@@ -128,6 +140,22 @@ func (m *mockNotifier) getNotifications() []notification {
 	return result
 }
 
+// cancelOnNotify is a mockNotifier that calls cancel at each
+// notification, as if shutdown cut the check short there.
+type cancelOnNotify struct {
+	*mockNotifier
+
+	cancel context.CancelFunc
+}
+
+func (n cancelOnNotify) SendNotification(
+	ctx context.Context,
+	title, message, priority string,
+) {
+	n.mockNotifier.SendNotification(ctx, title, message, priority)
+	n.cancel()
+}
+
 // --- Helpers to build a Watcher and run its checks against live DNS ---
 
 type testDeps struct {
@@ -206,8 +234,10 @@ func defaultTestConfig(t *testing.T) *config.Config {
 
 // checkOnce runs the watcher's checks once and returns an error when a
 // configured name has no hostname state saved by this check, or that
-// state holds no address. Either live DNS gave no answer for the name,
+// state holds no address, or a configured domain's nameserver has no
-// or the watcher saved no fresh result for it.
+// address saved or still has oldIP, which the tests save and live DNS
+// never returns. Either live DNS gave no answer for the name, or the
+// watcher saved no fresh result for it.
 func checkOnce(
 	ctx context.Context,
 	w *watcher.Watcher,
@@ -231,48 +261,76 @@ func checkOnce(
 		}
 	}
 
+	for _, name := range deps.config.Domains {
+		ds, _ := deps.state.GetDomainState(name)
+		for _, ns := range ds.Nameservers {
+			ips := ds.NameserverAddresses[ns]
+			if len(ips) == 0 || slices.Contains(ips, oldIP) {
+				return fmt.Errorf(
+					"%s: nameserver %s: %w, or the watcher saved "+
+						"no fresh addresses for it",
+					name, ns, livednstest.ErrNoAnswer,
+				)
+			}
+		}
+	}
+
 	return nil
 }
 
 // runChecks builds a watcher, lets prepare set up the saved state and
 // stand-ins it starts from, and runs its checks once against live DNS.
-// If change is not nil, change then alters the saved state or stand-ins
+// When the check finds no fresh address for a name (see checkOnce), the
-// and the checks run a second time. When either check finds no fresh
+// watcher is thrown away and all of this runs again on a new one, so a
-// address for a name (see checkOnce), the watcher is thrown away and
+// failed attempt leaves nothing behind in the saved state, the
-// all of this runs again on a new one, so a failed attempt leaves
+// stand-ins or the notifications.
-// nothing behind in the saved state, the stand-ins or the notifications.
 func runChecks(
 	t *testing.T,
 	cfg *config.Config,
-	prepare, change func(deps *testDeps),
+	prepare func(deps *testDeps),
-) *testDeps {
+) (*watcher.Watcher, *testDeps) {
 	t.Helper()
 
-	var deps *testDeps
+	var (
+		w    *watcher.Watcher
+		deps *testDeps
+	)
 
 	livednstest.Retry(t, "watcher checks", func(ctx context.Context) error {
-		var w *watcher.Watcher
-
 		w, deps = newTestWatcher(t, cfg)
 
 		if prepare != nil {
 			prepare(deps)
 		}
 
-		err := checkOnce(ctx, w, deps)
-		if err != nil || change == nil {
-			return err
-		}
-
-		change(deps)
-
 		return checkOnce(ctx, w, deps)
 	})
 
-	return deps
+	return w, deps
 }
 
-// addresses returns the A and AAAA values saved for a hostname.
+// lookupNameservers returns the nameservers live DNS lists for name,
+// for a test to save in the state its check starts from.
+func lookupNameservers(t *testing.T, name string) []string {
+	t.Helper()
+
+	res := resolver.NewFromLogger(slog.Default())
+
+	var nameservers []string
+
+	livednstest.Retry(t, "LookupNS("+name+")", func(ctx context.Context) error {
+		var err error
+
+		nameservers, err = res.LookupNS(ctx, name)
+
+		return err
+	})
+
+	return nameservers
+}
+
+// addresses returns the A and AAAA values saved for a hostname, and the
+// addresses saved at the end of its CNAME chain.
 func addresses(hs *state.HostnameState) []string {
 	var ips []string
 
@@ -281,7 +339,7 @@ func addresses(hs *state.HostnameState) []string {
 		ips = append(ips, nsState.Records["AAAA"]...)
 	}
 
-	return ips
+	return append(ips, hs.CNAMEAddresses...)
 }
 
 // assertNotified checks that a notification with this title and
@@ -324,13 +382,21 @@ func TestFirstRunBaseline(t *testing.T) {
 	t.Parallel()
 
 	cfg := defaultTestConfig(t)
-	cfg.Domains = []string{testDomain}
+	cfg.Domains = []string{testSmallDomain}
 	cfg.Hostnames = []string{testHost}
 
-	deps := runChecks(t, cfg, nil, nil)
+	_, deps := runChecks(t, cfg, nil)
 
 	assertNoNotifications(t, deps)
 	assertStatePopulated(t, deps)
+
+	// testHost answers with an address, so the check saves an empty list
+	// of CNAME addresses for it; nil would mean the check did not look
+	// at whether to follow a CNAME.
+	hs, _ := deps.state.GetHostnameState(testHost)
+	if hs.CNAMEAddresses == nil || len(hs.CNAMEAddresses) != 0 {
+		t.Errorf("saved CNAME addresses %#v, want []", hs.CNAMEAddresses)
+	}
 }
 
 func assertNoNotifications(
@@ -377,9 +443,9 @@ func TestDomainPortAndTLSChecks(t *testing.T) {
 	t.Parallel()
 
 	cfg := defaultTestConfig(t)
-	cfg.Domains = []string{testDomain}
+	cfg.Domains = []string{testSmallDomain}
 
-	deps := runChecks(t, cfg, nil, nil)
+	_, deps := runChecks(t, cfg, nil)
 
 	snap := deps.state.GetSnapshot()
 
@@ -412,42 +478,330 @@ func TestDomainPortAndTLSChecks(t *testing.T) {
 	}
 }
 
+// TestFirstCheckAfterLoadingFileWithoutSections loads a state file
+// holding {}, and one that leaves out the certificates section, and runs
+// the first check. It saves domain, hostname, port and certificate
+// entries; a section loaded as nil made it panic.
+func TestFirstCheckAfterLoadingFileWithoutSections(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		file string
+	}{
+		{"no sections", `{}`},
+		{"no certificates", `{"domains": {}, "hostnames": {}, "ports": {}}`},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			cfg := defaultTestConfig(t)
+			cfg.Domains = []string{testSmallDomain}
+
+			_, deps := runChecks(t, cfg, func(deps *testDeps) {
+				err := os.WriteFile(cfg.StatePath(), []byte(tt.file), 0o600)
+				if err != nil {
+					t.Fatalf("writing the state file: %v", err)
+				}
+
+				err = deps.state.Load()
+				if err != nil {
+					t.Fatalf("loading the state file: %v", err)
+				}
+			})
+
+			snap := deps.state.GetSnapshot()
+			if len(snap.Domains) == 0 || len(snap.Hostnames) == 0 ||
+				len(snap.Ports) == 0 || len(snap.Certificates) == 0 {
+				t.Errorf(
+					"saved %d domain, %d hostname, %d port and %d "+
+						"certificate entries, want at least one of each",
+					len(snap.Domains), len(snap.Hostnames),
+					len(snap.Ports), len(snap.Certificates),
+				)
+			}
+		})
+	}
+}
+
 func TestNSChangeDetection(t *testing.T) {
 	t.Parallel()
 
 	cfg := defaultTestConfig(t)
-	cfg.Domains = []string{testDomain}
+	cfg.Domains = []string{testSmallDomain}
 
 	// The saved state lists nameservers that live DNS does not.
-	deps := runChecks(t, cfg, func(deps *testDeps) {
+	_, deps := runChecks(t, cfg, func(deps *testDeps) {
-		deps.state.SetDomainState(testDomain, &state.DomainState{
+		deps.state.SetDomainState(testSmallDomain, &state.DomainState{
 			Nameservers: []string{oldNS1, oldNS2},
 		})
-	}, nil)
+	})
 
-	assertNotified(t, deps, "NS Change: "+testDomain, "warning")
+	assertNotified(t, deps, "NS Change: "+testSmallDomain, "warning")
 
-	ds, _ := deps.state.GetDomainState(testDomain)
+	ds, _ := deps.state.GetDomainState(testSmallDomain)
 	if slices.Contains(ds.Nameservers, oldNS1) {
 		t.Errorf("saved nameservers not updated: %v", ds.Nameservers)
 	}
 }
 
+// TestDomainThatDoesNotExist checks a .com domain that does not exist,
+// with nameservers and records saved by an earlier check. The .com
+// servers answer that it does not exist, so it is saved with nxdomain
+// set and no nameservers, an NS Change removes them all, and its saved
+// records are removed rather than asked for at the .com servers.
+func TestDomainThatDoesNotExist(t *testing.T) {
+	t.Parallel()
+
+	const domain = "dnswatcher-test-does-not-exist.com"
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{domain}
+
+	var deps *testDeps
+
+	livednstest.Retry(t, "watcher checks", func(ctx context.Context) error {
+		var w *watcher.Watcher
+
+		w, deps = newTestWatcher(t, cfg)
+
+		deps.state.SetDomainState(domain, &state.DomainState{
+			Nameservers: []string{oldNS1, oldNS2},
+		})
+		deps.state.SetHostnameState(domain, &state.HostnameState{
+			RecordsByNameserver: map[string]*state.NameserverRecordState{
+				oldNS1: {
+					Records: map[string][]string{"A": {oldIP}},
+					Status:  "ok",
+				},
+			},
+		})
+
+		started := time.Now()
+
+		w.RunOnce(ctx)
+
+		// When no server answered, the domain's state is not saved.
+		ds, _ := deps.state.GetDomainState(domain)
+		if ds.LastChecked.Before(started) {
+			return fmt.Errorf("%s: %w", domain, livednstest.ErrNoAnswer)
+		}
+
+		return nil
+	})
+
+	ds, _ := deps.state.GetDomainState(domain)
+	if !ds.NXDomain || len(ds.Nameservers) != 0 {
+		t.Errorf("saved nxdomain %v and nameservers %v, want true and none",
+			ds.NXDomain, ds.Nameservers)
+	}
+
+	if hs, ok := deps.state.GetHostnameState(domain); ok {
+		t.Errorf("records saved for %s: %v", domain, hs.RecordsByNameserver)
+	}
+
+	assertNotified(t, deps, "NS Change: "+domain, "warning")
+
+	// That is the only notification, and it removes both nameservers,
+	// in either order.
+	for _, n := range deps.notifier.getNotifications() {
+		removed := strings.TrimPrefix(
+			n.Message, "Domain: "+domain+"\nAdded: \nRemoved: ",
+		)
+		if removed != oldNS1+", "+oldNS2 && removed != oldNS2+", "+oldNS1 {
+			t.Errorf("unexpected notification: %v", n)
+		}
+	}
+}
+
+// TestDomainWithNoDelegationOfItsOwn checks a domain with no delegation
+// of its own: codeberg.page is on the public suffix list, so
+// docs.codeberg.page is a domain, but the .page servers delegate only
+// codeberg.page, whose servers answer for it. It is saved with no
+// nameservers and without nxdomain, and its records, asked at the
+// codeberg.page servers, are saved. Those are testSmallDomain's two
+// nameservers; github.io, the zone of the README's example, has eight.
+// The previous check saved a delegation to oldNS1, now withdrawn, and
+// records asked at oldNS1. A first check is cut short at its first
+// notification, as shutdown would, and a second runs in full: across
+// them the NS Change of its delegation removes oldNS1, and no other NS
+// Change lists it again.
+func TestDomainWithNoDelegationOfItsOwn(t *testing.T) {
+	t.Parallel()
+
+	const domain = "docs.codeberg.page"
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{domain}
+
+	var deps *testDeps
+
+	livednstest.Retry(t, "watcher checks", func(ctx context.Context) error {
+		deps = newTestDeps(t, cfg)
+
+		firstCtx, cancel := context.WithCancel(ctx)
+		defer cancel()
+
+		w := watcher.NewForTest(
+			cfg,
+			deps.state,
+			resolver.NewFromLogger(slog.Default()),
+			deps.portChecker,
+			deps.tlsChecker,
+			cancelOnNotify{mockNotifier: deps.notifier, cancel: cancel},
+		)
+
+		deps.state.SetDomainState(domain, &state.DomainState{
+			Nameservers: []string{oldNS1},
+		})
+		deps.state.SetHostnameState(domain, saved(
+			map[string]*state.NameserverRecordState{
+				oldNS1: answered(map[string][]string{"A": {oldIP}}),
+			},
+		))
+
+		w.RunOnce(firstCtx)
+
+		err := checkOnce(ctx, w, deps)
+
+		// A domain saved as not existing has no records to wait for;
+		// the checks below fail on it.
+		if ds, ok := deps.state.GetDomainState(domain); ok && ds.NXDomain {
+			return nil
+		}
+
+		return err
+	})
+
+	ds, _ := deps.state.GetDomainState(domain)
+	if ds.NXDomain || len(ds.Nameservers) != 0 {
+		t.Errorf("saved nxdomain %v and nameservers %v, want false and none",
+			ds.NXDomain, ds.Nameservers)
+	}
+
+	if _, ok := deps.state.GetHostnameState(domain); !ok {
+		t.Errorf("no records saved for %s", domain)
+	}
+
+	title := "NS Change: " + domain
+	want := "Domain: " + domain + "\nAdded: \nRemoved: " + oldNS1
+
+	var changes []notification
+
+	for _, n := range deps.notifier.getNotifications() {
+		if n.Title == title {
+			changes = append(changes, n)
+		}
+	}
+
+	if len(changes) != 1 || changes[0].Message != want {
+		t.Errorf("sent %v, want one %q with message:\n%s",
+			changes, title, want)
+	}
+}
+
+func TestNSAddressChangeDetection(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{testSmallDomain}
+
+	nameservers := lookupNameservers(t, testSmallDomain)
+
+	// The saved state lists the nameservers live DNS lists, each at an
+	// address live DNS never returns.
+	_, deps := runChecks(t, cfg, func(deps *testDeps) {
+		nsAddresses := make(map[string][]string, len(nameservers))
+		for _, ns := range nameservers {
+			nsAddresses[ns] = []string{oldIP}
+		}
+
+		deps.state.SetDomainState(testSmallDomain, &state.DomainState{
+			Nameservers:         nameservers,
+			NameserverAddresses: nsAddresses,
+		})
+	})
+
+	title := "NS Address Change: " + testSmallDomain
+	ds, _ := deps.state.GetDomainState(testSmallDomain)
+
+	// One alert per nameserver, naming it and the address it had.
+	for _, ns := range ds.Nameservers {
+		prefix := "Domain: " + testSmallDomain + "\nNameserver: " + ns +
+			"\nOld: " + oldIP + "\nNew: "
+
+		sent := 0
+
+		for _, n := range deps.notifier.getNotifications() {
+			if n.Title == title && strings.HasPrefix(n.Message, prefix) {
+				sent++
+			}
+		}
+
+		if sent != 1 {
+			t.Errorf("sent %d address changes for %s, want 1", sent, ns)
+		}
+	}
+
+	if n := countNotifications(deps, title); n != len(ds.Nameservers) {
+		t.Errorf(
+			"sent %d address changes for %d nameservers",
+			n, len(ds.Nameservers),
+		)
+	}
+
+	if n := countNotifications(deps, "NS Change: "+testSmallDomain); n != 0 {
+		t.Errorf("sent %d NS changes, want 0", n)
+	}
+}
+
+func TestNSAddedAndRemovedIsNoAddressChange(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{testSmallDomain}
+
+	nameservers := lookupNameservers(t, testSmallDomain)
+
+	// The saved state lists oldNS1, which live DNS does not, in place of
+	// the first nameserver live DNS lists, so that the check finds that
+	// one added and oldNS1 removed. Only oldNS1 has addresses saved.
+	_, deps := runChecks(t, cfg, func(deps *testDeps) {
+		deps.state.SetDomainState(testSmallDomain, &state.DomainState{
+			Nameservers:         append([]string{oldNS1}, nameservers[1:]...),
+			NameserverAddresses: map[string][]string{oldNS1: {oldIP}},
+		})
+	})
+
+	if n := countNotifications(deps, "NS Change: "+testSmallDomain); n != 1 {
+		t.Errorf("sent %d NS changes, want 1", n)
+	}
+
+	title := "NS Address Change: " + testSmallDomain
+	if n := countNotifications(deps, title); n != 0 {
+		t.Errorf("sent %d address changes, want 0", n)
+	}
+}
+
 func TestRecordChangeDetection(t *testing.T) {
 	t.Parallel()
 
 	cfg := defaultTestConfig(t)
 	cfg.Hostnames = []string{testHost}
 
-	// Between the checks, save for every nameserver an address live DNS
+	nameservers := lookupNameservers(t, testHost)
-	// never returns.
+
-	deps := runChecks(t, cfg, nil, func(deps *testDeps) {
+	// The saved state has every nameserver live DNS lists answering
-		hs, _ := deps.state.GetHostnameState(testHost)
+	// with an address live DNS never returns.
-		for _, nsState := range hs.RecordsByNameserver {
+	_, deps := runChecks(t, cfg, func(deps *testDeps) {
-			nsState.Records = map[string][]string{"A": {oldIP}}
+		byNameserver := make(map[string]*state.NameserverRecordState)
+		for _, ns := range nameservers {
+			byNameserver[ns] = answered(map[string][]string{"A": {oldIP}})
 		}
 
-		deps.state.SetHostnameState(testHost, hs)
+		deps.state.SetHostnameState(testHost, saved(byNameserver))
 	})
 
 	assertNotified(t, deps, "Record Change: "+testHost, "warning")
@@ -459,16 +813,20 @@ func TestPortStateChange(t *testing.T) {
 	cfg := defaultTestConfig(t)
 	cfg.Hostnames = []string{testHost}
 
-	// Between the checks, every port closes.
+	w, deps := runChecks(t, cfg, nil)
-	deps := runChecks(t, cfg, nil, func(deps *testDeps) {
+
-		deps.portChecker.mu.Lock()
+	// Every port closes, and the port checks run again. They look
-		deps.portChecker.closed = true
+	// nothing up.
-		deps.portChecker.mu.Unlock()
+	deps.portChecker.mu.Lock()
-	})
+	deps.portChecker.closed = true
+	deps.portChecker.mu.Unlock()
+
+	w.CheckAllPorts(t.Context())
 
 	hs, _ := deps.state.GetHostnameState(testHost)
 	assertNotified(
-		t, deps, "Port Change: "+addresses(hs)[0]+":443", "warning",
+		t, deps, "Port Change: "+net.JoinHostPort(addresses(hs)[0], "443"),
+		"warning",
 	)
 }
 
@@ -484,38 +842,59 @@ func TestTLSExpiryWarning(t *testing.T) {
 	cfg := defaultTestConfig(t)
 	cfg.Hostnames = []string{testHost}
 
-	deps := runChecks(t, cfg, expiresInThreeDays, nil)
+	_, deps := runChecks(t, cfg, expiresInThreeDays)
 
 	assertNotified(t, deps, "TLS Expiry Warning: "+testHost, "warning")
 }
 
-func TestTLSExpiryWarningDedup(t *testing.T) {
+// TestTLSExpiryWarningEachCheck runs the TLS checks three times in a
+// row on hostname and port state built here, for a certificate that
+// expires within the warning period. Each check warns once, whether the
+// TLS interval is a nanosecond, shorter than the time between two
+// checks, or a day, longer than it.
+func TestTLSExpiryWarningEachCheck(t *testing.T) {
 	t.Parallel()
 
-	cfg := defaultTestConfig(t)
+	title := "TLS Expiry Warning: " + host
-	cfg.Hostnames = []string{testHost}
-	cfg.TLSInterval = 24 * time.Hour
 
-	title := "TLS Expiry Warning: " + testHost
+	for _, interval := range []time.Duration{time.Nanosecond, 24 * time.Hour} {
+		t.Run(interval.String(), func(t *testing.T) {
+			t.Parallel()
 
-	// The second check comes within the TLS interval of the first,
+			cfg := defaultTestConfig(t)
-	// so it must not warn again.
+			cfg.Hostnames = []string{host}
-	var warnings int
+			cfg.TLSInterval = interval
 
-	deps := runChecks(t, cfg, expiresInThreeDays, func(deps *testDeps) {
+			// The TLS checks read the saved hostname and port state and
-		warnings = countNotifications(deps, title)
+			// look nothing up, so the watcher has no resolver.
-	})
+			deps := newTestDeps(t, cfg)
+			w := watcher.NewForTest(
+				cfg, deps.state, nil,
+				deps.portChecker, deps.tlsChecker, deps.notifier,
+			)
 
-	if warnings == 0 {
+			expiresInThreeDays(deps)
-		t.Fatal("expected expiry warnings from the first check")
+			deps.state.SetHostnameState(host, saved(
-	}
+				map[string]*state.NameserverRecordState{
+					nsA: answered(map[string][]string{"A": {ip1}}),
+				},
+			))
+			deps.state.SetPortState(ip1+":443", &state.PortState{
+				Open: true, Hostnames: []string{host},
+			})
 
-	got := countNotifications(deps, title)
+			for check := 1; check <= 3; check++ {
-	if got != warnings {
+				w.RunTLSChecks(t.Context())
-		t.Errorf(
+
-			"expected %d expiry warnings (dedup), got %d",
+				got := countNotifications(deps, title)
-			warnings, got,
+				if got != check {
-		)
+					t.Fatalf(
+						"after check %d: %d expiry warnings, want %d",
+						check, got, check,
+					)
+				}
+			}
+		})
 	}
 }
 
@@ -635,7 +1014,7 @@ func TestDNSRunsBeforePortAndTLSChecks(t *testing.T) {
 	cfg.Hostnames = []string{testHost}
 
 	// The saved state says the last check found testHost at oldIP.
-	deps := runChecks(t, cfg, func(deps *testDeps) {
+	_, deps := runChecks(t, cfg, func(deps *testDeps) {
 		deps.state.SetHostnameState(testHost, &state.HostnameState{
 			RecordsByNameserver: map[string]*state.NameserverRecordState{
 				oldNS1: {
@@ -644,7 +1023,7 @@ func TestDNSRunsBeforePortAndTLSChecks(t *testing.T) {
 				},
 			},
 		})
-	}, nil)
+	})
 
 	snap := deps.state.GetSnapshot()
 
@@ -654,11 +1033,12 @@ func TestDNSRunsBeforePortAndTLSChecks(t *testing.T) {
 
 	// Port and TLS checks must use the addresses this check found.
 	for _, ip := range addresses(snap.Hostnames[testHost]) {
-		if _, ok := snap.Ports[ip+":80"]; !ok {
+		portKey := net.JoinHostPort(ip, "80")
-			t.Error("port check used stale DNS: missing " + ip + ":80")
+		if _, ok := snap.Ports[portKey]; !ok {
+			t.Error("port check used stale DNS: missing " + portKey)
 		}
 
-		certKey := ip + ":443:" + testHost
+		certKey := net.JoinHostPort(ip, "443") + ":" + testHost
 		if _, ok := snap.Certificates[certKey]; !ok {
 			t.Error("TLS check used stale DNS: missing " + certKey)
 		}
@@ -717,18 +1097,27 @@ func TestSendTestNotification_ViaRun(t *testing.T) {
 
 	notifications := deps.notifier.getNotifications()
 
+	// No names are configured, so every count is 0.
+	wantMessage := "dnswatcher has started and completed its initial scan.\n" +
+		"Monitoring 0 domain(s) and 0 hostname(s).\n" +
+		"Tracking 0 port endpoint(s) and 0 TLS certificate(s).\n" +
+		"This is a test notification, sent to every configured " +
+		"notification endpoint."
+
 	found := false
 
 	for _, n := range notifications {
 		if n.Priority == "success" &&
-			n.Title == "✅ dnswatcher startup complete" {
+			n.Title == "✅ dnswatcher startup complete" &&
+			n.Message == wantMessage {
 			found = true
 		}
 	}
 
 	if !found {
 		t.Errorf(
-			"expected startup test notification, got: %v",
+			"expected startup test notification with message %q, got: %v",
+			wantMessage,
 			notifications,
 		)
 	}
@@ -769,30 +1158,29 @@ func TestSendTestNotification_Disabled(t *testing.T) {
 	}
 }
 
-func TestNSFailureAndRecovery(t *testing.T) {
+func TestNSChangeAndRecovery(t *testing.T) {
 	t.Parallel()
 
 	cfg := defaultTestConfig(t)
 	cfg.Hostnames = []string{testHost}
 
-	// Between the checks, save every nameserver the first check found
+	nameservers := lookupNameservers(t, testHost)
-	// as one that did not answer, and add, as answering, one that live
+
-	// DNS does not list, which then disappears.
+	// The saved state has every nameserver live DNS lists as one that
-	deps := runChecks(t, cfg, nil, func(deps *testDeps) {
+	// did not answer, and, as answering, one that live DNS does not
-		hs, _ := deps.state.GetHostnameState(testHost)
+	// list, which the check then finds removed.
-		for ns := range hs.RecordsByNameserver {
+	_, deps := runChecks(t, cfg, func(deps *testDeps) {
-			hs.RecordsByNameserver[ns] = failed()
+		byNameserver := map[string]*state.NameserverRecordState{
+			oldNS1: answered(map[string][]string{"A": {oldIP}}),
+		}
+		for _, ns := range nameservers {
+			byNameserver[ns] = failed()
 		}
 
-		hs.RecordsByNameserver[oldNS1] = &state.NameserverRecordState{
+		deps.state.SetHostnameState(testHost, saved(byNameserver))
-			Records: map[string][]string{"A": {oldIP}},
-			Status:  "ok",
-		}
-
-		deps.state.SetHostnameState(testHost, hs)
 	})
 
-	assertNotified(t, deps, "NS Failure: "+testHost, "error")
+	assertNotified(t, deps, "NS Change: "+testHost, "warning")
 	assertNotified(t, deps, "NS Recovery: "+testHost, "success")
 
 	// A nameserver that did not answer has no records to compare, so

package.json

@@ -0,0 +1,9 @@
+{
+    "name": "dnswatcher-tooling",
+    "version": "0.0.0",
+    "private": true,
+    "description": "Pins the prettier that script/fmt and script/fmt-check run against this repo's markdown. Not a JavaScript project; nothing here is imported, published, or shipped.",
+    "devDependencies": {
+        "prettier": "3.9.6"
+    }
+}

script/bootstrap

@@ -3,20 +3,16 @@
 # this repo. Idempotent: every install is guarded by a check so already
 # installed tools are skipped. Base tooling comes from nix, apt, brew,
 # or apk (detected in that order); assumes nothing is present.
-# goimports is installed via `go install` at a pinned commit (never
+# goimports is not installed here: script/fmt and script/fmt-check run
-# "latest") because script/fmt runs it on the host; script/fmt-check
+# it with `go run` at a pinned commit.
-# does not (it runs gofmt only).
 # The linter is NOT installed here: golangci-lint runs via docker only
 # (script/lint), pinned by image digest, so its only prerequisite is a
-# working docker.
+# working docker. Nor is prettier: script/fmt and script/fmt-check run
+# it in a stage of the Dockerfile.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
-# Pinned version, 2026-08-07 (same pin as the Dockerfile)
-# goimports v0.42.0
-GOIMPORTS_REF="golang.org/x/tools/cmd/goimports@009367f5c17a8d4c45a961a3a509277190a9a6f0"
-
 PKGMGR=""
 SUDO=""
 APT_UPDATED=""
@@ -71,15 +67,12 @@ main() {
     if missing make; then pkg_install gnumake make make make; fi
     if missing go; then pkg_install go golang go go; fi
 
-    # Format tools, pinned via go install (installs into
+    # Testing, linting and the markdown formatter run via docker only.
-    # "$(go env GOPATH)/bin"; ensure that is on your PATH).
+    # Warn, don't fail: make build works without it.
-    if missing goimports; then go install "$GOIMPORTS_REF"; fi
-
-    # Linting runs via docker only (script/lint). Warn, don't fail:
-    # everything except `make lint` works without it.
     if missing docker; then
         echo "bootstrap: WARNING: docker not found; install it to" \
-            "run make lint and make docker." >&2
+            "run make test, make lint, make fmt, make fmt-check," \
+            "make check and make docker." >&2
     fi
 
     go mod download

script/cibuild

@@ -1,18 +1,28 @@
 #!/bin/sh
-# script/cibuild: run the CI build. The Dockerfile's lint stage runs
+# script/cibuild: run the CI build. It bootstraps first: a CI runner
-# make fmt-check and golangci-lint; its builder stage runs make test
+# checks out and runs this and nothing else, and script/fmt-check runs
-# and make build.
+# the formatter on the host, which a pristine checkout cannot do.
-#
+# --no-cache for the same reason as script/docker: the gate phases the
-# --no-cache-filter=lint,builder runs both stages on every invocation;
+# final stage depends on are RUN steps, and a cached one is a check that
-# otherwise an unchanged tree is served from the layer cache and passes
+# did not run.
-# without linting or querying live DNS.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build --no-cache-filter=lint,builder .
+    "$SCRIPT_DIR/bootstrap"
+    "$SCRIPT_DIR/check"
+    # Own line: a failing command substitution inside an argument does
+    # not trip `set -e`, so the inline form degrades silently to an
+    # empty constant. The VERSION build argument takes precedence over
+    # the version a build stage derives from the .git in the context.
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    [ -n "$version" ] || version="unknown"
+    docker build --no-cache \
+        --build-arg VERSION="$version" \
+        -t "$("$SCRIPT_DIR/projectname")" .
 }
 
 main "$@"

script/docker

@@ -1,10 +1,8 @@
 #!/bin/sh
 # script/docker: build the Docker image tagged with the project name.
-# The tag comes from script/projectname.
+# Identical in all repos; the tag comes from script/projectname.
-#
+# --no-cache because the gate phases the final stage depends on are RUN
-# --no-cache-filter=lint,builder runs the lint stage and the builder
+# steps, and a cached one is a check that did not run.
-# stage (make test) on every invocation; otherwise an unchanged tree is
-# served from the layer cache without linting or querying live DNS.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -14,11 +12,11 @@ main() {
     cd "$ROOT"
     # Own line: a failing command substitution inside an argument does
     # not trip `set -e`, so the inline form degrades silently to an
-    # empty constant. VERSION is computed here because .dockerignore
+    # empty constant. The VERSION build argument takes precedence over
-    # excludes .git, so `git describe` in a build stage cannot find it.
+    # the version a build stage derives from the .git in the context.
     version="$(git describe --tags --always --dirty 2>/dev/null || true)"
     [ -n "$version" ] || version="unknown"
-    docker build --no-cache-filter=lint,builder \
+    docker build --no-cache \
         --build-arg VERSION="$version" \
         -t "$("$SCRIPT_DIR/projectname")" .
 }

script/fmt

@@ -1,13 +1,58 @@
 #!/bin/sh
-# script/fmt: format all files (writes).
+# script/fmt: format all files (writes). Go with gofmt and goimports on
+# the host, markdown with prettier in the Dockerfile's fmt stage.
+#
+# goimports runs with `go run` at a pinned commit, never from PATH, so
+# every machine formats with the same version and nothing installs it.
+#
+# The markdown pass is a `docker build --output type=local` rather than a
+# `docker run -v`, so it needs no bind mount and behaves the same against
+# a remote daemon; the formatted documents come back out of the build and
+# are copied over the tree here. --output writes files and makes no
+# image, so there is nothing to tag.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
+# goimports v0.42.0, 2026-08-07. Must match script/fmt-check.
+GOIMPORTS_REF="golang.org/x/tools/cmd/goimports@009367f5c17a8d4c45a961a3a509277190a9a6f0"
+
+die() {
+    echo "script/fmt: $*" >&2
+    exit 1
+}
+
 main() {
     cd "$ROOT"
     gofmt -s -w .
-    goimports -w .
+    go run "$GOIMPORTS_REF" -w .
+
+    tmp="$(mktemp -d "${TMPDIR:-/tmp}/dnswatcher-fmt.XXXXXX")"
+    trap 'rm -rf "$tmp"' EXIT INT TERM
+
+    docker build --no-cache \
+        --target fmt-out \
+        --output "type=local,dest=$tmp/out" .
+
+    # An empty export means prettier was handed nothing, which must not
+    # read as "already formatted".
+    (cd "$tmp/out" && find . -type f -name '*.md') |
+        sed 's|^\./||' | LC_ALL=C sort >"$tmp/files"
+
+    [ -s "$tmp/files" ] ||
+        die "the formatting build produced no markdown; the build" \
+            "context reached prettier empty"
+
+    # Copied only where the bytes differ, so an already-formatted tree
+    # keeps its timestamps and says nothing.
+    while IFS= read -r f; do
+        [ -n "$f" ] || continue
+        if [ -f "$f" ] && cmp -s "$tmp/out/$f" "$f"; then
+            continue
+        fi
+        cp "$tmp/out/$f" "$f"
+        echo "prettier: reformatted $f"
+    done <"$tmp/files"
 }
 
 main "$@"

script/fmt-check

@@ -1,18 +1,37 @@
 #!/bin/sh
-# script/fmt-check: check formatting (read-only). Same scope as
+# script/fmt-check: check formatting (read-only). Same tools and scope
-# script/fmt, but fails instead of writing.
+# as script/fmt, but fails instead of writing and names what it would
+# change: the Go on the host, the markdown with prettier in the
+# Dockerfile's fmt-check stage.
+#
+# --no-cache because a cached check layer is a check that did not run.
+# The tag makes each build replace the previous image instead of leaving
+# a dangling one behind.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+
+# goimports v0.42.0, 2026-08-07. Must match script/fmt.
+GOIMPORTS_REF="golang.org/x/tools/cmd/goimports@009367f5c17a8d4c45a961a3a509277190a9a6f0"
 
 main() {
     cd "$ROOT"
-    files="$(gofmt -l .)"
+    files="$(gofmt -s -l .)"
     if [ -n "$files" ]; then
         echo "gofmt: files not formatted:" >&2
         echo "$files" >&2
         exit 1
     fi
+    files="$(go run "$GOIMPORTS_REF" -l .)"
+    if [ -n "$files" ]; then
+        echo "goimports: files not formatted:" >&2
+        echo "$files" >&2
+        exit 1
+    fi
+    docker build --no-cache \
+        --target fmt-check \
+        -t "$("$SCRIPT_DIR/projectname")-fmt-check" .
 }
 
 main "$@"

script/lint

@@ -1,28 +1,23 @@
 #!/bin/sh
-# script/lint: run the linter. golangci-lint is never installed or run
+# script/lint: run the linter. Linting is a phase of the Dockerfile and
-# on the host: it runs via docker only, one way, everywhere. This
+# this builds that phase alone; the linter is never installed or run on
-# builds Dockerfile.lint, which COPYs the repo into the digest-pinned
+# a developer host, where a shared result cache and a host-global lock
-# golangci-lint image and lints as a build step, so a successful build
+# make its answer untrustworthy.
-# means a clean lint.
 #
-# --no-cache-filter=lint forces the lint stage (source copy + linter
+# The phase is not the last stage in the file, so it is built only when
-# run) to execute on every invocation. Without it an unchanged tree
+# --target names it. --no-cache because a cached lint layer is a lint
-# returns success in well under a second having linted nothing. The
+# that did not run. The tag makes each build replace the previous image
-# deps stage (base image + go mod download) stays cached, and no global
+# instead of leaving a dangling one behind.
-# cache invalidation is performed. --progress=plain keeps the linter's
-# own output visible.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build \
+    docker build --no-cache \
-        --progress=plain \
-        --no-cache-filter=lint \
         --target lint \
-        -f Dockerfile.lint \
+        -t "$("$SCRIPT_DIR/projectname")-lint" .
-        .
 }
 
 main "$@"

script/test

@@ -1,35 +1,19 @@
 #!/bin/sh
-# script/test: run the test suite.
+# script/test: run the test suite. Testing is a phase of the Dockerfile
-#
+# and this builds that phase alone, on the same terms as script/lint:
-# -count=1 disables Go's test cache, and is load-bearing here. This
+# --target because a phase that is not the last stage is built only when
-# suite queries live DNS on every run by policy (TESTING.md); a cached
+# named, --no-cache because a cached test layer is a test that did not
-# result is a replay of an earlier run's output with no query made at
+# run, and a tag so each build replaces the previous image.
-# all. On an unchanged tree the whole suite would return success in
-# under a second having resolved nothing, which makes the repeated-run
-# green that is used as evidence for flakiness fixes worthless. Do not
-# remove it.
-#
-# Conditional verbose rerun per REPO_POLICIES.md: run quiet first so
-# CI and docker build logs stay readable, and rerun with -v only on
-# failure. The rerun also carries -count=1 (a cached replay of the
-# failure would show nothing new), and the exit status is forced to 1
-# no matter how the rerun ends: the first failure already proved the
-# suite broken, so a flaky test that passes the second time must not
-# turn the build green.
-#
-# -timeout 90s is a deliberate backstop above the 60s hard cap on
-# suite duration. Do not lower it.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    go test -count=1 -race -timeout 90s -cover ./... || {
+    docker build --no-cache \
-        echo "--- Rerunning with -v for details ---" >&2
+        --target test \
-        go test -count=1 -race -timeout 90s -v ./... || true
+        -t "$("$SCRIPT_DIR/projectname")-test" .
-        exit 1
-    }
 }
 
 main "$@"

yarn.lock

@@ -0,0 +1,8 @@
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+
+
+prettier@3.9.6:
+  version "3.9.6"
+  resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.9.6.tgz#b3ea5146515d40fc53f18aa63f74dfab1e10dbf6"
+  integrity sha512-OpN0zzVdiaiAhxpuuj5efpIS4sY9j7bY6uR5mnj5yPzGkdkjNKSJeUThPb60Jw29QuAZgA4o+/iB49kFiaBX6g==