next (#136)

Long-lived integration branch. One commit per work unit lands here; this PR accumulates them until it is merged to `main`.

## Landed units

- **Run all linting in Docker via `Dockerfile.lint` + `script/lint`** — #134

    golangci-lint is no longer installed or run on the host. New root `Dockerfile.lint` COPYs the repo into the digest-pinned `golangci/golangci-lint:v2.12.2` image and lints as a build step, so a successful build IS a clean lint; `script/lint` is reduced to a thin wrapper that builds it. This also works where the docker daemon is remote and bind mounts are impossible.

    **Pinned digest and how it was verified.** `golangci/golangci-lint:v2.12.2@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240`, exactly as quoted in the issue. It resolves, and it is genuinely v2.12.2:

    ```
    $ docker buildx imagetools inspect golangci/golangci-lint:v2.12.2
    Name:      docker.io/golangci/golangci-lint:v2.12.2
    MediaType: application/vnd.oci.image.index.v1+json
    Digest:    sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240

    $ docker run --rm golangci/golangci-lint@sha256:5cceeef04e...ad5240 golangci-lint --version
    golangci-lint has version 2.12.2 built with go1.26.2 from c0d3ddc9 on 2026-05-06T11:07:58Z
    ```

    The tag's index digest is the quoted digest, and the binary inside reports commit `c0d3ddc9`, matching the org's canonical pin `c0d3ddc9cf3faa61a4e378e879ece580256d76e5`.

    **Forcing the linter to actually run.** `Dockerfile.lint` is split into a `deps` stage (base image + `go mod download`) and a `lint` stage (source copy + linter run). `script/lint` runs:

    ```
    docker build --progress=plain --no-cache-filter=lint --target lint -f Dockerfile.lint .
    ```

    Caching is explicitly waived for linting, and a cached build lints nothing, so the `lint` stage is invalidated on every invocation. The invalidation is scoped: the `deps` stage stays cached and no global cache wipe is performed. `--progress=plain` keeps the linter's own output visible.

    **`golangci-lint config verify`: deliberately NOT included.** It fetches its JSON schema over a live, unpinned HTTPS call, which would make linting network-dependent and defeat hash-pinning. Omitted for that reason, and the reason is recorded in a comment at the top of `Dockerfile.lint`.

    **`script/bootstrap`** no longer installs golangci-lint (and its pinned ref is gone); it warns non-fatally when `docker` is absent instead. The `goimports` install stays, because `script/fmt` and `script/fmt-check` still run on the host. Header comment updated accordingly.

    **Root `Dockerfile`** — required consequence, not scope creep. Its builder stage ran `make check`, which now calls `script/lint`, which shells out to `docker build`; there is no docker daemon inside a docker build, so `script/cibuild` and `script/docker` would have broken. It gains its own lint stage on the same pinned image (linter invoked directly, with a comment explaining why not `make lint`), with the builder stage depending on it via `COPY --from=lint /src/go.sum /dev/null` and running `make fmt-check`, `make test`, `make build`. The now-unneeded golangci-lint install is gone from the builder stage.

    **README** `Entrypoints` and `Building` sections now describe linting as a docker-only operation. `TODO.md` updated in the same commit.

    ### Verification

    All runs via `make` / `script/` entrypoints only.

    Two consecutive `make lint` runs on an unchanged tree, both executing the linter:

    ```
    # run 1
    #10 [lint 2/2] RUN golangci-lint run --config .golangci.yml ./...
    #10 10.98 0 issues.
    #10 DONE 12.0s

    # run 2, tree untouched
    #10 [lint 2/2] RUN golangci-lint run --config .golangci.yml ./...
    #10 14.63 0 issues.
    ```

    A third run shows the cache scoping is working as intended — `deps` served from cache, `lint` re-executed:

    ```
    #6 [deps 2/4] WORKDIR /src
    #6 CACHED
    #7 [deps 3/4] COPY go.mod go.sum ./
    #7 CACHED
    #8 [deps 4/4] RUN go mod download
    #8 CACHED
    #9 [lint 1/2] COPY . .
    #10 [lint 2/2] RUN golangci-lint run --config .golangci.yml ./...
    ```

    **Negative control.** A deliberate violation (an unused function containing an ineffectual assignment) was added to `internal/config/config.go`:

    ```
    #10 11.26 internal/config/config.go:29:2: ineffectual assignment to x (ineffassign)
    #10 11.26 internal/config/config.go:28:6: func negativeControlUnused is unused (unused)
    #10 11.26 2 issues:
    #10 ERROR: process "/bin/sh -c golangci-lint run --config .golangci.yml ./..." did not complete successfully: exit code: 1
    ERROR: failed to build: failed to solve: process "/bin/sh -c golangci-lint run --config .golangci.yml ./..." did not complete successfully: exit code: 1
    make: *** [Makefile:26: lint] Error 1
    ```

    `make lint` exited non-zero naming both findings and their exact lines. After reverting the file, `make lint` was clean again (`0 issues.`).

    **`make check`** green end to end (test, lint, fmt-check), exit 0.

    **`script/cibuild`** green, confirming the `Dockerfile` restructure does not recurse: the lint stage ran (`#16 12.56 0 issues.`), then `#22 [builder 8/9] RUN make test` with `PASS` lines, then `#23 [builder 9/9] RUN make build`.

    ### Notes for the owner

    This supersedes two PRs you still have queued for merge, both of which tune host linting that no longer exists after this change: #128 (isolates the host golangci-lint cache and lock) and #131 (always installs the pinned lint tools in `script/bootstrap`). Neither was merged or incorporated here.

    Made moot by this change: #121 and #130.

    ### Review outcome

    Reviewed at #136 (comment) — **PASS**. Three non-blocking comment-accuracy findings were recorded there for the next touch of those files; the reviewer independently confirmed the lint gate is live by negative control from a warm cache.

- **Live DNS tests made robust instead of gated; test caps moved to the org-wide 60s/20s/90s values** — #93

    The resolver's live-DNS tests failed nondeterministically, a different subset each run. Fixed by engineering the nondeterminism out, not by routing around the network. **Nothing is mocked, faked, stubbed, recorded or replayed; there is no `-short` flag, no build tag, no skip, and no environment-tolerance for restricted egress.** Production resolver behaviour is unchanged.

    ### Root causes, all test-side

    1. **Burst fan-out at one root server.** Every test in `internal/resolver` calls `t.Parallel()` and the build hosts have many cores (48 here), so all ~35 iterative resolutions started within milliseconds of each other, and because `queryServers` walks `rootServerList()` in fixed order they all aimed their first query at `198.41.0.4`. Root servers rate-limit that, which fits the reported symptom of a different arbitrary subset failing each run.
    2. **No retry anywhere.** One dropped UDP packet in a delegation chain failed a test outright.
    3. **Unanimity assertions.** `TestQueryAllNameservers_AllReturnOK` and `_NXDomainFromAllNS` required *every* nameserver of a domain to answer — four independent chances to fail per run, with no tolerance for one being slow.

    ### What was built

    New `internal/resolver/livedns_test.go` holds all the live-DNS machinery, so `resolver_test.go` itself takes only call-site edits:

    - **Bounded live concurrency.** A package-wide semaphore (`liveConcurrency = 6`) caps how many live resolutions are in flight at once. Tests keep `t.Parallel()`; only their network work is throttled. This is the direct fix for cause 1, and the 60s budget is what makes it affordable.
    - **Retry with exponential backoff.** Three attempts per live operation, 8s deadline each, 500ms base backoff doubling. The retry predicate is deliberately **transport-level** — "did a nameserver answer at all" — and never the assertion the test is making, so a resolver that answers *incorrectly* still fails on the first attempt rather than being retried into a false green.
    - **Quorum instead of unanimity, tolerating SILENCE ONLY.** A strict majority of the discovered nameservers must answer as expected, and every individual result must additionally fall inside a closed **allowlist** of statuses the test explicitly sanctions: `ok`/`timeout`/`error` for the all-OK test, `nxdomain`/`timeout`/`error` for the NXDOMAIN test. A nameserver that stays silent is tolerated; one that answers **wrongly** is not, at any count. The allowlist is the load-bearing part — see the rework note below for why a blocklist was not enough.

    New `internal/resolver/livedns_harness_test.go` tests that machinery directly — quorum arithmetic, status counting, the allowlist, the gate's concurrency bound, per-attempt deadlines, and recovery from a transient failure. It performs no DNS resolution of any kind, so it neither mocks DNS nor depends on it.

    ### Rework after review — the quorum could not fail on a wrong answer

    The review at #136 (comment) returned **FAIL** on `9cb2c2b`, correctly. Fixed in `87bce43`.

    **The defect.** The claim above was, as first written, false for `resolver.StatusNoData`. Each test banned exactly one wrong status — `_AllReturnOK` banned only `nxdomain`, `_NXDomainFromAllNS` banned only `ok` — and `nodata` is neither. It is a **wrong answer, not silence**: `answeredCount` counted it as answered, so it did not even trigger a retry, and with a quorum of 3-of-4 a single wrong nameserver slid through undetected. The pre-change unanimity assertions would have caught it. That is robustness work quietly becoming assertion-loosening, which is exactly what this repo cannot afford.

    **The fix.** Tolerance is now an allowlist, not a blocklist of one status. New `unsanctionedStatuses()` returns every per-nameserver result whose status the caller did not explicitly sanction, and each test asserts that list is empty in addition to its quorum. A blocklist bans the one wrong answer its author thought of and silently admits everything else, including any status added to the resolver later; an allowlist fails on anything nobody sanctioned. `answeredCount` was reframed the same way — it now counts the closed set `ok`/`nxdomain`/`nodata`, so an unfamiliar status is treated as silence and can only ever cause a retry and then a loud failure, never a quiet pass.

    **Evidence — the reviewer's exact probe, re-run.** `queryEachNS` in `internal/resolver/iterative.go` was patched to force one of `google.com`'s four nameservers to return `StatusNoData` with empty records. `make test` now goes **red**, naming the offending nameserver and status:

    ```
    exit=2
    --- FAIL: TestQueryAllNameservers_AllReturnOK (1.12s)
        Error:    Should be empty, but was [ns1.google.com.=nodata]
        Messages: every nameserver must answer OK or not answer at all:
                  ns1.google.com.=nodata ns2.google.com.=ok
                  ns3.google.com.=ok ns4.google.com.=ok
    --- FAIL: TestQueryAllNameservers_NXDomainFromAllNS (1.34s)
        Error:    Should be empty, but was [ns1.google.com.=nodata]
        Messages: every nameserver must report NXDOMAIN or not answer at all:
                  ns1.google.com.=nodata ns2.google.com.=nxdomain
                  ns3.google.com.=nxdomain ns4.google.com.=nxdomain
    FAIL  sneak.berlin/go/dnswatcher/internal/resolver  1.704s
    ```

    That is the same input that returned `exit=0` with both tests **passing** under the old assertions. Probe reverted, tree clean, suite green again:

    ```
    exit=0
    ok  sneak.berlin/go/dnswatcher/internal/resolver  4.185s  coverage: 77.1% of statements
    (zero `(cached)` lines)
    ```

    Two harness tests lock the regression in without any probe: three OK plus one `nodata` (quorum satisfied, no NXDOMAIN present — the exact input that used to pass) is reported as unsanctioned, and an unknown status is neither counted as answered nor tolerated.

    Also fixed from the review: the per-attempt deadline assertion in `livedns_harness_test.go` had no lower bound, so it passed for a deadline far shorter than intended. It now asserts the remaining time exceeds `liveAttemptTimeout/2` as well.

    Deliberately **not** done in this rework, per the review and the owner: no `-count=1` in `script/test` (the test-cache issue is real but pre-existing and repo-wide, filed separately); the remaining non-DNS mocks stay for #97; `queryServers` root-ordering stays untouched under #138.

    ### The `-timeout` backstop value: 90s

    Per the ruling at sneak/prompts#41 (comment) the cap is org-wide with two tiers: **60s hard cap for CI green, 20s target, and anything between the two must be filed as an improvement bug.** The backstop is **`90s`**, matching sneak/prompts#42 and preserving the 1.5x backstop-to-cap ratio the old 20s/30s pair had. It must strictly exceed the 60s cap or the cap is unreachable — the old `-timeout 30s` would have killed a 60s-capped suite at half its allowance. Applied to `script/test`; nothing else in the repo carried the old `30s`.

    Worst case for one live operation is 3 attempts x 8s plus ~1.5s of backoff, about 26s — comfortably inside the 90s backstop even if several operations exhaust their attempts at once.

    ### `REPO_POLICIES.md` is re-vendored, not hand-edited

    The file is org-canonical, so it was **copied byte-for-byte** from `prompts/REPO_POLICIES.md` on `sneak/prompts` branch `org-wide-60s-test-cap` (commit `52b5192`) rather than reworded to approximately the same thing. Verified:

    ```
    $ cmp prompts/REPO_POLICIES.md dnswatcher/REPO_POLICIES.md && echo identical
    identical
    $ sha256sum REPO_POLICIES.md
    bcf11c312a1bee18a0e937eb412b51914411c1ab23308b8362409f3f88379ff7
    ```

    **What that byte-identity does and does not certify.** The source branch `org-wide-60s-test-cap` is an **unmerged proposal** — sneak/prompts#42 — not `prompts` `main`. So, precisely:

    - The **60s hard cap and 20s improvement-bug tier ARE the owner's ruling** (sneak/prompts#41 (comment)).
    - The **`90s` backstop is our own proposed number and is NOT ratified** (sneak/prompts#41 (comment)).
    - The vendored text is therefore **the proposed canonical text, pending** sneak/prompts#42. If that PR lands with different numbers, this file must be re-vendored to match; it should not be hand-edited here either way.

    **Known mismatch with this repo's actual state, recorded not papered over.** Re-vendoring also picked up the paragraph at `REPO_POLICIES.md:266-271` mandating that canonical golangci-lint be installed commit-pinned via `go install ...@c0d3ddc9...`. This repo does **not** comply with that mechanism: `cc86473` in this same PR made linting Docker-only, and `script/bootstrap` now installs golangci-lint nowhere. The **version and commit match** (`v2.12.2` / `c0d3ddc9`); the **installation mechanism does not**. The vendored file is org-canonical and must not be edited downstream, so this is being raised upstream for the org text to accommodate Docker-only linting rather than patched here.

    `TESTING.md`'s stale "within the 30-second target" follows to 60. That edit is deliberately a single line so it merges cleanly when #97 lands.

    ### Verification

    All runs through `make` / `script/` entrypoints only; lint runs in Docker.

    **Ten consecutive `make check` runs, all green, none served from cache.** Go's test cache will happily report `ok pkg (cached)` without executing anything, which proves nothing about nondeterminism, so every run was forced to actually execute and each log was checked for zero `(cached)` lines:

    ```
    check#1  exit=0 wall=32s resolver=2.895s fails=0 cached=0
    check#2  exit=0 wall=27s resolver=2.872s fails=0 cached=0
    check#3  exit=0 wall=47s resolver=2.729s fails=0 cached=0
    check#4  exit=0 wall=36s resolver=2.885s fails=0 cached=0
    check#5  exit=0 wall=32s resolver=2.899s fails=0 cached=0
    check#6  exit=0 (harness tests added)      fails=0 cached=0
    check#7  exit=0 wall=41s resolver=2.891s fails=0 cached=0
    check#8  exit=0 wall=36s resolver=2.871s fails=0 cached=0
    check#9  exit=0 wall=26s resolver=2.846s fails=0 cached=0
    check#10 exit=0 wall=46s resolver=2.833s fails=0 cached=0
    ```

    After the rework commit `87bce43`, `make check` green again end to end, zero `(cached)` test lines, Docker lint stage demonstrably executed rather than served from cache:

    ```
    exit=0  cached=0
    #8 [deps 4/4] RUN go mod download
    #8 CACHED
    #10 [lint 2/2] RUN golangci-lint run --config .golangci.yml ./...
    #10 30.72 0 issues.
    ```

    The Docker lint stage was confirmed to execute rather than cache on each run:

    ```
    #8 [deps 4/4] RUN go mod download
    #8 CACHED
    #9 [lint 1/2] COPY . .
    #9 DONE 0.6s
    #10 [lint 2/2] RUN golangci-lint run --config .golangci.yml ./...
    #10 DONE 39.7s
    ```

    **`make test` wall time: 3.6-4.1s** across three timed uncached runs (`4093ms`, `3649ms`, `3729ms`). `internal/resolver` went from 2.0s to ~2.9s — the concurrency gate's cost. That is inside the 20s target, so no improvement bug is owed under the new two-tier rule.

    **Honest note on what these runs do and do not prove.** Live DNS was healthy throughout: **no live-DNS retry fired even once**, and no flake was observed either before or after the change (six pre-change baseline runs were also clean). So these runs demonstrate the change is not itself flaky and does not slow the suite; they do **not** demonstrate recovery from a real DNS failure, because no real DNS failure occurred. The original flakiness is *not reproduced* rather than *shown fixed*. The retry path is instead proven by `TestRetryLiveRecoversFromTransientFailure`, the only source of the single `retrying in 500ms` line in each log:

    ```
    livedns_harness_test.go:90: transient: attempt 1 of 3 failed
        (no answer from live DNS), retrying in 500ms
    ```

    ### Observation, not acted on

    The single most effective remaining lever against root-server rate limiting would be to stop `queryServers` always trying `rootServerList()` in the same order, so that load spreads across all thirteen roots instead of concentrating on `a.root-servers.net`. That is **production** code and this issue scopes the work as test-side, so it was left alone rather than changed quietly. It is now tracked for the owner's decision at #138.

    ### Interaction with #97

    `TESTING.md` and `internal/resolver/resolver_test.go` auto-merge — that PR touches `resolver_test.go` only at the import block and the final timeout-test section, while this change touches the body of the file and adds two new files, and it leaves the mock-`DNSClient` timeout test at the tail of `resolver_test.go` entirely alone since removing it is that PR's job. `TODO.md` does conflict; that PR is already labelled `needs-rebase`, so this adds nothing material to its rebase.

- **Go's test cache disabled, so every `make test` actually queries live DNS** — #139

    `script/test` did not pass `-count=1`, so on an unchanged tree Go served the whole suite from cache: exit 0 in ~0.2s, every package marked `(cached)`, and not one DNS query made. This repo's suite exists to exercise live resolution on every run (`TESTING.md`), so that green asserted nothing — and it is exactly the green used as evidence that a flakiness fix works, since "run it a few times" stops being runs after the first. It had already misled two agents, each of whom forced uncached runs by hand.

    `-count=1` now disables caching on every invocation.

    **The conditional verbose rerun was missing and is added here.** `REPO_POLICIES.md` mandates it; the primary run had been unconditionally `-v`, which is the failure mode the policy exists to prevent (unreadable CI and `docker build` logs on success). Tests now run quiet, and only a failure triggers the `-v` rerun. Two properties matter and both are covered: the rerun carries `-count=1` too, so it cannot replay a cached copy of the failure it is meant to diagnose; and its exit status is discarded in favour of a forced `1`, so a flake that passes the second time cannot turn the build green — the first failure already proved the suite broken.

    **`-timeout 90s` untouched.** It is a deliberate backstop that must strictly exceed the 60s hard cap.

    **No special-casing for the Docker build**, which reaches the same script via `RUN make test`: a fresh container's test cache is empty, so `-count=1` is a no-op there, and carving out an exception would only create a second code path that could drift.

    ### Verification

    **Proven from a warm cache, not a cold one.** The suite was run first to populate the cache, and the pre-change state confirmed:

    ```
    ok  sneak.berlin/go/dnswatcher/internal/config    (cached)  coverage: 92.6% of statements
    ok  sneak.berlin/go/dnswatcher/internal/resolver  (cached)  coverage: 77.1% of statements
    ...8 of 8 packages (cached)...
    real 0m0.203s
    ```

    With the change applied to that same warm cache, three back-to-back runs on an unchanged tree, **zero `(cached)` markers** in all three:

    ```
    # run 1                                          # run 2
    ok  .../internal/config     1.045s               ok  .../internal/config     1.040s
    ok  .../internal/handlers   1.029s               ok  .../internal/handlers   1.021s
    ok  .../internal/notify     1.148s               ok  .../internal/notify     1.252s
    ok  .../internal/portcheck  1.026s               ok  .../internal/portcheck  1.025s
    ok  .../internal/resolver   3.005s               ok  .../internal/resolver   2.846s
    ok  .../internal/state      1.078s               ok  .../internal/state      1.097s
    ok  .../internal/tlscheck   1.067s               ok  .../internal/tlscheck   1.079s
    ok  .../internal/watcher    1.566s               ok  .../internal/watcher    1.544s
    real 0m4.174s                                    real 0m4.015s

    # run 3: grep -c '(cached)' => 0                 real 0m4.519s
    ```

    **Measured uncached wall time: 4.0-4.5s** (was ~0.2s served from cache). Inside the 20s target, so no improvement bug is owed under the two-tier rule at sneak/prompts#41 (comment).

    **`-count=1` composes with `-race` and `-cover`**: both still present in the primary run, and the per-package coverage percentages above are identical to the pre-change values.

    **The failure path was exercised, not assumed.** A purpose-built flaky test that fails on its first run and passes every run after (marker file kept outside the module, so the tree stays byte-identical and a cached result would be served if caching were on) was run through the script:

    ```
    exit code: 1
    --- FAIL: TestFlaky (0.00s)
    FAIL    flakeproof  0.013s
    --- Rerunning with -v for details ---
    --- PASS: TestFlaky (0.00s)
    ok      flakeproof  1.014s
    ```

    Quiet failure, verbose rerun that genuinely re-executed (it passed, so it did not replay the cached `FAIL`), and exit `1` regardless of the rerun passing. Scratch module removed afterwards.

    **`make check` green**, exit 0, with the Docker lint stage demonstrably executed rather than served from cache:

    ```
    #8  [deps 4/4] RUN go mod download
    #8  CACHED
    #10 [lint 2/2] RUN golangci-lint run --config .golangci.yml ./...
    #10 21.36 0 issues.
    #10 DONE 26.2s
    ```

    `README.md` and `TESTING.md` record why the cache is waived, and `TODO.md` is updated in the same commit.

    ### Question for the owner, not filed as a defect

    The Docker lint run emits `The linter 'gomodguard' is deprecated (since v2.12.0) due to: new major version. Replaced by gomodguard_v2.` It is pre-existing and out of this issue's scope. It is not filed as an issue here because `.golangci.yml` tracks the org-canonical config, so switching to `gomodguard_v2` looks like an upstream `sneak/prompts` decision rather than a per-repo fix. Say the word and it gets filed in whichever place you consider canonical.

- **MIT `LICENSE` added; README states the licence** — #102

    The repo had no licence file at all, so publicly readable code was all-rights-reserved by default and nobody could legally use it. `LICENSE` was also the last file missing from `REPO_POLICIES.md`'s required minimum.

    MIT, by standing org policy rather than a per-repo call: any public repo lacking a licence gets MIT, and a private one with no licence is already all-rights-reserved. `sneak/dnswatcher` is public (`private: false` on the Gitea repo record).

    `README.md`'s first line now names the licence, per the Description requirement, and the License section states MIT and points at the file instead of recording the decision as pending. `TODO.md` updated in the same commit.

    ### Verification

    `LICENSE` is the canonical MIT text byte-for-byte with only the copyright line filled in (`Copyright (c) 2026 sneak`) — no clauses added, removed, reworded, or reflowed. It was not typed from memory: the file was copied from an existing verbatim MIT template on disk and only the copyright line edited (`diff` against that template shows that one line and nothing else), then the result was word-diffed against SPDX `MIT.txt` fetched from `spdx/license-list-data`, ignoring only line wrapping and the placeholder — identical.

    `make fmt` did **not** touch `LICENSE`, and cannot: `script/fmt` runs `gofmt -s -w .` and `goimports -w .` only, with no prettier or markdown step in the repo, so no exclusion was needed.

    `make check` green, exit 0. Tests executed rather than replayed (zero `(cached)` lines, `internal/resolver 3.098s`), and the Docker lint stage ran rather than cached:

    ```
    #10 [deps 4/4] RUN go mod download
    #10 CACHED
    #12 [lint 2/2] RUN golangci-lint run --config .golangci.yml ./...
    #12 36.44 0 issues.
    #12 DONE 36.7s
    ```

- **Comment-only corrections in `script/bootstrap`, `script/cibuild`, and `Dockerfile.lint`** — #137

    Follow-up to this PR's own review. Nothing executable changed: the diff touches comment lines, one warning string, and `TODO.md`.

    - `script/bootstrap`'s header justified the pinned `goimports` install by claiming `script/fmt-check` runs it on the host. Verified against the script: `script/fmt-check` runs `gofmt -l .` and nothing else. The header now credits `script/fmt` alone. That `fmt-check` does not verify goimports at all is #119 and was deliberately left alone.
    - `script/cibuild`'s header still said the `Dockerfile` runs `make check`. It now describes the current file: lint stage runs `make fmt-check` and `golangci-lint`, builder stage runs `make test` and `make build`.
    - The `docker`-missing warning was three fragments, each re-prefixed with `bootstrap:` mid-clause. Now one sentence: `bootstrap: WARNING: docker not found; install it to run make lint and make docker.`
    - `Dockerfile.lint`'s comment explained why `golangci-lint config verify` is omitted but read as though the omission were free. It now states the residual risk: unknown top-level keys in `.golangci.yml` are silently ignored, so a mistyped or wrong-schema key lints clean while applying nothing. `config verify` was **not** added — the network-dependence reasoning stands.

    ### Verification

    `make check` green, exit 0. Tests executed rather than replayed (zero `(cached)` lines, `internal/resolver 2.820s`), Docker lint stage executed rather than cached:

    ```
    #8 [deps 4/4] RUN go mod download
    #8 CACHED
    #10 [lint 2/2] RUN golangci-lint run --config .golangci.yml ./...
    #10 13.30 0 issues.
    ```

    Comment-only confirmed by reading the whole diff: no statement, flag, or command changed anywhere.

---

## Issues closed by this merge

The commits on `next` each carry a bare `(closes #N)` in their subject, but the
references in the prose above are full URLs, which Gitea's auto-close parser
does not act on. Listing them here in bare form so the merge to `main`
definitively closes them rather than leaving them open to be re-picked up as
idle work:

Closes #93
Closes #102
Closes #134
Closes #137
Closes #139

Co-authored-by: sneak <sneak@sneak.berlin>
Reviewed-on: #136
Co-authored-by: clawbot <clawbot@noreply.example.org>
Co-committed-by: clawbot <clawbot@noreply.example.org>

.dockerignore

@@ -0,0 +1,6 @@
+.git/
+bin/
+*.md
+LICENSE
+.editorconfig
+.gitignore

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[Makefile]
+indent_style = tab

.gitea/workflows/check.yml

@@ -0,0 +1,9 @@
+name: check
+on: [push]
+jobs:
+    check:
+        runs-on: ubuntu-latest
+        steps:
+            # actions/checkout v4.2.2, 2026-02-28
+            - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+            - run: script/cibuild

.golangci.yml

@@ -1,5 +1,9 @@
 version: "2"
 
+# Config schema uses the golangci-lint v2 layout (settings live under
+# linters.settings, not top-level linters-settings) so that the
+# thresholds below are actually applied by golangci-lint >= v2.
+
 run:
   timeout: 5m
   modules-download-mode: readonly
@@ -14,8 +18,7 @@ linters:
     - wsl              # Deprecated, replaced by wsl_v5
     - wrapcheck        # Too verbose for internal packages
     - varnamelen       # Short names like db, id are idiomatic Go
-
-linters-settings:
+  settings:
     lll:
       line-length: 88
     funlen:
@@ -27,6 +30,5 @@ linters-settings:
       threshold: 100
 
 issues:
-  exclude-use-default: false
   max-issues-per-linter: 0
   max-same-issues: 0

CLAUDE.md

@@ -1,68 +0,0 @@
-# Repository Rules
-
-Last Updated 2026-01-08
-
-These rules MUST be followed at all times, it is very important.
-
-* Never use `git add -A` - add specific changes to a deliberate commit. A
-  commit should contain one change. After each change, make a commit with a
-  good one-line summary.
-
-* NEVER modify the linter config without asking first.
-
-* NEVER modify tests to exclude special cases or otherwise get them to pass
-  without asking first. In almost all cases, the code should be changed,
-  NOT the tests. If you think the test needs to be changed, make your case
-  for that and ask for permission to proceed, then stop. You need explicit
-  user approval to modify existing tests. (You do not need user approval
-  for writing NEW tests.)
-
-* When linting, assume the linter config is CORRECT, and that each item
-  output by the linter is something that legitimately needs fixing in the
-  code.
-
-* When running tests, use `make test`.
-
-* Before commits, run `make check`. This runs `make lint` and `make test`
-  and `make check-fmt`. Any issues discovered MUST be resolved before
-  committing unless explicitly told otherwise.
-
-* When fixing a bug, write a failing test for the bug FIRST. Add
-  appropriate logging to the test to ensure it is written correctly. Commit
-  that. Then go about fixing the bug until the test passes (without
-  modifying the test further). Then commit that.
-
-* When adding a new feature, do the same - implement a test first (TDD). It
-  doesn't have to be super complex. Commit the test, then commit the
-  feature.
-
-* When adding a new feature, use a feature branch. When the feature is
-  completely finished and the code is up to standards (passes `make check`)
-  then and only then can the feature branch be merged into `main` and the
-  branch deleted.
-
-* Write godoc documentation comments for all exported types and functions as
-  you go along.
-
-* ALWAYS be consistent in naming. If you name something one thing in one
-  place, name it the EXACT SAME THING in another place.
-
-* Be descriptive and specific in naming. `wl` is bad;
-  `SourceHostWhitelist` is good. `ConnsPerHost` is bad;
-  `MaxConnectionsPerHost` is good.
-
-* This is not prototype or teaching code - this is designed for production.
-  Any security issues (such as denial of service) or other web
-  vulnerabilities are P1 bugs and must be added to TODO.md at the top.
-
-* As this is production code, no stubbing of implementations unless
-  specifically instructed. We need working implementations.
-
-* Avoid vendoring deps unless specifically instructed to.  NEVER commit
-  the vendor directory, NEVER commit compiled binaries.  If these
-  directories or files exist, add them to .gitignore (and commit the
-  .gitignore) if they are not already in there.  Keep the entire git
-  repository (with history) small - under 20MiB, unless you specifically
-  must commit larger files (e.g. test fixture example media files).  Only
-  OUR source code and immediately supporting files (such as test examples)
-  goes into the repo/history.

Dockerfile

@@ -1,11 +1,9 @@
-# Build stage
-FROM golang:1.25-alpine AS builder
-
-RUN apk add --no-cache git make gcc musl-dev
-
-# Install golangci-lint v2
-RUN go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
-RUN go install golang.org/x/tools/cmd/goimports@latest
+# Lint stage - fast feedback on lint issues, before the build starts.
+# The linter is invoked directly rather than through `make lint`: that
+# target shells out to `docker build -f Dockerfile.lint`, and there is
+# no docker daemon inside a docker build.
+# 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 ./
@@ -13,14 +11,33 @@ RUN go mod download
 
 COPY . .
 
-# Run all checks - build fails if any check fails
-RUN make check
+RUN make fmt-check
+RUN golangci-lint run --config .golangci.yml ./...
+
+# Build stage
+# golang 1.25-alpine, 2026-02-28
+FROM golang@sha256:f6751d823c26342f9506c03797d2527668d095b0a15f1862cddb4d927a7a4ced AS builder
+
+RUN apk add --no-cache git make gcc musl-dev binutils-gold
+
+# Force BuildKit to run the lint stage before proceeding
+COPY --from=lint /src/go.sum /dev/null
+
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+
+# Run the tests - build fails if any test fails
+RUN make test
 
 # Build the binary
 RUN make build
 
 # Runtime stage
-FROM alpine:3.21
+# alpine 3.21, 2026-02-28
+FROM alpine@sha256:c3f8e73fdb79deaebaa2037150150191b9dcbfba68b4a46d70103204c53f4709
 
 RUN apk add --no-cache ca-certificates tzdata
 

Dockerfile.lint

@@ -0,0 +1,29 @@
+# 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 ./...

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sneak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -1,37 +1,44 @@
-.PHONY: all build lint fmt test check clean
+.PHONY: all bootstrap setup build lint fmt fmt-check test check clean hooks docker
 
 BINARY := dnswatcher
 VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
-BUILDARCH := $(shell go env GOARCH)
-LDFLAGS := -X main.Version=$(VERSION) -X main.Buildarch=$(BUILDARCH)
+LDFLAGS := -X main.Version=$(VERSION)
+
+# Standard targets are thin shims; the implementations live in script/
+# per the scripts-to-rule-them-all pattern (see the Entrypoints section
+# of README.md).
 
 all: check build
 
+bootstrap:
+	@script/bootstrap
+
+setup:
+	@script/setup
+
 build:
 	go build -ldflags "$(LDFLAGS)" -o bin/$(BINARY) ./cmd/dnswatcher
 
+test:
+	@script/test
+
 lint:
-	golangci-lint run --config .golangci.yml ./...
+	@script/lint
 
 fmt:
-	gofmt -s -w .
-	goimports -w .
+	@script/fmt
 
-test:
-	go test -v -race -cover ./...
+fmt-check:
+	@script/fmt-check
 
-# Check runs all validation without making changes
-# Used by CI and Docker build - fails if anything is wrong
 check:
-	@echo "==> Checking formatting..."
-	@test -z "$$(gofmt -l .)" || (echo "Files not formatted:" && gofmt -l . && exit 1)
-	@echo "==> Running linter..."
-	golangci-lint run --config .golangci.yml ./...
-	@echo "==> Running tests..."
-	go test -v -race ./...
-	@echo "==> Building..."
-	go build -ldflags "$(LDFLAGS)" -o /dev/null ./cmd/dnswatcher
-	@echo "==> All checks passed!"
+	@script/check
+
+docker:
+	@script/docker
+
+hooks:
+	@script/install-precommit
 
 clean:
 	rm -rf bin/

README.md

@@ -1,7 +1,10 @@
 # dnswatcher
 
-dnswatcher is a production DNS and infrastructure monitoring daemon written in
-Go.  It watches configured DNS domains and hostnames for changes, monitors TCP
+dnswatcher is an MIT-licensed, pre-1.0 Go daemon by [@sneak](https://sneak.berlin) that monitors DNS records, TCP port availability, and TLS certificates, delivering real-time change notifications via Slack, Mattermost, and ntfy webhooks.
+
+> ⚠️ Pre-1.0 software. APIs, configuration, and behavior may change without notice.
+
+dnswatcher watches configured DNS domains and hostnames for changes, monitors TCP
 port availability, tracks TLS certificate expiry, and delivers real-time
 notifications via Slack, Mattermost, and/or ntfy webhooks.
 
@@ -14,6 +17,26 @@ without requiring an external database.
 
 ---
 
+## No DNS mocking. Ever.
+
+**DNS is never mocked in this project — not in tests, not anywhere else.**
+No mock resolvers, no fake DNS servers, no stubbed lookups.
+
+dnswatcher's entire purpose is correct behavior against the real DNS.
+Tests exercise real iterative resolution against live nameservers by
+design; a test suite that passes against a mock proves nothing about the
+one thing this program exists to do.
+
+When live tests are flaky, that is a robustness problem, and it gets
+fixed with robustness: retries with backoff, querying multiple
+independent nameservers, longer timeouts — or explicit opt-in gating
+decided by the project owner. Never with mocks.
+
+Contributions that introduce mocked, faked, or stubbed DNS will be
+rejected.
+
+---
+
 ## Features
 
 ### DNS Domain Monitoring (Apex Domains)
@@ -49,10 +72,6 @@ without requiring an external database.
     responding again.
   - **Inconsistency detected**: Two nameservers that previously agreed
     now return different record sets for the same hostname.
-  - **Inconsistency resolved**: Nameservers that previously disagreed
-    are now back in agreement.
-  - **Empty response**: A nameserver that previously returned records
-    now returns an authoritative empty response (NODATA/NXDOMAIN).
 
 ### TCP Port Monitoring
 
@@ -107,8 +126,8 @@ includes:
 - **NS recoveries**: Which nameserver recovered, which hostname/domain.
 - **NS inconsistencies**: Which nameservers disagree, what each one
   returned, which hostname affected.
-- **Port changes**: Which IP:port, old state, new state, associated
-  hostname.
+- **Port changes**: Which IP:port, old state, new state, all associated
+  hostnames.
 - **TLS expiry warnings**: Which certificate, days remaining, CN,
   issuer, associated hostname and IP.
 - **TLS certificate changes**: Old and new CN/issuer/SANs, associated
@@ -125,16 +144,42 @@ includes:
 - State is written atomically (write to temp file, then rename) to prevent
   corruption.
 
+### Web Dashboard
+
+dnswatcher includes an unauthenticated, read-only web dashboard at the
+root URL (`/`). It displays:
+
+- **Summary counts** for monitored domains, hostnames, ports, and
+  certificates.
+- **Domains** with their discovered nameservers.
+- **Hostnames** with per-nameserver DNS records and status.
+- **Ports** with open/closed state and associated hostnames.
+- **TLS certificates** with CN, issuer, expiry, and status.
+- **Recent alerts** (last 100 notifications sent since the process
+  started), displayed in reverse chronological order.
+
+Every data point shows its age (e.g. "5m ago") so you can tell at a
+glance how fresh the information is. The page auto-refreshes every 30
+seconds.
+
+The dashboard intentionally does not expose any configuration details
+such as webhook URLs, notification endpoints, or API tokens.
+
+All assets (CSS) are embedded in the binary and served from the
+application itself. The dashboard makes zero external HTTP requests —
+no CDN dependencies or third-party resources are loaded at runtime.
+
 ### HTTP API
 
 dnswatcher exposes a lightweight HTTP API for operational visibility:
 
 | Endpoint                              | Description                    |
 |---------------------------------------|--------------------------------|
-| `GET /health`                         | Health check (JSON)            |
+| `GET /`                               | Web dashboard (HTML)           |
+| `GET /s/...`                          | Static assets (embedded CSS)   |
+| `GET /.well-known/healthcheck`        | Health check (JSON)            |
+| `GET /health`                         | Health check (JSON, legacy)    |
 | `GET /api/v1/status`                  | Current monitoring state       |
-| `GET /api/v1/domains`                 | Configured domains and status  |
-| `GET /api/v1/hostnames`              | Configured hostnames and status|
 | `GET /metrics`                        | Prometheus metrics (optional)  |
 
 ---
@@ -146,7 +191,7 @@ cmd/dnswatcher/main.go         Entry point (uber/fx bootstrap)
 
 internal/
   config/config.go             Viper-based configuration
-  globals/globals.go           Build-time variables (version, arch)
+  globals/globals.go           Build-time variables (version)
   logger/logger.go             slog structured logging (TTY detection)
   healthcheck/healthcheck.go   Health check service
   middleware/middleware.go      HTTP middleware (logging, CORS, metrics auth)
@@ -173,7 +218,8 @@ internal/
 - **Structured logging**: All logs use `log/slog` with JSON output in
   production (TTY detection for development).
 - **Graceful shutdown**: All background goroutines respect context
-  cancellation and the fx lifecycle.
+  cancellation and the fx lifecycle. In-flight notification deliveries
+  are drained on shutdown, bounded by the shutdown timeout.
 
 ---
 
@@ -194,9 +240,8 @@ the following precedence (highest to lowest):
 |---------------------------------|--------------------------------------------|-------------|
 | `PORT`                          | HTTP listen port                           | `8080`      |
 | `DNSWATCHER_DEBUG`              | Enable debug logging                       | `false`     |
-| `DNSWATCHER_DATA_DIR`           | Directory for state file                   | `./data`    |
-| `DNSWATCHER_DOMAINS`            | Comma-separated list of apex domains       | `""`        |
-| `DNSWATCHER_HOSTNAMES`          | Comma-separated list of hostnames          | `""`        |
+| `DNSWATCHER_DATA_DIR`           | Directory for state file                   | `/var/lib/dnswatcher` |
+| `DNSWATCHER_TARGETS`            | Comma-separated DNS names (auto-classified via PSL) | `""`  |
 | `DNSWATCHER_SLACK_WEBHOOK`      | Slack incoming webhook URL                 | `""`        |
 | `DNSWATCHER_MATTERMOST_WEBHOOK` | Mattermost incoming webhook URL            | `""`        |
 | `DNSWATCHER_NTFY_TOPIC`         | ntfy topic URL                             | `""`        |
@@ -207,18 +252,25 @@ the following precedence (highest to lowest):
 | `DNSWATCHER_MAINTENANCE_MODE`   | Enable maintenance mode                    | `false`     |
 | `DNSWATCHER_METRICS_USERNAME`   | Basic auth username for /metrics           | `""`        |
 | `DNSWATCHER_METRICS_PASSWORD`   | Basic auth password for /metrics           | `""`        |
+| `DNSWATCHER_SEND_TEST_NOTIFICATION` | Send a test notification after first scan completes | `false` |
+
+**`DNSWATCHER_TARGETS` is required.** dnswatcher will refuse to start if no
+monitoring targets are configured. A monitoring daemon with nothing to monitor
+is a misconfiguration, so dnswatcher fails fast with a clear error message
+rather than running silently. Set `DNSWATCHER_TARGETS` to a comma-separated
+list of DNS names before starting.
 
 ### Example `.env`
 
 ```sh
 PORT=8080
 DNSWATCHER_DEBUG=false
-DNSWATCHER_DATA_DIR=./data
-DNSWATCHER_DOMAINS=example.com,example.org
-DNSWATCHER_HOSTNAMES=www.example.com,api.example.com,mail.example.org
+DNSWATCHER_DATA_DIR=/var/lib/dnswatcher
+DNSWATCHER_TARGETS=example.com,example.org,www.example.com,api.example.com,mail.example.org
 DNSWATCHER_SLACK_WEBHOOK=https://hooks.slack.com/services/T.../B.../xxx
 DNSWATCHER_MATTERMOST_WEBHOOK=https://mattermost.example.com/hooks/xxx
 DNSWATCHER_NTFY_TOPIC=https://ntfy.sh/my-dns-alerts
+DNSWATCHER_SEND_TEST_NOTIFICATION=true
 ```
 
 ---
@@ -289,12 +341,12 @@ not as a merged view, to enable inconsistency detection.
   "ports": {
     "93.184.216.34:80": {
       "open": true,
-      "hostname": "www.example.com",
+      "hostnames": ["www.example.com"],
       "lastChecked": "2026-02-19T12:00:00Z"
     },
     "93.184.216.34:443": {
       "open": true,
-      "hostname": "www.example.com",
+      "hostnames": ["www.example.com"],
       "lastChecked": "2026-02-19T12:00:00Z"
     }
   },
@@ -318,29 +370,63 @@ tracks reachability:
 |-------------|-------------------------------------------------|
 | `ok`        | Query succeeded, records are current             |
 | `error`     | Query failed (timeout, SERVFAIL, network error)  |
-| `nxdomain`  | Authoritative NXDOMAIN response                  |
-| `nodata`    | Authoritative empty response (NODATA)            |
 
 ---
 
+## Entrypoints
+
+This repository adheres to the
+[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+standard: normalized scripts in `script/` are the entrypoints for the
+development workflow, and the Makefile targets are thin shims that call
+them. We provide:
+
+- `script/bootstrap` — install all dependencies (go, pinned goimports,
+  `go mod download`). It does not install golangci-lint: see
+  `script/lint` below.
+- `script/setup` — make a fresh clone ready for development: bootstrap
+  plus the git pre-commit hook
+- `script/projectname` — print the project name (used for the Docker
+  image tag)
+- `script/test` — run the test suite (race detector, coverage). Caching
+  is waived for testing, exactly as it is for linting: `-count=1`
+  forces every invocation to execute, because the suite queries live
+  DNS and a cached pass queries nothing. Failures are rerun with `-v`
+  automatically, and the build fails even if that rerun passes.
+- `script/lint` — run golangci-lint, always inside Docker: it builds
+  `Dockerfile.lint`, which COPYs the repo into the digest-pinned
+  `golangci-lint` image and lints as a build step, so a successful
+  build is a clean lint. The linter is never installed or run on the
+  host, and Docker is the only prerequisite. Caching is waived for
+  linting: the lint stage is forced to execute on every run with
+  `--no-cache-filter`, because a cached build lints nothing.
+- `script/fmt` — format all code (gofmt -s, goimports)
+- `script/fmt-check` — check formatting (read-only)
+- `script/check` — run test, lint, and fmt-check
+- `script/docker` — build the Docker image tagged via
+  `script/projectname`
+- `script/cibuild` — CI entrypoint: plain `docker build .`
+- `script/precommit` — run by the git pre-commit hook; `go mod tidy`
+  guard, then `script/check`
+- `script/install-precommit` — install the git pre-commit hook
+
 ## Building
 
 ```sh
 make build      # Build binary to bin/dnswatcher
 make test       # Run tests with race detector
-make lint       # Run golangci-lint
+make lint       # Run golangci-lint in Docker (requires docker)
 make fmt        # Format code
-make check      # Run all checks (format, lint, test, build)
+make check      # Run all checks (test, lint, fmt-check)
 make clean      # Remove build artifacts
 ```
 
 ### Build-Time Variables
 
-Version and architecture are injected via `-ldflags`:
+Version is injected via `-ldflags`:
 
 ```sh
-go build -ldflags "-X main.Version=$(git describe --tags --always) \
-  -X main.Buildarch=$(go env GOARCH)" ./cmd/dnswatcher
+go build -ldflags "-X main.Version=$(git describe --tags --always)" ./cmd/dnswatcher
 ```
 
 ---
@@ -352,9 +438,9 @@ docker build -t dnswatcher .
 docker run -d \
   -p 8080:8080 \
   -v dnswatcher-data:/var/lib/dnswatcher \
-  -e DNSWATCHER_DOMAINS=example.com \
-  -e DNSWATCHER_HOSTNAMES=www.example.com \
+  -e DNSWATCHER_TARGETS=example.com,www.example.com \
   -e DNSWATCHER_NTFY_TOPIC=https://ntfy.sh/my-alerts \
+  -e DNSWATCHER_SEND_TEST_NOTIFICATION=true \
   dnswatcher
 ```
 
@@ -367,19 +453,50 @@ docker run -d \
    triggering change notifications).
 2. **Initial check**: Immediately perform all DNS, port, and TLS checks
    on startup.
-3. **Periodic checks**:
-   - DNS and port checks: every `DNSWATCHER_DNS_INTERVAL` (default 1h).
-   - TLS checks: every `DNSWATCHER_TLS_INTERVAL` (default 12h).
+3. **Periodic checks** (DNS always runs first):
+   - DNS checks: every `DNSWATCHER_DNS_INTERVAL` (default 1h). Also
+     re-run before every TLS check cycle to ensure fresh IPs.
+   - Port checks: every `DNSWATCHER_DNS_INTERVAL`, after DNS completes.
+   - TLS checks: every `DNSWATCHER_TLS_INTERVAL` (default 12h), after
+     DNS completes.
+   - Port and TLS checks always use freshly resolved IP addresses from
+     the DNS phase that immediately precedes them — never stale IPs
+     from a previous cycle.
 4. **On change detection**: Send notifications to all configured
    endpoints, update in-memory state, persist to disk.
-5. **Shutdown**: Persist final state to disk, complete in-flight
-   notifications, stop gracefully.
+5. **Shutdown**: Persist final state to disk, wait for in-flight
+   notification deliveries to complete, stop gracefully. The wait is
+   bounded by the fx shutdown timeout (15s by default): deliveries still
+   retrying against an unreachable endpoint when that expires are
+   abandoned, and the number abandoned is logged at warn level rather
+   than dropped silently. Notifications generated after shutdown has
+   begun are refused and logged, so a late burst cannot extend the
+   shutdown.
+
+---
+
+## Planned Future Features (Post-1.0)
+
+- **DNSSEC validation**: Validate the DNSSEC chain of trust during
+  iterative resolution and report DNSSEC failures as notifications.
 
 ---
 
 ## Project Structure
 
-Follows the conventions defined in `CONVENTIONS.md`, adapted from the
+Follows the conventions defined in `REPO_POLICIES.md`, adapted from the
 [upaas](https://git.eeqj.de/sneak/upaas) project template.  Uses uber/fx
 for dependency injection, go-chi for HTTP routing, slog for logging, and
 Viper for configuration.
+
+---
+
+## License
+
+dnswatcher is released under the MIT License, Copyright (c) 2026
+[@sneak](https://sneak.berlin). See the [`LICENSE`](./LICENSE) file in the
+repository root for the full text.
+
+## Author
+
+[@sneak](https://sneak.berlin)

REPO_POLICIES.md

@@ -0,0 +1,416 @@
+---
+title: Repository Policies
+last_modified: 2026-08-07
+---
+
+This document covers repository structure, tooling, and workflow standards. Code
+style conventions are in separate documents:
+
+- [Code Styleguide](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE.md)
+  (general, bash, Docker)
+- [Go](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_GO.md)
+- [JavaScript](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_JS.md)
+- [Python](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_PYTHON.md)
+- [Go HTTP Server Conventions](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/GO_HTTP_SERVER_CONVENTIONS.md)
+
+---
+
+- Cross-project documentation (such as this file) must include
+  `last_modified: YYYY-MM-DD` in the YAML front matter so it can be kept in sync
+  with the authoritative source as policies evolve.
+
+- **ALL external references must be pinned by cryptographic hash.** This
+  includes Docker base images, Go modules, npm packages, GitHub Actions, and
+  anything else fetched from a remote source. Version tags (`@v4`, `@latest`,
+  `:3.21`, etc.) are server-mutable and therefore remote code execution
+  vulnerabilities. The ONLY acceptable way to reference an external dependency
+  is by its content hash (Docker `@sha256:...`, Go module hash in `go.sum`, npm
+  integrity hash in lockfile, GitHub Actions `@<commit-sha>`). No exceptions.
+  This also means never `curl | bash` to install tools like pyenv, nvm, rustup,
+  etc. Instead, download a specific release archive from GitHub, verify its hash
+  (hardcoded in the Dockerfile or script), and only then install. Unverified
+  install scripts are arbitrary remote code execution. This is the single most
+  important rule in this document. Double-check every external reference in
+  every file before committing. There are zero exceptions to this rule.
+
+- Every repo with software must have a root `Makefile` with these targets:
+  `make bootstrap`, `make setup`, `make test`, `make lint`, `make fmt` (writes),
+  `make fmt-check` (read-only), `make check` (runs `test`, `lint`, `fmt-check`),
+  `make docker`, and `make hooks` (installs pre-commit hook). A model Makefile
+  is at `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`.
+
+- Repos follow the
+  [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+  pattern: the implementation of each Makefile target lives in an executable
+  script in `script/` (`script/bootstrap`, `script/setup`, `script/test`,
+  `script/lint`, `script/fmt`, `script/fmt-check`, `script/check`,
+  `script/docker`), and the Makefile targets are thin shims that call them. The
+  scripts must be POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run in
+  minimal containers (e.g. alpine images have no bash); locate the repo root
+  with `$(cd "$(dirname "$0")/.." && pwd -P)` and `cd` there before acting. From
+  the standard's canonical set we use `bootstrap`, `setup` (make the repo ready
+  for development after a fresh clone: runs `bootstrap`, then
+  `install-precommit`, plus any repo-specific initialization), `test`, and
+  `cibuild`. `script/bootstrap` installs all dependencies idempotently and
+  assumes nothing is present: base tools come from nix, apt, brew, or apk
+  (detected in that order; apt runs noninteractive). For node it uses the
+  installed node if present; otherwise it installs a PINNED node version via
+  nvm, first installing nvm itself if missing — from a hash-verified GitHub
+  release archive (never `curl | sh`), with bash installed as an explicit
+  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
+  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).
+
+- Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.)
+  instead of invoking the underlying tools directly. The Makefile is the single
+  source of truth for how these operations are run.
+
+- The Makefile is authoritative documentation for how the repo is used. Beyond
+  the required targets above, it should have targets for every common operation:
+  running a local development server (`make run`, `make dev`), re-initializing
+  or migrating the database (`make db-reset`, `make migrate`), building
+  artifacts (`make build`), generating code, seeding data, or anything else a
+  developer would do regularly. If someone checks out the repo and types
+  `make<tab>`, they should see every meaningful operation available. A new
+  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`
+  as a build step so the build fails if the branch is not green. For non-server
+  repos, the Dockerfile should bring up a development environment and run
+  `make check`. For server repos, `make check` should run as an early build
+  stage before the final image is assembled. Dockerfiles install development
+  prerequisites by running `script/bootstrap` rather than duplicating installs
+  inline; COPY `script/` and the dependency manifests (`package.json` +
+  `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it so the bootstrap
+  layer stays cached until dependencies change.
+
+- **Dockerfiles must use a separate lint stage for fail-fast feedback.** Go
+  repos use a multistage build where linting runs in an independent stage based
+  on the `golangci/golangci-lint` image (pinned by hash). This stage runs
+  `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:
+
+    ```dockerfile
+    # Lint stage — fast feedback on formatting and lint issues
+    # 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 make lint
+
+    # Build stage
+    # golang:1.x-alpine, YYYY-MM-DD
+    FROM golang@sha256:... AS builder
+    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
+
+    ARG VERSION=dev
+    RUN CGO_ENABLED=0 go build -trimpath \
+        -ldflags="-s -w -X main.Version=${VERSION}" \
+        -o /app ./cmd/app/
+
+    # Runtime stage
+    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
+      includes both Go and the linter), so there is no need to install the
+      linter separately.
+    - `COPY --from=lint /src/go.sum /dev/null` is a no-op file copy that creates
+      a stage dependency. BuildKit runs stages in parallel by default; without
+      this line, the build stage would not wait for lint to finish and a lint
+      failure might not fail the overall build.
+    - 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
+      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
+      fail fast.
+    - If the project requires CGO or system libraries for linting (e.g.
+      `vips-dev`), install them in the lint stage with `apk add`.
+    - The build stage runs `make test` after compilation setup. Tests run in the
+      build stage, not the lint stage, because they may require compiled
+      artifacts or heavier dependencies.
+
+- Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
+  runs `script/cibuild` (which runs `docker build .`) on push. Since the
+  Dockerfile already runs `make check`, a successful build implies all checks
+  pass.
+
+- Use platform-standard formatters: `black` for Python, `prettier` for
+  JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
+  two exceptions: four-space indents (except Go), and `proseWrap: always` for
+  Markdown (hard-wrap at 80 columns). Documentation and writing repos (Markdown,
+  HTML, CSS) should also have `.prettierrc` and `.prettierignore`.
+
+- Pre-commit hook: runs `script/precommit`, which calls `script/check`. If local
+  testing is not possible in the repo, `script/precommit` may skip `script/test`
+  and run only `script/lint` and `script/fmt-check`. The hook is installed by
+  `script/install-precommit`; the Makefile must provide a `make hooks` target
+  that shims to it.
+
+- All repos with software must have tests that run via the platform-standard
+  test framework (`go test`, `pytest`, `jest`/`vitest`, etc.). If no meaningful
+  tests exist yet, add the most minimal test possible — e.g. importing the
+  module under test to verify it compiles/parses. There is no excuse for
+  `make test` to be a no-op.
+
+- `make test` must complete in under 60 seconds. That is the hard cap, and a
+  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
+  sits above the hard cap so that it catches a genuinely hung test rather than a
+  merely slow one.
+
+- **`make test` should use the conditional verbose rerun pattern.** Run tests
+  without `-v` (verbose) first. If tests fail, automatically rerun with `-v` to
+  show full output. This keeps CI logs and `docker build` output clean on
+  success (just package/suite summaries) while providing full diagnostic detail
+  on failure (every test case, every assertion). The general shell pattern:
+
+    ```makefile
+    test:
+    	@<test-command> || \
+    		{ echo "--- Rerunning with -v for details ---"; \
+    		  <test-command-with-v>; exit 1; }
+    ```
+
+    Go example:
+
+    ```makefile
+    test:
+    	@go test -timeout 90s -race -cover ./... || \
+    		{ echo "--- Rerunning with -v for details ---"; \
+    		  go test -timeout 90s -race -v ./...; exit 1; }
+    ```
+
+    Python example:
+
+    ```makefile
+    test:
+    	@python -m pytest || \
+    		{ echo "--- Rerunning with -v for details ---"; \
+    		  python -m pytest -v; exit 1; }
+    ```
+
+    The `exit 1` ensures the target always fails after a rerun — the first run
+    already proved the tests are broken, so the build must not pass even if a
+    flaky test happens to succeed on the second attempt. The rerun exists solely
+    for diagnostic output.
+
+- Docker builds must complete in under 5 minutes.
+
+- `make check` must not modify any files in the repo. Tests may use temporary
+  directories.
+
+- `main` must always pass `make check`, no exceptions.
+
+- Never commit secrets. `.env` files, credentials, API keys, and private keys
+  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/`.
+  Fetch the standard `.gitignore` from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
+  a new repo.
+
+- **No build artifacts in version control.** Code-derived data (compiled
+  bundles, minified output, generated assets) must never be committed to the
+  repository if it can be avoided. The build process (e.g. Dockerfile, Makefile)
+  should generate these at build time. Notable exception: Go protobuf generated
+  files (`.pb.go`) ARE committed because repos need to work with `go get`, which
+  downloads code but does not execute code generation.
+
+- Never use `git add -A` or `git add .`. Always stage files explicitly by name.
+
+- Never force-push to `main`.
+
+- 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
+  manually by the user. Fetch from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`. The
+  canonical golangci-lint version is v2.12.2 (released 2026-05-06), installed
+  commit-pinned via
+  `go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@c0d3ddc9cf3faa61a4e378e879ece580256d76e5`.
+
+- When pinning images or packages by hash, add a comment above the reference
+  with the version and date (YYYY-MM-DD).
+
+- Use `yarn`, not `npm`.
+
+- Write all dates as YYYY-MM-DD (ISO 8601).
+
+- Simple projects should be configured with environment variables.
+
+- Dockerized web services listen on port 8080 by default, overridable with
+  `PORT`.
+
+- **HTTP/web services must be hardened for production internet exposure before
+  tagging 1.0.** This means full compliance with security best practices
+  including, without limitation, all of the following:
+    - **Security headers** on every response:
+        - `Strict-Transport-Security` (HSTS) with `max-age` of at least one year
+          and `includeSubDomains`.
+        - `Content-Security-Policy` (CSP) with a restrictive default policy
+          (`default-src 'self'` as a baseline, tightened per-resource as
+          needed). Never use `unsafe-inline` or `unsafe-eval` unless
+          unavoidable, and document the reason.
+        - `X-Frame-Options: DENY` (or `SAMEORIGIN` if framing is required).
+          Prefer the `frame-ancestors` CSP directive as the primary control.
+        - `X-Content-Type-Options: nosniff`.
+        - `Referrer-Policy: strict-origin-when-cross-origin` (or stricter).
+        - `Permissions-Policy` restricting access to browser features the
+          application does not use (camera, microphone, geolocation, etc.).
+    - **Request and response limits:**
+        - Maximum request body size enforced on all endpoints (e.g. Go
+          `http.MaxBytesReader`). Choose a sane default per-route; never accept
+          unbounded input.
+        - Maximum response body size where applicable (e.g. paginated APIs).
+        - `ReadTimeout` and `ReadHeaderTimeout` on the `http.Server` to defend
+          against slowloris attacks.
+        - `WriteTimeout` on the `http.Server`.
+        - `IdleTimeout` on the `http.Server`.
+        - Per-handler execution time limits via `context.WithTimeout` or
+          chi/stdlib `middleware.Timeout`.
+    - **Authentication and session security:**
+        - Rate limiting on password-based authentication endpoints. API keys are
+          high-entropy and not susceptible to brute force, so they are exempt.
+        - CSRF tokens on all state-mutating HTML forms. API endpoints
+          authenticated via `Authorization` header (Bearer token, API key) are
+          exempt because the browser does not attach these automatically.
+        - Passwords stored using bcrypt, scrypt, or argon2 — never plain-text,
+          MD5, or SHA.
+        - Session cookies set with `HttpOnly`, `Secure`, and `SameSite=Lax` (or
+          `Strict`) attributes.
+    - **Reverse proxy awareness:**
+        - True client IP detection when behind a reverse proxy
+          (`X-Forwarded-For`, `X-Real-IP`). The application must accept
+          forwarded headers only from a configured set of trusted proxy
+          addresses — never trust `X-Forwarded-For` unconditionally.
+    - **CORS:**
+        - Authenticated endpoints must restrict `Access-Control-Allow-Origin` to
+          an explicit allowlist of known origins. Wildcard (`*`) is acceptable
+          only for public, unauthenticated read-only APIs.
+    - **Error handling:**
+        - Internal errors must never leak stack traces, SQL queries, file paths,
+          or other implementation details to the client. Return generic error
+          messages in production; detailed errors only when `DEBUG` is enabled.
+    - **TLS:**
+        - Services never terminate TLS directly. They are always deployed behind
+          a TLS-terminating reverse proxy. The service itself listens on plain
+          HTTP. However, HSTS headers and `Secure` cookie flags must still be
+          set by the application so that the browser enforces HTTPS end-to-end.
+
+    This list is non-exhaustive. Apply defense-in-depth: if a standard security
+    hardening measure exists for HTTP services and is not listed here, it is
+    still expected. When in doubt, harden.
+
+- `README.md` is the primary documentation. Required sections:
+    - **Description**: First line must include the project name, purpose,
+      category (web server, SPA, CLI tool, etc.), license, and author. Example:
+      "µPaaS is an MIT-licensed Go web application by @sneak that receives
+      git-frontend webhooks and deploys applications via Docker in realtime."
+    - **Getting Started**: Copy-pasteable install/usage code block.
+    - **Entrypoints**: Opens by stating that the repo adheres to the
+      [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+      standard (with that link), then documents each provided `script/`
+      entrypoint and its purpose.
+    - **Rationale**: Why does this exist?
+    - **Design**: How is the program structured?
+    - **TODO**: Update meticulously, even between commits. When planning, put
+      the todo list in the README so a new agent can pick up where the last one
+      left off.
+    - **License**: MIT, GPL, or WTFPL. Ask the user for new projects. Include a
+      `LICENSE` file in the repo root and a License section in the README.
+    - **Author**: [@sneak](https://sneak.berlin).
+
+- First commit of a new repo should contain only `README.md`.
+
+- Go module root: `sneak.berlin/go/<name>`. Always run `go mod tidy` before
+  committing.
+
+- Use SemVer.
+
+- Database migrations live in `internal/db/migrations/` and must be embedded in
+  the binary.
+    - `000_migration.sql` — contains ONLY the creation of the migrations
+      tracking table itself. Nothing else.
+    - `001_schema.sql` — the full application schema.
+    - **Pre-1.0.0:** never add additional migration files (002, 003, etc.).
+      There is no installed base to migrate. Edit `001_schema.sql` directly.
+    - **Post-1.0.0:** add new numbered migration files for each schema change.
+      Never edit existing migrations after release.
+
+- All repos should have an `.editorconfig` enforcing the project's indentation
+  settings.
+
+- Avoid putting files in the repo root unless necessary. Root should contain
+  only project-level config files (`README.md`, `Makefile`, `Dockerfile`,
+  `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and
+  language-specific config). Everything else goes in a subdirectory. Canonical
+  subdirectory names:
+    - `bin/` — executable scripts and tools
+    - `cmd/` — Go command entrypoints
+    - `configs/` — configuration templates and examples
+    - `deploy/` — deployment manifests (k8s, compose, terraform)
+    - `docs/` — documentation and markdown (README.md stays in root)
+    - `internal/` — Go internal packages
+    - `internal/db/migrations/` — database migrations
+    - `pkg/` — Go library packages
+    - `share/` — systemd units, data files
+    - `static/` — static assets (images, fonts, etc.)
+    - `web/` — web frontend source
+
+- When setting up a new repo, files from the `prompts` repo may be used as
+  templates. Fetch them from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/<path>`.
+
+- New repos must contain at minimum:
+    - `README.md`, `.git`, `.gitignore`, `.editorconfig`
+    - `LICENSE`, `REPO_POLICIES.md` (copy from the `prompts` repo)
+    - `Makefile`
+    - `script/` entrypoints (`bootstrap`, `setup`, `projectname`, `test`,
+      `lint`, `fmt`, `fmt-check`, `check`, `docker`, `cibuild`, `precommit`,
+      `install-precommit`)
+    - `Dockerfile`, `.dockerignore`
+    - `.gitea/workflows/check.yml`
+    - Go: `go.mod`, `go.sum`, `.golangci.yml`
+    - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
+    - Python: `pyproject.toml`

TESTING.md

@@ -0,0 +1,37 @@
+# Testing Policy
+
+## DNS Resolution Tests
+
+All resolver tests **MUST** use live queries against real DNS servers.
+No mocking of the DNS client layer is permitted.
+
+### Rationale
+
+The resolver performs iterative resolution from root nameservers through
+the full delegation chain. Mocked responses cannot faithfully represent
+the variety of real-world DNS behavior (truncation, referrals, glue
+records, DNSSEC, varied response times, EDNS, etc.). Testing against
+real servers ensures the resolver works correctly in production.
+
+### Constraints
+
+- Tests hit real DNS infrastructure and require network access
+- Test duration depends on network conditions; timeout tuning keeps
+  the suite within the 60-second target
+- Query timeout is calibrated to 3× maximum antipodal RTT (~300ms)
+  plus processing margin
+- Root server fan-out is limited to reduce parallel query load
+- Flaky failures from transient network issues are acceptable and
+  should be investigated as potential resolver bugs, not papered over
+  with mocks or skip flags
+
+### What NOT to do
+
+- **Do not mock `DNSClient`** for resolver tests (the mock constructor
+  exists for unit-testing other packages that consume the resolver)
+- **Do not add `-short` flags** to skip slow tests
+- **Do not increase `-timeout`** to hide hanging queries
+- **Do not remove `-count=1` from `script/test`** — Go's 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

@@ -0,0 +1,227 @@
+# Workflow
+
+* branch (from `main`)
+* do the work in Next Step
+* move Next Step to the top of Completed Steps
+* move the top item of Future Steps into Next Step
+* commit (`TODO.md` changes in the same commit as the work)
+* merge to `main` if the branch is not protected, otherwise open a PR
+* push
+
+# Status
+
+pre-1.0. No git tags. Core resolver work in flight on feature/resolver
+(dirty: internal/resolver/resolver_test.go). Local checkout has diverged
+from origin: origin/main is 8 commits ahead (watcher orchestrator,
+unified TARGETS) and origin/feature/resolver already contains the full
+iterative resolver implementation with hermetic mocked tests.
+
+# Next Step
+
+Add the README sections required by policy (Description, Getting Started,
+Rationale, Design, TODO, License, Author) if any are still missing.
+
+# Completed Steps
+
+- 2026-08-10: comment-only corrections to `script/bootstrap`,
+  `script/cibuild`, and `Dockerfile.lint`. The `goimports` pin in
+  `script/bootstrap` was justified by a claim that `script/fmt-check`
+  runs it on the host; it does not (it runs `gofmt -l .` only), so the
+  header now credits `script/fmt` alone. `script/cibuild` still claimed
+  the `Dockerfile` runs `make check`, which stopped being true when
+  linting moved to its own stage; it now describes the lint stage
+  (`make fmt-check` plus `golangci-lint`) and the builder stage
+  (`make test`, `make build`). The `docker`-missing warning in
+  `script/bootstrap` reads as one sentence instead of three fragments
+  each re-prefixed with `bootstrap:`. `Dockerfile.lint` now records the
+  residual risk of omitting `golangci-lint config verify`: unknown
+  top-level keys in `.golangci.yml` are silently ignored, so a mistyped
+  key lints clean while applying nothing. No behaviour changed
+- 2026-08-10: MIT `LICENSE` added at the repository root, closing the
+  last gap in `REPO_POLICIES.md`'s required-minimum file list and
+  removing the all-rights-reserved default that would otherwise have
+  shipped with a 1.0 tag. The licence choice is the standing org policy
+  (any public repo lacking a licence gets MIT; a private repo with no
+  licence is already all-rights-reserved), and this repo is public. The
+  file holds the canonical MIT text byte-for-byte with only the
+  copyright line filled in (`Copyright (c) 2026 sneak`); no clauses were
+  added, removed, or reflowed. `README.md`'s first line now names the
+  licence, as the Description requirement demands, and the License
+  section states MIT and points at the file instead of saying the choice
+  is pending. `make fmt` covers only Go sources (`gofmt -s`,
+  `goimports`), so it cannot reflow `LICENSE`
+- 2026-08-10: the policy scaffold (`REPO_POLICIES.md`, `.editorconfig`,
+  `.dockerignore`, `.gitea/workflows/check.yml`, and the `fmt-check`,
+  `docker`, and hooks Makefile targets) is present; it landed piecemeal
+  across the scripts-to-rule-them-all and policy commits rather than as
+  the single commit this file once planned
+- 2026-08-10: Go's test cache disabled for `script/test` via `-count=1`,
+  so every invocation actually executes. A cached pass replays an
+  earlier run's output without querying DNS at all, which in this repo
+  means the suite's entire premise goes unexercised while the run
+  reports green in under a second. The conditional verbose rerun that
+  `REPO_POLICIES.md` mandates was added at the same time (the primary
+  run had been unconditionally `-v`): quiet first, `-v` only on
+  failure, `-count=1` on both, and exit 1 forced regardless of the
+  rerun's result so a flake passing the second time cannot turn the
+  build green. `-timeout 90s` left alone as the deliberate backstop
+  above the 60s hard cap. Uncached suite runs ~4s, well inside the 20s
+  target
+- 2026-08-10: live-DNS test flakiness addressed by robustness rather
+  than gating, per the owner's ruling on #93: new
+  `internal/resolver/livedns_test.go` adds a package-wide concurrency
+  gate (so parallel tests stop bursting at the first root server),
+  retry with exponential backoff on transport failures only, and
+  quorum instead of unanimity for multi-nameserver assertions. Quorum
+  tolerates silence only: every per-nameserver status must be in a
+  closed allowlist (`ok`/`timeout`/`error`, or
+  `nxdomain`/`timeout`/`error`), so a wrong answer from a minority —
+  `nodata` today, any status added later — fails the test instead of
+  sliding through under the majority. The
+  `make test` cap moved to the new org-wide 60s hard cap / 20s target
+  with a 90s `-timeout` backstop; `REPO_POLICIES.md` re-vendored
+  byte-identical from `sneak/prompts`. No mocks, no `-short`, no build
+  tags, no skips, and no change to production resolver behaviour
+- 2026-08-10: all linting moved into Docker: new root `Dockerfile.lint`
+  on the digest-pinned `golangci/golangci-lint:v2.12.2` image,
+  `script/lint` reduced to a thin wrapper that builds it with
+  `--no-cache-filter=lint` so the linter actually executes every run,
+  golangci-lint install dropped from `script/bootstrap` (goimports
+  stays, `script/fmt` needs it on the host), and the root `Dockerfile`
+  given its own lint stage so its build no longer recurses through
+  `make check` into `script/lint`. `golangci-lint config verify` is
+  deliberately omitted: it fetches its schema over an unpinned live
+  HTTPS call
+- 2026-08-09: in-flight notification deliveries are now drained at
+  shutdown (#106): `notify.New` registers an fx `OnStop` hook that waits
+  on a `sync.WaitGroup` of tracked delivery goroutines, bounded by the
+  `OnStop` context; on expiry the outstanding count is logged at warn
+  level and parked retry backoffs are released instead of being dropped
+  silently, and deliveries submitted after the drain begins are refused
+  so shutdown cannot be extended indefinitely; an `OnStop` context that
+  is already expired on entry with nothing outstanding drains quietly
+  rather than warning about deliveries that were never abandoned
+- 2026-08-07: golangci-lint bumped to v2.12.2 (commit-pinned installs
+  in `Dockerfile` and `script/bootstrap`); `.golangci.yml` set to the
+  org-standard v2-schema config used across the org's repos
+  (owner-authorized; same file is being landed as canonical via prompts
+  PR #24), with settings under `linters.settings` so the
+  lll/funlen/cyclop/dupl thresholds apply; fixed the resulting
+  `goconst`, `dupl`, and `lll` findings; the informational `gomodguard`
+  deprecation warning under this config is accepted
+- 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints,
+  Makefile shims, README Entrypoints section
+- 2026-02-20: iterative DNS resolver implemented; tests made hermetic
+  with mocked DNS (origin/feature/resolver, unmerged)
+- 2026-02-20: CI actions and go install refs pinned to commit SHAs;
+  Gitea Actions workflow for make check (origin/ci/make-check, unmerged)
+- 2026-02-20: watcher monitoring orchestrator merged to main (#8)
+- 2026-02-20: DOMAINS/HOSTNAMES unified into single TARGETS config (#11)
+- 2026-02-19: TCP port connectivity checker, made concurrent with port
+  validation; gosec G704 SSRF findings fixed without suppression
+  (feature branches, unmerged)
+- 2026-02-19: TLS certificate inspector with no-peer-certificates error
+  path and IP SANs (feature branch, unmerged)
+- 2026-02-19: gosec SSRF and formatting fixes on main
+- 2026-02-19: initial scaffold with per-nameserver DNS monitoring model
+
+# Future Steps
+
+Compliance:
+
+- Pin Dockerfile base images by sha256 and ensure the Docker build runs
+  make check
+
+Branch reconciliation:
+
+- Sync local checkout with origin: local main is 8 commits behind
+  origin/main; local feature/resolver has diverged from
+  origin/feature/resolver, which already implements the resolver
+- Merge in-flight branches to main once green: feature/resolver,
+  ci/make-check, feature/portcheck-implementation,
+  feature/tlscheck-implementation
+
+Resolver (plan from untracked TODO.md; largely implemented on
+origin/feature/resolver, verify each item before closing):
+
+- Add github.com/miekg/dns dependency
+- roots.go: hardcoded IANA root server list (a through m, IPv4/IPv6),
+  rootServers() returning ip:53 strings
+- query.go: low-level query(ctx, server, name, qtype): UDP with TCP
+  fallback on truncation, RD=0, context respected, 5s per-query timeout,
+  returns raw *dns.Msg
+- trace.go: iterative delegation chasing from roots: referral detection
+  (NOERROR, empty answer, NS in authority), glue extraction with
+  bailiwick check, out-of-bailiwick NS resolved with recursion guard,
+  delegation depth limit (20), retry across nameservers on failure, do
+  not chase CNAMEs inside trace
+- FindAuthoritativeNameservers: NS set via trace, sorted, FQDN
+  normalized, trailing dot handled; must pass its 9 tests
+- QueryNameserver: resolve NS host to IPs, query A/AAAA/CNAME/MX/TXT/
+  SRV/CAA/NS, build NameserverResponse with status mapping (OK,
+  NXDomain, NoData, Error), documented record formatting, sorted values,
+  lame delegation detection; must pass its 16 tests
+- QueryAllNameservers: find NS set for parent domain (public suffix
+  list), query all NS in parallel with bounded concurrency, return map
+  even when all fail, context cancellation; must pass its 4 tests
+- LookupNS: thin wrapper over FindAuthoritativeNameservers, sorted,
+  identical results; must pass its 3 tests
+- ResolveIPAddresses: collect A/AAAA from all NS, follow CNAME chains
+  with MaxCNAMEDepth, dedupe, sort, NXDOMAIN returns empty slice with
+  nil error; must pass its 9 tests
+- All 39 resolver tests pass, make check green, merge to main
+
+Watcher (internal/watcher/watcher.go):
+
+- Scheduling loop in Run(ctx): initial check on startup, separate
+  tickers for DNS/port and TLS intervals, persist state via state.Save()
+  after each cycle, clean shutdown on context cancel
+- Domain check: LookupNS, compare to stored state, store silently on
+  first run, notify with old/new NS lists on change
+- Hostname check: QueryAllNameservers, compare per-NS records; notify on
+  record changes, NS failure, NS recovery, inconsistency detected,
+  inconsistency resolved, empty response; store silently on first run
+- Port check: ResolveIPAddresses, check ports 80 and 443 per IP, notify
+  on open/closed transitions, handle new and disappeared IPs
+- TLS check: for each open IP:443, CheckCertificate; notify on expiry
+  warning, certificate change (CN/issuer/SANs), TLS failure/recovery
+
+Port checker (internal/portcheck/portcheck.go):
+
+- Tests against known-open ports and RFC documentation IPs
+- CheckPort: net.DialTimeout (5s), context respected; (true, nil) open,
+  (false, nil) closed/timeout/refused, error only for unexpected
+  failures
+
+TLS checker (internal/tlscheck/tlscheck.go):
+
+- Tests against known public HTTPS servers, verify fields populated
+- CheckCertificate: tls.Dial to specific IP:443 with hostname as SNI;
+  extract subject CN, issuer CN and org, NotAfter, SANs; error on
+  handshake failure
+
+Notification service (internal/notify/notify.go, Slack/Mattermost/ntfy
+backends exist):
+
+- Structured notification types: DNS change, port change, TLS expiry,
+  TLS change, NS failure, NS recovery, NS inconsistency
+- Per-backend formatting: Slack/Mattermost attachment colors (red
+  failures/expiry, yellow warnings, green recoveries, blue info); ntfy
+  priorities (urgent failures, high warnings, default changes, low
+  recoveries); include hostname, nameserver, old/new values, timestamps
+
+HTTP API handlers:
+
+- Wire *state.State and *watcher.Watcher into handler params
+- GET /api/v1/status: full state snapshot as JSON
+- GET /api/v1/domains: domain states with NS records and last-checked
+- GET /api/v1/hostnames: hostname states with per-NS record data
+
+Infrastructure notes (from untracked TODO.md):
+
+- Module path sneak.berlin/go/dnswatcher differs from the git.eeqj.de
+  remote intentionally; do not "fix" it
+- Dependencies: github.com/miekg/dns, golang.org/x/net/publicsuffix
+- Resolver tests originally used live DNS against *.dns.sneak.cloud
+  (required records documented in the test file header); origin now has
+  mocked hermetic tests, keep them hermetic

cmd/dnswatcher/main.go

@@ -27,13 +27,11 @@ import (
 var (
 	Appname = "dnswatcher"
 	Version string
-	Buildarch string
 )
 
 func main() {
 	globals.SetAppname(Appname)
 	globals.SetVersion(Version)
-	globals.SetBuildarch(Buildarch)
 
 	fx.New(
 		fx.Provide(
@@ -51,6 +49,20 @@ func main() {
 			handlers.New,
 			server.New,
 		),
+		fx.Provide(
+			func(r *resolver.Resolver) watcher.DNSResolver {
+				return r
+			},
+			func(p *portcheck.Checker) watcher.PortChecker {
+				return p
+			},
+			func(t *tlscheck.Checker) watcher.TLSChecker {
+				return t
+			},
+			func(n *notify.Service) watcher.Notifier {
+				return n
+			},
+		),
 		fx.Invoke(func(*server.Server, *watcher.Watcher) {}),
 	).Run()
 }

go.mod

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

go.sum

@@ -28,6 +28,8 @@ github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
 github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
+github.com/miekg/dns v1.1.72 h1:vhmr+TF2A3tuoGNkLDFK9zi36F2LS+hKTRW0Uf8kbzI=
+github.com/miekg/dns v1.1.72/go.mod h1:+EuEPhdHOsfk6Wk5TT2CzssZdqkmFhf8r+aVyDEToIs=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
 github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
@@ -74,10 +76,18 @@ go.yaml.in/yaml/v2 v2.4.2 h1:DzmwEr2rDGHl7lsFgAHxmNz/1NlQ7xLIrlN2h5d1eGI=
 go.yaml.in/yaml/v2 v2.4.2/go.mod h1:081UH+NErpNdqlCXm3TtEran0rJZGxAYx9hb/ELlsPU=
 go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
-golang.org/x/sys v0.35.0 h1:vz1N37gP5bs89s7He8XuIYXpyY0+QlsKmzipCbUtyxI=
-golang.org/x/sys v0.35.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
-golang.org/x/text v0.28.0 h1:rhazDwis8INMIwQ4tpjLDzUhx6RlXqZNPEM0huQojng=
-golang.org/x/text v0.28.0/go.mod h1:U8nCwOR8jO/marOQ0QbDiOngZVEBB7MAiitBuMjXiNU=
+golang.org/x/mod v0.32.0 h1:9F4d3PHLljb6x//jOyokMv3eX+YDeepZSEo3mFJy93c=
+golang.org/x/mod v0.32.0/go.mod h1:SgipZ/3h2Ci89DlEtEXWUk/HteuRin+HHhN+WbNhguU=
+golang.org/x/net v0.50.0 h1:ucWh9eiCGyDR3vtzso0WMQinm2Dnt8cFMuQa9K33J60=
+golang.org/x/net v0.50.0/go.mod h1:UgoSli3F/pBgdJBHCTc+tp3gmrU4XswgGRgtnwWTfyM=
+golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
+golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
+golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
+golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
+golang.org/x/tools v0.41.0 h1:a9b8iMweWG+S0OBnlU36rzLp20z1Rp10w+IY2czHTQc=
+golang.org/x/tools v0.41.0/go.mod h1:XSY6eDqxVNiYgezAVqqCeihT4j1U2CCsqvH3WhQpnlg=
 google.golang.org/protobuf v1.36.8 h1:xHScyCOEuuwZEc6UtSOvPbAT4zRh0xcNRYekJwfqyMc=
 google.golang.org/protobuf v1.36.8/go.mod h1:fuxRtAxBytpl4zzqUh6/eyUujkJdNiuEkXntxiD/uRU=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

internal/config/classify.go

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

internal/config/classify_test.go

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

internal/config/config.go

@@ -23,6 +23,11 @@ const (
 	defaultTLSExpiryWarning = 7
 )
 
+// ErrNoTargets is returned when no monitoring targets are configured.
+var ErrNoTargets = errors.New(
+	"no monitoring targets configured: set DNSWATCHER_TARGETS environment variable",
+)
+
 // Params contains dependencies for Config.
 type Params struct {
 	fx.In
@@ -48,6 +53,7 @@ type Config struct {
 	MaintenanceMode      bool
 	MetricsUsername      string
 	MetricsPassword      string
+	SendTestNotification bool
 	params               *Params
 	log                  *slog.Logger
 }
@@ -88,9 +94,8 @@ func setupViper(name string) {
 
 	viper.SetDefault("PORT", defaultPort)
 	viper.SetDefault("DEBUG", false)
-	viper.SetDefault("DATA_DIR", "./data")
-	viper.SetDefault("DOMAINS", "")
-	viper.SetDefault("HOSTNAMES", "")
+	viper.SetDefault("DATA_DIR", "/var/lib/"+name)
+	viper.SetDefault("TARGETS", "")
 	viper.SetDefault("SLACK_WEBHOOK", "")
 	viper.SetDefault("MATTERMOST_WEBHOOK", "")
 	viper.SetDefault("NTFY_TOPIC", "")
@@ -101,6 +106,7 @@ func setupViper(name string) {
 	viper.SetDefault("MAINTENANCE_MODE", false)
 	viper.SetDefault("METRICS_USERNAME", "")
 	viper.SetDefault("METRICS_PASSWORD", "")
+	viper.SetDefault("SEND_TEST_NOTIFICATION", false)
 }
 
 func buildConfig(
@@ -133,12 +139,17 @@ func buildConfig(
 		tlsInterval = defaultTLSInterval
 	}
 
+	domains, hostnames, err := parseAndValidateTargets()
+	if err != nil {
+		return nil, err
+	}
+
 	cfg := &Config{
 		Port:                 viper.GetInt("PORT"),
 		Debug:                viper.GetBool("DEBUG"),
 		DataDir:              viper.GetString("DATA_DIR"),
-		Domains:           parseCSV(viper.GetString("DOMAINS")),
-		Hostnames:         parseCSV(viper.GetString("HOSTNAMES")),
+		Domains:              domains,
+		Hostnames:            hostnames,
 		SlackWebhook:         viper.GetString("SLACK_WEBHOOK"),
 		MattermostWebhook:    viper.GetString("MATTERMOST_WEBHOOK"),
 		NtfyTopic:            viper.GetString("NTFY_TOPIC"),
@@ -149,6 +160,7 @@ func buildConfig(
 		MaintenanceMode:      viper.GetBool("MAINTENANCE_MODE"),
 		MetricsUsername:      viper.GetString("METRICS_USERNAME"),
 		MetricsPassword:      viper.GetString("METRICS_PASSWORD"),
+		SendTestNotification: viper.GetBool("SEND_TEST_NOTIFICATION"),
 		params:               params,
 		log:                  log,
 	}
@@ -156,6 +168,23 @@ func buildConfig(
 	return cfg, nil
 }
 
+func parseAndValidateTargets() ([]string, []string, error) {
+	domains, hostnames, err := ClassifyTargets(
+		parseCSV(viper.GetString("TARGETS")),
+	)
+	if err != nil {
+		return nil, nil, fmt.Errorf(
+			"invalid targets configuration: %w", err,
+		)
+	}
+
+	if len(domains) == 0 && len(hostnames) == 0 {
+		return nil, nil, ErrNoTargets
+	}
+
+	return domains, hostnames, nil
+}
+
 func parseCSV(input string) []string {
 	if input == "" {
 		return nil

internal/config/config_test.go

@@ -0,0 +1,262 @@
+package config_test
+
+import (
+	"testing"
+	"time"
+
+	"github.com/spf13/viper"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"sneak.berlin/go/dnswatcher/internal/config"
+	"sneak.berlin/go/dnswatcher/internal/globals"
+	"sneak.berlin/go/dnswatcher/internal/logger"
+)
+
+// newTestParams creates config.Params suitable for testing
+// without requiring the fx dependency injection framework.
+func newTestParams(t *testing.T) config.Params {
+	t.Helper()
+
+	g := &globals.Globals{
+		Appname: "dnswatcher",
+		Version: "test",
+	}
+
+	l, err := logger.New(nil, logger.Params{Globals: g})
+	require.NoError(t, err, "failed to create logger")
+
+	return config.Params{
+		Globals: g,
+		Logger:  l,
+	}
+}
+
+// These tests exercise viper global state and MUST NOT use
+// t.Parallel(). Each test resets viper for isolation.
+
+func TestNew_DefaultValues(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "example.com,www.example.com")
+
+	cfg, err := config.New(nil, newTestParams(t))
+	require.NoError(t, err)
+
+	assert.Equal(t, 8080, cfg.Port)
+	assert.False(t, cfg.Debug)
+	assert.Equal(t, "/var/lib/dnswatcher", cfg.DataDir)
+	assert.Equal(t, time.Hour, cfg.DNSInterval)
+	assert.Equal(t, 12*time.Hour, cfg.TLSInterval)
+	assert.Equal(t, 7, cfg.TLSExpiryWarning)
+	assert.False(t, cfg.MaintenanceMode)
+	assert.Empty(t, cfg.SlackWebhook)
+	assert.Empty(t, cfg.MattermostWebhook)
+	assert.Empty(t, cfg.NtfyTopic)
+	assert.Empty(t, cfg.SentryDSN)
+	assert.Empty(t, cfg.MetricsUsername)
+	assert.Empty(t, cfg.MetricsPassword)
+	assert.False(t, cfg.SendTestNotification)
+}
+
+func TestNew_EnvironmentOverrides(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "example.com")
+	t.Setenv("PORT", "9090")
+	t.Setenv("DNSWATCHER_DEBUG", "true")
+	t.Setenv("DNSWATCHER_DATA_DIR", "/tmp/test-data")
+	t.Setenv("DNSWATCHER_DNS_INTERVAL", "30m")
+	t.Setenv("DNSWATCHER_TLS_INTERVAL", "6h")
+	t.Setenv("DNSWATCHER_TLS_EXPIRY_WARNING", "14")
+	t.Setenv("DNSWATCHER_SLACK_WEBHOOK", "https://hooks.slack.com/t")
+	t.Setenv("DNSWATCHER_MATTERMOST_WEBHOOK", "https://mm.test/hooks/t")
+	t.Setenv("DNSWATCHER_NTFY_TOPIC", "https://ntfy.sh/test")
+	t.Setenv("DNSWATCHER_SENTRY_DSN", "https://sentry.test/1")
+	t.Setenv("DNSWATCHER_MAINTENANCE_MODE", "true")
+	t.Setenv("DNSWATCHER_METRICS_USERNAME", "admin")
+	t.Setenv("DNSWATCHER_METRICS_PASSWORD", "secret")
+	t.Setenv("DNSWATCHER_SEND_TEST_NOTIFICATION", "true")
+
+	cfg, err := config.New(nil, newTestParams(t))
+	require.NoError(t, err)
+
+	assert.Equal(t, 9090, cfg.Port)
+	assert.True(t, cfg.Debug)
+	assert.Equal(t, "/tmp/test-data", cfg.DataDir)
+	assert.Equal(t, 30*time.Minute, cfg.DNSInterval)
+	assert.Equal(t, 6*time.Hour, cfg.TLSInterval)
+	assert.Equal(t, 14, cfg.TLSExpiryWarning)
+	assert.Equal(t, "https://hooks.slack.com/t", cfg.SlackWebhook)
+	assert.Equal(t, "https://mm.test/hooks/t", cfg.MattermostWebhook)
+	assert.Equal(t, "https://ntfy.sh/test", cfg.NtfyTopic)
+	assert.Equal(t, "https://sentry.test/1", cfg.SentryDSN)
+	assert.True(t, cfg.MaintenanceMode)
+	assert.Equal(t, "admin", cfg.MetricsUsername)
+	assert.Equal(t, "secret", cfg.MetricsPassword)
+	assert.True(t, cfg.SendTestNotification)
+}
+
+func TestNew_NoTargetsError(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "")
+
+	_, err := config.New(nil, newTestParams(t))
+	require.Error(t, err)
+	assert.ErrorIs(t, err, config.ErrNoTargets)
+}
+
+func TestNew_OnlyEmptyCSVSegments(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", " , , ")
+
+	_, err := config.New(nil, newTestParams(t))
+	require.Error(t, err)
+	assert.ErrorIs(t, err, config.ErrNoTargets)
+}
+
+func TestNew_InvalidDNSInterval_FallsBackToDefault(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "example.com")
+	t.Setenv("DNSWATCHER_DNS_INTERVAL", "banana")
+
+	cfg, err := config.New(nil, newTestParams(t))
+	require.NoError(t, err)
+	assert.Equal(t, time.Hour, cfg.DNSInterval,
+		"invalid DNS interval should fall back to 1h default")
+}
+
+func TestNew_InvalidTLSInterval_FallsBackToDefault(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "example.com")
+	t.Setenv("DNSWATCHER_TLS_INTERVAL", "notaduration")
+
+	cfg, err := config.New(nil, newTestParams(t))
+	require.NoError(t, err)
+	assert.Equal(t, 12*time.Hour, cfg.TLSInterval,
+		"invalid TLS interval should fall back to 12h default")
+}
+
+func TestNew_BothIntervalsInvalid(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "example.com")
+	t.Setenv("DNSWATCHER_DNS_INTERVAL", "xyz")
+	t.Setenv("DNSWATCHER_TLS_INTERVAL", "abc")
+
+	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)
+}
+
+func TestNew_DebugEnablesDebugLogging(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "example.com")
+	t.Setenv("DNSWATCHER_DEBUG", "true")
+
+	cfg, err := config.New(nil, newTestParams(t))
+	require.NoError(t, err)
+	assert.True(t, cfg.Debug)
+}
+
+func TestNew_PortEnvNotPrefixed(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "example.com")
+	t.Setenv("PORT", "3000")
+
+	cfg, err := config.New(nil, newTestParams(t))
+	require.NoError(t, err)
+	assert.Equal(t, 3000, cfg.Port,
+		"PORT env should work without DNSWATCHER_ prefix")
+}
+
+func TestNew_TargetClassification(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS",
+		"example.com,www.example.com,api.example.com,example.org")
+
+	cfg, err := config.New(nil, newTestParams(t))
+	require.NoError(t, err)
+
+	// example.com and example.org are apex domains
+	assert.Len(t, cfg.Domains, 2)
+	// www.example.com and api.example.com are hostnames
+	assert.Len(t, cfg.Hostnames, 2)
+}
+
+func TestNew_InvalidTargetPublicSuffix(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "co.uk")
+
+	_, err := config.New(nil, newTestParams(t))
+	require.Error(t, err, "public suffix should be rejected")
+}
+
+func TestNew_EmptyAppnameDefaultsToDnswatcher(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "example.com")
+
+	g := &globals.Globals{Appname: "", Version: "test"}
+
+	l, err := logger.New(nil, logger.Params{Globals: g})
+	require.NoError(t, err)
+
+	cfg, err := config.New(
+		nil, config.Params{Globals: g, Logger: l},
+	)
+	require.NoError(t, err)
+	assert.Equal(t, 8080, cfg.Port,
+		"defaults should load when appname is empty")
+}
+
+func TestNew_TargetsWithWhitespace(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", " example.com , www.example.com ")
+
+	cfg, err := config.New(nil, newTestParams(t))
+	require.NoError(t, err)
+	assert.Equal(t, 2, len(cfg.Domains)+len(cfg.Hostnames),
+		"whitespace around targets should be trimmed")
+}
+
+func TestNew_TargetsWithTrailingComma(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "example.com,www.example.com,")
+
+	cfg, err := config.New(nil, newTestParams(t))
+	require.NoError(t, err)
+	assert.Equal(t, 2, len(cfg.Domains)+len(cfg.Hostnames),
+		"trailing comma should be ignored")
+}
+
+func TestNew_CustomDNSIntervalDuration(t *testing.T) {
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "example.com")
+	t.Setenv("DNSWATCHER_DNS_INTERVAL", "5s")
+
+	cfg, err := config.New(nil, newTestParams(t))
+	require.NoError(t, err)
+	assert.Equal(t, 5*time.Second, cfg.DNSInterval)
+}
+
+func TestStatePath(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		dataDir string
+		want    string
+	}{
+		{"default", "/var/lib/dnswatcher", "/var/lib/dnswatcher/state.json"},
+		{"absolute", "/var/lib/dw", "/var/lib/dw/state.json"},
+		{"nested", "/opt/app/data", "/opt/app/data/state.json"},
+		{"empty", "", "/state.json"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			cfg := &config.Config{DataDir: tt.dataDir}
+			assert.Equal(t, tt.want, cfg.StatePath())
+		})
+	}
+}

internal/config/export_test.go

@@ -0,0 +1,6 @@
+package config
+
+// ParseCSVForTest exports parseCSV for use in external tests.
+func ParseCSVForTest(input string) []string {
+	return parseCSV(input)
+}

internal/config/parsecsv_test.go

@@ -0,0 +1,44 @@
+package config_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"sneak.berlin/go/dnswatcher/internal/config"
+)
+
+func TestParseCSV(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name  string
+		input string
+		want  []string
+	}{
+		{"empty string", "", nil},
+		{"single value", "a", []string{"a"}},
+		{"multiple values", "a,b,c", []string{"a", "b", "c"}},
+		{"whitespace trimmed", " a , b ", []string{"a", "b"}},
+		{"trailing comma", "a,b,", []string{"a", "b"}},
+		{"leading comma", ",a,b", []string{"a", "b"}},
+		{"consecutive commas", "a,,b", []string{"a", "b"}},
+		{"all empty segments", ",,,", nil},
+		{"whitespace only", " , , ", nil},
+		{"tabs", "\ta\t,\tb\t", []string{"a", "b"}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got := config.ParseCSVForTest(tt.input)
+			require.Len(t, got, len(tt.want))
+
+			for i, w := range tt.want {
+				assert.Equal(t, w, got[i])
+			}
+		})
+	}
+}

internal/globals/globals.go

@@ -15,14 +15,12 @@ var (
 	mu      sync.RWMutex
 	appname string
 	version string
-	buildarch string
 )
 
 // Globals holds build-time variables for dependency injection.
 type Globals struct {
 	Appname string
 	Version string
-	Buildarch string
 }
 
 // New creates a new Globals instance from package-level variables.
@@ -33,7 +31,6 @@ func New(_ fx.Lifecycle) (*Globals, error) {
 	return &Globals{
 		Appname: appname,
 		Version: version,
-		Buildarch: buildarch,
 	}, nil
 }
 
@@ -52,11 +49,3 @@ func SetVersion(ver string) {
 
 	version = ver
 }
-
-// SetBuildarch sets the build architecture.
-func SetBuildarch(arch string) {
-	mu.Lock()
-	defer mu.Unlock()
-
-	buildarch = arch
-}

internal/handlers/dashboard.go

@@ -0,0 +1,151 @@
+package handlers
+
+import (
+	"embed"
+	"fmt"
+	"html/template"
+	"math"
+	"net/http"
+	"strings"
+	"time"
+
+	"sneak.berlin/go/dnswatcher/internal/notify"
+	"sneak.berlin/go/dnswatcher/internal/state"
+)
+
+//go:embed templates/dashboard.html
+var dashboardFS embed.FS
+
+// Time unit constants for relative time calculations.
+const (
+	secondsPerMinute = 60
+	minutesPerHour   = 60
+	hoursPerDay      = 24
+)
+
+// newDashboardTemplate parses the embedded dashboard HTML
+// template with helper functions.
+func newDashboardTemplate() *template.Template {
+	funcs := template.FuncMap{
+		"relTime":       relTime,
+		"joinStrings":   joinStrings,
+		"formatRecords": formatRecords,
+		"expiryDays":    expiryDays,
+	}
+
+	return template.Must(
+		template.New("dashboard.html").
+			Funcs(funcs).
+			ParseFS(dashboardFS, "templates/dashboard.html"),
+	)
+}
+
+// dashboardData is the data passed to the dashboard template.
+type dashboardData struct {
+	Snapshot    state.Snapshot
+	Alerts      []notify.AlertEntry
+	StateAge    string
+	GeneratedAt string
+}
+
+// HandleDashboard returns the dashboard page handler.
+func (h *Handlers) HandleDashboard() http.HandlerFunc {
+	tmpl := newDashboardTemplate()
+
+	return func(
+		writer http.ResponseWriter,
+		_ *http.Request,
+	) {
+		snap := h.state.GetSnapshot()
+		alerts := h.notifyHistory.Recent()
+
+		data := dashboardData{
+			Snapshot:    snap,
+			Alerts:      alerts,
+			StateAge:    relTime(snap.LastUpdated),
+			GeneratedAt: time.Now().UTC().Format("2006-01-02 15:04:05"),
+		}
+
+		writer.Header().Set(
+			"Content-Type", "text/html; charset=utf-8",
+		)
+
+		err := tmpl.Execute(writer, data)
+		if err != nil {
+			h.log.Error(
+				"dashboard template error",
+				"error", err,
+			)
+		}
+	}
+}
+
+// relTime returns a human-readable relative time string such
+// as "2 minutes ago" or "never" for zero times.
+func relTime(t time.Time) string {
+	if t.IsZero() {
+		return "never"
+	}
+
+	d := time.Since(t)
+	if d < 0 {
+		return "just now"
+	}
+
+	seconds := int(math.Round(d.Seconds()))
+	if seconds < secondsPerMinute {
+		return fmt.Sprintf("%ds ago", seconds)
+	}
+
+	minutes := seconds / secondsPerMinute
+	if minutes < minutesPerHour {
+		return fmt.Sprintf("%dm ago", minutes)
+	}
+
+	hours := minutes / minutesPerHour
+	if hours < hoursPerDay {
+		return fmt.Sprintf(
+			"%dh %dm ago", hours, minutes%minutesPerHour,
+		)
+	}
+
+	days := hours / hoursPerDay
+
+	return fmt.Sprintf(
+		"%dd %dh ago", days, hours%hoursPerDay,
+	)
+}
+
+// joinStrings joins a string slice with a separator.
+func joinStrings(items []string, sep string) string {
+	return strings.Join(items, sep)
+}
+
+// formatRecords formats a map of record type → values into a
+// compact display string.
+func formatRecords(records map[string][]string) string {
+	if len(records) == 0 {
+		return "-"
+	}
+
+	var parts []string
+
+	for rtype, values := range records {
+		for _, v := range values {
+			parts = append(parts, rtype+": "+v)
+		}
+	}
+
+	return strings.Join(parts, ", ")
+}
+
+// expiryDays returns the number of days until the given time,
+// rounded down. Returns 0 if already expired.
+func expiryDays(t time.Time) int {
+	d := time.Until(t).Hours() / hoursPerDay
+	if d < 0 {
+		return 0
+	}
+
+	return int(d)
+}

internal/handlers/dashboard_test.go

@@ -0,0 +1,80 @@
+package handlers_test
+
+import (
+	"testing"
+	"time"
+
+	"sneak.berlin/go/dnswatcher/internal/handlers"
+)
+
+func TestRelTime(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		dur  time.Duration
+		want string
+	}{
+		{"zero", 0, "never"},
+		{"seconds", 30 * time.Second, "30s ago"},
+		{"minutes", 5 * time.Minute, "5m ago"},
+		{"hours", 2*time.Hour + 15*time.Minute, "2h 15m ago"},
+		{"days", 48*time.Hour + 3*time.Hour, "2d 3h ago"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			var input time.Time
+			if tt.dur > 0 {
+				input = time.Now().Add(-tt.dur)
+			}
+
+			got := handlers.RelTime(input)
+			if got != tt.want {
+				t.Errorf(
+					"RelTime(%v) = %q, want %q",
+					tt.dur, got, tt.want,
+				)
+			}
+		})
+	}
+}
+
+func TestExpiryDays(t *testing.T) {
+	t.Parallel()
+
+	// 10 days from now.
+	future := time.Now().Add(10 * 24 * time.Hour)
+
+	days := handlers.ExpiryDays(future)
+	if days < 9 || days > 10 {
+		t.Errorf("expected ~10 days, got %d", days)
+	}
+
+	// Already expired.
+	past := time.Now().Add(-24 * time.Hour)
+
+	days = handlers.ExpiryDays(past)
+	if days != 0 {
+		t.Errorf("expected 0 for expired, got %d", days)
+	}
+}
+
+func TestFormatRecords(t *testing.T) {
+	t.Parallel()
+
+	got := handlers.FormatRecords(nil)
+	if got != "-" {
+		t.Errorf("expected -, got %q", got)
+	}
+
+	got = handlers.FormatRecords(map[string][]string{
+		"A": {"1.2.3.4"},
+	})
+
+	if got != "A: 1.2.3.4" {
+		t.Errorf("unexpected format: %q", got)
+	}
+}

internal/handlers/export_test.go

@@ -0,0 +1,18 @@
+package handlers
+
+import "time"
+
+// RelTime exports relTime for testing.
+func RelTime(t time.Time) string {
+	return relTime(t)
+}
+
+// ExpiryDays exports expiryDays for testing.
+func ExpiryDays(t time.Time) int {
+	return expiryDays(t)
+}
+
+// FormatRecords exports formatRecords for testing.
+func FormatRecords(records map[string][]string) string {
+	return formatRecords(records)
+}

internal/handlers/handlers.go

@@ -11,6 +11,8 @@ import (
 	"sneak.berlin/go/dnswatcher/internal/globals"
 	"sneak.berlin/go/dnswatcher/internal/healthcheck"
 	"sneak.berlin/go/dnswatcher/internal/logger"
+	"sneak.berlin/go/dnswatcher/internal/notify"
+	"sneak.berlin/go/dnswatcher/internal/state"
 )
 
 // Params contains dependencies for Handlers.
@@ -20,6 +22,8 @@ type Params struct {
 	Logger      *logger.Logger
 	Globals     *globals.Globals
 	Healthcheck *healthcheck.Healthcheck
+	State       *state.State
+	Notify      *notify.Service
 }
 
 // Handlers provides HTTP request handlers.
@@ -28,6 +32,8 @@ type Handlers struct {
 	params        *Params
 	globals       *globals.Globals
 	hc            *healthcheck.Healthcheck
+	state         *state.State
+	notifyHistory *notify.AlertHistory
 }
 
 // New creates a new Handlers instance.
@@ -37,6 +43,8 @@ func New(_ fx.Lifecycle, params Params) (*Handlers, error) {
 		params:        &params,
 		globals:       params.Globals,
 		hc:            params.Healthcheck,
+		state:         params.State,
+		notifyHistory: params.Notify.History(),
 	}, nil
 }
 

internal/handlers/status.go

@@ -2,22 +2,217 @@ package handlers
 
 import (
 	"net/http"
+	"sort"
+	"time"
+
+	"sneak.berlin/go/dnswatcher/internal/state"
 )
 
+// statusDomainInfo holds status information for a monitored domain.
+type statusDomainInfo struct {
+	Nameservers []string  `json:"nameservers"`
+	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"`
+	LastChecked time.Time           `json:"lastChecked"`
+}
+
+// statusHostnameInfo holds status information for a monitored hostname.
+type statusHostnameInfo struct {
+	Nameservers map[string]*statusHostnameNSInfo `json:"nameservers"`
+	LastChecked time.Time                        `json:"lastChecked"`
+}
+
+// statusPortInfo holds status information for a monitored port.
+type statusPortInfo struct {
+	Open        bool      `json:"open"`
+	Hostnames   []string  `json:"hostnames"`
+	LastChecked time.Time `json:"lastChecked"`
+}
+
+// statusCertificateInfo holds status information for a TLS certificate.
+type statusCertificateInfo struct {
+	CommonName              string    `json:"commonName"`
+	Issuer                  string    `json:"issuer"`
+	NotAfter                time.Time `json:"notAfter"`
+	SubjectAlternativeNames []string  `json:"subjectAlternativeNames"`
+	Status                  string    `json:"status"`
+	LastChecked             time.Time `json:"lastChecked"`
+}
+
+// statusCounts holds summary counts of monitored resources.
+type statusCounts struct {
+	Domains      int `json:"domains"`
+	Hostnames    int `json:"hostnames"`
+	Ports        int `json:"ports"`
+	PortsOpen    int `json:"portsOpen"`
+	Certificates int `json:"certificates"`
+	CertsOK      int `json:"certificatesOk"`
+	CertsError   int `json:"certificatesError"`
+}
+
+// statusResponse is the full /api/v1/status response.
+type statusResponse struct {
+	Status       string                            `json:"status"`
+	LastUpdated  time.Time                         `json:"lastUpdated"`
+	Counts       statusCounts                      `json:"counts"`
+	Domains      map[string]*statusDomainInfo      `json:"domains"`
+	Hostnames    map[string]*statusHostnameInfo    `json:"hostnames"`
+	Ports        map[string]*statusPortInfo        `json:"ports"`
+	Certificates map[string]*statusCertificateInfo `json:"certificates"`
+}
+
 // HandleStatus returns the monitoring status handler.
 func (h *Handlers) HandleStatus() http.HandlerFunc {
-	type response struct {
-		Status string `json:"status"`
-	}
-
 	return func(
 		writer http.ResponseWriter,
 		request *http.Request,
 	) {
+		snap := h.state.GetSnapshot()
+
+		resp := buildStatusResponse(snap)
+
 		h.respondJSON(
 			writer, request,
-			&response{Status: "ok"},
+			resp,
 			http.StatusOK,
 		)
 	}
 }
+
+// buildStatusResponse constructs the full status response from
+// the current monitoring snapshot.
+func buildStatusResponse(
+	snap state.Snapshot,
+) *statusResponse {
+	resp := &statusResponse{
+		Status:       "ok",
+		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)
+	buildHostnames(snap, resp)
+	buildPorts(snap, resp)
+	buildCertificates(snap, resp)
+	buildCounts(resp)
+
+	return resp
+}
+
+func buildDomains(
+	snap state.Snapshot,
+	resp *statusResponse,
+) {
+	for name, ds := range snap.Domains {
+		ns := make([]string, len(ds.Nameservers))
+		copy(ns, ds.Nameservers)
+		sort.Strings(ns)
+
+		resp.Domains[name] = &statusDomainInfo{
+			Nameservers: ns,
+			LastChecked: ds.LastChecked,
+		}
+	}
+}
+
+func buildHostnames(
+	snap state.Snapshot,
+	resp *statusResponse,
+) {
+	for name, hs := range snap.Hostnames {
+		info := &statusHostnameInfo{
+			Nameservers: make(map[string]*statusHostnameNSInfo),
+			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(
+	snap state.Snapshot,
+	resp *statusResponse,
+) {
+	for key, ps := range snap.Ports {
+		hostnames := make([]string, len(ps.Hostnames))
+		copy(hostnames, ps.Hostnames)
+		sort.Strings(hostnames)
+
+		resp.Ports[key] = &statusPortInfo{
+			Open:        ps.Open,
+			Hostnames:   hostnames,
+			LastChecked: ps.LastChecked,
+		}
+	}
+}
+
+func buildCertificates(
+	snap state.Snapshot,
+	resp *statusResponse,
+) {
+	for key, cs := range snap.Certificates {
+		sans := make([]string, len(cs.SubjectAlternativeNames))
+		copy(sans, cs.SubjectAlternativeNames)
+
+		resp.Certificates[key] = &statusCertificateInfo{
+			CommonName:              cs.CommonName,
+			Issuer:                  cs.Issuer,
+			NotAfter:                cs.NotAfter,
+			SubjectAlternativeNames: sans,
+			Status:                  cs.Status,
+			LastChecked:             cs.LastChecked,
+		}
+	}
+}
+
+func buildCounts(resp *statusResponse) {
+	var portsOpen, certsOK, certsError int
+
+	for _, ps := range resp.Ports {
+		if ps.Open {
+			portsOpen++
+		}
+	}
+
+	for _, cs := range resp.Certificates {
+		switch cs.Status {
+		case "ok":
+			certsOK++
+		case "error":
+			certsError++
+		}
+	}
+
+	resp.Counts = statusCounts{
+		Domains:      len(resp.Domains),
+		Hostnames:    len(resp.Hostnames),
+		Ports:        len(resp.Ports),
+		PortsOpen:    portsOpen,
+		Certificates: len(resp.Certificates),
+		CertsOK:      certsOK,
+		CertsError:   certsError,
+	}
+}

internal/handlers/templates/dashboard.html

@@ -0,0 +1,370 @@
+<!doctype html>
+<html lang="en" class="bg-slate-950">
+  <head>
+    <meta charset="utf-8" />
+    <meta http-equiv="refresh" content="30" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>dnswatcher</title>
+    <link rel="stylesheet" href="/s/css/tailwind.min.css" />
+  </head>
+  <body
+    class="bg-surface-950 text-slate-300 font-mono text-sm min-h-screen antialiased"
+  >
+    <div class="max-w-6xl mx-auto px-4 py-8">
+      {{/* ---- Header ---- */}}
+      <div class="mb-8">
+        <h1 class="text-2xl font-bold text-teal-400 tracking-tight">
+          dnswatcher
+        </h1>
+        <p class="text-xs text-slate-500 mt-1">
+          state updated {{ .StateAge }} &middot; page generated
+          {{ .GeneratedAt }} UTC &middot; auto-refresh 30s
+        </p>
+      </div>
+
+      {{/* ---- Summary bar ---- */}}
+      <div
+        class="grid grid-cols-2 sm:grid-cols-4 gap-3 mb-8"
+      >
+        <div class="bg-surface-800 border border-slate-700/50 rounded-lg p-4">
+          <div class="text-xs text-slate-500 uppercase tracking-wider">
+            Domains
+          </div>
+          <div class="text-2xl font-bold text-teal-400 mt-1">
+            {{ len .Snapshot.Domains }}
+          </div>
+        </div>
+        <div class="bg-surface-800 border border-slate-700/50 rounded-lg p-4">
+          <div class="text-xs text-slate-500 uppercase tracking-wider">
+            Hostnames
+          </div>
+          <div class="text-2xl font-bold text-teal-400 mt-1">
+            {{ len .Snapshot.Hostnames }}
+          </div>
+        </div>
+        <div class="bg-surface-800 border border-slate-700/50 rounded-lg p-4">
+          <div class="text-xs text-slate-500 uppercase tracking-wider">
+            Ports
+          </div>
+          <div class="text-2xl font-bold text-teal-400 mt-1">
+            {{ len .Snapshot.Ports }}
+          </div>
+        </div>
+        <div class="bg-surface-800 border border-slate-700/50 rounded-lg p-4">
+          <div class="text-xs text-slate-500 uppercase tracking-wider">
+            Certificates
+          </div>
+          <div class="text-2xl font-bold text-teal-400 mt-1">
+            {{ len .Snapshot.Certificates }}
+          </div>
+        </div>
+      </div>
+
+      {{/* ---- Domains ---- */}}
+      <section class="mb-8">
+        <h2
+          class="text-sm font-semibold text-teal-300 uppercase tracking-wider mb-3 border-b border-slate-700/50 pb-2"
+        >
+          Domains
+        </h2>
+        {{ if .Snapshot.Domains }}
+        <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">Domain</th>
+                <th class="py-2 px-3">Nameservers</th>
+                <th class="py-2 px-3">Checked</th>
+              </tr>
+            </thead>
+            <tbody class="divide-y divide-slate-800">
+              {{ range $name, $ds := .Snapshot.Domains }}
+              <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">
+                  {{ joinStrings $ds.Nameservers ", " }}
+                </td>
+                <td class="py-2 px-3 text-slate-500 whitespace-nowrap">
+                  {{ relTime $ds.LastChecked }}
+                </td>
+              </tr>
+              {{ end }}
+            </tbody>
+          </table>
+        </div>
+        {{ else }}
+        <p class="text-slate-600 italic text-xs">
+          No domains configured.
+        </p>
+        {{ end }}
+      </section>
+
+      {{/* ---- Hostnames ---- */}}
+      <section class="mb-8">
+        <h2
+          class="text-sm font-semibold text-teal-300 uppercase tracking-wider mb-3 border-b border-slate-700/50 pb-2"
+        >
+          Hostnames
+        </h2>
+        {{ if .Snapshot.Hostnames }}
+        <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">Hostname</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">
+              {{ range $name, $hs := .Snapshot.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>
+        {{ else }}
+        <p class="text-slate-600 italic text-xs">
+          No hostnames configured.
+        </p>
+        {{ end }}
+      </section>
+
+      {{/* ---- Ports ---- */}}
+      <section class="mb-8">
+        <h2
+          class="text-sm font-semibold text-teal-300 uppercase tracking-wider mb-3 border-b border-slate-700/50 pb-2"
+        >
+          Ports
+        </h2>
+        {{ if .Snapshot.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">Hostnames</th>
+                <th class="py-2 px-3">Checked</th>
+              </tr>
+            </thead>
+            <tbody class="divide-y divide-slate-800">
+              {{ range $key, $ps := .Snapshot.Ports }}
+              <tr class="hover:bg-surface-800/50">
+                <td class="py-2 px-3 text-slate-200 font-medium">
+                  {{ $key }}
+                </td>
+                <td class="py-2 px-3">
+                  {{ if $ps.Open }}
+                  <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"
+                    >open</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"
+                    >closed</span
+                  >
+                  {{ end }}
+                </td>
+                <td class="py-2 px-3 text-slate-400 break-all">
+                  {{ joinStrings $ps.Hostnames ", " }}
+                </td>
+                <td class="py-2 px-3 text-slate-500 whitespace-nowrap">
+                  {{ relTime $ps.LastChecked }}
+                </td>
+              </tr>
+              {{ end }}
+            </tbody>
+          </table>
+        </div>
+        {{ else }}
+        <p class="text-slate-600 italic text-xs">
+          No port data yet.
+        </p>
+        {{ end }}
+      </section>
+
+      {{/* ---- Certificates ---- */}}
+      <section class="mb-8">
+        <h2
+          class="text-sm font-semibold text-teal-300 uppercase tracking-wider mb-3 border-b border-slate-700/50 pb-2"
+        >
+          Certificates
+        </h2>
+        {{ if .Snapshot.Certificates }}
+        <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">Endpoint</th>
+                <th class="py-2 px-3">Status</th>
+                <th class="py-2 px-3">CN</th>
+                <th class="py-2 px-3">Issuer</th>
+                <th class="py-2 px-3">Expires</th>
+                <th class="py-2 px-3">Checked</th>
+              </tr>
+            </thead>
+            <tbody class="divide-y divide-slate-800">
+              {{ range $key, $cs := .Snapshot.Certificates }}
+              <tr class="hover:bg-surface-800/50">
+                <td class="py-2 px-3 text-slate-400 break-all">
+                  {{ $key }}
+                </td>
+                <td class="py-2 px-3">
+                  {{ if eq $cs.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"
+                    >{{ $cs.Status }}</span
+                  >
+                  {{ end }}
+                </td>
+                <td class="py-2 px-3 text-slate-200">
+                  {{ $cs.CommonName }}
+                </td>
+                <td class="py-2 px-3 text-slate-400 break-all">
+                  {{ $cs.Issuer }}
+                </td>
+                <td class="py-2 px-3 whitespace-nowrap">
+                  {{ if not $cs.NotAfter.IsZero }}
+                    {{ $days := expiryDays $cs.NotAfter }}
+                    {{ if lt $days 7 }}
+                    <span class="text-red-400 font-medium"
+                      >{{ $cs.NotAfter.Format "2006-01-02" }}
+                      ({{ $days }}d)</span
+                    >
+                    {{ else if lt $days 30 }}
+                    <span class="text-amber-400"
+                      >{{ $cs.NotAfter.Format "2006-01-02" }}
+                      ({{ $days }}d)</span
+                    >
+                    {{ else }}
+                    <span class="text-slate-400"
+                      >{{ $cs.NotAfter.Format "2006-01-02" }}
+                      ({{ $days }}d)</span
+                    >
+                    {{ end }}
+                  {{ end }}
+                </td>
+                <td class="py-2 px-3 text-slate-500 whitespace-nowrap">
+                  {{ relTime $cs.LastChecked }}
+                </td>
+              </tr>
+              {{ end }}
+            </tbody>
+          </table>
+        </div>
+        {{ else }}
+        <p class="text-slate-600 italic text-xs">
+          No certificate data yet.
+        </p>
+        {{ end }}
+      </section>
+
+      {{/* ---- Recent Alerts ---- */}}
+      <section class="mb-8">
+        <h2
+          class="text-sm font-semibold text-teal-300 uppercase tracking-wider mb-3 border-b border-slate-700/50 pb-2"
+        >
+          Recent Alerts ({{ len .Alerts }})
+        </h2>
+        {{ if .Alerts }}
+        <div class="space-y-2">
+          {{ range .Alerts }}
+          <div
+            class="bg-surface-800 border rounded-lg px-4 py-3 {{ if eq .Priority "error" }}border-red-700/40{{ else if eq .Priority "warning" }}border-amber-700/40{{ else if eq .Priority "success" }}border-teal-700/40{{ else }}border-blue-700/40{{ end }}"
+          >
+            <div class="flex items-center gap-3 mb-1">
+              {{ if eq .Priority "error" }}
+              <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"
+                >error</span
+              >
+              {{ else if eq .Priority "warning" }}
+              <span
+                class="inline-block px-1.5 py-0.5 rounded text-[10px] font-bold uppercase bg-amber-900/50 text-amber-400 border border-amber-700/30"
+                >warning</span
+              >
+              {{ else if eq .Priority "success" }}
+              <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"
+                >success</span
+              >
+              {{ else }}
+              <span
+                class="inline-block px-1.5 py-0.5 rounded text-[10px] font-bold uppercase bg-blue-900/50 text-blue-400 border border-blue-700/30"
+                >info</span
+              >
+              {{ end }}
+              <span class="text-slate-200 text-xs font-medium">
+                {{ .Title }}
+              </span>
+              <span class="text-slate-600 text-[11px] ml-auto whitespace-nowrap">
+                {{ .Timestamp.Format "2006-01-02 15:04:05" }} UTC
+                ({{ relTime .Timestamp }})
+              </span>
+            </div>
+            <p
+              class="text-slate-400 text-xs whitespace-pre-line pl-0.5"
+            >
+              {{ .Message }}
+            </p>
+          </div>
+          {{ end }}
+        </div>
+        {{ else }}
+        <p class="text-slate-600 italic text-xs">
+          No alerts recorded since last restart.
+        </p>
+        {{ end }}
+      </section>
+
+      {{/* ---- Footer ---- */}}
+      <div
+        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
+      </div>
+    </div>
+  </body>
+</html>

internal/logger/logger.go

@@ -78,6 +78,5 @@ func (l *Logger) Identify() {
 	l.log.Info("starting",
 		"appname", l.params.Globals.Appname,
 		"version", l.params.Globals.Version,
-		"buildarch", l.params.Globals.Buildarch,
 	)
 }

internal/notify/export_test.go

@@ -0,0 +1,121 @@
+package notify
+
+import (
+	"context"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/url"
+	"time"
+)
+
+// NtfyPriority exports ntfyPriority for testing.
+func NtfyPriority(priority string) string {
+	return ntfyPriority(priority)
+}
+
+// SlackColor exports slackColor for testing.
+func SlackColor(priority string) string {
+	return slackColor(priority)
+}
+
+// NewRequestForTest exports newRequest for testing.
+func NewRequestForTest(
+	ctx context.Context,
+	method string,
+	target *url.URL,
+	body io.Reader,
+) *http.Request {
+	return newRequest(ctx, method, target, body)
+}
+
+// NewTestService creates a Service suitable for unit testing.
+// It discards log output and uses the given transport.
+func NewTestService(transport http.RoundTripper) *Service {
+	return newService(slog.New(slog.DiscardHandler), transport)
+}
+
+// NewTestServiceWithLogger creates a Service that writes to the
+// given handler, so tests can assert on emitted log records.
+func NewTestServiceWithLogger(
+	transport http.RoundTripper,
+	handler slog.Handler,
+) *Service {
+	return newService(slog.New(handler), transport)
+}
+
+// Drain exports drain for testing.
+func (svc *Service) Drain(ctx context.Context) {
+	svc.drain(ctx)
+}
+
+// OutstandingDeliveries reports how many delivery goroutines
+// are currently tracked as in flight.
+func (svc *Service) OutstandingDeliveries() int64 {
+	return svc.outstanding.Load()
+}
+
+// SetNtfyURL sets the ntfy URL on a Service for testing.
+func (svc *Service) SetNtfyURL(u *url.URL) {
+	svc.ntfyURL = u
+}
+
+// SetSlackWebhookURL sets the Slack webhook URL on a
+// Service for testing.
+func (svc *Service) SetSlackWebhookURL(u *url.URL) {
+	svc.slackWebhookURL = u
+}
+
+// SetMattermostWebhookURL sets the Mattermost webhook URL on
+// a Service for testing.
+func (svc *Service) SetMattermostWebhookURL(u *url.URL) {
+	svc.mattermostWebhookURL = u
+}
+
+// SendNtfy exports sendNtfy for testing.
+func (svc *Service) SendNtfy(
+	ctx context.Context,
+	topicURL *url.URL,
+	title, message, priority string,
+) error {
+	return svc.sendNtfy(ctx, topicURL, title, message, priority)
+}
+
+// SendSlack exports sendSlack for testing.
+func (svc *Service) SendSlack(
+	ctx context.Context,
+	webhookURL *url.URL,
+	title, message, priority string,
+) error {
+	return svc.sendSlack(
+		ctx, webhookURL, title, message, priority,
+	)
+}
+
+// SetRetryConfig overrides the retry configuration for
+// testing.
+func (svc *Service) SetRetryConfig(cfg RetryConfig) {
+	svc.retryConfig = cfg
+}
+
+// SetSleepFunc overrides the sleep function so tests can
+// eliminate real delays.
+func (svc *Service) SetSleepFunc(
+	fn func(time.Duration) <-chan time.Time,
+) {
+	svc.sleepFn = fn
+}
+
+// DeliverWithRetry exports deliverWithRetry for testing.
+func (svc *Service) DeliverWithRetry(
+	ctx context.Context,
+	endpoint string,
+	fn func(context.Context) error,
+) error {
+	return svc.deliverWithRetry(ctx, endpoint, fn)
+}
+
+// BackoffDuration exports RetryConfig.backoff for testing.
+func (rc RetryConfig) BackoffDuration(attempt int) time.Duration {
+	return rc.defaults().backoff(attempt)
+}

internal/notify/history.go

@@ -0,0 +1,62 @@
+package notify
+
+import (
+	"sync"
+	"time"
+)
+
+// maxAlertHistory is the maximum number of alerts to retain.
+const maxAlertHistory = 100
+
+// AlertEntry represents a single notification that was sent.
+type AlertEntry struct {
+	Timestamp time.Time
+	Title     string
+	Message   string
+	Priority  string
+}
+
+// AlertHistory is a thread-safe ring buffer that stores
+// the most recent alerts.
+type AlertHistory struct {
+	mu      sync.RWMutex
+	entries [maxAlertHistory]AlertEntry
+	count   int
+	index   int
+}
+
+// NewAlertHistory creates a new empty AlertHistory.
+func NewAlertHistory() *AlertHistory {
+	return &AlertHistory{}
+}
+
+// Add records a new alert entry in the ring buffer.
+func (h *AlertHistory) Add(entry AlertEntry) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+
+	h.entries[h.index] = entry
+	h.index = (h.index + 1) % maxAlertHistory
+
+	if h.count < maxAlertHistory {
+		h.count++
+	}
+}
+
+// Recent returns the stored alerts in reverse chronological
+// order (newest first). Returns at most maxAlertHistory entries.
+func (h *AlertHistory) Recent() []AlertEntry {
+	h.mu.RLock()
+	defer h.mu.RUnlock()
+
+	result := make([]AlertEntry, h.count)
+
+	for i := range h.count {
+		// Walk backwards from the most recent entry.
+		idx := (h.index - 1 - i + maxAlertHistory) %
+			maxAlertHistory
+		result[i] = h.entries[idx]
+	}
+
+	return result
+}

internal/notify/history_test.go

@@ -0,0 +1,88 @@
+package notify_test
+
+import (
+	"testing"
+	"time"
+
+	"sneak.berlin/go/dnswatcher/internal/notify"
+)
+
+func TestAlertHistoryEmpty(t *testing.T) {
+	t.Parallel()
+
+	h := notify.NewAlertHistory()
+
+	entries := h.Recent()
+	if len(entries) != 0 {
+		t.Fatalf("expected 0 entries, got %d", len(entries))
+	}
+}
+
+func TestAlertHistoryAddAndRecent(t *testing.T) {
+	t.Parallel()
+
+	h := notify.NewAlertHistory()
+
+	now := time.Now().UTC()
+
+	h.Add(notify.AlertEntry{
+		Timestamp: now.Add(-2 * time.Minute),
+		Title:     "first",
+		Message:   "msg1",
+		Priority:  prioInfo,
+	})
+
+	h.Add(notify.AlertEntry{
+		Timestamp: now.Add(-1 * time.Minute),
+		Title:     "second",
+		Message:   "msg2",
+		Priority:  prioWarning,
+	})
+
+	entries := h.Recent()
+	if len(entries) != 2 {
+		t.Fatalf("expected 2 entries, got %d", len(entries))
+	}
+
+	// Newest first.
+	if entries[0].Title != "second" {
+		t.Errorf(
+			"expected newest first, got %q", entries[0].Title,
+		)
+	}
+
+	if entries[1].Title != "first" {
+		t.Errorf(
+			"expected oldest second, got %q", entries[1].Title,
+		)
+	}
+}
+
+func TestAlertHistoryOverflow(t *testing.T) {
+	t.Parallel()
+
+	h := notify.NewAlertHistory()
+
+	const totalEntries = 110
+
+	// Fill beyond capacity.
+	for i := range totalEntries {
+		h.Add(notify.AlertEntry{
+			Timestamp: time.Now().UTC(),
+			Title:     "alert",
+			Message:   "msg",
+			Priority:  string(rune('0' + i%10)),
+		})
+	}
+
+	entries := h.Recent()
+
+	const maxHistory = 100
+
+	if len(entries) != maxHistory {
+		t.Fatalf(
+			"expected %d entries, got %d",
+			maxHistory, len(entries),
+		)
+	}
+}

internal/notify/notify.go

@@ -1,4 +1,5 @@
-// Package notify provides notification delivery to Slack, Mattermost, and ntfy.
+// Package notify provides notification delivery to Slack,
+// Mattermost, and ntfy.
 package notify
 
 import (
@@ -7,8 +8,12 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
 	"log/slog"
 	"net/http"
+	"net/url"
+	"sync"
+	"sync/atomic"
 	"time"
 
 	"go.uber.org/fx"
@@ -33,8 +38,66 @@ var (
 	ErrMattermostFailed = errors.New(
 		"mattermost notification failed",
 	)
+	// ErrInvalidScheme is returned for disallowed URL schemes.
+	ErrInvalidScheme = errors.New("URL scheme not allowed")
+	// ErrMissingHost is returned when a URL has no host.
+	ErrMissingHost = errors.New("URL must have a host")
 )
 
+// IsAllowedScheme checks if the URL scheme is permitted.
+func IsAllowedScheme(scheme string) bool {
+	return scheme == "https" || scheme == "http"
+}
+
+// ValidateWebhookURL validates and sanitizes a webhook URL.
+// It ensures the URL has an allowed scheme (http/https),
+// a non-empty host, and returns a pre-parsed *url.URL
+// reconstructed from validated components.
+func ValidateWebhookURL(raw string) (*url.URL, error) {
+	u, err := url.ParseRequestURI(raw)
+	if err != nil {
+		return nil, fmt.Errorf("invalid URL: %w", err)
+	}
+
+	if !IsAllowedScheme(u.Scheme) {
+		return nil, fmt.Errorf(
+			"%w: %s", ErrInvalidScheme, u.Scheme,
+		)
+	}
+
+	if u.Host == "" {
+		return nil, fmt.Errorf("%w", ErrMissingHost)
+	}
+
+	// Reconstruct from parsed components.
+	clean := &url.URL{
+		Scheme:   u.Scheme,
+		Host:     u.Host,
+		Path:     u.Path,
+		RawQuery: u.RawQuery,
+	}
+
+	return clean, nil
+}
+
+// newRequest creates an http.Request from a pre-validated *url.URL.
+// This avoids passing URL strings to http.NewRequestWithContext,
+// which gosec flags as a potential SSRF vector.
+func newRequest(
+	ctx context.Context,
+	method string,
+	target *url.URL,
+	body io.Reader,
+) *http.Request {
+	return (&http.Request{
+		Method: method,
+		URL:    target,
+		Host:   target.Host,
+		Header: make(http.Header),
+		Body:   io.NopCloser(body),
+	}).WithContext(ctx)
+}
+
 // Params contains dependencies for Service.
 type Params struct {
 	fx.In
@@ -46,108 +109,223 @@ type Params struct {
 // Service provides notification functionality.
 type Service struct {
 	log                  *slog.Logger
-	client *http.Client
+	transport            http.RoundTripper
 	config               *config.Config
+	ntfyURL              *url.URL
+	slackWebhookURL      *url.URL
+	mattermostWebhookURL *url.URL
+	history              *AlertHistory
+	retryConfig          RetryConfig
+	sleepFn              func(time.Duration) <-chan time.Time
+
+	// Shutdown draining state.  drainMu guards draining and
+	// serialises it against the counter increment in
+	// startDelivery; inFlight tracks the delivery goroutines
+	// themselves and outstanding mirrors its count so a timed
+	// out drain can report how many were abandoned.
+	drainMu     sync.Mutex
+	draining    bool
+	inFlight    sync.WaitGroup
+	outstanding atomic.Int64
+	abandon     chan struct{}
+	abandonOnce sync.Once
+}
+
+// newService builds a Service with the fields every Service
+// needs regardless of how it was constructed.
+func newService(
+	log *slog.Logger,
+	transport http.RoundTripper,
+) *Service {
+	return &Service{
+		log:       log,
+		transport: transport,
+		history:   NewAlertHistory(),
+		abandon:   make(chan struct{}),
+	}
 }
 
 // New creates a new notify Service.
 func New(
-	_ fx.Lifecycle,
+	lifecycle fx.Lifecycle,
 	params Params,
 ) (*Service, error) {
-	return &Service{
-		log: params.Logger.Get(),
-		client: &http.Client{
-			Timeout: httpClientTimeout,
+	svc := newService(params.Logger.Get(), http.DefaultTransport)
+	svc.config = params.Config
+
+	if params.Config.NtfyTopic != "" {
+		u, err := ValidateWebhookURL(
+			params.Config.NtfyTopic,
+		)
+		if err != nil {
+			return nil, fmt.Errorf(
+				"invalid ntfy topic URL: %w", err,
+			)
+		}
+
+		svc.ntfyURL = u
+	}
+
+	if params.Config.SlackWebhook != "" {
+		u, err := ValidateWebhookURL(
+			params.Config.SlackWebhook,
+		)
+		if err != nil {
+			return nil, fmt.Errorf(
+				"invalid slack webhook URL: %w", err,
+			)
+		}
+
+		svc.slackWebhookURL = u
+	}
+
+	if params.Config.MattermostWebhook != "" {
+		u, err := ValidateWebhookURL(
+			params.Config.MattermostWebhook,
+		)
+		if err != nil {
+			return nil, fmt.Errorf(
+				"invalid mattermost webhook URL: %w", err,
+			)
+		}
+
+		svc.mattermostWebhookURL = u
+	}
+
+	lifecycle.Append(fx.Hook{
+		OnStop: func(ctx context.Context) error {
+			svc.drain(ctx)
+
+			return nil
 		},
-		config: params.Config,
-	}, nil
+	})
+
+	return svc, nil
 }
 
-// SendNotification sends a notification to all configured endpoints.
+// History returns the alert history for reading recent alerts.
+func (svc *Service) History() *AlertHistory {
+	return svc.history
+}
+
+// SendNotification sends a notification to all configured
+// endpoints and records it in the alert history.
 func (svc *Service) SendNotification(
 	ctx context.Context,
 	title, message, priority string,
 ) {
-	if svc.config.NtfyTopic != "" {
-		go func() {
+	svc.history.Add(AlertEntry{
+		Timestamp: time.Now().UTC(),
+		Title:     title,
+		Message:   message,
+		Priority:  priority,
+	})
+
+	svc.dispatchNtfy(ctx, title, message, priority)
+	svc.dispatchSlack(ctx, title, message, priority)
+	svc.dispatchMattermost(ctx, title, message, priority)
+}
+
+// dispatch delivers a notification to one endpoint on a
+// tracked background goroutine.
+//
+// The delivery context is detached from ctx with
+// context.WithoutCancel so that a cancelled caller does not
+// kill a delivery already under way; the shutdown drain, not
+// the caller, decides how long deliveries may keep running.
+func (svc *Service) dispatch(
+	ctx context.Context,
+	endpoint string,
+	send func(context.Context) error,
+) {
 	notifyCtx := context.WithoutCancel(ctx)
 
-			err := svc.sendNtfy(
-				notifyCtx,
-				svc.config.NtfyTopic,
-				title, message, priority,
-			)
+	svc.startDelivery(endpoint, func() {
+		err := svc.deliverWithRetry(notifyCtx, endpoint, send)
 		if err != nil {
 			svc.log.Error(
-					"failed to send ntfy notification",
+				"failed to send notification after retries",
+				"endpoint", endpoint,
 				"error", err,
 			)
 		}
-		}()
+	})
+}
+
+func (svc *Service) dispatchNtfy(
+	ctx context.Context,
+	title, message, priority string,
+) {
+	if svc.ntfyURL == nil {
+		return
 	}
 
-	if svc.config.SlackWebhook != "" {
-		go func() {
-			notifyCtx := context.WithoutCancel(ctx)
+	svc.dispatch(ctx, "ntfy", func(c context.Context) error {
+		return svc.sendNtfy(
+			c, svc.ntfyURL, title, message, priority,
+		)
+	})
+}
 
-			err := svc.sendSlack(
-				notifyCtx,
-				svc.config.SlackWebhook,
+func (svc *Service) dispatchSlack(
+	ctx context.Context,
+	title, message, priority string,
+) {
+	if svc.slackWebhookURL == nil {
+		return
+	}
+
+	svc.dispatch(ctx, "slack", func(c context.Context) error {
+		return svc.sendSlack(
+			c, svc.slackWebhookURL, title, message, priority,
+		)
+	})
+}
+
+func (svc *Service) dispatchMattermost(
+	ctx context.Context,
+	title, message, priority string,
+) {
+	if svc.mattermostWebhookURL == nil {
+		return
+	}
+
+	svc.dispatch(
+		ctx, "mattermost",
+		func(c context.Context) error {
+			return svc.sendSlack(
+				c, svc.mattermostWebhookURL,
 				title, message, priority,
 			)
-			if err != nil {
-				svc.log.Error(
-					"failed to send slack notification",
-					"error", err,
+		},
 	)
-			}
-		}()
-	}
-
-	if svc.config.MattermostWebhook != "" {
-		go func() {
-			notifyCtx := context.WithoutCancel(ctx)
-
-			err := svc.sendSlack(
-				notifyCtx,
-				svc.config.MattermostWebhook,
-				title, message, priority,
-			)
-			if err != nil {
-				svc.log.Error(
-					"failed to send mattermost notification",
-					"error", err,
-				)
-			}
-		}()
-	}
 }
 
 func (svc *Service) sendNtfy(
 	ctx context.Context,
-	topic, title, message, priority string,
+	topicURL *url.URL,
+	title, message, priority string,
 ) error {
 	svc.log.Debug(
 		"sending ntfy notification",
-		"topic", topic,
+		"topic", topicURL.String(),
 		"title", title,
 	)
 
-	request, err := http.NewRequestWithContext(
-		ctx,
-		http.MethodPost,
-		topic,
-		bytes.NewBufferString(message),
+	ctx, cancel := context.WithTimeout(
+		ctx, httpClientTimeout,
+	)
+	defer cancel()
+
+	body := bytes.NewBufferString(message)
+	request := newRequest(
+		ctx, http.MethodPost, topicURL, body,
 	)
-	if err != nil {
-		return fmt.Errorf("creating ntfy request: %w", err)
-	}
 
 	request.Header.Set("Title", title)
 	request.Header.Set("Priority", ntfyPriority(priority))
 
-	resp, err := svc.client.Do(request)
+	resp, err := svc.transport.RoundTrip(request)
 	if err != nil {
 		return fmt.Errorf("sending ntfy request: %w", err)
 	}
@@ -156,7 +334,8 @@ func (svc *Service) sendNtfy(
 
 	if resp.StatusCode >= httpStatusClientError {
 		return fmt.Errorf(
-			"%w: status %d", ErrNtfyFailed, resp.StatusCode,
+			"%w: status %d",
+			ErrNtfyFailed, resp.StatusCode,
 		)
 	}
 
@@ -193,11 +372,17 @@ type SlackAttachment struct {
 
 func (svc *Service) sendSlack(
 	ctx context.Context,
-	webhookURL, title, message, priority string,
+	webhookURL *url.URL,
+	title, message, priority string,
 ) error {
+	ctx, cancel := context.WithTimeout(
+		ctx, httpClientTimeout,
+	)
+	defer cancel()
+
 	svc.log.Debug(
 		"sending webhook notification",
-		"url", webhookURL,
+		"url", webhookURL.String(),
 		"title", title,
 	)
 
@@ -213,22 +398,19 @@ func (svc *Service) sendSlack(
 
 	body, err := json.Marshal(payload)
 	if err != nil {
-		return fmt.Errorf("marshaling webhook payload: %w", err)
+		return fmt.Errorf(
+			"marshaling webhook payload: %w", err,
+		)
 	}
 
-	request, err := http.NewRequestWithContext(
-		ctx,
-		http.MethodPost,
-		webhookURL,
+	request := newRequest(
+		ctx, http.MethodPost, webhookURL,
 		bytes.NewBuffer(body),
 	)
-	if err != nil {
-		return fmt.Errorf("creating webhook request: %w", err)
-	}
 
 	request.Header.Set("Content-Type", "application/json")
 
-	resp, err := svc.client.Do(request)
+	resp, err := svc.transport.RoundTrip(request)
 	if err != nil {
 		return fmt.Errorf("sending webhook request: %w", err)
 	}

internal/notify/notify_test.go

@@ -0,0 +1,100 @@
+package notify_test
+
+import (
+	"testing"
+
+	"sneak.berlin/go/dnswatcher/internal/notify"
+)
+
+func TestValidateWebhookURLValid(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		input   string
+		wantURL string
+	}{
+		{
+			name:    "valid https URL",
+			input:   "https://hooks.slack.com/T00/B00",
+			wantURL: "https://hooks.slack.com/T00/B00",
+		},
+		{
+			name:    "valid http URL",
+			input:   "http://localhost:8080/webhook",
+			wantURL: "http://localhost:8080/webhook",
+		},
+		{
+			name:    "https with query",
+			input:   "https://ntfy.sh/topic?auth=tok",
+			wantURL: "https://ntfy.sh/topic?auth=tok",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got, err := notify.ValidateWebhookURL(tt.input)
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+
+			if got.String() != tt.wantURL {
+				t.Errorf(
+					"got %q, want %q",
+					got.String(), tt.wantURL,
+				)
+			}
+		})
+	}
+}
+
+func TestValidateWebhookURLInvalid(t *testing.T) {
+	t.Parallel()
+
+	invalid := []struct {
+		name  string
+		input string
+	}{
+		{"ftp scheme", "ftp://example.com/file"},
+		{"file scheme", "file:///etc/passwd"},
+		{"empty string", ""},
+		{"no scheme", "example.com/webhook"},
+		{"no host", "https:///path"},
+	}
+
+	for _, tt := range invalid {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got, err := notify.ValidateWebhookURL(tt.input)
+			if err == nil {
+				t.Errorf(
+					"expected error for %q, got %v",
+					tt.input, got,
+				)
+			}
+		})
+	}
+}
+
+func TestIsAllowedScheme(t *testing.T) {
+	t.Parallel()
+
+	if !notify.IsAllowedScheme("https") {
+		t.Error("https should be allowed")
+	}
+
+	if !notify.IsAllowedScheme("http") {
+		t.Error("http should be allowed")
+	}
+
+	if notify.IsAllowedScheme("ftp") {
+		t.Error("ftp should not be allowed")
+	}
+
+	if notify.IsAllowedScheme("") {
+		t.Error("empty scheme should not be allowed")
+	}
+}

internal/notify/retry.go

@@ -0,0 +1,148 @@
+package notify
+
+import (
+	"context"
+	"fmt"
+	"math"
+	"math/rand/v2"
+	"time"
+)
+
+// Retry defaults.
+const (
+	// DefaultMaxRetries is the number of additional attempts
+	// after the first failure.
+	DefaultMaxRetries = 5
+
+	// DefaultBaseDelay is the initial delay before the first
+	// retry attempt.
+	DefaultBaseDelay = 1 * time.Second
+
+	// DefaultMaxDelay caps the computed backoff delay.
+	DefaultMaxDelay = 60 * time.Second
+
+	// backoffMultiplier is the exponential growth factor.
+	backoffMultiplier = 2
+
+	// jitterFraction controls the ±random spread applied
+	// to each delay (0.25 = ±25%).
+	jitterFraction = 0.25
+)
+
+// RetryConfig holds tuning knobs for the retry loop.
+// Zero values fall back to the package defaults above.
+type RetryConfig struct {
+	MaxRetries int
+	BaseDelay  time.Duration
+	MaxDelay   time.Duration
+}
+
+// defaults returns a copy with zero fields replaced by
+// package defaults.
+func (rc RetryConfig) defaults() RetryConfig {
+	if rc.MaxRetries <= 0 {
+		rc.MaxRetries = DefaultMaxRetries
+	}
+
+	if rc.BaseDelay <= 0 {
+		rc.BaseDelay = DefaultBaseDelay
+	}
+
+	if rc.MaxDelay <= 0 {
+		rc.MaxDelay = DefaultMaxDelay
+	}
+
+	return rc
+}
+
+// backoff computes the delay for attempt n (0-indexed) with
+// jitter.  The raw delay is BaseDelay * 2^n, capped at
+// MaxDelay, then randomised by ±jitterFraction.
+func (rc RetryConfig) backoff(attempt int) time.Duration {
+	raw := float64(rc.BaseDelay) *
+		math.Pow(backoffMultiplier, float64(attempt))
+
+	if raw > float64(rc.MaxDelay) {
+		raw = float64(rc.MaxDelay)
+	}
+
+	// Apply jitter: uniform in [raw*(1-j), raw*(1+j)].
+	lo := raw * (1 - jitterFraction)
+	hi := raw * (1 + jitterFraction)
+
+	jittered := lo + rand.Float64()*(hi-lo) //nolint:gosec // jitter needs no crypto/rand
+
+	return time.Duration(jittered)
+}
+
+// deliverWithRetry calls fn, retrying on error with
+// exponential backoff.  It logs every failed attempt and
+// returns the last error if all attempts are exhausted.
+func (svc *Service) deliverWithRetry(
+	ctx context.Context,
+	endpoint string,
+	fn func(context.Context) error,
+) error {
+	cfg := svc.retryConfig.defaults()
+
+	var lastErr error
+
+	// attempt 0 is the initial call; attempts 1..MaxRetries
+	// are retries.
+	for attempt := range cfg.MaxRetries + 1 {
+		lastErr = fn(ctx)
+		if lastErr == nil {
+			if attempt > 0 {
+				svc.log.Info(
+					"notification delivered after retry",
+					"endpoint", endpoint,
+					"attempt", attempt+1,
+				)
+			}
+
+			return nil
+		}
+
+		// Last attempt — don't sleep, just return.
+		if attempt == cfg.MaxRetries {
+			break
+		}
+
+		delay := cfg.backoff(attempt)
+
+		svc.log.Warn(
+			"notification delivery failed, retrying",
+			"endpoint", endpoint,
+			"attempt", attempt+1,
+			"maxAttempts", cfg.MaxRetries+1,
+			"retryIn", delay,
+			"error", lastErr,
+		)
+
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-svc.abandon:
+			// Shutdown drained past its deadline; stop
+			// sleeping rather than outlive the process.
+			// A nil channel (Service built without a
+			// constructor) simply never fires.
+			return fmt.Errorf(
+				"%w: %s", ErrDeliveryAbandoned, endpoint,
+			)
+		case <-svc.sleepFunc(delay):
+		}
+	}
+
+	return lastErr
+}
+
+// sleepFunc returns a channel that closes after d.
+// It is a field-level indirection so tests can override it.
+func (svc *Service) sleepFunc(d time.Duration) <-chan time.Time {
+	if svc.sleepFn != nil {
+		return svc.sleepFn(d)
+	}
+
+	return time.After(d)
+}

internal/notify/retry_test.go

@@ -0,0 +1,493 @@
+package notify_test
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/dnswatcher/internal/notify"
+)
+
+// Static test errors (err113).
+var (
+	errTransient = errors.New("transient failure")
+	errPermanent = errors.New("permanent failure")
+	errFail      = errors.New("fail")
+)
+
+// instantSleep returns a closed channel immediately, removing
+// real delays from tests.
+func instantSleep(_ time.Duration) <-chan time.Time {
+	ch := make(chan time.Time, 1)
+	ch <- time.Now()
+
+	return ch
+}
+
+// ── backoff calculation ───────────────────────────────────
+
+func TestBackoffDurationIncreases(t *testing.T) {
+	t.Parallel()
+
+	cfg := notify.RetryConfig{
+		MaxRetries: 5,
+		BaseDelay:  1 * time.Second,
+		MaxDelay:   30 * time.Second,
+	}
+
+	prev := time.Duration(0)
+
+	// With jitter the exact value varies, but the trend
+	// should be increasing for the first few attempts.
+	for attempt := range 4 {
+		d := cfg.BackoffDuration(attempt)
+		if d <= 0 {
+			t.Fatalf(
+				"attempt %d: backoff must be positive, got %v",
+				attempt, d,
+			)
+		}
+
+		// Allow jitter to occasionally flatten a step, but
+		// the midpoint (no-jitter) should be strictly higher.
+		midpoint := cfg.BaseDelay * (1 << attempt)
+		if attempt > 0 && midpoint <= prev {
+			t.Fatalf(
+				"midpoint should grow: attempt %d midpoint=%v prev=%v",
+				attempt, midpoint, prev,
+			)
+		}
+
+		prev = midpoint
+	}
+}
+
+func TestBackoffDurationCappedAtMax(t *testing.T) {
+	t.Parallel()
+
+	cfg := notify.RetryConfig{
+		MaxRetries: 5,
+		BaseDelay:  1 * time.Second,
+		MaxDelay:   5 * time.Second,
+	}
+
+	// Attempt 10 would be 1024s without capping.
+	d := cfg.BackoffDuration(10)
+
+	// With ±25% jitter on a 5s cap: max is 6.25s.
+	const maxWithJitter = 5*time.Second +
+		5*time.Second/4 +
+		time.Millisecond // rounding margin
+
+	if d > maxWithJitter {
+		t.Errorf(
+			"backoff %v exceeds max+jitter %v",
+			d, maxWithJitter,
+		)
+	}
+}
+
+// ── deliverWithRetry ──────────────────────────────────────
+
+func TestDeliverWithRetrySucceedsFirstAttempt(t *testing.T) {
+	t.Parallel()
+
+	svc := notify.NewTestService(http.DefaultTransport)
+	svc.SetSleepFunc(instantSleep)
+
+	var calls atomic.Int32
+
+	err := svc.DeliverWithRetry(
+		context.Background(), "test",
+		func(_ context.Context) error {
+			calls.Add(1)
+
+			return nil
+		},
+	)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if calls.Load() != 1 {
+		t.Errorf("expected 1 call, got %d", calls.Load())
+	}
+}
+
+func TestDeliverWithRetryRetriesOnFailure(t *testing.T) {
+	t.Parallel()
+
+	svc := notify.NewTestService(http.DefaultTransport)
+	svc.SetSleepFunc(instantSleep)
+	svc.SetRetryConfig(notify.RetryConfig{
+		MaxRetries: 3,
+		BaseDelay:  time.Millisecond,
+		MaxDelay:   10 * time.Millisecond,
+	})
+
+	var calls atomic.Int32
+
+	// Fail twice, then succeed on the third attempt.
+	err := svc.DeliverWithRetry(
+		context.Background(), "test",
+		func(_ context.Context) error {
+			n := calls.Add(1)
+			if n <= 2 {
+				return errTransient
+			}
+
+			return nil
+		},
+	)
+	if err != nil {
+		t.Fatalf("expected success after retries: %v", err)
+	}
+
+	if calls.Load() != 3 {
+		t.Errorf("expected 3 calls, got %d", calls.Load())
+	}
+}
+
+func TestDeliverWithRetryExhaustsAttempts(t *testing.T) {
+	t.Parallel()
+
+	svc := notify.NewTestService(http.DefaultTransport)
+	svc.SetSleepFunc(instantSleep)
+	svc.SetRetryConfig(notify.RetryConfig{
+		MaxRetries: 2,
+		BaseDelay:  time.Millisecond,
+		MaxDelay:   10 * time.Millisecond,
+	})
+
+	var calls atomic.Int32
+
+	err := svc.DeliverWithRetry(
+		context.Background(), "test",
+		func(_ context.Context) error {
+			calls.Add(1)
+
+			return errPermanent
+		},
+	)
+	if err == nil {
+		t.Fatal("expected error when all retries exhausted")
+	}
+
+	if !errors.Is(err, errPermanent) {
+		t.Errorf("expected permanent failure, got: %v", err)
+	}
+
+	// 1 initial + 2 retries = 3 total.
+	if calls.Load() != 3 {
+		t.Errorf("expected 3 calls, got %d", calls.Load())
+	}
+}
+
+func TestDeliverWithRetryRespectsContextCancellation(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	svc := notify.NewTestService(http.DefaultTransport)
+	svc.SetRetryConfig(notify.RetryConfig{
+		MaxRetries: 5,
+		BaseDelay:  time.Millisecond,
+		MaxDelay:   10 * time.Millisecond,
+	})
+
+	// Use a blocking sleep so the context cancellation is
+	// the only way out.
+	svc.SetSleepFunc(func(_ time.Duration) <-chan time.Time {
+		return make(chan time.Time) // never fires
+	})
+
+	ctx, cancel := context.WithCancel(context.Background())
+
+	done := make(chan error, 1)
+
+	go func() {
+		done <- svc.DeliverWithRetry(
+			ctx, "test",
+			func(_ context.Context) error {
+				return errFail
+			},
+		)
+	}()
+
+	// Wait for the first failure + retry sleep to be
+	// entered, then cancel.
+	time.Sleep(50 * time.Millisecond)
+	cancel()
+
+	select {
+	case err := <-done:
+		if !errors.Is(err, context.Canceled) {
+			t.Errorf(
+				"expected context.Canceled, got: %v", err,
+			)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("deliverWithRetry did not return after cancel")
+	}
+}
+
+// ── integration: SendNotification with retry ──────────────
+
+func TestSendNotificationRetriesTransientFailure(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	var (
+		mu       sync.Mutex
+		attempts int
+	)
+
+	srv := httptest.NewServer(
+		http.HandlerFunc(
+			func(w http.ResponseWriter, _ *http.Request) {
+				mu.Lock()
+				attempts++
+				n := attempts
+				mu.Unlock()
+
+				if n <= 2 {
+					w.WriteHeader(
+						http.StatusInternalServerError,
+					)
+
+					return
+				}
+
+				w.WriteHeader(http.StatusOK)
+			}),
+	)
+	defer srv.Close()
+
+	svc := newRetryTestService(srv.URL, "ntfy")
+
+	svc.SendNotification(
+		context.Background(),
+		"Retry Test", "body", "warning",
+	)
+
+	waitForCondition(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+
+		return attempts >= 3
+	})
+}
+
+// newRetryTestService creates a test service with instant
+// sleep and low retry delays for the named endpoint.
+func newRetryTestService(
+	rawURL, endpoint string,
+) *notify.Service {
+	svc := notify.NewTestService(http.DefaultTransport)
+	svc.SetSleepFunc(instantSleep)
+	svc.SetRetryConfig(notify.RetryConfig{
+		MaxRetries: 3,
+		BaseDelay:  time.Millisecond,
+		MaxDelay:   10 * time.Millisecond,
+	})
+
+	u, _ := url.Parse(rawURL)
+
+	switch endpoint {
+	case "ntfy":
+		svc.SetNtfyURL(u)
+	case "slack":
+		svc.SetSlackWebhookURL(u)
+	case "mattermost":
+		svc.SetMattermostWebhookURL(u)
+	}
+
+	return svc
+}
+
+func TestSendNotificationAllEndpointsRetrySetup(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	result := newEndpointRetryResult()
+	ntfySrv, slackSrv, mmSrv := newRetryServers(result)
+
+	defer ntfySrv.Close()
+	defer slackSrv.Close()
+	defer mmSrv.Close()
+
+	svc := buildAllEndpointRetryService(
+		ntfySrv.URL, slackSrv.URL, mmSrv.URL,
+	)
+
+	svc.SendNotification(
+		context.Background(),
+		"Multi-Retry", "testing", "error",
+	)
+
+	assertAllEndpointsRetried(t, result)
+}
+
+// endpointRetryResult tracks per-endpoint retry state.
+type endpointRetryResult struct {
+	mu            sync.Mutex
+	ntfyAttempts  int
+	slackAttempts int
+	mmAttempts    int
+	ntfyOK        bool
+	slackOK       bool
+	mmOK          bool
+}
+
+func newEndpointRetryResult() *endpointRetryResult {
+	return &endpointRetryResult{}
+}
+
+func newRetryServers(
+	r *endpointRetryResult,
+) (*httptest.Server, *httptest.Server, *httptest.Server) {
+	mk := func(
+		attempts *int, ok *bool,
+	) *httptest.Server {
+		return httptest.NewServer(
+			http.HandlerFunc(
+				func(w http.ResponseWriter, _ *http.Request) {
+					r.mu.Lock()
+					*attempts++
+					n := *attempts
+					r.mu.Unlock()
+
+					if n == 1 {
+						w.WriteHeader(
+							http.StatusServiceUnavailable,
+						)
+
+						return
+					}
+
+					r.mu.Lock()
+					*ok = true
+					r.mu.Unlock()
+
+					w.WriteHeader(http.StatusOK)
+				}),
+		)
+	}
+
+	return mk(&r.ntfyAttempts, &r.ntfyOK),
+		mk(&r.slackAttempts, &r.slackOK),
+		mk(&r.mmAttempts, &r.mmOK)
+}
+
+func buildAllEndpointRetryService(
+	ntfyURL, slackURL, mmURL string,
+) *notify.Service {
+	svc := notify.NewTestService(http.DefaultTransport)
+	svc.SetSleepFunc(instantSleep)
+	svc.SetRetryConfig(notify.RetryConfig{
+		MaxRetries: 3,
+		BaseDelay:  time.Millisecond,
+		MaxDelay:   10 * time.Millisecond,
+	})
+
+	nu, _ := url.Parse(ntfyURL)
+	su, _ := url.Parse(slackURL)
+	mu, _ := url.Parse(mmURL)
+
+	svc.SetNtfyURL(nu)
+	svc.SetSlackWebhookURL(su)
+	svc.SetMattermostWebhookURL(mu)
+
+	return svc
+}
+
+func assertAllEndpointsRetried(
+	t *testing.T,
+	r *endpointRetryResult,
+) {
+	t.Helper()
+
+	waitForCondition(t, func() bool {
+		r.mu.Lock()
+		defer r.mu.Unlock()
+
+		return r.ntfyOK && r.slackOK && r.mmOK
+	})
+
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	if r.ntfyAttempts < 2 {
+		t.Errorf(
+			"ntfy: expected >= 2 attempts, got %d",
+			r.ntfyAttempts,
+		)
+	}
+
+	if r.slackAttempts < 2 {
+		t.Errorf(
+			"slack: expected >= 2 attempts, got %d",
+			r.slackAttempts,
+		)
+	}
+
+	if r.mmAttempts < 2 {
+		t.Errorf(
+			"mattermost: expected >= 2 attempts, got %d",
+			r.mmAttempts,
+		)
+	}
+}
+
+func TestSendNotificationPermanentFailureLogsError(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	var (
+		mu       sync.Mutex
+		attempts int
+	)
+
+	srv := httptest.NewServer(
+		http.HandlerFunc(
+			func(w http.ResponseWriter, _ *http.Request) {
+				mu.Lock()
+				attempts++
+				mu.Unlock()
+
+				w.WriteHeader(
+					http.StatusInternalServerError,
+				)
+			}),
+	)
+	defer srv.Close()
+
+	svc := newRetryTestService(srv.URL, "slack")
+	svc.SetRetryConfig(notify.RetryConfig{
+		MaxRetries: 2,
+		BaseDelay:  time.Millisecond,
+		MaxDelay:   10 * time.Millisecond,
+	})
+
+	svc.SendNotification(
+		context.Background(),
+		"Permanent Fail", "body", "error",
+	)
+
+	// 1 initial + 2 retries = 3 total.
+	waitForCondition(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+
+		return attempts >= 3
+	})
+}

internal/notify/shutdown.go

@@ -0,0 +1,119 @@
+package notify
+
+import (
+	"context"
+	"errors"
+)
+
+// ErrDeliveryAbandoned is returned by a retry loop that was
+// cut short because shutdown drained past its deadline.
+var ErrDeliveryAbandoned = errors.New(
+	"notification delivery abandoned at shutdown",
+)
+
+// startDelivery runs fn on its own goroutine while tracking it,
+// so that drain can wait for it during shutdown.
+//
+// The WaitGroup counter is incremented here, on the caller's
+// goroutine, before the worker exists: incrementing it inside
+// the worker would race with drain's Wait and could let
+// shutdown sail past a delivery that had not started yet.
+//
+// Once draining has begun the delivery is refused outright
+// rather than queued, so a steady stream of newly submitted
+// notifications cannot keep extending the drain.
+func (svc *Service) startDelivery(endpoint string, fn func()) {
+	svc.drainMu.Lock()
+
+	if svc.draining {
+		svc.drainMu.Unlock()
+
+		svc.log.Warn(
+			"notification not dispatched: shutdown in progress",
+			"endpoint", endpoint,
+		)
+
+		return
+	}
+
+	svc.outstanding.Add(1)
+
+	// WaitGroup.Go increments the counter synchronously, here,
+	// and only then starts the goroutine.
+	svc.inFlight.Go(func() {
+		// Runs before the WaitGroup counter is decremented, so
+		// a drain that times out reports an accurate count.
+		defer svc.outstanding.Add(-1)
+
+		fn()
+	})
+
+	svc.drainMu.Unlock()
+}
+
+// drain waits for in-flight notification deliveries to finish.
+//
+// It first stops accepting new deliveries, then waits until
+// either every outstanding delivery has completed or ctx
+// expires — whichever comes first.  ctx is the context fx
+// passes to the OnStop hook, so a permanently dead webhook
+// cannot hang shutdown indefinitely.
+//
+// When the deadline arrives with deliveries still outstanding,
+// the count is logged at warn level and the abandon channel is
+// closed, which releases any retry loop sleeping in backoff.
+// Deliveries already inside an HTTP round trip are bounded by
+// the existing httpClientTimeout instead.
+//
+// A ctx that is already expired on entry is not by itself cause
+// for alarm: if nothing is outstanding there is nothing to
+// abandon, and the drain says so at debug level rather than
+// warning about deliveries that do not exist.
+func (svc *Service) drain(ctx context.Context) {
+	svc.drainMu.Lock()
+	svc.draining = true
+	svc.drainMu.Unlock()
+
+	done := make(chan struct{})
+
+	go func() {
+		svc.inFlight.Wait()
+		close(done)
+	}()
+
+	select {
+	case <-done:
+		svc.log.Debug(
+			"all in-flight notifications completed",
+		)
+	case <-ctx.Done():
+		// outstanding is decremented before the WaitGroup
+		// counter, and startDelivery can no longer add to it
+		// now that draining is set, so a zero here means every
+		// delivery really did finish.  ctx expiring in that
+		// state (an OnStop context that was already cancelled
+		// on entry is the usual way) abandons nothing, so it
+		// must not close abandon or warn about it.
+		abandoned := svc.outstanding.Load()
+		if abandoned == 0 {
+			svc.log.Debug(
+				"all in-flight notifications completed",
+			)
+
+			return
+		}
+
+		svc.abandonOnce.Do(func() {
+			if svc.abandon != nil {
+				close(svc.abandon)
+			}
+		})
+
+		svc.log.Warn(
+			"shutdown deadline reached with notifications "+
+				"still in flight; abandoning them",
+			"abandoned", abandoned,
+			"error", ctx.Err(),
+		)
+	}
+}

internal/notify/shutdown_test.go

@@ -0,0 +1,531 @@
+package notify_test
+
+import (
+	"bytes"
+	"context"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"go.uber.org/fx"
+
+	"sneak.berlin/go/dnswatcher/internal/config"
+	"sneak.berlin/go/dnswatcher/internal/globals"
+	"sneak.berlin/go/dnswatcher/internal/logger"
+	"sneak.berlin/go/dnswatcher/internal/notify"
+)
+
+// Timings used by the drain tests.  They stay in the same
+// 10-100ms band as the retry tests so the suite never waits on
+// a real backoff delay.
+const (
+	// inFlightHold is how long a delivery is kept mid-request
+	// before the handler is released.
+	inFlightHold = 30 * time.Millisecond
+
+	// drainDeadline bounds a drain that is expected to time
+	// out.
+	drainDeadline = 50 * time.Millisecond
+
+	// drainSlack is the upper bound on how long a bounded
+	// drain may take; generous enough for a loaded CI box,
+	// still far below the 20s test ceiling.
+	drainSlack = 2 * time.Second
+
+	// settleDelay is how long to wait before asserting that
+	// something did *not* happen.
+	settleDelay = 50 * time.Millisecond
+
+	// idleDrainBound is the upper bound on a drain that has
+	// nothing in flight.  It is deliberately far above the cost
+	// of the goroutine hop through inFlight.Wait() — which
+	// reached 57ms on a loaded box under -race with the package's
+	// parallel tests — and far below drainSlack, the deadline
+	// such a drain is given.  A drain that blocked until its
+	// deadline instead of returning on the WaitGroup therefore
+	// still fails this bound, but scheduling delay alone cannot.
+	idleDrainBound = 500 * time.Millisecond
+)
+
+// syncBuffer is an io.Writer safe for concurrent use, so log
+// output written from delivery goroutines can be inspected.
+type syncBuffer struct {
+	mu  sync.Mutex
+	buf bytes.Buffer
+}
+
+func (sb *syncBuffer) Write(p []byte) (int, error) {
+	sb.mu.Lock()
+	defer sb.mu.Unlock()
+
+	return sb.buf.Write(p) //nolint:wrapcheck // test helper
+}
+
+func (sb *syncBuffer) String() string {
+	sb.mu.Lock()
+	defer sb.mu.Unlock()
+
+	return sb.buf.String()
+}
+
+// newLoggingService returns a Service writing JSON logs into
+// the returned buffer.
+func newLoggingService(
+	transport http.RoundTripper,
+) (*notify.Service, *syncBuffer) {
+	logs := &syncBuffer{}
+	handler := slog.NewJSONHandler(logs, nil)
+
+	return notify.NewTestServiceWithLogger(transport, handler),
+		logs
+}
+
+// blockingNtfyServer returns a server whose handler signals on
+// entered, waits for release, and then responds 200.
+func blockingNtfyServer(
+	entered chan<- struct{},
+	release <-chan struct{},
+	served *atomic.Bool,
+) *httptest.Server {
+	var once sync.Once
+
+	return httptest.NewServer(
+		http.HandlerFunc(
+			func(w http.ResponseWriter, _ *http.Request) {
+				once.Do(func() { close(entered) })
+				<-release
+
+				served.Store(true)
+
+				w.WriteHeader(http.StatusOK)
+			}),
+	)
+}
+
+// TestDrainWaitsForInFlightDelivery verifies that a delivery
+// already under way when shutdown starts is allowed to finish.
+func TestDrainWaitsForInFlightDelivery(t *testing.T) {
+	t.Parallel()
+
+	var served atomic.Bool
+
+	entered := make(chan struct{})
+	release := make(chan struct{})
+
+	srv := blockingNtfyServer(entered, release, &served)
+	defer srv.Close()
+
+	topicURL, _ := url.Parse(srv.URL)
+
+	svc := notify.NewTestService(http.DefaultTransport)
+	svc.SetNtfyURL(topicURL)
+
+	svc.SendNotification(
+		context.Background(), "t", "m", prioInfo,
+	)
+
+	// Make sure the delivery really is mid-request before the
+	// drain begins.
+	select {
+	case <-entered:
+	case <-time.After(drainSlack):
+		t.Fatal("delivery never reached the endpoint")
+	}
+
+	// As in TestDrainBoundedByContextDeadline: start is captured
+	// before the clock it is compared against, here the timer
+	// holding the delivery open, so elapsed covers the whole hold
+	// and the lower bound cannot come out short from scheduling
+	// delay alone.
+	start := time.Now()
+
+	timer := time.AfterFunc(inFlightHold, func() {
+		close(release)
+	})
+	defer timer.Stop()
+
+	ctx, cancel := context.WithTimeout(
+		context.Background(), drainSlack,
+	)
+	defer cancel()
+
+	svc.Drain(ctx)
+
+	elapsed := time.Since(start)
+
+	if !served.Load() {
+		t.Error(
+			"drain returned before the in-flight delivery " +
+				"completed",
+		)
+	}
+
+	if elapsed < inFlightHold {
+		t.Errorf(
+			"drain took %v, want at least %v",
+			elapsed, inFlightHold,
+		)
+	}
+
+	if got := svc.OutstandingDeliveries(); got != 0 {
+		t.Errorf("outstanding deliveries = %d, want 0", got)
+	}
+}
+
+// neverFires returns a channel that never delivers, standing in
+// for a long backoff sleep without actually sleeping.
+func neverFires(_ time.Duration) <-chan time.Time {
+	return make(chan time.Time)
+}
+
+// TestDrainBoundedByContextDeadline verifies that a delivery
+// stuck retrying against a dead endpoint does not hold shutdown
+// past the OnStop context deadline, and that the abandoned
+// deliveries are logged at warn level rather than dropped
+// silently.
+func TestDrainBoundedByContextDeadline(t *testing.T) {
+	t.Parallel()
+
+	var requests atomic.Int64
+
+	srv := httptest.NewServer(
+		http.HandlerFunc(
+			func(w http.ResponseWriter, _ *http.Request) {
+				requests.Add(1)
+
+				w.WriteHeader(http.StatusInternalServerError)
+			}),
+	)
+	defer srv.Close()
+
+	topicURL, _ := url.Parse(srv.URL)
+
+	svc, logs := newLoggingService(http.DefaultTransport)
+	svc.SetNtfyURL(topicURL)
+	// Never let the backoff sleep complete: the delivery is
+	// parked in its retry wait until shutdown releases it.
+	svc.SetSleepFunc(neverFires)
+	svc.SetRetryConfig(notify.RetryConfig{
+		MaxRetries: 5,
+		BaseDelay:  time.Hour,
+		MaxDelay:   time.Hour,
+	})
+
+	svc.SendNotification(
+		context.Background(), "t", "m", prioError,
+	)
+
+	waitForCondition(t, func() bool {
+		return requests.Load() >= 1 &&
+			svc.OutstandingDeliveries() == 1
+	})
+
+	// start must be captured *before* the deadline clock starts,
+	// so that the measured interval is a superset of the deadline
+	// interval.  Capturing it after context.WithTimeout would
+	// make elapsed structurally smaller than drainDeadline and
+	// the lower bound below unfalsifiable-by-luck: it would fail
+	// whenever the two statements were separated by any
+	// scheduling delay, and pass otherwise, regardless of what
+	// the drain did.
+	start := time.Now()
+
+	ctx, cancel := context.WithTimeout(
+		context.Background(), drainDeadline,
+	)
+	defer cancel()
+
+	// The upper bound is enforced by a watchdog rather than by
+	// measuring after the fact: a drain that is not bounded at
+	// all never returns here (the delivery is parked in a backoff
+	// that never fires), so an unbounded drain must fail this
+	// test promptly instead of hanging the package until the test
+	// binary's 30s timeout.
+	returned := make(chan struct{})
+
+	go func() {
+		defer close(returned)
+
+		svc.Drain(ctx)
+	}()
+
+	select {
+	case <-returned:
+	case <-time.After(drainSlack):
+		t.Fatalf(
+			"drain did not return within %v; its %v deadline "+
+				"did not bound it",
+			drainSlack, drainDeadline,
+		)
+	}
+
+	// The lower bound is the real assertion: the drain must have
+	// waited for its whole deadline rather than giving up on the
+	// outstanding delivery early.  With start captured above, an
+	// early return is the only thing that can make it fail.
+	if elapsed := time.Since(start); elapsed < drainDeadline {
+		t.Errorf(
+			"drain returned after %v, before its %v deadline",
+			elapsed, drainDeadline,
+		)
+	}
+
+	assertAbandonLogged(t, logs.String())
+
+	// The abandoned delivery must stop retrying rather than
+	// outlive the drain.
+	waitForCondition(t, func() bool {
+		return svc.OutstandingDeliveries() == 0
+	})
+}
+
+// assertAbandonLogged checks that the drain logged the
+// abandoned deliveries at warn level with a count.
+func assertAbandonLogged(t *testing.T, output string) {
+	t.Helper()
+
+	if !strings.Contains(output, `"level":"WARN"`) {
+		t.Errorf(
+			"abandoned deliveries not logged at warn level; "+
+				"log output: %s",
+			output,
+		)
+	}
+
+	if !strings.Contains(output, `"abandoned":1`) {
+		t.Errorf(
+			"abandoned delivery count not logged; "+
+				"log output: %s",
+			output,
+		)
+	}
+}
+
+// TestDrainRefusesNewDeliveries verifies that notifications
+// submitted after the drain has begun are refused and logged,
+// so a stream of new work cannot extend shutdown indefinitely.
+func TestDrainRefusesNewDeliveries(t *testing.T) {
+	t.Parallel()
+
+	var requests atomic.Int64
+
+	srv := httptest.NewServer(
+		http.HandlerFunc(
+			func(w http.ResponseWriter, _ *http.Request) {
+				requests.Add(1)
+
+				w.WriteHeader(http.StatusOK)
+			}),
+	)
+	defer srv.Close()
+
+	target, _ := url.Parse(srv.URL)
+
+	svc, logs := newLoggingService(http.DefaultTransport)
+	svc.SetNtfyURL(target)
+	svc.SetSlackWebhookURL(target)
+	svc.SetMattermostWebhookURL(target)
+
+	ctx, cancel := context.WithTimeout(
+		context.Background(), drainSlack,
+	)
+	defer cancel()
+
+	// Nothing is in flight, so this returns immediately and
+	// leaves the service refusing further deliveries.
+	svc.Drain(ctx)
+
+	for range 3 {
+		svc.SendNotification(
+			context.Background(), "t", "m", prioInfo,
+		)
+	}
+
+	time.Sleep(settleDelay)
+
+	if got := requests.Load(); got != 0 {
+		t.Errorf(
+			"%d requests reached the endpoint after drain, "+
+				"want 0",
+			got,
+		)
+	}
+
+	if got := svc.OutstandingDeliveries(); got != 0 {
+		t.Errorf("outstanding deliveries = %d, want 0", got)
+	}
+
+	output := logs.String()
+	if !strings.Contains(output, "shutdown in progress") {
+		t.Errorf(
+			"refused deliveries not logged; log output: %s",
+			output,
+		)
+	}
+}
+
+// recordingLifecycle is a minimal fx.Lifecycle that records the
+// hooks appended to it, so the wiring done by notify.New can be
+// inspected without standing up a whole fx application.
+type recordingLifecycle struct {
+	hooks []fx.Hook
+}
+
+func (l *recordingLifecycle) Append(hook fx.Hook) {
+	l.hooks = append(l.hooks, hook)
+}
+
+// newNotifyService builds a Service through the real
+// constructor, wired to the given lifecycle.
+func newNotifyService(
+	t *testing.T,
+	lifecycle fx.Lifecycle,
+	ntfyTopic string,
+) *notify.Service {
+	t.Helper()
+
+	g, err := globals.New(nil)
+	if err != nil {
+		t.Fatalf("globals.New: %v", err)
+	}
+
+	log, err := logger.New(nil, logger.Params{Globals: g})
+	if err != nil {
+		t.Fatalf("logger.New: %v", err)
+	}
+
+	svc, err := notify.New(lifecycle, notify.Params{
+		Logger: log,
+		Config: &config.Config{NtfyTopic: ntfyTopic},
+	})
+	if err != nil {
+		t.Fatalf("notify.New: %v", err)
+	}
+
+	return svc
+}
+
+// TestNewRegistersDrainingStopHook verifies that notify.New
+// wires an OnStop hook into the fx lifecycle and that the hook
+// waits for in-flight deliveries.
+func TestNewRegistersDrainingStopHook(t *testing.T) {
+	t.Parallel()
+
+	var served atomic.Bool
+
+	entered := make(chan struct{})
+	release := make(chan struct{})
+
+	srv := blockingNtfyServer(entered, release, &served)
+	defer srv.Close()
+
+	lifecycle := &recordingLifecycle{}
+	svc := newNotifyService(t, lifecycle, srv.URL)
+
+	if len(lifecycle.hooks) != 1 {
+		t.Fatalf(
+			"appended %d lifecycle hooks, want 1",
+			len(lifecycle.hooks),
+		)
+	}
+
+	stop := lifecycle.hooks[0].OnStop
+	if stop == nil {
+		t.Fatal("lifecycle hook has no OnStop function")
+	}
+
+	svc.SendNotification(
+		context.Background(), "t", "m", prioInfo,
+	)
+
+	select {
+	case <-entered:
+	case <-time.After(drainSlack):
+		t.Fatal("delivery never reached the endpoint")
+	}
+
+	timer := time.AfterFunc(inFlightHold, func() {
+		close(release)
+	})
+	defer timer.Stop()
+
+	ctx, cancel := context.WithTimeout(
+		context.Background(), drainSlack,
+	)
+	defer cancel()
+
+	err := stop(ctx)
+	if err != nil {
+		t.Fatalf("OnStop returned error: %v", err)
+	}
+
+	if !served.Load() {
+		t.Error(
+			"OnStop returned before the in-flight delivery " +
+				"completed",
+		)
+	}
+}
+
+// TestDrainWithoutDeliveriesReturnsImmediately verifies the
+// common case: nothing in flight, shutdown is not delayed.
+func TestDrainWithoutDeliveriesReturnsImmediately(t *testing.T) {
+	t.Parallel()
+
+	svc := notify.NewTestService(http.DefaultTransport)
+
+	// Captured before the deadline clock, as elsewhere in this
+	// file; for an upper bound that is the conservative
+	// direction, since the measured interval can then only be
+	// longer than the drain itself.
+	start := time.Now()
+
+	ctx, cancel := context.WithTimeout(
+		context.Background(), drainSlack,
+	)
+	defer cancel()
+
+	svc.Drain(ctx)
+
+	if elapsed := time.Since(start); elapsed > idleDrainBound {
+		t.Errorf(
+			"drain of an idle service took %v, want well "+
+				"under its %v deadline",
+			elapsed, drainSlack,
+		)
+	}
+}
+
+// TestDrainWithCancelledContextDoesNotWarn verifies that an
+// OnStop context that is already dead on entry does not produce
+// an "abandoning them" warning when there was nothing in flight
+// to abandon.  The expired context wins the select immediately,
+// so only the outstanding count can tell the difference between
+// a genuine timeout and a shutdown that had simply already run
+// out of time with no work left.
+func TestDrainWithCancelledContextDoesNotWarn(t *testing.T) {
+	t.Parallel()
+
+	svc, logs := newLoggingService(http.DefaultTransport)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	svc.Drain(ctx)
+
+	if output := logs.String(); strings.Contains(
+		output, `"level":"WARN"`,
+	) {
+		t.Errorf(
+			"drain with nothing in flight warned about "+
+				"abandoned deliveries; log output: %s",
+			output,
+		)
+	}
+}

internal/portcheck/portcheck.go

@@ -4,18 +4,39 @@ package portcheck
 import (
 	"context"
 	"errors"
+	"fmt"
 	"log/slog"
+	"net"
+	"strconv"
+	"sync"
+	"time"
 
 	"go.uber.org/fx"
+	"golang.org/x/sync/errgroup"
 
 	"sneak.berlin/go/dnswatcher/internal/logger"
 )
 
-// ErrNotImplemented indicates the port checker is not yet implemented.
-var ErrNotImplemented = errors.New(
-	"port checker not yet implemented",
+const (
+	minPort        = 1
+	maxPort        = 65535
+	defaultTimeout = 5 * time.Second
 )
 
+// ErrInvalidPort is returned when a port number is outside
+// the valid TCP range (1–65535).
+var ErrInvalidPort = errors.New("invalid port number")
+
+// PortResult holds the outcome of a single TCP port check.
+type PortResult struct {
+	// Open indicates whether the port accepted a connection.
+	Open bool
+	// Error contains a description if the connection failed.
+	Error string
+	// Latency is the time taken for the TCP handshake.
+	Latency time.Duration
+}
+
 // Params contains dependencies for Checker.
 type Params struct {
 	fx.In
@@ -38,11 +59,145 @@ func New(
 	}, nil
 }
 
+// NewStandalone creates a Checker without fx dependencies.
+func NewStandalone() *Checker {
+	return &Checker{
+		log: slog.Default(),
+	}
+}
+
+// validatePort checks that a port number is within the valid
+// TCP port range (1–65535).
+func validatePort(port int) error {
+	if port < minPort || port > maxPort {
+		return fmt.Errorf(
+			"%w: %d (must be between %d and %d)",
+			ErrInvalidPort, port, minPort, maxPort,
+		)
+	}
+
+	return nil
+}
+
 // CheckPort tests TCP connectivity to the given address and port.
+// It uses a 5-second timeout unless the context has an earlier
+// deadline.
 func (c *Checker) CheckPort(
-	_ context.Context,
-	_ string,
-	_ int,
-) (bool, error) {
-	return false, ErrNotImplemented
+	ctx context.Context,
+	address string,
+	port int,
+) (*PortResult, error) {
+	err := validatePort(port)
+	if err != nil {
+		return nil, err
+	}
+
+	target := net.JoinHostPort(
+		address, strconv.Itoa(port),
+	)
+
+	timeout := defaultTimeout
+
+	deadline, hasDeadline := ctx.Deadline()
+	if hasDeadline {
+		remaining := time.Until(deadline)
+		if remaining < timeout {
+			timeout = remaining
+		}
+	}
+
+	return c.checkConnection(ctx, target, timeout), nil
+}
+
+// CheckPorts tests TCP connectivity to multiple ports on the
+// given address concurrently. It returns a map of port number
+// to result.
+func (c *Checker) CheckPorts(
+	ctx context.Context,
+	address string,
+	ports []int,
+) (map[int]*PortResult, error) {
+	for _, port := range ports {
+		err := validatePort(port)
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	var mu sync.Mutex
+
+	results := make(map[int]*PortResult, len(ports))
+
+	g, ctx := errgroup.WithContext(ctx)
+
+	for _, port := range ports {
+		g.Go(func() error {
+			result, err := c.CheckPort(ctx, address, port)
+			if err != nil {
+				return fmt.Errorf(
+					"checking port %d: %w", port, err,
+				)
+			}
+
+			mu.Lock()
+			results[port] = result
+			mu.Unlock()
+
+			return nil
+		})
+	}
+
+	err := g.Wait()
+	if err != nil {
+		return nil, err
+	}
+
+	return results, nil
+}
+
+// checkConnection performs the TCP dial and returns a result.
+func (c *Checker) checkConnection(
+	ctx context.Context,
+	target string,
+	timeout time.Duration,
+) *PortResult {
+	dialer := &net.Dialer{Timeout: timeout}
+	start := time.Now()
+
+	conn, dialErr := dialer.DialContext(ctx, "tcp", target)
+	latency := time.Since(start)
+
+	if dialErr != nil {
+		c.log.Debug(
+			"port check failed",
+			"target", target,
+			"error", dialErr.Error(),
+		)
+
+		return &PortResult{
+			Open:    false,
+			Error:   dialErr.Error(),
+			Latency: latency,
+		}
+	}
+
+	closeErr := conn.Close()
+	if closeErr != nil {
+		c.log.Debug(
+			"closing connection",
+			"target", target,
+			"error", closeErr.Error(),
+		)
+	}
+
+	c.log.Debug(
+		"port check succeeded",
+		"target", target,
+		"latency", latency,
+	)
+
+	return &PortResult{
+		Open:    true,
+		Latency: latency,
+	}
 }

internal/portcheck/portcheck_test.go

@@ -0,0 +1,211 @@
+package portcheck_test
+
+import (
+	"context"
+	"net"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/dnswatcher/internal/portcheck"
+)
+
+func listenTCP(
+	t *testing.T,
+) (net.Listener, int) {
+	t.Helper()
+
+	lc := &net.ListenConfig{}
+
+	ln, err := lc.Listen(
+		context.Background(), "tcp", "127.0.0.1:0",
+	)
+	if err != nil {
+		t.Fatalf("failed to start listener: %v", err)
+	}
+
+	addr, ok := ln.Addr().(*net.TCPAddr)
+	if !ok {
+		t.Fatal("unexpected address type")
+	}
+
+	return ln, addr.Port
+}
+
+func TestCheckPortOpen(t *testing.T) {
+	t.Parallel()
+
+	ln, port := listenTCP(t)
+
+	defer func() { _ = ln.Close() }()
+
+	checker := portcheck.NewStandalone()
+
+	result, err := checker.CheckPort(
+		context.Background(), "127.0.0.1", port,
+	)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if !result.Open {
+		t.Error("expected port to be open")
+	}
+
+	if result.Error != "" {
+		t.Errorf("expected no error, got: %s", result.Error)
+	}
+
+	if result.Latency <= 0 {
+		t.Error("expected positive latency")
+	}
+}
+
+func TestCheckPortClosed(t *testing.T) {
+	t.Parallel()
+
+	ln, port := listenTCP(t)
+	_ = ln.Close()
+
+	checker := portcheck.NewStandalone()
+
+	result, err := checker.CheckPort(
+		context.Background(), "127.0.0.1", port,
+	)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if result.Open {
+		t.Error("expected port to be closed")
+	}
+
+	if result.Error == "" {
+		t.Error("expected error message for closed port")
+	}
+}
+
+func TestCheckPortContextCanceled(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	checker := portcheck.NewStandalone()
+
+	result, err := checker.CheckPort(ctx, "127.0.0.1", 1)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if result.Open {
+		t.Error("expected port to not be open")
+	}
+}
+
+func TestCheckPortsMultiple(t *testing.T) {
+	t.Parallel()
+
+	ln, openPort := listenTCP(t)
+
+	defer func() { _ = ln.Close() }()
+
+	ln2, closedPort := listenTCP(t)
+	_ = ln2.Close()
+
+	checker := portcheck.NewStandalone()
+
+	results, err := checker.CheckPorts(
+		context.Background(),
+		"127.0.0.1",
+		[]int{openPort, closedPort},
+	)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if len(results) != 2 {
+		t.Fatalf(
+			"expected 2 results, got %d", len(results),
+		)
+	}
+
+	if !results[openPort].Open {
+		t.Error("expected open port to be open")
+	}
+
+	if results[closedPort].Open {
+		t.Error("expected closed port to be closed")
+	}
+}
+
+func TestCheckPortInvalidPorts(t *testing.T) {
+	t.Parallel()
+
+	checker := portcheck.NewStandalone()
+
+	cases := []struct {
+		name string
+		port int
+	}{
+		{"zero", 0},
+		{"negative", -1},
+		{"too high", 65536},
+		{"very negative", -1000},
+		{"very high", 100000},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			_, err := checker.CheckPort(
+				context.Background(), "127.0.0.1", tc.port,
+			)
+			if err == nil {
+				t.Errorf(
+					"expected error for port %d, got nil",
+					tc.port,
+				)
+			}
+		})
+	}
+}
+
+func TestCheckPortsInvalidPort(t *testing.T) {
+	t.Parallel()
+
+	checker := portcheck.NewStandalone()
+
+	_, err := checker.CheckPorts(
+		context.Background(),
+		"127.0.0.1",
+		[]int{80, 0, 443},
+	)
+	if err == nil {
+		t.Error("expected error for invalid port in list")
+	}
+}
+
+func TestCheckPortLatencyReasonable(t *testing.T) {
+	t.Parallel()
+
+	ln, port := listenTCP(t)
+
+	defer func() { _ = ln.Close() }()
+
+	checker := portcheck.NewStandalone()
+
+	result, err := checker.CheckPort(
+		context.Background(), "127.0.0.1", port,
+	)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if result.Latency > time.Second {
+		t.Errorf(
+			"latency too high for localhost: %v",
+			result.Latency,
+		)
+	}
+}

internal/resolver/dns_client.go

@@ -0,0 +1,48 @@
+package resolver
+
+import (
+	"context"
+	"time"
+
+	"github.com/miekg/dns"
+)
+
+// DNSClient abstracts DNS wire-protocol exchanges so the resolver
+// can be tested without hitting real nameservers.
+type DNSClient interface {
+	ExchangeContext(
+		ctx context.Context,
+		msg *dns.Msg,
+		addr string,
+	) (*dns.Msg, time.Duration, error)
+}
+
+// udpClient wraps a real dns.Client for production use.
+type udpClient struct {
+	timeout time.Duration
+}
+
+func (c *udpClient) ExchangeContext(
+	ctx context.Context,
+	msg *dns.Msg,
+	addr string,
+) (*dns.Msg, time.Duration, error) {
+	cl := &dns.Client{Timeout: c.timeout}
+
+	return cl.ExchangeContext(ctx, msg, addr)
+}
+
+// tcpClient wraps a real dns.Client using TCP.
+type tcpClient struct {
+	timeout time.Duration
+}
+
+func (c *tcpClient) ExchangeContext(
+	ctx context.Context,
+	msg *dns.Msg,
+	addr string,
+) (*dns.Msg, time.Duration, error) {
+	cl := &dns.Client{Net: "tcp", Timeout: c.timeout}
+
+	return cl.ExchangeContext(ctx, msg, addr)
+}

internal/resolver/errors.go

@@ -0,0 +1,22 @@
+package resolver
+
+import "errors"
+
+// Sentinel errors returned by the resolver.
+var (
+	// ErrNoNameservers is returned when no authoritative NS
+	// could be discovered for a domain.
+	ErrNoNameservers = errors.New(
+		"no authoritative nameservers found",
+	)
+
+	// ErrCNAMEDepthExceeded is returned when a CNAME chain
+	// exceeds MaxCNAMEDepth.
+	ErrCNAMEDepthExceeded = errors.New(
+		"CNAME chain depth exceeded",
+	)
+
+	// ErrContextCanceled wraps context cancellation for the
+	// resolver's iterative queries.
+	ErrContextCanceled = errors.New("context canceled")
+)

internal/resolver/iterative.go

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

internal/resolver/livedns_harness_test.go

@@ -0,0 +1,284 @@
+package resolver_test
+
+import (
+	"context"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+
+	"sneak.berlin/go/dnswatcher/internal/resolver"
+)
+
+// Tests for the live-DNS harness in livedns_test.go itself. These
+// exercise pure logic and the retry/concurrency plumbing; they
+// perform no DNS resolution of any kind, so they neither mock DNS
+// nor depend on it.
+
+// Names for the synthetic status maps below. Nothing is ever queried
+// at them: they are map keys handed to the package's pure counting
+// helpers, not a stand-in for a nameserver.
+const (
+	nsExample1 = "ns1.example."
+	nsExample2 = "ns2.example."
+	nsExample3 = "ns3.example."
+	nsExample4 = "ns4.example."
+)
+
+func TestLiveQuorumIsStrictMajority(t *testing.T) {
+	t.Parallel()
+
+	cases := map[int]int{
+		0:  1,
+		1:  1,
+		2:  2,
+		3:  2,
+		4:  3,
+		5:  3,
+		13: 7,
+	}
+
+	for total, want := range cases {
+		assert.Equal(
+			t, want, liveQuorum(total),
+			"liveQuorum(%d)", total,
+		)
+	}
+}
+
+func TestStatusCountingIgnoresSilentNameservers(t *testing.T) {
+	t.Parallel()
+
+	results := map[string]*resolver.NameserverResponse{
+		nsExample1: {
+			Nameserver: nsExample1,
+			Status:     resolver.StatusOK,
+		},
+		nsExample2: {
+			Nameserver: nsExample2,
+			Status:     resolver.StatusOK,
+		},
+		nsExample3: {
+			Nameserver: nsExample3,
+			Status:     resolver.StatusTimeout,
+		},
+		nsExample4: {
+			Nameserver: nsExample4,
+			Status:     resolver.StatusError,
+		},
+	}
+
+	assert.Equal(
+		t, 2, countStatus(results, resolver.StatusOK),
+	)
+	assert.Equal(
+		t, 0, countStatus(results, resolver.StatusNXDomain),
+	)
+
+	// Two of four answered, which is short of the quorum of
+	// three: this is the state that triggers a retry rather
+	// than an assertion failure.
+	assert.Equal(t, 2, answeredCount(results))
+	assert.Less(t, answeredCount(results), liveQuorum(len(results)))
+
+	assert.Equal(
+		t,
+		"ns1.example.=ok ns2.example.=ok "+
+			"ns3.example.=timeout ns4.example.=error",
+		describeStatuses(results),
+	)
+}
+
+func TestRetryLiveRecoversFromTransientFailure(t *testing.T) {
+	t.Parallel()
+
+	const wantAttempts = 2
+
+	attempts := 0
+
+	retryLive(t, "transient", func(_ context.Context) error {
+		attempts++
+
+		if attempts < wantAttempts {
+			return errLiveNoAnswer
+		}
+
+		return nil
+	})
+
+	assert.Equal(t, wantAttempts, attempts)
+}
+
+func TestRetryLiveGivesEachAttemptADeadline(t *testing.T) {
+	t.Parallel()
+
+	retryLive(t, "deadline", func(ctx context.Context) error {
+		deadline, ok := ctx.Deadline()
+		assert.True(t, ok, "attempt should carry a deadline")
+
+		remaining := time.Until(deadline)
+
+		assert.LessOrEqual(t, remaining, liveAttemptTimeout)
+
+		// Lower bound too: without one this passes for a
+		// deadline far shorter than intended, which would
+		// silently turn every live attempt into an instant
+		// timeout.
+		assert.Greater(t, remaining, liveAttemptTimeout/2)
+
+		return nil
+	})
+}
+
+// TestUnsanctionedStatusesRejectsWrongAnswers is the regression test
+// for the defect this allowlist exists to prevent: a minority of
+// nameservers answering WRONGLY while quorum keeps the suite green.
+// nodata is the case that motivated it — it is a wrong answer, not
+// silence, and it was previously banned by neither test.
+func TestUnsanctionedStatusesRejectsWrongAnswers(t *testing.T) {
+	t.Parallel()
+
+	// Four nameservers, three OK and one answering nodata: a
+	// quorum of three is satisfied and no NXDOMAIN is present, so
+	// the old blocklist assertions both passed on this input.
+	results := map[string]*resolver.NameserverResponse{
+		nsExample1: {
+			Nameserver: nsExample1,
+			Status:     resolver.StatusOK,
+		},
+		nsExample2: {
+			Nameserver: nsExample2,
+			Status:     resolver.StatusOK,
+		},
+		nsExample3: {
+			Nameserver: nsExample3,
+			Status:     resolver.StatusOK,
+		},
+		nsExample4: {
+			Nameserver: nsExample4,
+			Status:     resolver.StatusNoData,
+		},
+	}
+
+	assert.GreaterOrEqual(
+		t,
+		countStatus(results, resolver.StatusOK),
+		liveQuorum(len(results)),
+	)
+	assert.Zero(t, countStatus(results, resolver.StatusNXDomain))
+
+	// nodata is an ANSWER, so it never triggers a retry: nothing
+	// but the allowlist stands between it and a false green.
+	assert.Equal(t, len(results), answeredCount(results))
+
+	assert.Equal(
+		t,
+		[]string{nsExample4 + "=nodata"},
+		unsanctionedStatuses(
+			results,
+			resolver.StatusOK,
+			resolver.StatusTimeout,
+			resolver.StatusError,
+		),
+		"nodata must be reported as an unsanctioned status",
+	)
+}
+
+func TestUnsanctionedStatusesToleratesSilenceOnly(t *testing.T) {
+	t.Parallel()
+
+	results := map[string]*resolver.NameserverResponse{
+		nsExample1: {
+			Nameserver: nsExample1,
+			Status:     resolver.StatusNXDomain,
+		},
+		nsExample2: {
+			Nameserver: nsExample2,
+			Status:     resolver.StatusTimeout,
+		},
+		nsExample3: {
+			Nameserver: nsExample3,
+			Status:     resolver.StatusError,
+		},
+	}
+
+	allowed := []string{
+		resolver.StatusNXDomain,
+		resolver.StatusTimeout,
+		resolver.StatusError,
+	}
+
+	assert.Empty(
+		t,
+		unsanctionedStatuses(results, allowed...),
+		"timeout and error are non-answers and are tolerated",
+	)
+
+	// The same silent nameservers do not count towards a quorum.
+	assert.Equal(t, 1, answeredCount(results))
+
+	// An unknown status is treated as silence by answeredCount —
+	// so it retries and fails loudly — and is unsanctioned by the
+	// allowlist rather than quietly permitted.
+	const laterStatus = "some-status-added-later"
+
+	results[nsExample4] = &resolver.NameserverResponse{
+		Nameserver: nsExample4,
+		Status:     laterStatus,
+	}
+
+	assert.Equal(t, 1, answeredCount(results))
+	assert.Equal(
+		t,
+		[]string{nsExample4 + "=" + laterStatus},
+		unsanctionedStatuses(results, allowed...),
+	)
+}
+
+func TestRunLiveBoundsConcurrency(t *testing.T) {
+	t.Parallel()
+
+	const workers = 24
+
+	var (
+		mu       sync.Mutex
+		wg       sync.WaitGroup
+		inFlight int
+		maxSeen  int
+	)
+
+	wg.Add(workers)
+
+	for range workers {
+		go func() {
+			defer wg.Done()
+
+			_ = runLive(func(_ context.Context) error {
+				mu.Lock()
+				inFlight++
+
+				if inFlight > maxSeen {
+					maxSeen = inFlight
+				}
+				mu.Unlock()
+
+				time.Sleep(time.Millisecond)
+
+				mu.Lock()
+				inFlight--
+				mu.Unlock()
+
+				return nil
+			})
+		}()
+	}
+
+	wg.Wait()
+
+	assert.Positive(t, maxSeen)
+	assert.LessOrEqual(
+		t, maxSeen, liveConcurrency,
+		"live queries must stay under the package-wide gate",
+	)
+}

internal/resolver/livedns_test.go

@@ -0,0 +1,495 @@
+package resolver_test
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"slices"
+	"sort"
+	"strings"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/dnswatcher/internal/resolver"
+)
+
+// ----------------------------------------------------------------
+// Live DNS test support
+// ----------------------------------------------------------------
+//
+// Every test in this package resolves against the real, live DNS —
+// see TESTING.md. Nothing here mocks, fakes, stubs, records or
+// replays DNS, and nothing here skips or gates a test: the helpers
+// below only change *how* the live queries are issued, so that a
+// single dropped UDP packet or one slow authoritative server does
+// not turn a correct resolver into a red build.
+//
+// Three mechanisms, all test-side:
+//
+//  1. Bounded concurrency. The package's tests are 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 first root server in rootServerList() within
+//     a few milliseconds of each other. Root servers rate-limit
+//     that, which shows up as a different arbitrary subset of tests
+//     failing on each run. liveGate caps how many resolutions are
+//     in flight at once.
+//
+//  2. Retry with exponential backoff. Each live operation gets
+//     several attempts with its own timeout. The retry predicate is
+//     strictly transport-level — "did a nameserver answer at all" —
+//     never the assertion the test is making. A resolver that
+//     answers incorrectly still fails on the first attempt.
+//
+//  3. Quorum. Where an assertion spans several independent
+//     nameservers, a strict majority answering as expected is
+//     enough; a server that fails to answer is tolerated, while a
+//     server that answers *wrongly* still fails the test.
+//
+// The tolerance in (3) is expressed as an ALLOWLIST of sanctioned
+// statuses, never as a blocklist of known-bad ones. A blocklist bans
+// the one wrong answer its author thought of and silently admits
+// every other status, including any added to the resolver later; an
+// allowlist fails on anything nobody explicitly sanctioned. Silence
+// (timeout, error) is the only thing quorum exists to tolerate. A
+// *wrong answer* — nxdomain for a name that exists, ok for one that
+// does not, nodata for either — is never tolerated at any count.
+
+const (
+	// liveAttempts is how many times a live DNS operation is
+	// attempted before the test fails.
+	liveAttempts = 3
+
+	// liveAttemptTimeout bounds one attempt. Worst case for an
+	// operation is liveAttempts * liveAttemptTimeout plus the
+	// backoff — about 26 seconds, well inside the 90-second
+	// `go test -timeout` backstop even when several operations
+	// exhaust their attempts.
+	liveAttemptTimeout = 8 * time.Second
+
+	// liveBackoffBase is the delay after the first failed
+	// attempt; it is multiplied by liveBackoffFactor each time.
+	liveBackoffBase = 500 * time.Millisecond
+
+	// liveBackoffFactor is the exponential backoff multiplier.
+	liveBackoffFactor = 2
+
+	// liveConcurrency caps how many live resolutions may be in
+	// flight across the whole package at once.
+	liveConcurrency = 6
+
+	// minNameservers is the smallest nameserver count a
+	// well-run zone is expected to publish.
+	minNameservers = 2
+)
+
+// liveGate bounds concurrent live resolutions package-wide. It has
+// to be package scoped: the whole point is that it is shared by
+// every parallel test in the package.
+//
+//nolint:gochecknoglobals // package-wide live query rate limit
+var liveGate = make(chan struct{}, liveConcurrency)
+
+var (
+	// errLiveNoAnswer reports that a live operation produced no
+	// usable answer, which is retried rather than asserted on.
+	errLiveNoAnswer = errors.New("no answer from live DNS")
+
+	// errLiveNoQuorum reports that too few of a domain's
+	// nameservers answered for a quorum assertion to be made.
+	errLiveNoQuorum = errors.New("no nameserver quorum")
+)
+
+// runLive executes one attempt of a live operation, holding a slot
+// in liveGate for its duration and bounding it with its own
+// timeout.
+func runLive(op func(ctx context.Context) error) error {
+	liveGate <- struct{}{}
+	defer func() { <-liveGate }()
+
+	ctx, cancel := context.WithTimeout(
+		context.Background(), liveAttemptTimeout,
+	)
+	defer cancel()
+
+	return op(ctx)
+}
+
+// retryLive runs op until it reports success, retrying transport
+// failures with exponential backoff, and fails the test if every
+// attempt fails. op returns an error only for a failure to obtain
+// an answer — never for an answer the test disagrees with, which
+// belongs in an assertion so that it fails immediately. op stores
+// whatever it obtained where its caller can find it.
+func retryLive(
+	t *testing.T,
+	what string,
+	op func(ctx context.Context) error,
+) {
+	t.Helper()
+
+	var last error
+
+	backoff := liveBackoffBase
+
+	for attempt := range liveAttempts {
+		if attempt > 0 {
+			t.Logf(
+				"%s: attempt %d of %d failed (%v), "+
+					"retrying in %s",
+				what, attempt, liveAttempts, last, backoff,
+			)
+			time.Sleep(backoff)
+
+			backoff *= liveBackoffFactor
+		}
+
+		last = runLive(op)
+		if last == nil {
+			return
+		}
+	}
+
+	t.Fatalf(
+		"%s: no answer after %d live attempts: %v",
+		what, liveAttempts, last,
+	)
+}
+
+// liveQuorum is how many of total nameservers must agree for a
+// multi-nameserver assertion to hold: a strict majority.
+func liveQuorum(total int) int {
+	if total < 1 {
+		return 1
+	}
+
+	return total/2 + 1
+}
+
+// countStatus counts the responses carrying the given status.
+func countStatus(
+	results map[string]*resolver.NameserverResponse,
+	status string,
+) int {
+	n := 0
+
+	for _, resp := range results {
+		if resp.Status == status {
+			n++
+		}
+	}
+
+	return n
+}
+
+// liveAnswerStatuses is the closed set of statuses that count as a
+// nameserver having ANSWERED at all, whether or not the test agrees
+// with the answer. It is deliberately an allowlist: a status added
+// to the resolver later is treated as silence, so it can only ever
+// cause a retry and then a loud failure, never a quiet pass.
+func liveAnswerStatuses() []string {
+	return []string{
+		resolver.StatusOK,
+		resolver.StatusNXDomain,
+		resolver.StatusNoData,
+	}
+}
+
+// answeredCount counts the nameservers that produced an answer of
+// any kind, as opposed to failing or timing out.
+func answeredCount(
+	results map[string]*resolver.NameserverResponse,
+) int {
+	answers := liveAnswerStatuses()
+
+	n := 0
+
+	for _, resp := range results {
+		if slices.Contains(answers, resp.Status) {
+			n++
+		}
+	}
+
+	return n
+}
+
+// unsanctionedStatuses returns "nameserver=status" for every result
+// whose status the caller did not explicitly sanction, sorted for a
+// stable failure message. Callers pass the full closed set they will
+// accept — the expected answer plus whichever non-answers (timeout,
+// error) quorum is allowed to tolerate — so that any status outside
+// it fails the test by name.
+func unsanctionedStatuses(
+	results map[string]*resolver.NameserverResponse,
+	allowed ...string,
+) []string {
+	offenders := make([]string, 0, len(results))
+
+	for ns, resp := range results {
+		if slices.Contains(allowed, resp.Status) {
+			continue
+		}
+
+		offenders = append(
+			offenders, fmt.Sprintf("%s=%s", ns, resp.Status),
+		)
+	}
+
+	sort.Strings(offenders)
+
+	return offenders
+}
+
+// describeStatuses renders per-nameserver statuses for use in
+// assertion failure messages.
+func describeStatuses(
+	results map[string]*resolver.NameserverResponse,
+) string {
+	parts := make([]string, 0, len(results))
+	for ns, resp := range results {
+		parts = append(
+			parts, fmt.Sprintf("%s=%s", ns, resp.Status),
+		)
+	}
+
+	sort.Strings(parts)
+
+	return strings.Join(parts, " ")
+}
+
+// ----------------------------------------------------------------
+// Live operation wrappers
+// ----------------------------------------------------------------
+
+// liveFindAuthoritative resolves a domain's authoritative
+// nameservers, retrying until the delegation chain can be walked.
+func liveFindAuthoritative(
+	t *testing.T,
+	r *resolver.Resolver,
+	domain string,
+) []string {
+	t.Helper()
+
+	var out []string
+
+	retryLive(
+		t,
+		"FindAuthoritativeNameservers("+domain+")",
+		func(ctx context.Context) error {
+			ns, err := r.FindAuthoritativeNameservers(ctx, domain)
+			if err != nil {
+				return err
+			}
+
+			if len(ns) == 0 {
+				return fmt.Errorf(
+					"%w: %s has no nameservers",
+					errLiveNoAnswer, domain,
+				)
+			}
+
+			out = ns
+
+			return nil
+		},
+	)
+
+	return out
+}
+
+// liveLookupNS is liveFindAuthoritative through the LookupNS entry
+// point, so that both entry points stay independently exercised.
+func liveLookupNS(
+	t *testing.T,
+	r *resolver.Resolver,
+	domain string,
+) []string {
+	t.Helper()
+
+	var out []string
+
+	retryLive(
+		t,
+		"LookupNS("+domain+")",
+		func(ctx context.Context) error {
+			ns, err := r.LookupNS(ctx, domain)
+			if err != nil {
+				return err
+			}
+
+			if len(ns) == 0 {
+				return fmt.Errorf(
+					"%w: %s has no nameservers",
+					errLiveNoAnswer, domain,
+				)
+			}
+
+			out = ns
+
+			return nil
+		},
+	)
+
+	return out
+}
+
+// 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.
+func liveQueryNameserver(
+	t *testing.T,
+	r *resolver.Resolver,
+	nameserver string,
+	hostname string,
+) *resolver.NameserverResponse {
+	t.Helper()
+
+	what := fmt.Sprintf(
+		"QueryNameserver(%s, %s)", nameserver, hostname,
+	)
+
+	var out *resolver.NameserverResponse
+
+	retryLive(
+		t,
+		what,
+		func(ctx context.Context) error {
+			resp, err := r.QueryNameserver(
+				ctx, nameserver, hostname,
+			)
+			if err != nil {
+				return err
+			}
+
+			if resp.Status == resolver.StatusTimeout ||
+				resp.Status == resolver.StatusError {
+				return fmt.Errorf(
+					"%w: %s returned %s: %s",
+					errLiveNoAnswer, nameserver,
+					resp.Status, resp.Error,
+				)
+			}
+
+			out = resp
+
+			return nil
+		},
+	)
+
+	return out
+}
+
+// liveQueryAllNameservers queries every authoritative nameserver
+// for a hostname, retrying until a quorum of them has answered.
+// Individual nameservers that stay silent are left in the result
+// for the caller to account for.
+func liveQueryAllNameservers(
+	t *testing.T,
+	r *resolver.Resolver,
+	hostname string,
+) map[string]*resolver.NameserverResponse {
+	t.Helper()
+
+	var out map[string]*resolver.NameserverResponse
+
+	retryLive(
+		t,
+		"QueryAllNameservers("+hostname+")",
+		func(ctx context.Context) error {
+			results, err := r.QueryAllNameservers(ctx, hostname)
+			if err != nil {
+				return err
+			}
+
+			if len(results) == 0 {
+				return fmt.Errorf(
+					"%w: no nameservers queried for %s",
+					errLiveNoAnswer, hostname,
+				)
+			}
+
+			answered := answeredCount(results)
+			if answered < liveQuorum(len(results)) {
+				return fmt.Errorf(
+					"%w: %d of %d answered: %s",
+					errLiveNoQuorum, answered,
+					len(results), describeStatuses(results),
+				)
+			}
+
+			out = results
+
+			return nil
+		},
+	)
+
+	return out
+}
+
+// liveResolveIPs resolves a hostname that is expected to have
+// addresses, retrying until at least one is returned.
+func liveResolveIPs(
+	t *testing.T,
+	r *resolver.Resolver,
+	hostname string,
+) []string {
+	t.Helper()
+
+	var out []string
+
+	retryLive(
+		t,
+		"ResolveIPAddresses("+hostname+")",
+		func(ctx context.Context) error {
+			ips, err := r.ResolveIPAddresses(ctx, hostname)
+			if err != nil {
+				return err
+			}
+
+			if len(ips) == 0 {
+				return fmt.Errorf(
+					"%w: no addresses for %s",
+					errLiveNoAnswer, hostname,
+				)
+			}
+
+			out = ips
+
+			return nil
+		},
+	)
+
+	return out
+}
+
+// liveResolveIPsAllowingEmpty resolves a hostname that may legitimately
+// have no addresses, so the empty result is returned rather than
+// retried. Used for names that must not exist; the corresponding
+// QueryAllNameservers test is what proves the nameservers actively
+// said NXDOMAIN rather than merely staying silent.
+func liveResolveIPsAllowingEmpty(
+	t *testing.T,
+	r *resolver.Resolver,
+	hostname string,
+) []string {
+	t.Helper()
+
+	var out []string
+
+	retryLive(
+		t,
+		"ResolveIPAddresses("+hostname+")",
+		func(ctx context.Context) error {
+			ips, err := r.ResolveIPAddresses(ctx, hostname)
+			if err != nil {
+				return err
+			}
+
+			out = ips
+
+			return nil
+		},
+	)
+
+	return out
+}

internal/resolver/resolver.go

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

internal/resolver/resolver_test.go

@@ -0,0 +1,584 @@
+package resolver_test
+
+import (
+	"context"
+	"log/slog"
+	"net"
+	"os"
+	"sort"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/miekg/dns"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"sneak.berlin/go/dnswatcher/internal/resolver"
+)
+
+// ----------------------------------------------------------------
+// Test helpers
+// ----------------------------------------------------------------
+
+func newTestResolver(t *testing.T) *resolver.Resolver {
+	t.Helper()
+
+	log := slog.New(slog.NewTextHandler(
+		os.Stderr,
+		&slog.HandlerOptions{Level: slog.LevelDebug},
+	))
+
+	return resolver.NewFromLogger(log)
+}
+
+// findOneNSForDomain picks one authoritative nameserver to aim a
+// test at. Live-DNS retry, concurrency and quorum handling live in
+// livedns_test.go.
+func findOneNSForDomain(
+	t *testing.T,
+	r *resolver.Resolver,
+	domain string,
+) string {
+	t.Helper()
+
+	return liveFindAuthoritative(t, r, domain)[0]
+}
+
+// ----------------------------------------------------------------
+// FindAuthoritativeNameservers tests
+// ----------------------------------------------------------------
+
+func TestFindAuthoritativeNameservers_ValidDomain(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	nameservers := liveFindAuthoritative(t, r, "google.com")
+
+	hasGoogleNS := false
+
+	for _, ns := range nameservers {
+		if strings.Contains(ns, "google") {
+			hasGoogleNS = true
+
+			break
+		}
+	}
+
+	assert.True(t, hasGoogleNS,
+		"expected google nameservers, got: %v", nameservers,
+	)
+}
+
+func TestFindAuthoritativeNameservers_Subdomain(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	nameservers := liveFindAuthoritative(t, r, "www.google.com")
+
+	assert.NotEmpty(t, nameservers)
+}
+
+func TestFindAuthoritativeNameservers_ReturnsSorted(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	nameservers := liveFindAuthoritative(t, r, "google.com")
+
+	assert.True(
+		t,
+		sort.StringsAreSorted(nameservers),
+		"nameservers should be sorted, got: %v", nameservers,
+	)
+}
+
+func TestFindAuthoritativeNameservers_Deterministic(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	first := liveFindAuthoritative(t, r, "google.com")
+	second := liveFindAuthoritative(t, r, "google.com")
+
+	assert.Equal(t, first, second)
+}
+
+func TestFindAuthoritativeNameservers_TrailingDot(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ns1 := liveFindAuthoritative(t, r, "google.com")
+	ns2 := liveFindAuthoritative(t, r, "google.com.")
+
+	assert.Equal(t, ns1, ns2)
+}
+
+func TestFindAuthoritativeNameservers_CloudflareDomain(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	nameservers := liveFindAuthoritative(t, r, "cloudflare.com")
+
+	for _, ns := range nameservers {
+		assert.True(t, strings.HasSuffix(ns, "."),
+			"NS should be FQDN with trailing dot: %s", ns,
+		)
+	}
+}
+
+// ----------------------------------------------------------------
+// QueryNameserver tests
+// ----------------------------------------------------------------
+
+func TestQueryNameserver_BasicA(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ns := findOneNSForDomain(t, r, "google.com")
+	resp := liveQueryNameserver(t, r, ns, "www.google.com")
+
+	require.NotNil(t, resp)
+
+	assert.Equal(t, resolver.StatusOK, resp.Status)
+	assert.Equal(t, ns, resp.Nameserver)
+
+	hasRecords := len(resp.Records["A"]) > 0 ||
+		len(resp.Records["CNAME"]) > 0
+	assert.True(t, hasRecords,
+		"expected A or CNAME records for www.google.com",
+	)
+}
+
+func TestQueryNameserver_AAAA(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ns := findOneNSForDomain(t, r, "cloudflare.com")
+	resp := liveQueryNameserver(t, r, ns, "cloudflare.com")
+
+	aaaaRecords := resp.Records["AAAA"]
+	require.NotEmpty(t, aaaaRecords,
+		"cloudflare.com should have AAAA records",
+	)
+
+	for _, ip := range aaaaRecords {
+		parsed := net.ParseIP(ip)
+		require.NotNil(t, parsed,
+			"should be valid IP: %s", ip,
+		)
+	}
+}
+
+func TestQueryNameserver_MX(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ns := findOneNSForDomain(t, r, "google.com")
+	resp := liveQueryNameserver(t, r, ns, "google.com")
+
+	mxRecords := resp.Records["MX"]
+	require.NotEmpty(t, mxRecords,
+		"google.com should have MX records",
+	)
+}
+
+func TestQueryNameserver_TXT(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ns := findOneNSForDomain(t, r, "google.com")
+	resp := liveQueryNameserver(t, r, ns, "google.com")
+
+	txtRecords := resp.Records["TXT"]
+	require.NotEmpty(t, txtRecords,
+		"google.com should have TXT records",
+	)
+
+	hasSPF := false
+
+	for _, txt := range txtRecords {
+		if strings.Contains(txt, "v=spf1") {
+			hasSPF = true
+
+			break
+		}
+	}
+
+	assert.True(t, hasSPF,
+		"google.com should have SPF TXT record",
+	)
+}
+
+func TestQueryNameserver_NXDomain(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ns := findOneNSForDomain(t, r, "google.com")
+	resp := liveQueryNameserver(
+		t, r, ns, "this-surely-does-not-exist-xyz.google.com",
+	)
+
+	assert.Equal(t, resolver.StatusNXDomain, resp.Status)
+}
+
+func TestQueryNameserver_RecordsSorted(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ns := findOneNSForDomain(t, r, "google.com")
+	resp := liveQueryNameserver(t, r, ns, "google.com")
+
+	for recordType, values := range resp.Records {
+		assert.True(
+			t,
+			sort.StringsAreSorted(values),
+			"%s records should be sorted", recordType,
+		)
+	}
+}
+
+func TestQueryNameserver_ResponseIncludesNameserver(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ns := findOneNSForDomain(t, r, "cloudflare.com")
+	resp := liveQueryNameserver(t, r, ns, "cloudflare.com")
+
+	assert.Equal(t, ns, resp.Nameserver)
+}
+
+func TestQueryNameserver_EmptyRecordsOnNXDomain(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ns := findOneNSForDomain(t, r, "google.com")
+	resp := liveQueryNameserver(
+		t, r, ns, "this-surely-does-not-exist-xyz.google.com",
+	)
+
+	totalRecords := 0
+	for _, values := range resp.Records {
+		totalRecords += len(values)
+	}
+
+	assert.Zero(t, totalRecords)
+}
+
+func TestQueryNameserver_TrailingDotHandling(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ns := findOneNSForDomain(t, r, "google.com")
+	resp1 := liveQueryNameserver(t, r, ns, "google.com")
+	resp2 := liveQueryNameserver(t, r, ns, "google.com.")
+
+	assert.Equal(t, resp1.Status, resp2.Status)
+}
+
+// ----------------------------------------------------------------
+// QueryAllNameservers tests
+// ----------------------------------------------------------------
+
+func TestQueryAllNameservers_ReturnsAllNS(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	results := liveQueryAllNameservers(t, r, "google.com")
+
+	assert.GreaterOrEqual(t, len(results), minNameservers)
+
+	for ns, resp := range results {
+		assert.Equal(t, ns, resp.Nameserver)
+	}
+}
+
+func TestQueryAllNameservers_AllReturnOK(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	results := liveQueryAllNameservers(t, r, "google.com")
+
+	// A quorum, not unanimity: one authoritative server being
+	// slow or rate-limiting us is a property of the live
+	// internet, not a resolver defect.
+	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
+	// 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(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	results := liveQueryAllNameservers(
+		t, r, "this-surely-does-not-exist-xyz.google.com",
+	)
+
+	assert.GreaterOrEqual(
+		t,
+		countStatus(results, resolver.StatusNXDomain),
+		liveQuorum(len(results)),
+		"a quorum of nameservers should report NXDOMAIN: %s",
+		describeStatuses(results),
+	)
+
+	// Silence is tolerated; any actual answer other than NXDOMAIN
+	// is not. Closed allowlist for the same reason as above: a
+	// server answering `ok` or `nodata` for a name that must not
+	// exist is a wrong answer, not a slow one.
+	assert.Empty(
+		t,
+		unsanctionedStatuses(
+			results,
+			resolver.StatusNXDomain,
+			resolver.StatusTimeout,
+			resolver.StatusError,
+		),
+		"every nameserver must report NXDOMAIN or not answer "+
+			"at all: %s",
+		describeStatuses(results),
+	)
+}
+
+// ----------------------------------------------------------------
+// LookupNS tests
+// ----------------------------------------------------------------
+
+func TestLookupNS_ValidDomain(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	nameservers := liveLookupNS(t, r, "google.com")
+
+	for _, ns := range nameservers {
+		assert.True(t, strings.HasSuffix(ns, "."),
+			"NS should have trailing dot: %s", ns,
+		)
+	}
+}
+
+func TestLookupNS_Sorted(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	nameservers := liveLookupNS(t, r, "google.com")
+
+	assert.True(t, sort.StringsAreSorted(nameservers))
+}
+
+func TestLookupNS_MatchesFindAuthoritative(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	fromLookup := liveLookupNS(t, r, "google.com")
+	fromFind := liveFindAuthoritative(t, r, "google.com")
+
+	assert.Equal(t, fromFind, fromLookup)
+}
+
+// ----------------------------------------------------------------
+// ResolveIPAddresses tests
+// ----------------------------------------------------------------
+
+func TestResolveIPAddresses_ReturnsIPs(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ips := liveResolveIPs(t, r, "google.com")
+
+	for _, ip := range ips {
+		parsed := net.ParseIP(ip)
+		assert.NotNil(t, parsed,
+			"should be valid IP: %s", ip,
+		)
+	}
+}
+
+func TestResolveIPAddresses_Deduplicated(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ips := liveResolveIPs(t, r, "google.com")
+
+	seen := make(map[string]bool)
+
+	for _, ip := range ips {
+		assert.False(t, seen[ip], "duplicate IP: %s", ip)
+		seen[ip] = true
+	}
+}
+
+func TestResolveIPAddresses_Sorted(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ips := liveResolveIPs(t, r, "google.com")
+
+	assert.True(t, sort.StringsAreSorted(ips))
+}
+
+func TestResolveIPAddresses_NXDomainReturnsEmpty(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ips := liveResolveIPsAllowingEmpty(
+		t, r, "this-surely-does-not-exist-xyz.google.com",
+	)
+
+	assert.Empty(t, ips)
+}
+
+func TestResolveIPAddresses_CloudflareDomain(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ips := liveResolveIPs(t, r, "cloudflare.com")
+
+	assert.NotEmpty(t, ips)
+}
+
+// ----------------------------------------------------------------
+// Context cancellation tests
+// ----------------------------------------------------------------
+
+func TestFindAuthoritativeNameservers_ContextCanceled(
+	t *testing.T,
+) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, err := r.FindAuthoritativeNameservers(ctx, "google.com")
+	assert.Error(t, err)
+}
+
+func TestQueryNameserver_ContextCanceled(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, err := r.QueryNameserver(
+		ctx, "ns1.google.com.", "google.com",
+	)
+	assert.Error(t, err)
+}
+
+func TestQueryAllNameservers_ContextCanceled(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, err := r.QueryAllNameservers(ctx, "google.com")
+	assert.Error(t, err)
+}
+
+// ----------------------------------------------------------------
+// Timeout tests
+// ----------------------------------------------------------------
+
+func TestQueryNameserverIP_Timeout(t *testing.T) {
+	t.Parallel()
+
+	log := slog.New(slog.NewTextHandler(
+		os.Stderr,
+		&slog.HandlerOptions{Level: slog.LevelDebug},
+	))
+
+	r := resolver.NewFromLoggerWithClient(
+		log, &timeoutClient{},
+	)
+
+	ctx, cancel := context.WithTimeout(
+		context.Background(), 10*time.Second,
+	)
+	t.Cleanup(cancel)
+
+	// Query any IP — the client always returns a timeout error.
+	resp, err := r.QueryNameserverIP(
+		ctx, "unreachable.test.", "192.0.2.1",
+		"example.com",
+	)
+	require.NoError(t, err)
+
+	assert.Equal(t, resolver.StatusTimeout, resp.Status)
+	assert.NotEmpty(t, resp.Error)
+}
+
+// timeoutClient simulates DNS timeout errors for testing.
+type timeoutClient struct{}
+
+func (c *timeoutClient) ExchangeContext(
+	_ context.Context,
+	_ *dns.Msg,
+	_ string,
+) (*dns.Msg, time.Duration, error) {
+	return nil, 0, &net.OpError{
+		Op:  "read",
+		Net: "udp",
+		Err: &timeoutError{},
+	}
+}
+
+type timeoutError struct{}
+
+func (e *timeoutError) Error() string   { return "i/o timeout" }
+func (e *timeoutError) Timeout() bool   { return true }
+func (e *timeoutError) Temporary() bool { return true }
+
+func TestResolveIPAddresses_ContextCanceled(t *testing.T) {
+	t.Parallel()
+
+	r := newTestResolver(t)
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, err := r.ResolveIPAddresses(ctx, "google.com")
+	assert.Error(t, err)
+}

internal/server/routes.go

@@ -1,11 +1,14 @@
 package server
 
 import (
+	"net/http"
 	"time"
 
 	"github.com/go-chi/chi/v5"
 	chimw "github.com/go-chi/chi/v5/middleware"
 	"github.com/prometheus/client_golang/prometheus/promhttp"
+
+	"sneak.berlin/go/dnswatcher/static"
 )
 
 // requestTimeout is the maximum duration for handling a request.
@@ -22,7 +25,25 @@ func (s *Server) SetupRoutes() {
 	s.router.Use(s.mw.CORS())
 	s.router.Use(chimw.Timeout(requestTimeout))
 
-	// Health check
+	// Dashboard (read-only web UI)
+	s.router.Get("/", s.handlers.HandleDashboard())
+
+	// Static assets (embedded CSS/JS)
+	s.router.Mount(
+		"/s",
+		http.StripPrefix(
+			"/s",
+			http.FileServer(http.FS(static.Static)),
+		),
+	)
+
+	// Health check (standard well-known path)
+	s.router.Get(
+		"/.well-known/healthcheck",
+		s.handlers.HandleHealthCheck(),
+	)
+
+	// Legacy health check (keep for backward compatibility)
 	s.router.Get("/health", s.handlers.HandleHealthCheck())
 
 	// API v1 routes

internal/state/state.go

@@ -57,10 +57,49 @@ type HostnameState struct {
 // PortState holds the monitoring state for a port.
 type PortState struct {
 	Open        bool      `json:"open"`
-	Hostname    string    `json:"hostname"`
+	Hostnames   []string  `json:"hostnames"`
 	LastChecked time.Time `json:"lastChecked"`
 }
 
+// UnmarshalJSON implements custom unmarshaling to handle both
+// the old single-hostname format and the new multi-hostname
+// format for backward compatibility with existing state files.
+func (ps *PortState) UnmarshalJSON(data []byte) error {
+	// Use an alias to prevent infinite recursion.
+	type portStateAlias struct {
+		Open        bool      `json:"open"`
+		Hostnames   []string  `json:"hostnames"`
+		LastChecked time.Time `json:"lastChecked"`
+	}
+
+	var alias portStateAlias
+
+	err := json.Unmarshal(data, &alias)
+	if err != nil {
+		return fmt.Errorf("unmarshaling port state: %w", err)
+	}
+
+	ps.Open = alias.Open
+	ps.Hostnames = alias.Hostnames
+	ps.LastChecked = alias.LastChecked
+
+	// If Hostnames is empty, try reading the old single-hostname
+	// format for backward compatibility.
+	if len(ps.Hostnames) == 0 {
+		var old struct {
+			Hostname string `json:"hostname"`
+		}
+
+		// Best-effort: ignore errors since the main unmarshal
+		// already succeeded.
+		if json.Unmarshal(data, &old) == nil && old.Hostname != "" {
+			ps.Hostnames = []string{old.Hostname}
+		}
+	}
+
+	return nil
+}
+
 // CertificateState holds TLS certificate monitoring state.
 type CertificateState struct {
 	CommonName              string    `json:"commonName"`
@@ -156,8 +195,8 @@ func (s *State) Load() error {
 
 // Save writes the current state to disk atomically.
 func (s *State) Save() error {
-	s.mu.RLock()
-	defer s.mu.RUnlock()
+	s.mu.Lock()
+	defer s.mu.Unlock()
 
 	s.snapshot.LastUpdated = time.Now().UTC()
 
@@ -263,6 +302,27 @@ func (s *State) GetPortState(key string) (*PortState, bool) {
 	return ps, ok
 }
 
+// DeletePortState removes a port state entry.
+func (s *State) DeletePortState(key string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	delete(s.snapshot.Ports, key)
+}
+
+// GetAllPortKeys returns all port state keys.
+func (s *State) GetAllPortKeys() []string {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	keys := make([]string, 0, len(s.snapshot.Ports))
+	for k := range s.snapshot.Ports {
+		keys = append(keys, k)
+	}
+
+	return keys
+}
+
 // SetCertificateState updates the state for a certificate.
 func (s *State) SetCertificateState(
 	key string,

internal/state/state_test_helper.go

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

internal/tlscheck/extractcertinfo_test.go

@@ -0,0 +1,67 @@
+package tlscheck_test
+
+import (
+	"context"
+	"crypto/tls"
+	"errors"
+	"net"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/dnswatcher/internal/tlscheck"
+)
+
+func TestCheckCertificateNoPeerCerts(t *testing.T) {
+	t.Parallel()
+
+	lc := &net.ListenConfig{}
+
+	ln, err := lc.Listen(
+		context.Background(), "tcp", "127.0.0.1:0",
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	defer func() { _ = ln.Close() }()
+
+	addr, ok := ln.Addr().(*net.TCPAddr)
+	if !ok {
+		t.Fatal("unexpected address type")
+	}
+
+	// Accept and immediately close to cause TLS handshake failure.
+	go func() {
+		conn, err := ln.Accept()
+		if err != nil {
+			return
+		}
+
+		_ = conn.Close()
+	}()
+
+	checker := tlscheck.NewStandalone(
+		tlscheck.WithTimeout(2*time.Second),
+		tlscheck.WithTLSConfig(&tls.Config{
+			InsecureSkipVerify: true, //nolint:gosec // test
+			MinVersion:         tls.VersionTLS12,
+		}),
+		tlscheck.WithPort(addr.Port),
+	)
+
+	_, err = checker.CheckCertificate(
+		context.Background(), "127.0.0.1", "localhost",
+	)
+	if err == nil {
+		t.Fatal("expected error when server presents no certs")
+	}
+}
+
+func TestErrNoPeerCertificatesIsSentinel(t *testing.T) {
+	t.Parallel()
+
+	err := tlscheck.ErrNoPeerCertificates
+	if !errors.Is(err, tlscheck.ErrNoPeerCertificates) {
+		t.Fatal("expected sentinel error to match")
+	}
+}

internal/tlscheck/tlscheck.go

@@ -3,8 +3,12 @@ package tlscheck
 
 import (
 	"context"
+	"crypto/tls"
 	"errors"
+	"fmt"
 	"log/slog"
+	"net"
+	"strconv"
 	"time"
 
 	"go.uber.org/fx"
@@ -12,11 +16,56 @@ import (
 	"sneak.berlin/go/dnswatcher/internal/logger"
 )
 
-// ErrNotImplemented indicates the TLS checker is not yet implemented.
-var ErrNotImplemented = errors.New(
-	"tls checker not yet implemented",
+const (
+	defaultTimeout = 10 * time.Second
+	defaultPort    = 443
 )
 
+// ErrUnexpectedConnType indicates the connection was not a TLS
+// connection.
+var ErrUnexpectedConnType = errors.New(
+	"unexpected connection type",
+)
+
+// ErrNoPeerCertificates indicates the TLS connection had no peer
+// certificates.
+var ErrNoPeerCertificates = errors.New(
+	"no peer certificates",
+)
+
+// CertificateInfo holds information about a TLS certificate.
+type CertificateInfo struct {
+	CommonName              string
+	Issuer                  string
+	NotAfter                time.Time
+	SubjectAlternativeNames []string
+	SerialNumber            string
+}
+
+// Option configures a Checker.
+type Option func(*Checker)
+
+// WithTimeout sets the connection timeout.
+func WithTimeout(d time.Duration) Option {
+	return func(c *Checker) {
+		c.timeout = d
+	}
+}
+
+// WithTLSConfig sets a custom TLS configuration.
+func WithTLSConfig(cfg *tls.Config) Option {
+	return func(c *Checker) {
+		c.tlsConfig = cfg
+	}
+}
+
+// WithPort sets the TLS port to connect to.
+func WithPort(port int) Option {
+	return func(c *Checker) {
+		c.port = port
+	}
+}
+
 // Params contains dependencies for Checker.
 type Params struct {
 	fx.In
@@ -27,14 +76,9 @@ type Params struct {
 // Checker performs TLS certificate inspection.
 type Checker struct {
 	log       *slog.Logger
-}
-
-// CertificateInfo holds information about a TLS certificate.
-type CertificateInfo struct {
-	CommonName              string
-	Issuer                  string
-	NotAfter                time.Time
-	SubjectAlternativeNames []string
+	timeout   time.Duration
+	tlsConfig *tls.Config
+	port      int
 }
 
 // New creates a new TLS Checker instance.
@@ -44,15 +88,109 @@ func New(
 ) (*Checker, error) {
 	return &Checker{
 		log:     params.Logger.Get(),
+		timeout: defaultTimeout,
+		port:    defaultPort,
 	}, nil
 }
 
-// CheckCertificate connects to the given IP:port using SNI and
-// returns certificate information.
+// NewStandalone creates a Checker without fx dependencies.
+func NewStandalone(opts ...Option) *Checker {
+	checker := &Checker{
+		log:     slog.Default(),
+		timeout: defaultTimeout,
+		port:    defaultPort,
+	}
+
+	for _, opt := range opts {
+		opt(checker)
+	}
+
+	return checker
+}
+
+// CheckCertificate connects to the given IP address using the
+// specified SNI hostname and returns certificate information.
 func (c *Checker) CheckCertificate(
-	_ context.Context,
-	_ string,
-	_ string,
+	ctx context.Context,
+	ipAddress string,
+	sniHostname string,
 ) (*CertificateInfo, error) {
-	return nil, ErrNotImplemented
+	target := net.JoinHostPort(
+		ipAddress, strconv.Itoa(c.port),
+	)
+
+	tlsCfg := c.buildTLSConfig(sniHostname)
+	dialer := &tls.Dialer{
+		NetDialer: &net.Dialer{Timeout: c.timeout},
+		Config:    tlsCfg,
+	}
+
+	conn, err := dialer.DialContext(ctx, "tcp", target)
+	if err != nil {
+		return nil, fmt.Errorf(
+			"TLS dial to %s: %w", target, err,
+		)
+	}
+
+	defer func() {
+		closeErr := conn.Close()
+		if closeErr != nil {
+			c.log.Debug(
+				"closing TLS connection",
+				"target", target,
+				"error", closeErr.Error(),
+			)
+		}
+	}()
+
+	tlsConn, ok := conn.(*tls.Conn)
+	if !ok {
+		return nil, fmt.Errorf(
+			"%s: %w", target, ErrUnexpectedConnType,
+		)
+	}
+
+	return c.extractCertInfo(tlsConn)
+}
+
+func (c *Checker) buildTLSConfig(
+	sniHostname string,
+) *tls.Config {
+	if c.tlsConfig != nil {
+		cfg := c.tlsConfig.Clone()
+		cfg.ServerName = sniHostname
+
+		return cfg
+	}
+
+	return &tls.Config{
+		ServerName: sniHostname,
+		MinVersion: tls.VersionTLS12,
+	}
+}
+
+func (c *Checker) extractCertInfo(
+	conn *tls.Conn,
+) (*CertificateInfo, error) {
+	state := conn.ConnectionState()
+	if len(state.PeerCertificates) == 0 {
+		return nil, ErrNoPeerCertificates
+	}
+
+	cert := state.PeerCertificates[0]
+
+	sans := make([]string, 0, len(cert.DNSNames)+len(cert.IPAddresses))
+	sans = append(sans, cert.DNSNames...)
+
+	for _, ip := range cert.IPAddresses {
+		sans = append(sans, ip.String())
+	}
+
+	return &CertificateInfo{
+		CommonName:              cert.Subject.CommonName,
+		Issuer:                  cert.Issuer.CommonName,
+		NotAfter:                cert.NotAfter,
+		SubjectAlternativeNames: sans,
+		SerialNumber:            cert.SerialNumber.String(),
+	}, nil
 }

internal/tlscheck/tlscheck_test.go

@@ -0,0 +1,169 @@
+package tlscheck_test
+
+import (
+	"context"
+	"crypto/tls"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/dnswatcher/internal/tlscheck"
+)
+
+func startTLSServer(
+	t *testing.T,
+) (*httptest.Server, string, int) {
+	t.Helper()
+
+	srv := httptest.NewTLSServer(
+		http.HandlerFunc(
+			func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusOK)
+			},
+		),
+	)
+
+	addr, ok := srv.Listener.Addr().(*net.TCPAddr)
+	if !ok {
+		t.Fatal("unexpected address type")
+	}
+
+	return srv, addr.IP.String(), addr.Port
+}
+
+func TestCheckCertificateValid(t *testing.T) {
+	t.Parallel()
+
+	srv, ip, port := startTLSServer(t)
+
+	defer srv.Close()
+
+	checker := tlscheck.NewStandalone(
+		tlscheck.WithTimeout(5*time.Second),
+		tlscheck.WithTLSConfig(&tls.Config{
+			//nolint:gosec // test uses self-signed cert
+			InsecureSkipVerify: true,
+		}),
+		tlscheck.WithPort(port),
+	)
+
+	info, err := checker.CheckCertificate(
+		context.Background(), ip, "localhost",
+	)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if info == nil {
+		t.Fatal("expected non-nil CertificateInfo")
+	}
+
+	if info.NotAfter.IsZero() {
+		t.Error("expected non-zero NotAfter")
+	}
+
+	if info.SerialNumber == "" {
+		t.Error("expected non-empty SerialNumber")
+	}
+}
+
+func TestCheckCertificateConnectionRefused(t *testing.T) {
+	t.Parallel()
+
+	lc := &net.ListenConfig{}
+
+	ln, err := lc.Listen(
+		context.Background(), "tcp", "127.0.0.1:0",
+	)
+	if err != nil {
+		t.Fatalf("failed to listen: %v", err)
+	}
+
+	addr, ok := ln.Addr().(*net.TCPAddr)
+	if !ok {
+		t.Fatal("unexpected address type")
+	}
+
+	port := addr.Port
+
+	_ = ln.Close()
+
+	checker := tlscheck.NewStandalone(
+		tlscheck.WithTimeout(2*time.Second),
+		tlscheck.WithPort(port),
+	)
+
+	_, err = checker.CheckCertificate(
+		context.Background(), "127.0.0.1", "localhost",
+	)
+	if err == nil {
+		t.Fatal("expected error for connection refused")
+	}
+}
+
+func TestCheckCertificateContextCanceled(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	checker := tlscheck.NewStandalone(
+		tlscheck.WithTimeout(2*time.Second),
+		tlscheck.WithPort(1),
+	)
+
+	_, err := checker.CheckCertificate(
+		ctx, "127.0.0.1", "localhost",
+	)
+	if err == nil {
+		t.Fatal("expected error for canceled context")
+	}
+}
+
+func TestCheckCertificateTimeout(t *testing.T) {
+	t.Parallel()
+
+	checker := tlscheck.NewStandalone(
+		tlscheck.WithTimeout(1*time.Millisecond),
+		tlscheck.WithPort(1),
+	)
+
+	_, err := checker.CheckCertificate(
+		context.Background(),
+		"192.0.2.1",
+		"example.com",
+	)
+	if err == nil {
+		t.Fatal("expected error for timeout")
+	}
+}
+
+func TestCheckCertificateSANs(t *testing.T) {
+	t.Parallel()
+
+	srv, ip, port := startTLSServer(t)
+
+	defer srv.Close()
+
+	checker := tlscheck.NewStandalone(
+		tlscheck.WithTimeout(5*time.Second),
+		tlscheck.WithTLSConfig(&tls.Config{
+			//nolint:gosec // test uses self-signed cert
+			InsecureSkipVerify: true,
+		}),
+		tlscheck.WithPort(port),
+	)
+
+	info, err := checker.CheckCertificate(
+		context.Background(), ip, "localhost",
+	)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if info.CommonName == "" && len(info.SubjectAlternativeNames) == 0 {
+		t.Error("expected CN or SANs to be populated")
+	}
+}

internal/watcher/interfaces.go

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

internal/watcher/watcher.go

@@ -1,21 +1,37 @@
-// Package watcher provides the main monitoring orchestrator and scheduler.
 package watcher
 
 import (
 	"context"
+	"fmt"
 	"log/slog"
+	"sort"
+	"strings"
+	"sync"
+	"time"
 
 	"go.uber.org/fx"
 
 	"sneak.berlin/go/dnswatcher/internal/config"
 	"sneak.berlin/go/dnswatcher/internal/logger"
-	"sneak.berlin/go/dnswatcher/internal/notify"
-	"sneak.berlin/go/dnswatcher/internal/portcheck"
-	"sneak.berlin/go/dnswatcher/internal/resolver"
 	"sneak.berlin/go/dnswatcher/internal/state"
 	"sneak.berlin/go/dnswatcher/internal/tlscheck"
 )
 
+// monitoredPorts are the TCP ports checked for each IP address.
+var monitoredPorts = []int{80, 443} //nolint:gochecknoglobals
+
+// tlsPort is the port used for TLS certificate checks.
+const tlsPort = 443
+
+// hoursPerDay converts days to hours for duration calculations.
+const hoursPerDay = 24
+
+// Status values recorded for nameserver and certificate checks.
+const (
+	statusOK    = "ok"
+	statusError = "error"
+)
+
 // Params contains dependencies for Watcher.
 type Params struct {
 	fx.In
@@ -23,10 +39,10 @@ type Params struct {
 	Logger    *logger.Logger
 	Config    *config.Config
 	State     *state.State
-	Resolver  *resolver.Resolver
-	PortCheck *portcheck.Checker
-	TLSCheck  *tlscheck.Checker
-	Notify    *notify.Service
+	Resolver  DNSResolver
+	PortCheck PortChecker
+	TLSCheck  TLSChecker
+	Notify    Notifier
 }
 
 // Watcher orchestrates all monitoring checks on a schedule.
@@ -34,19 +50,22 @@ type Watcher struct {
 	log              *slog.Logger
 	config           *config.Config
 	state            *state.State
-	resolver  *resolver.Resolver
-	portCheck *portcheck.Checker
-	tlsCheck  *tlscheck.Checker
-	notify    *notify.Service
+	resolver         DNSResolver
+	portCheck        PortChecker
+	tlsCheck         TLSChecker
+	notify           Notifier
 	cancel           context.CancelFunc
+	firstRun         bool
+	expiryNotifiedMu sync.Mutex
+	expiryNotified   map[string]time.Time
 }
 
-// New creates a new Watcher instance.
+// New creates a new Watcher instance wired into the fx lifecycle.
 func New(
 	lifecycle fx.Lifecycle,
 	params Params,
 ) (*Watcher, error) {
-	watcher := &Watcher{
+	w := &Watcher{
 		log:            params.Logger.Get(),
 		config:         params.Config,
 		state:          params.State,
@@ -54,30 +73,58 @@ func New(
 		portCheck:      params.PortCheck,
 		tlsCheck:       params.TLSCheck,
 		notify:         params.Notify,
+		firstRun:       true,
+		expiryNotified: make(map[string]time.Time),
 	}
 
 	lifecycle.Append(fx.Hook{
-		OnStart: func(startCtx context.Context) error {
-			ctx, cancel := context.WithCancel(startCtx)
-			watcher.cancel = cancel
+		OnStart: func(_ context.Context) error {
+			// Use context.Background() — the fx startup context
+			// expires after startup completes, so deriving from it
+			// would cancel the watcher immediately. The watcher's
+			// lifetime is controlled by w.cancel in OnStop.
+			ctx, cancel := context.WithCancel(context.Background())
+			w.cancel = cancel
 
-			go watcher.Run(ctx)
+			go w.Run(ctx) //nolint:contextcheck // intentionally not derived from startCtx
 
 			return nil
 		},
 		OnStop: func(_ context.Context) error {
-			if watcher.cancel != nil {
-				watcher.cancel()
+			if w.cancel != nil {
+				w.cancel()
 			}
 
 			return nil
 		},
 	})
 
-	return watcher, nil
+	return w, nil
 }
 
-// Run starts the monitoring loop.
+// NewForTest creates a Watcher without fx for unit testing.
+func NewForTest(
+	cfg *config.Config,
+	st *state.State,
+	res DNSResolver,
+	pc PortChecker,
+	tc TLSChecker,
+	n Notifier,
+) *Watcher {
+	return &Watcher{
+		log:            slog.Default(),
+		config:         cfg,
+		state:          st,
+		resolver:       res,
+		portCheck:      pc,
+		tlsCheck:       tc,
+		notify:         n,
+		firstRun:       true,
+		expiryNotified: make(map[string]time.Time),
+	}
+}
+
+// Run starts the monitoring loop with periodic scheduling.
 func (w *Watcher) Run(ctx context.Context) {
 	w.log.Info(
 		"watcher starting",
@@ -87,8 +134,812 @@ func (w *Watcher) Run(ctx context.Context) {
 		"tlsInterval", w.config.TLSInterval,
 	)
 
-	// Stub: wait for context cancellation.
-	// Implementation will add initial check + periodic scheduling.
-	<-ctx.Done()
+	w.RunOnce(ctx)
+	w.maybeSendTestNotification(ctx)
+
+	dnsTicker := time.NewTicker(w.config.DNSInterval)
+	tlsTicker := time.NewTicker(w.config.TLSInterval)
+
+	defer dnsTicker.Stop()
+	defer tlsTicker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
 			w.log.Info("watcher stopped")
+
+			return
+		case <-dnsTicker.C:
+			w.runDNSChecks(ctx)
+
+			w.checkAllPorts(ctx)
+			w.saveState()
+		case <-tlsTicker.C:
+			// Run DNS first so TLS checks use freshly
+			// resolved IP addresses, not stale ones from
+			// a previous cycle.
+			w.runDNSChecks(ctx)
+
+			w.runTLSChecks(ctx)
+			w.saveState()
+		}
+	}
+}
+
+// RunOnce performs a single complete monitoring cycle.
+// DNS checks run first so that port and TLS checks use
+// freshly resolved IP addresses. Port checks run before
+// TLS because TLS checks only target IPs with an open
+// port 443.
+func (w *Watcher) RunOnce(ctx context.Context) {
+	w.detectFirstRun()
+
+	// Phase 1: DNS resolution must complete first so that
+	// subsequent checks use fresh IP addresses.
+	w.runDNSChecks(ctx)
+
+	// Phase 2: Port checks populate port state that TLS
+	// checks depend on (TLS only targets IPs where port
+	// 443 is open).
+	w.checkAllPorts(ctx)
+
+	// Phase 3: TLS checks use fresh DNS IPs and current
+	// port state.
+	w.runTLSChecks(ctx)
+
+	w.saveState()
+	w.firstRun = false
+}
+
+func (w *Watcher) detectFirstRun() {
+	snap := w.state.GetSnapshot()
+	hasState := len(snap.Domains) > 0 ||
+		len(snap.Hostnames) > 0 ||
+		len(snap.Ports) > 0 ||
+		len(snap.Certificates) > 0
+
+	if hasState {
+		w.firstRun = false
+	}
+}
+
+// runDNSChecks performs DNS resolution for all configured domains
+// and hostnames, updating state with freshly resolved records.
+// This must complete before port or TLS checks run so those
+// checks operate on current IP addresses.
+func (w *Watcher) runDNSChecks(ctx context.Context) {
+	for _, domain := range w.config.Domains {
+		w.checkDomain(ctx, domain)
+	}
+
+	for _, hostname := range w.config.Hostnames {
+		w.checkHostname(ctx, hostname)
+	}
+}
+
+func (w *Watcher) checkDomain(
+	ctx context.Context,
+	domain string,
+) {
+	nameservers, err := w.resolver.LookupNS(ctx, domain)
+	if err != nil {
+		w.log.Error(
+			"failed to lookup NS",
+			"domain", domain,
+			"error", err,
+		)
+
+		return
+	}
+
+	sort.Strings(nameservers)
+
+	now := time.Now().UTC()
+
+	prev, hasPrev := w.state.GetDomainState(domain)
+	if hasPrev && !w.firstRun {
+		w.detectNSChanges(ctx, domain, prev.Nameservers, nameservers)
+	}
+
+	w.state.SetDomainState(domain, &state.DomainState{
+		Nameservers: nameservers,
+		LastChecked: now,
+	})
+
+	// Also look up A/AAAA records for the apex domain so that
+	// port and TLS checks (which read HostnameState) can find
+	// the domain's IP addresses.
+	records, err := w.resolver.LookupAllRecords(ctx, domain)
+	if err != nil {
+		w.log.Error(
+			"failed to lookup records for domain",
+			"domain", domain,
+			"error", err,
+		)
+
+		return
+	}
+
+	prevHS, hasPrevHS := w.state.GetHostnameState(domain)
+	if hasPrevHS && !w.firstRun {
+		w.detectHostnameChanges(ctx, domain, prevHS, records)
+	}
+
+	newState := buildHostnameState(records, now)
+	w.state.SetHostnameState(domain, newState)
+}
+
+func (w *Watcher) detectNSChanges(
+	ctx context.Context,
+	domain string,
+	oldNS, newNS []string,
+) {
+	oldSet := toSet(oldNS)
+	newSet := toSet(newNS)
+
+	var added, removed []string
+
+	for ns := range newSet {
+		if !oldSet[ns] {
+			added = append(added, ns)
+		}
+	}
+
+	for ns := range oldSet {
+		if !newSet[ns] {
+			removed = append(removed, ns)
+		}
+	}
+
+	if len(added) == 0 && len(removed) == 0 {
+		return
+	}
+
+	msg := fmt.Sprintf(
+		"Domain: %s\nAdded: %s\nRemoved: %s",
+		domain,
+		strings.Join(added, ", "),
+		strings.Join(removed, ", "),
+	)
+
+	w.notify.SendNotification(
+		ctx,
+		"NS Change: "+domain,
+		msg,
+		"warning",
+	)
+}
+
+func (w *Watcher) checkHostname(
+	ctx context.Context,
+	hostname string,
+) {
+	records, err := w.resolver.LookupAllRecords(ctx, hostname)
+	if err != nil {
+		w.log.Error(
+			"failed to lookup records",
+			"hostname", hostname,
+			"error", err,
+		)
+
+		return
+	}
+
+	now := time.Now().UTC()
+	prev, hasPrev := w.state.GetHostnameState(hostname)
+
+	if hasPrev && !w.firstRun {
+		w.detectHostnameChanges(ctx, hostname, prev, records)
+	}
+
+	newState := buildHostnameState(records, now)
+	w.state.SetHostnameState(hostname, newState)
+}
+
+func buildHostnameState(
+	records map[string]map[string][]string,
+	now time.Time,
+) *state.HostnameState {
+	hs := &state.HostnameState{
+		RecordsByNameserver: make(
+			map[string]*state.NameserverRecordState,
+		),
+		LastChecked: now,
+	}
+
+	for ns, recs := range records {
+		hs.RecordsByNameserver[ns] = &state.NameserverRecordState{
+			Records:     recs,
+			Status:      statusOK,
+			LastChecked: now,
+		}
+	}
+
+	return hs
+}
+
+func (w *Watcher) detectHostnameChanges(
+	ctx context.Context,
+	hostname string,
+	prev *state.HostnameState,
+	current map[string]map[string][]string,
+) {
+	w.detectRecordChanges(ctx, hostname, prev, current)
+	w.detectNSDisappearances(ctx, hostname, prev, current)
+	w.detectInconsistencies(ctx, hostname, current)
+}
+
+func (w *Watcher) detectRecordChanges(
+	ctx context.Context,
+	hostname string,
+	prev *state.HostnameState,
+	current map[string]map[string][]string,
+) {
+	for ns, recs := range current {
+		prevNS, ok := prev.RecordsByNameserver[ns]
+		if !ok {
+			continue
+		}
+
+		if recordsEqual(prevNS.Records, recs) {
+			continue
+		}
+
+		msg := fmt.Sprintf(
+			"Hostname: %s\nNameserver: %s\n"+
+				"Old: %v\nNew: %v",
+			hostname, ns,
+			prevNS.Records, recs,
+		)
+
+		w.notify.SendNotification(
+			ctx,
+			"Record Change: "+hostname,
+			msg,
+			"warning",
+		)
+	}
+}
+
+func (w *Watcher) detectNSDisappearances(
+	ctx context.Context,
+	hostname string,
+	prev *state.HostnameState,
+	current map[string]map[string][]string,
+) {
+	for ns, prevNS := range prev.RecordsByNameserver {
+		if _, ok := current[ns]; ok || prevNS.Status != statusOK {
+			continue
+		}
+
+		msg := fmt.Sprintf(
+			"Hostname: %s\nNameserver: %s disappeared",
+			hostname, ns,
+		)
+
+		w.notify.SendNotification(
+			ctx,
+			"NS Failure: "+hostname,
+			msg,
+			"error",
+		)
+	}
+
+	for ns := range current {
+		prevNS, ok := prev.RecordsByNameserver[ns]
+		if !ok || prevNS.Status != statusError {
+			continue
+		}
+
+		msg := fmt.Sprintf(
+			"Hostname: %s\nNameserver: %s recovered",
+			hostname, ns,
+		)
+
+		w.notify.SendNotification(
+			ctx,
+			"NS Recovery: "+hostname,
+			msg,
+			"success",
+		)
+	}
+}
+
+func (w *Watcher) detectInconsistencies(
+	ctx context.Context,
+	hostname string,
+	current map[string]map[string][]string,
+) {
+	nameservers := make([]string, 0, len(current))
+	for ns := range current {
+		nameservers = append(nameservers, ns)
+	}
+
+	sort.Strings(nameservers)
+
+	for i := range len(nameservers) - 1 {
+		ns1 := nameservers[i]
+		ns2 := nameservers[i+1]
+
+		if recordsEqual(current[ns1], current[ns2]) {
+			continue
+		}
+
+		msg := fmt.Sprintf(
+			"Hostname: %s\n%s: %v\n%s: %v",
+			hostname,
+			ns1, current[ns1],
+			ns2, current[ns2],
+		)
+
+		w.notify.SendNotification(
+			ctx,
+			"Inconsistency: "+hostname,
+			msg,
+			"warning",
+		)
+	}
+}
+
+func (w *Watcher) checkAllPorts(ctx context.Context) {
+	// Phase 1: Build current IP:port → hostname associations
+	// from fresh DNS data.
+	associations := w.buildPortAssociations()
+
+	// Phase 2: Check each unique IP:port and update state
+	// with the full set of associated hostnames.
+	for key, hostnames := range associations {
+		ip, port := parsePortKey(key)
+		if port == 0 {
+			continue
+		}
+
+		w.checkSinglePort(ctx, ip, port, hostnames)
+	}
+
+	// Phase 3: Remove port state entries that no longer have
+	// any hostname referencing them.
+	w.cleanupStalePorts(associations)
+}
+
+// buildPortAssociations constructs a map from IP:port keys to
+// the sorted set of hostnames currently resolving to that IP.
+func (w *Watcher) buildPortAssociations() map[string][]string {
+	assoc := make(map[string]map[string]bool)
+
+	allNames := make(
+		[]string, 0,
+		len(w.config.Hostnames)+len(w.config.Domains),
+	)
+	allNames = append(allNames, w.config.Hostnames...)
+	allNames = append(allNames, w.config.Domains...)
+
+	for _, name := range allNames {
+		ips := w.collectIPs(name)
+		for _, ip := range ips {
+			for _, port := range monitoredPorts {
+				key := fmt.Sprintf("%s:%d", ip, port)
+				if assoc[key] == nil {
+					assoc[key] = make(map[string]bool)
+				}
+
+				assoc[key][name] = true
+			}
+		}
+	}
+
+	result := make(map[string][]string, len(assoc))
+	for key, set := range assoc {
+		hostnames := make([]string, 0, len(set))
+		for h := range set {
+			hostnames = append(hostnames, h)
+		}
+
+		sort.Strings(hostnames)
+
+		result[key] = hostnames
+	}
+
+	return result
+}
+
+// parsePortKey splits an "ip:port" key into its components.
+func parsePortKey(key string) (string, int) {
+	lastColon := strings.LastIndex(key, ":")
+	if lastColon < 0 {
+		return key, 0
+	}
+
+	ip := key[:lastColon]
+
+	var p int
+
+	_, err := fmt.Sscanf(key[lastColon+1:], "%d", &p)
+	if err != nil {
+		return ip, 0
+	}
+
+	return ip, p
+}
+
+// cleanupStalePorts removes port state entries that are no
+// longer referenced by any hostname in the current DNS data.
+func (w *Watcher) cleanupStalePorts(
+	currentAssociations map[string][]string,
+) {
+	for _, key := range w.state.GetAllPortKeys() {
+		if _, exists := currentAssociations[key]; !exists {
+			w.state.DeletePortState(key)
+		}
+	}
+}
+
+func (w *Watcher) collectIPs(hostname string) []string {
+	hs, ok := w.state.GetHostnameState(hostname)
+	if !ok {
+		return nil
+	}
+
+	ipSet := make(map[string]bool)
+
+	for _, nsState := range hs.RecordsByNameserver {
+		for _, ip := range nsState.Records["A"] {
+			ipSet[ip] = true
+		}
+
+		for _, ip := range nsState.Records["AAAA"] {
+			ipSet[ip] = true
+		}
+	}
+
+	result := make([]string, 0, len(ipSet))
+	for ip := range ipSet {
+		result = append(result, ip)
+	}
+
+	sort.Strings(result)
+
+	return result
+}
+
+func (w *Watcher) checkSinglePort(
+	ctx context.Context,
+	ip string,
+	port int,
+	hostnames []string,
+) {
+	result, err := w.portCheck.CheckPort(ctx, ip, port)
+	if err != nil {
+		w.log.Error(
+			"port check failed",
+			"ip", ip,
+			"port", port,
+			"error", err,
+		)
+
+		return
+	}
+
+	key := fmt.Sprintf("%s:%d", ip, port)
+	now := time.Now().UTC()
+	prev, hasPrev := w.state.GetPortState(key)
+
+	if hasPrev && !w.firstRun && prev.Open != result.Open {
+		stateStr := "closed"
+		if result.Open {
+			stateStr = "open"
+		}
+
+		msg := fmt.Sprintf(
+			"Hosts: %s\nAddress: %s\nPort now %s",
+			strings.Join(hostnames, ", "), key, stateStr,
+		)
+
+		w.notify.SendNotification(
+			ctx,
+			"Port Change: "+key,
+			msg,
+			"warning",
+		)
+	}
+
+	w.state.SetPortState(key, &state.PortState{
+		Open:        result.Open,
+		Hostnames:   hostnames,
+		LastChecked: now,
+	})
+}
+
+func (w *Watcher) runTLSChecks(ctx context.Context) {
+	for _, hostname := range w.config.Hostnames {
+		w.checkTLSForHostname(ctx, hostname)
+	}
+
+	for _, domain := range w.config.Domains {
+		w.checkTLSForHostname(ctx, domain)
+	}
+}
+
+func (w *Watcher) checkTLSForHostname(
+	ctx context.Context,
+	hostname string,
+) {
+	ips := w.collectIPs(hostname)
+
+	for _, ip := range ips {
+		portKey := fmt.Sprintf("%s:%d", ip, tlsPort)
+
+		ps, ok := w.state.GetPortState(portKey)
+		if !ok || !ps.Open {
+			continue
+		}
+
+		w.checkTLSCert(ctx, ip, hostname)
+	}
+}
+
+func (w *Watcher) checkTLSCert(
+	ctx context.Context,
+	ip string,
+	hostname string,
+) {
+	cert, err := w.tlsCheck.CheckCertificate(ctx, ip, hostname)
+	certKey := fmt.Sprintf("%s:%d:%s", ip, tlsPort, hostname)
+	now := time.Now().UTC()
+	prev, hasPrev := w.state.GetCertificateState(certKey)
+
+	if err != nil {
+		w.handleTLSError(
+			ctx, certKey, hostname, ip,
+			hasPrev, prev, now, err,
+		)
+
+		return
+	}
+
+	w.handleTLSSuccess(
+		ctx, certKey, hostname, ip,
+		hasPrev, prev, now, cert,
+	)
+}
+
+func (w *Watcher) handleTLSError(
+	ctx context.Context,
+	certKey, hostname, ip string,
+	hasPrev bool,
+	prev *state.CertificateState,
+	now time.Time,
+	err error,
+) {
+	if hasPrev && !w.firstRun && prev.Status == statusOK {
+		msg := fmt.Sprintf(
+			"Host: %s\nIP: %s\nError: %s",
+			hostname, ip, err,
+		)
+
+		w.notify.SendNotification(
+			ctx,
+			"TLS Failure: "+hostname,
+			msg,
+			"error",
+		)
+	}
+
+	w.state.SetCertificateState(
+		certKey, &state.CertificateState{
+			Status:      statusError,
+			Error:       err.Error(),
+			LastChecked: now,
+		},
+	)
+}
+
+func (w *Watcher) handleTLSSuccess(
+	ctx context.Context,
+	certKey, hostname, ip string,
+	hasPrev bool,
+	prev *state.CertificateState,
+	now time.Time,
+	cert *tlscheck.CertificateInfo,
+) {
+	if hasPrev && !w.firstRun {
+		w.detectTLSChanges(ctx, hostname, ip, prev, cert)
+	}
+
+	w.checkTLSExpiry(ctx, hostname, ip, cert)
+
+	w.state.SetCertificateState(
+		certKey, &state.CertificateState{
+			CommonName:              cert.CommonName,
+			Issuer:                  cert.Issuer,
+			NotAfter:                cert.NotAfter,
+			SubjectAlternativeNames: cert.SubjectAlternativeNames,
+			Status:                  statusOK,
+			LastChecked:             now,
+		},
+	)
+}
+
+func (w *Watcher) detectTLSChanges(
+	ctx context.Context,
+	hostname, ip string,
+	prev *state.CertificateState,
+	cert *tlscheck.CertificateInfo,
+) {
+	if prev.Status == statusError {
+		msg := fmt.Sprintf(
+			"Host: %s\nIP: %s\nTLS recovered",
+			hostname, ip,
+		)
+
+		w.notify.SendNotification(
+			ctx,
+			"TLS Recovery: "+hostname,
+			msg,
+			"success",
+		)
+
+		return
+	}
+
+	changed := prev.CommonName != cert.CommonName ||
+		prev.Issuer != cert.Issuer ||
+		!sliceEqual(
+			prev.SubjectAlternativeNames,
+			cert.SubjectAlternativeNames,
+		)
+
+	if !changed {
+		return
+	}
+
+	msg := fmt.Sprintf(
+		"Host: %s\nIP: %s\n"+
+			"Old CN: %s, Issuer: %s\n"+
+			"New CN: %s, Issuer: %s",
+		hostname, ip,
+		prev.CommonName, prev.Issuer,
+		cert.CommonName, cert.Issuer,
+	)
+
+	w.notify.SendNotification(
+		ctx,
+		"TLS Certificate Change: "+hostname,
+		msg,
+		"warning",
+	)
+}
+
+func (w *Watcher) checkTLSExpiry(
+	ctx context.Context,
+	hostname, ip string,
+	cert *tlscheck.CertificateInfo,
+) {
+	daysLeft := time.Until(cert.NotAfter).Hours() / hoursPerDay
+	warningDays := float64(w.config.TLSExpiryWarning)
+
+	if daysLeft > warningDays {
+		return
+	}
+
+	// Deduplicate expiry warnings: don't re-notify for the same
+	// hostname within the TLS check interval.
+	dedupKey := fmt.Sprintf("expiry:%s:%s", hostname, ip)
+
+	w.expiryNotifiedMu.Lock()
+
+	lastNotified, seen := w.expiryNotified[dedupKey]
+	if seen && time.Since(lastNotified) < w.config.TLSInterval {
+		w.expiryNotifiedMu.Unlock()
+
+		return
+	}
+
+	w.expiryNotified[dedupKey] = time.Now()
+	w.expiryNotifiedMu.Unlock()
+
+	msg := fmt.Sprintf(
+		"Host: %s\nIP: %s\nCN: %s\n"+
+			"Expires: %s (%.0f days)",
+		hostname, ip, cert.CommonName,
+		cert.NotAfter.Format(time.RFC3339),
+		daysLeft,
+	)
+
+	w.notify.SendNotification(
+		ctx,
+		"TLS Expiry Warning: "+hostname,
+		msg,
+		"warning",
+	)
+}
+
+func (w *Watcher) saveState() {
+	err := w.state.Save()
+	if err != nil {
+		w.log.Error("failed to save state", "error", err)
+	}
+}
+
+// maybeSendTestNotification sends a startup status notification
+// after the first full scan completes, if SEND_TEST_NOTIFICATION
+// is enabled. The message is clearly informational ("all ok")
+// and not an error or anomaly alert.
+func (w *Watcher) maybeSendTestNotification(ctx context.Context) {
+	if !w.config.SendTestNotification {
+		return
+	}
+
+	snap := w.state.GetSnapshot()
+
+	msg := fmt.Sprintf(
+		"dnswatcher has started and completed its initial scan.\n"+
+			"Monitoring %d domain(s) and %d hostname(s).\n"+
+			"Tracking %d port endpoint(s) and %d TLS certificate(s).\n"+
+			"All notification channels are working.",
+		len(snap.Domains),
+		len(snap.Hostnames),
+		len(snap.Ports),
+		len(snap.Certificates),
+	)
+
+	w.log.Info("sending startup test notification")
+
+	w.notify.SendNotification(
+		ctx,
+		"✅ dnswatcher startup complete",
+		msg,
+		"success",
+	)
+}
+
+// --- Utility functions ---
+
+func toSet(items []string) map[string]bool {
+	set := make(map[string]bool, len(items))
+	for _, item := range items {
+		set[item] = true
+	}
+
+	return set
+}
+
+func recordsEqual(
+	a, b map[string][]string,
+) bool {
+	if len(a) != len(b) {
+		return false
+	}
+
+	for k, av := range a {
+		bv, ok := b[k]
+		if !ok || !sliceEqual(av, bv) {
+			return false
+		}
+	}
+
+	return true
+}
+
+func sliceEqual(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+
+	aSorted := make([]string, len(a))
+	bSorted := make([]string, len(b))
+
+	copy(aSorted, a)
+	copy(bSorted, b)
+
+	sort.Strings(aSorted)
+	sort.Strings(bSorted)
+
+	for i := range aSorted {
+		if aSorted[i] != bSorted[i] {
+			return false
+		}
+	}
+
+	return true
 }

internal/watcher/watcher_test.go

@@ -0,0 +1,915 @@
+package watcher_test
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/dnswatcher/internal/config"
+	"sneak.berlin/go/dnswatcher/internal/portcheck"
+	"sneak.berlin/go/dnswatcher/internal/state"
+	"sneak.berlin/go/dnswatcher/internal/tlscheck"
+	"sneak.berlin/go/dnswatcher/internal/watcher"
+)
+
+// errNotFound is returned when mock data is missing.
+var errNotFound = errors.New("not found")
+
+// Fixture values shared across tests.
+const (
+	testDomain = "example.com"
+	testHost   = "www.example.com"
+	testNS1    = "ns1.example.com."
+	testNS2    = "ns2.example.com."
+	testIPv4   = "93.184.216.34"
+	testIP     = "1.2.3.4"
+	testIssuer = "DigiCert"
+)
+
+// --- Mock implementations ---
+
+type mockResolver struct {
+	mu             sync.Mutex
+	nsRecords      map[string][]string
+	allRecords     map[string]map[string]map[string][]string
+	ipAddresses    map[string][]string
+	lookupNSErr    error
+	allRecordsErr  error
+	resolveIPErr   error
+	lookupNSCalls  int
+	allRecordCalls int
+}
+
+func (m *mockResolver) LookupNS(
+	_ context.Context,
+	domain string,
+) ([]string, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	m.lookupNSCalls++
+
+	if m.lookupNSErr != nil {
+		return nil, m.lookupNSErr
+	}
+
+	ns, ok := m.nsRecords[domain]
+	if !ok {
+		return nil, fmt.Errorf(
+			"%w: NS for %s", errNotFound, domain,
+		)
+	}
+
+	return ns, nil
+}
+
+func (m *mockResolver) LookupAllRecords(
+	_ context.Context,
+	hostname string,
+) (map[string]map[string][]string, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	m.allRecordCalls++
+
+	if m.allRecordsErr != nil {
+		return nil, m.allRecordsErr
+	}
+
+	recs, ok := m.allRecords[hostname]
+	if !ok {
+		return nil, fmt.Errorf(
+			"%w: records for %s", errNotFound, hostname,
+		)
+	}
+
+	return recs, nil
+}
+
+func (m *mockResolver) ResolveIPAddresses(
+	_ context.Context,
+	hostname string,
+) ([]string, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	if m.resolveIPErr != nil {
+		return nil, m.resolveIPErr
+	}
+
+	ips, ok := m.ipAddresses[hostname]
+	if !ok {
+		return nil, fmt.Errorf(
+			"%w: IPs for %s", errNotFound, hostname,
+		)
+	}
+
+	return ips, nil
+}
+
+type mockPortChecker struct {
+	mu      sync.Mutex
+	results map[string]bool
+	err     error
+	calls   int
+}
+
+func (m *mockPortChecker) CheckPort(
+	_ context.Context,
+	address string,
+	port int,
+) (*portcheck.PortResult, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	m.calls++
+
+	if m.err != nil {
+		return nil, m.err
+	}
+
+	key := fmt.Sprintf("%s:%d", address, port)
+	open := m.results[key]
+
+	return &portcheck.PortResult{Open: open}, nil
+}
+
+type mockTLSChecker struct {
+	mu    sync.Mutex
+	certs map[string]*tlscheck.CertificateInfo
+	err   error
+	calls int
+}
+
+func (m *mockTLSChecker) CheckCertificate(
+	_ context.Context,
+	ip string,
+	hostname string,
+) (*tlscheck.CertificateInfo, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	m.calls++
+
+	if m.err != nil {
+		return nil, m.err
+	}
+
+	key := fmt.Sprintf("%s:%s", ip, hostname)
+	cert, ok := m.certs[key]
+
+	if !ok {
+		return nil, fmt.Errorf(
+			"%w: cert for %s", errNotFound, key,
+		)
+	}
+
+	return cert, nil
+}
+
+type notification struct {
+	Title    string
+	Message  string
+	Priority string
+}
+
+type mockNotifier struct {
+	mu            sync.Mutex
+	notifications []notification
+}
+
+func (m *mockNotifier) SendNotification(
+	_ context.Context,
+	title, message, priority string,
+) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	m.notifications = append(m.notifications, notification{
+		Title:    title,
+		Message:  message,
+		Priority: priority,
+	})
+}
+
+func (m *mockNotifier) getNotifications() []notification {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	result := make([]notification, len(m.notifications))
+	copy(result, m.notifications)
+
+	return result
+}
+
+// --- Helper to build a Watcher for testing ---
+
+type testDeps struct {
+	resolver    *mockResolver
+	portChecker *mockPortChecker
+	tlsChecker  *mockTLSChecker
+	notifier    *mockNotifier
+	state       *state.State
+	config      *config.Config
+}
+
+func newTestWatcher(
+	t *testing.T,
+	cfg *config.Config,
+) (*watcher.Watcher, *testDeps) {
+	t.Helper()
+
+	deps := &testDeps{
+		resolver: &mockResolver{
+			nsRecords:   make(map[string][]string),
+			allRecords:  make(map[string]map[string]map[string][]string),
+			ipAddresses: make(map[string][]string),
+		},
+		portChecker: &mockPortChecker{
+			results: make(map[string]bool),
+		},
+		tlsChecker: &mockTLSChecker{
+			certs: make(map[string]*tlscheck.CertificateInfo),
+		},
+		notifier: &mockNotifier{},
+		config:   cfg,
+	}
+
+	deps.state = state.NewForTest()
+
+	w := watcher.NewForTest(
+		deps.config,
+		deps.state,
+		deps.resolver,
+		deps.portChecker,
+		deps.tlsChecker,
+		deps.notifier,
+	)
+
+	return w, deps
+}
+
+func defaultTestConfig(t *testing.T) *config.Config {
+	t.Helper()
+
+	return &config.Config{
+		DNSInterval:      time.Hour,
+		TLSInterval:      12 * time.Hour,
+		TLSExpiryWarning: 7,
+		DataDir:          t.TempDir(),
+	}
+}
+
+func TestFirstRunBaseline(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{testDomain}
+	cfg.Hostnames = []string{testHost}
+
+	w, deps := newTestWatcher(t, cfg)
+	setupBaselineMocks(deps)
+
+	w.RunOnce(t.Context())
+
+	assertNoNotifications(t, deps)
+	assertStatePopulated(t, deps)
+}
+
+func setupBaselineMocks(deps *testDeps) {
+	deps.resolver.nsRecords[testDomain] = []string{
+		testNS1,
+		testNS2,
+	}
+	deps.resolver.allRecords[testDomain] = map[string]map[string][]string{
+		testNS1: {"A": {testIPv4}},
+		testNS2: {"A": {testIPv4}},
+	}
+	deps.resolver.allRecords[testHost] = map[string]map[string][]string{
+		testNS1: {"A": {testIPv4}},
+		testNS2: {"A": {testIPv4}},
+	}
+	deps.resolver.ipAddresses[testHost] = []string{
+		testIPv4,
+	}
+	deps.portChecker.results["93.184.216.34:80"] = true
+	deps.portChecker.results["93.184.216.34:443"] = true
+	deps.tlsChecker.certs["93.184.216.34:www.example.com"] = &tlscheck.CertificateInfo{
+		CommonName: testHost,
+		Issuer:     testIssuer,
+		NotAfter:   time.Now().Add(90 * 24 * time.Hour),
+		SubjectAlternativeNames: []string{
+			testHost,
+		},
+	}
+	deps.tlsChecker.certs["93.184.216.34:example.com"] = &tlscheck.CertificateInfo{
+		CommonName: testDomain,
+		Issuer:     testIssuer,
+		NotAfter:   time.Now().Add(90 * 24 * time.Hour),
+		SubjectAlternativeNames: []string{
+			testDomain,
+		},
+	}
+}
+
+func assertNoNotifications(
+	t *testing.T,
+	deps *testDeps,
+) {
+	t.Helper()
+
+	notifications := deps.notifier.getNotifications()
+	if len(notifications) != 0 {
+		t.Errorf(
+			"expected 0 notifications on first run, got %d",
+			len(notifications),
+		)
+	}
+}
+
+func assertStatePopulated(
+	t *testing.T,
+	deps *testDeps,
+) {
+	t.Helper()
+
+	snap := deps.state.GetSnapshot()
+
+	if len(snap.Domains) != 1 {
+		t.Errorf(
+			"expected 1 domain in state, got %d",
+			len(snap.Domains),
+		)
+	}
+
+	// Hostnames includes both explicit hostnames and domains
+	// (domains now also get hostname state for port/TLS checks).
+	if len(snap.Hostnames) < 1 {
+		t.Errorf(
+			"expected at least 1 hostname in state, got %d",
+			len(snap.Hostnames),
+		)
+	}
+}
+
+func TestDomainPortAndTLSChecks(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{testDomain}
+
+	w, deps := newTestWatcher(t, cfg)
+
+	deps.resolver.nsRecords[testDomain] = []string{
+		testNS1,
+	}
+	deps.resolver.allRecords[testDomain] = map[string]map[string][]string{
+		testNS1: {"A": {testIPv4}},
+	}
+	deps.portChecker.results["93.184.216.34:80"] = true
+	deps.portChecker.results["93.184.216.34:443"] = true
+	deps.tlsChecker.certs["93.184.216.34:example.com"] = &tlscheck.CertificateInfo{
+		CommonName: testDomain,
+		Issuer:     testIssuer,
+		NotAfter:   time.Now().Add(90 * 24 * time.Hour),
+		SubjectAlternativeNames: []string{
+			testDomain,
+		},
+	}
+
+	w.RunOnce(t.Context())
+
+	snap := deps.state.GetSnapshot()
+
+	// Domain should have port state populated
+	if len(snap.Ports) == 0 {
+		t.Error("expected port state for domain, got none")
+	}
+
+	// Domain should have certificate state populated
+	if len(snap.Certificates) == 0 {
+		t.Error("expected certificate state for domain, got none")
+	}
+
+	// Verify port checker was actually called
+	deps.portChecker.mu.Lock()
+	calls := deps.portChecker.calls
+	deps.portChecker.mu.Unlock()
+
+	if calls == 0 {
+		t.Error("expected port checker to be called for domain")
+	}
+
+	// Verify TLS checker was actually called
+	deps.tlsChecker.mu.Lock()
+	tlsCalls := deps.tlsChecker.calls
+	deps.tlsChecker.mu.Unlock()
+
+	if tlsCalls == 0 {
+		t.Error("expected TLS checker to be called for domain")
+	}
+}
+
+func TestNSChangeDetection(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{testDomain}
+
+	w, deps := newTestWatcher(t, cfg)
+
+	deps.resolver.nsRecords[testDomain] = []string{
+		testNS1,
+		testNS2,
+	}
+	deps.resolver.allRecords[testDomain] = map[string]map[string][]string{
+		testNS1: {"A": {testIP}},
+		testNS2: {"A": {testIP}},
+	}
+	deps.portChecker.results["1.2.3.4:80"] = false
+	deps.portChecker.results["1.2.3.4:443"] = false
+
+	ctx := t.Context()
+	w.RunOnce(ctx)
+
+	deps.resolver.mu.Lock()
+	deps.resolver.nsRecords[testDomain] = []string{
+		testNS1,
+		"ns3.example.com.",
+	}
+	deps.resolver.allRecords[testDomain] = map[string]map[string][]string{
+		testNS1:            {"A": {testIP}},
+		"ns3.example.com.": {"A": {testIP}},
+	}
+	deps.resolver.mu.Unlock()
+
+	w.RunOnce(ctx)
+
+	notifications := deps.notifier.getNotifications()
+	if len(notifications) == 0 {
+		t.Error("expected notification for NS change")
+	}
+
+	found := false
+
+	for _, n := range notifications {
+		if n.Priority == "warning" {
+			found = true
+		}
+	}
+
+	if !found {
+		t.Error("expected warning-priority NS change notification")
+	}
+}
+
+func TestRecordChangeDetection(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Hostnames = []string{testHost}
+
+	w, deps := newTestWatcher(t, cfg)
+
+	deps.resolver.allRecords[testHost] = map[string]map[string][]string{
+		testNS1: {"A": {testIPv4}},
+	}
+	deps.resolver.ipAddresses[testHost] = []string{
+		testIPv4,
+	}
+	deps.portChecker.results["93.184.216.34:80"] = false
+	deps.portChecker.results["93.184.216.34:443"] = false
+
+	ctx := t.Context()
+	w.RunOnce(ctx)
+
+	deps.resolver.mu.Lock()
+	deps.resolver.allRecords[testHost] = map[string]map[string][]string{
+		testNS1: {"A": {"93.184.216.35"}},
+	}
+	deps.resolver.ipAddresses[testHost] = []string{
+		"93.184.216.35",
+	}
+	deps.resolver.mu.Unlock()
+
+	deps.portChecker.mu.Lock()
+	deps.portChecker.results["93.184.216.35:80"] = false
+	deps.portChecker.results["93.184.216.35:443"] = false
+	deps.portChecker.mu.Unlock()
+
+	w.RunOnce(ctx)
+
+	notifications := deps.notifier.getNotifications()
+	if len(notifications) == 0 {
+		t.Error("expected notification for record change")
+	}
+}
+
+func TestPortStateChange(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Hostnames = []string{testHost}
+
+	w, deps := newTestWatcher(t, cfg)
+
+	deps.resolver.allRecords[testHost] = map[string]map[string][]string{
+		testNS1: {"A": {testIP}},
+	}
+	deps.resolver.ipAddresses[testHost] = []string{
+		testIP,
+	}
+	deps.portChecker.results["1.2.3.4:80"] = true
+	deps.portChecker.results["1.2.3.4:443"] = true
+	deps.tlsChecker.certs["1.2.3.4:www.example.com"] = &tlscheck.CertificateInfo{
+		CommonName: testHost,
+		Issuer:     testIssuer,
+		NotAfter:   time.Now().Add(90 * 24 * time.Hour),
+		SubjectAlternativeNames: []string{
+			testHost,
+		},
+	}
+
+	ctx := t.Context()
+	w.RunOnce(ctx)
+
+	deps.portChecker.mu.Lock()
+	deps.portChecker.results["1.2.3.4:443"] = false
+	deps.portChecker.mu.Unlock()
+
+	w.RunOnce(ctx)
+
+	notifications := deps.notifier.getNotifications()
+	if len(notifications) == 0 {
+		t.Error("expected notification for port state change")
+	}
+}
+
+func TestTLSExpiryWarning(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Hostnames = []string{testHost}
+
+	w, deps := newTestWatcher(t, cfg)
+
+	deps.resolver.allRecords[testHost] = map[string]map[string][]string{
+		testNS1: {"A": {testIP}},
+	}
+	deps.resolver.ipAddresses[testHost] = []string{
+		testIP,
+	}
+	deps.portChecker.results["1.2.3.4:80"] = true
+	deps.portChecker.results["1.2.3.4:443"] = true
+	deps.tlsChecker.certs["1.2.3.4:www.example.com"] = &tlscheck.CertificateInfo{
+		CommonName: testHost,
+		Issuer:     testIssuer,
+		NotAfter:   time.Now().Add(3 * 24 * time.Hour),
+		SubjectAlternativeNames: []string{
+			testHost,
+		},
+	}
+
+	ctx := t.Context()
+
+	// First run = baseline
+	w.RunOnce(ctx)
+
+	// Second run should warn about expiry
+	w.RunOnce(ctx)
+
+	notifications := deps.notifier.getNotifications()
+
+	found := false
+
+	for _, n := range notifications {
+		if n.Priority == "warning" {
+			found = true
+		}
+	}
+
+	if !found {
+		t.Errorf(
+			"expected expiry warning, got: %v",
+			notifications,
+		)
+	}
+}
+
+func TestTLSExpiryWarningDedup(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Hostnames = []string{testHost}
+	cfg.TLSInterval = 24 * time.Hour
+
+	w, deps := newTestWatcher(t, cfg)
+
+	deps.resolver.allRecords[testHost] = map[string]map[string][]string{
+		testNS1: {"A": {testIP}},
+	}
+	deps.resolver.ipAddresses[testHost] = []string{
+		testIP,
+	}
+	deps.portChecker.results["1.2.3.4:80"] = true
+	deps.portChecker.results["1.2.3.4:443"] = true
+	deps.tlsChecker.certs["1.2.3.4:www.example.com"] = &tlscheck.CertificateInfo{
+		CommonName: testHost,
+		Issuer:     testIssuer,
+		NotAfter:   time.Now().Add(3 * 24 * time.Hour),
+		SubjectAlternativeNames: []string{
+			testHost,
+		},
+	}
+
+	ctx := t.Context()
+
+	// First run = baseline, no notifications
+	w.RunOnce(ctx)
+
+	// Second run should fire one expiry warning
+	w.RunOnce(ctx)
+
+	// Third run should NOT fire another warning (dedup)
+	w.RunOnce(ctx)
+
+	notifications := deps.notifier.getNotifications()
+
+	expiryCount := 0
+
+	for _, n := range notifications {
+		if n.Title == "TLS Expiry Warning: www.example.com" {
+			expiryCount++
+		}
+	}
+
+	if expiryCount != 1 {
+		t.Errorf(
+			"expected exactly 1 expiry warning (dedup), got %d",
+			expiryCount,
+		)
+	}
+}
+
+func TestGracefulShutdown(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{testDomain}
+	cfg.DNSInterval = 100 * time.Millisecond
+	cfg.TLSInterval = 100 * time.Millisecond
+
+	w, deps := newTestWatcher(t, cfg)
+
+	deps.resolver.nsRecords[testDomain] = []string{
+		testNS1,
+	}
+	deps.resolver.allRecords[testDomain] = map[string]map[string][]string{
+		testNS1: {"A": {testIP}},
+	}
+	deps.portChecker.results["1.2.3.4:80"] = false
+	deps.portChecker.results["1.2.3.4:443"] = false
+
+	ctx, cancel := context.WithCancel(t.Context())
+
+	done := make(chan struct{})
+
+	go func() {
+		w.Run(ctx)
+		close(done)
+	}()
+
+	time.Sleep(250 * time.Millisecond)
+	cancel()
+
+	select {
+	case <-done:
+		// Shut down cleanly
+	case <-time.After(5 * time.Second):
+		t.Error("watcher did not shut down within timeout")
+	}
+}
+
+func setupHostnameIP(
+	deps *testDeps,
+	hostname, ip string,
+) {
+	deps.resolver.allRecords[hostname] = map[string]map[string][]string{
+		testNS1: {"A": {ip}},
+	}
+	deps.portChecker.results[ip+":80"] = true
+	deps.portChecker.results[ip+":443"] = true
+	deps.tlsChecker.certs[ip+":"+hostname] = &tlscheck.CertificateInfo{
+		CommonName:              hostname,
+		Issuer:                  testIssuer,
+		NotAfter:                time.Now().Add(90 * 24 * time.Hour),
+		SubjectAlternativeNames: []string{hostname},
+	}
+}
+
+func updateHostnameIP(deps *testDeps, hostname, ip string) {
+	deps.resolver.mu.Lock()
+	deps.resolver.allRecords[hostname] = map[string]map[string][]string{
+		testNS1: {"A": {ip}},
+	}
+	deps.resolver.mu.Unlock()
+
+	deps.portChecker.mu.Lock()
+	deps.portChecker.results[ip+":80"] = true
+	deps.portChecker.results[ip+":443"] = true
+	deps.portChecker.mu.Unlock()
+
+	deps.tlsChecker.mu.Lock()
+	deps.tlsChecker.certs[ip+":"+hostname] = &tlscheck.CertificateInfo{
+		CommonName:              hostname,
+		Issuer:                  testIssuer,
+		NotAfter:                time.Now().Add(90 * 24 * time.Hour),
+		SubjectAlternativeNames: []string{hostname},
+	}
+	deps.tlsChecker.mu.Unlock()
+}
+
+func TestDNSRunsBeforePortAndTLSChecks(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Hostnames = []string{testHost}
+
+	w, deps := newTestWatcher(t, cfg)
+
+	setupHostnameIP(deps, testHost, "10.0.0.1")
+
+	ctx := t.Context()
+	w.RunOnce(ctx)
+
+	snap := deps.state.GetSnapshot()
+	if _, ok := snap.Ports["10.0.0.1:80"]; !ok {
+		t.Fatal("expected port state for 10.0.0.1:80")
+	}
+
+	// DNS changes to a new IP; port and TLS must pick it up.
+	updateHostnameIP(deps, testHost, "10.0.0.2")
+
+	w.RunOnce(ctx)
+
+	snap = deps.state.GetSnapshot()
+
+	if _, ok := snap.Ports["10.0.0.2:80"]; !ok {
+		t.Error("port check used stale DNS: missing 10.0.0.2:80")
+	}
+
+	certKey := "10.0.0.2:443:www.example.com"
+	if _, ok := snap.Certificates[certKey]; !ok {
+		t.Error("TLS check used stale DNS: missing " + certKey)
+	}
+}
+
+func TestSendTestNotification_Enabled(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{testDomain}
+	cfg.Hostnames = []string{testHost}
+	cfg.SendTestNotification = true
+
+	w, deps := newTestWatcher(t, cfg)
+	setupBaselineMocks(deps)
+
+	w.RunOnce(t.Context())
+
+	// RunOnce does not send the test notification — it is
+	// sent by Run after RunOnce completes. Call the exported
+	// RunOnce then check that no test notification was sent
+	// (only Run triggers it). We test the full path via Run.
+	notifications := deps.notifier.getNotifications()
+	if len(notifications) != 0 {
+		t.Errorf(
+			"RunOnce should not send test notification, got %d",
+			len(notifications),
+		)
+	}
+}
+
+func TestSendTestNotification_ViaRun(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{testDomain}
+	cfg.Hostnames = []string{testHost}
+	cfg.SendTestNotification = true
+	cfg.DNSInterval = 24 * time.Hour
+	cfg.TLSInterval = 24 * time.Hour
+
+	w, deps := newTestWatcher(t, cfg)
+	setupBaselineMocks(deps)
+
+	ctx, cancel := context.WithCancel(t.Context())
+
+	done := make(chan struct{})
+
+	go func() {
+		w.Run(ctx)
+		close(done)
+	}()
+
+	// Wait for the initial scan and test notification.
+	time.Sleep(500 * time.Millisecond)
+	cancel()
+
+	<-done
+
+	notifications := deps.notifier.getNotifications()
+
+	found := false
+
+	for _, n := range notifications {
+		if n.Priority == "success" &&
+			n.Title == "✅ dnswatcher startup complete" {
+			found = true
+		}
+	}
+
+	if !found {
+		t.Errorf(
+			"expected startup test notification, got: %v",
+			notifications,
+		)
+	}
+}
+
+func TestSendTestNotification_Disabled(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Domains = []string{testDomain}
+	cfg.Hostnames = []string{testHost}
+	cfg.SendTestNotification = false
+	cfg.DNSInterval = 24 * time.Hour
+	cfg.TLSInterval = 24 * time.Hour
+
+	w, deps := newTestWatcher(t, cfg)
+	setupBaselineMocks(deps)
+
+	ctx, cancel := context.WithCancel(t.Context())
+
+	done := make(chan struct{})
+
+	go func() {
+		w.Run(ctx)
+		close(done)
+	}()
+
+	time.Sleep(500 * time.Millisecond)
+	cancel()
+
+	<-done
+
+	notifications := deps.notifier.getNotifications()
+
+	for _, n := range notifications {
+		if n.Title == "✅ dnswatcher startup complete" {
+			t.Error(
+				"test notification should not be sent when disabled",
+			)
+		}
+	}
+}
+
+func TestNSFailureAndRecovery(t *testing.T) {
+	t.Parallel()
+
+	cfg := defaultTestConfig(t)
+	cfg.Hostnames = []string{testHost}
+
+	w, deps := newTestWatcher(t, cfg)
+
+	deps.resolver.allRecords[testHost] = map[string]map[string][]string{
+		testNS1: {"A": {testIP}},
+		testNS2: {"A": {testIP}},
+	}
+	deps.resolver.ipAddresses[testHost] = []string{
+		testIP,
+	}
+	deps.portChecker.results["1.2.3.4:80"] = false
+	deps.portChecker.results["1.2.3.4:443"] = false
+
+	ctx := t.Context()
+
+	w.RunOnce(ctx)
+
+	deps.resolver.mu.Lock()
+	deps.resolver.allRecords[testHost] = map[string]map[string][]string{
+		testNS1: {"A": {testIP}},
+	}
+	deps.resolver.mu.Unlock()
+
+	w.RunOnce(ctx)
+
+	notifications := deps.notifier.getNotifications()
+	if len(notifications) == 0 {
+		t.Error("expected notification for NS disappearance")
+	}
+}

script/bootstrap

@@ -0,0 +1,90 @@
+#!/bin/sh
+# script/bootstrap: install all dependencies needed to build and develop
+# 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
+# "latest") because script/fmt runs it on the host; script/fmt-check
+# 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.
+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=""
+
+detect_pkgmgr() {
+    [ -n "$PKGMGR" ] && return 0
+    if command -v nix-env >/dev/null 2>&1; then
+        PKGMGR="nix"
+    elif command -v apt-get >/dev/null 2>&1; then
+        PKGMGR="apt"
+    elif command -v brew >/dev/null 2>&1; then
+        PKGMGR="brew"
+    elif command -v apk >/dev/null 2>&1; then
+        PKGMGR="apk"
+    else
+        echo "bootstrap: no supported package manager (nix, apt, brew, apk)" >&2
+        exit 1
+    fi
+    if [ "$PKGMGR" = "apt" ]; then
+        export DEBIAN_FRONTEND=noninteractive
+        if [ "$(id -u)" != "0" ]; then
+            SUDO="sudo"
+        fi
+    fi
+}
+
+# pkg_install <nix-attr> <apt-pkg> <brew-formula> <apk-pkg>
+pkg_install() {
+    detect_pkgmgr
+    case "$PKGMGR" in
+        nix) nix-env -iA "nixpkgs.$1" ;;
+        apt)
+            if [ -z "$APT_UPDATED" ]; then
+                $SUDO env DEBIAN_FRONTEND=noninteractive apt-get update
+                APT_UPDATED=1
+            fi
+            $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y "$2"
+            ;;
+        brew) brew install "$3" ;;
+        apk) apk add --no-cache "$4" ;;
+    esac
+}
+
+missing() {
+    ! command -v "$1" >/dev/null 2>&1
+}
+
+main() {
+    cd "$ROOT"
+
+    if missing git; then pkg_install git git git git; fi
+    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
+    # "$(go env GOPATH)/bin"; ensure that is on your PATH).
+    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
+    fi
+
+    go mod download
+
+    echo "bootstrap complete"
+}
+
+main "$@"

script/check

@@ -0,0 +1,14 @@
+#!/bin/sh
+# script/check: run all checks (test, lint, fmt-check). Our own
+# extension to scripts-to-rule-them-all. Must not modify any files.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/test"
+    "$SCRIPT_DIR/lint"
+    "$SCRIPT_DIR/fmt-check"
+}
+
+main "$@"

script/cibuild

@@ -0,0 +1,14 @@
+#!/bin/sh
+# script/cibuild: run the CI build. The Dockerfile's lint stage runs
+# make fmt-check and golangci-lint; its builder stage runs make test
+# and make build. A successful build implies all of those passed.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    docker build .
+}
+
+main "$@"

script/docker

@@ -0,0 +1,14 @@
+#!/bin/sh
+# script/docker: build the Docker image tagged with the project name.
+# Identical in all repos; the tag comes from script/projectname.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    docker build -t "$("$SCRIPT_DIR/projectname")" .
+}
+
+main "$@"

script/fmt

@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/fmt: format all files (writes).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    gofmt -s -w .
+    goimports -w .
+}
+
+main "$@"

script/fmt-check

@@ -0,0 +1,18 @@
+#!/bin/sh
+# script/fmt-check: check formatting (read-only). Same scope as
+# script/fmt, but fails instead of writing.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    files="$(gofmt -l .)"
+    if [ -n "$files" ]; then
+        echo "gofmt: files not formatted:" >&2
+        echo "$files" >&2
+        exit 1
+    fi
+}
+
+main "$@"

script/install-precommit

@@ -0,0 +1,16 @@
+#!/bin/sh
+# script/install-precommit: install the git pre-commit hook that runs
+# script/precommit. Our own extension to scripts-to-rule-them-all.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    hook=".git/hooks/pre-commit"
+    printf '#!/bin/sh\nset -e\nscript/precommit\n' > "$hook"
+    chmod +x "$hook"
+    echo "pre-commit hook installed: runs script/precommit"
+}
+
+main "$@"

script/lint

@@ -0,0 +1,28 @@
+#!/bin/sh
+# script/lint: run the linter. golangci-lint is never installed or run
+# on the host: it runs via docker only, one way, everywhere. This
+# builds Dockerfile.lint, which COPYs the repo into the digest-pinned
+# golangci-lint image and lints as a build step, so a successful build
+# means a clean lint.
+#
+# --no-cache-filter=lint forces the lint stage (source copy + linter
+# run) to execute on every invocation. Without it an unchanged tree
+# returns success in well under a second having linted nothing. The
+# deps stage (base image + go mod download) stays cached, and no global
+# cache invalidation is performed. --progress=plain keeps the linter's
+# own output visible.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    docker build \
+        --progress=plain \
+        --no-cache-filter=lint \
+        --target lint \
+        -f Dockerfile.lint \
+        .
+}
+
+main "$@"

script/precommit

@@ -0,0 +1,21 @@
+#!/bin/sh
+# script/precommit: run by the git pre-commit hook; fails the commit if
+# checks fail. Our own extension to scripts-to-rule-them-all. Go extra:
+# go mod tidy must be a no-op before the checks run.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    go mod tidy
+    if ! git diff --exit-code -- go.mod go.sum; then
+        echo "precommit: go mod tidy changed go.mod/go.sum;" \
+            "stage the changes and retry" >&2
+        exit 1
+    fi
+    "$SCRIPT_DIR/check"
+}
+
+main "$@"

script/projectname

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/projectname: output the name of this project. Our own
+# extension to scripts-to-rule-them-all. Other scripts that need the
+# name (e.g. script/docker) call this, so they can stay identical
+# across all repos.
+set -eu
+
+main() {
+    echo "dnswatcher"
+}
+
+main "$@"

script/setup

@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/setup: set up the repo for development after a fresh clone:
+# installs dependencies and the git pre-commit hook.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/bootstrap"
+    "$SCRIPT_DIR/install-precommit"
+}
+
+main "$@"

script/test

@@ -0,0 +1,35 @@
+#!/bin/sh
+# script/test: run the test suite.
+#
+# -count=1 disables Go's test cache, and is load-bearing here. This
+# suite queries live DNS on every run by policy (TESTING.md); a cached
+# result is a replay of an earlier run's output with no query made at
+# 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)"
+
+main() {
+    cd "$ROOT"
+    go test -count=1 -race -timeout 90s -cover ./... || {
+        echo "--- Rerunning with -v for details ---" >&2
+        go test -count=1 -race -timeout 90s -v ./... || true
+        exit 1
+    }
+}
+
+main "$@"

static/static.go

@@ -0,0 +1,10 @@
+// Package static provides embedded static assets.
+package static
+
+import "embed"
+
+// Static contains the embedded static assets (CSS, JS) served
+// at the /s/ URL prefix.
+//
+//go:embed css
+var Static embed.FS