Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 sneak
|
c302f1399d |
+9
-75
@@ -1,75 +1,9 @@
|
||||
# .dockerignore does NOT use .gitignore semantics. Docker matches with
|
||||
# moby/patternmatcher: filepath.Match plus `**`, so `*` does not cross
|
||||
# `/` and an unprefixed pattern is anchored at the context root. Every
|
||||
# depth-independent pattern therefore needs `**/`, or `config/.env` and
|
||||
# `certs/server.key` still ship while this file reads as solved. Only
|
||||
# genuinely root-anchored entries go unprefixed. Never transplant these
|
||||
# into .gitignore, where `**/` is wrong.
|
||||
#
|
||||
# Matching is case-sensitive, so secrets use character ranges rather
|
||||
# than an ALL-CAPS twin, which would still miss `Server.Key`.
|
||||
#
|
||||
# Extend with this repo's own host-built artifacts, written anchored:
|
||||
# `/myapp`, never `**/myapp`, which also matches `cmd/myapp/` and
|
||||
# deletes the package directory from the context.
|
||||
|
||||
# .git is sent without its config. Without a VERSION build argument the
|
||||
# stage that compiles runs `git describe --tags --always` on .git, which
|
||||
# does not need .git/config; that file can hold a credential, such as a
|
||||
# password in a remote URL or the token the CI checkout step stores there.
|
||||
# Each submodule keeps a config with the same exposure in its git directory
|
||||
# under .git/modules/, nested again for a submodule's own submodules, or in
|
||||
# its own .git directory when it keeps one.
|
||||
# KNOWN GAP: a submodule whose name has a `config` segment (`config`,
|
||||
# `deploy/config`, `config/lib`) loses its whole git directory, because
|
||||
# `**/.git/modules/**/config` also matches that segment's directory
|
||||
# under .git/modules/. Go's version stamping then fails the build;
|
||||
# nothing leaks. Name such a submodule without that segment:
|
||||
# `git submodule add --name`.
|
||||
**/.git/config
|
||||
**/.git/modules/**/config
|
||||
|
||||
# Agent scratch: one full checkout of the repo per in-flight agent.
|
||||
# Anchored because it occurs once where agents run at the repo root.
|
||||
# KNOWN GAP: a repo running agents in subdirectories still ships
|
||||
# `services/api/.claude/` and must add its own anchored entry.
|
||||
.claude
|
||||
|
||||
# Environment files. `*.env` covers bare `.env` and the `prod.env`
|
||||
# convention. Re-include a committed template with a negation if the
|
||||
# build needs one: `!docs/example.env`.
|
||||
**/*.[eE][nN][vV]
|
||||
**/.[eE][nN][vV].*
|
||||
**/.[eE][nN][vV][rR][cC]
|
||||
|
||||
# Private keys and the bundles carrying them. Public certificates
|
||||
# (*.crt, *.cer) are deliberately absent: they are legitimate inputs.
|
||||
**/*.[pP][eE][mM]
|
||||
**/*.[kK][eE][yY]
|
||||
**/*.[pP]12
|
||||
**/*.[pP][fF][xX]
|
||||
**/[iI][dD]_[rR][sS][aA]
|
||||
**/[iI][dD]_[dD][sS][aA]
|
||||
**/[iI][dD]_[eE][cC][dD][sS][aA]
|
||||
**/[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK]
|
||||
**/[iI][dD]_[eE][dD]25519
|
||||
**/[iI][dD]_[eE][dD]25519_[sS][kK]
|
||||
|
||||
# Dependencies: restored inside the image, never copied in.
|
||||
**/node_modules
|
||||
|
||||
# OS metadata.
|
||||
**/.DS_Store
|
||||
**/Thumbs.db
|
||||
|
||||
# Editor state: never a build input, and it churns COPY.
|
||||
**/*.swp
|
||||
**/*.swo
|
||||
**/*~
|
||||
**/*.bak
|
||||
**/.idea
|
||||
**/.vscode
|
||||
**/*.sublime-*
|
||||
|
||||
# This repository's host-built artifacts: `make build` writes bin/.
|
||||
/bin
|
||||
# .git is sent, without its config: the builder stage derives the version it
|
||||
# stamps into the binary from it, and `git describe` does not need the config,
|
||||
# which can hold a credential (a password in the remote URL, a CI token). No
|
||||
# tracked file may be listed here: git in the build would see it as deleted
|
||||
# and mark the version -dirty, and an excluded .md would silently drop out of
|
||||
# the prettier check in Dockerfile.fmt.
|
||||
.git/config
|
||||
bin/
|
||||
node_modules/
|
||||
|
||||
@@ -10,6 +10,3 @@ insert_final_newline = true
|
||||
|
||||
[Makefile]
|
||||
indent_style = tab
|
||||
|
||||
[*.go]
|
||||
indent_style = tab
|
||||
|
||||
@@ -9,7 +9,7 @@ jobs:
|
||||
check:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
# actions/checkout v4.2.2, 2026-02-22
|
||||
# actions/checkout v4.2.2, 2026-02-28
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
|
||||
# script/cibuild needs no token, so none is left in .git/config.
|
||||
with:
|
||||
|
||||
+2
-52
@@ -1,57 +1,7 @@
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Editors
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
*.bak
|
||||
.idea/
|
||||
.vscode/
|
||||
*.sublime-*
|
||||
|
||||
# Agent scratch (worktrees of this repo, created and destroyed by
|
||||
# in-flight tooling). Unanchored: .gitignore patterns already match at
|
||||
# every depth, so no prefix is wanted here. This is not a .dockerignore
|
||||
# entry and must not be given a `**/` prefix on the way into one.
|
||||
.claude/
|
||||
|
||||
# Node
|
||||
node_modules/
|
||||
|
||||
# Secrets. Unanchored like every entry above, so each matches at every
|
||||
# depth. Matching is case-sensitive on Linux, so names use character
|
||||
# ranges rather than a lowercase form that misses `Server.Key`.
|
||||
|
||||
# Environment files. `*.env` covers bare `.env` and the `prod.env`
|
||||
# convention. Only the templates `example.env` and `sample.env` are
|
||||
# re-included below. A repository that commits any other template adds
|
||||
# its own negation after these lines, for example `!.env.example`.
|
||||
*.[eE][nN][vV]
|
||||
.[eE][nN][vV].*
|
||||
.[eE][nN][vV][rR][cC]
|
||||
!example.env
|
||||
!sample.env
|
||||
|
||||
# Private keys and the bundles carrying them.
|
||||
*.[pP][eE][mM]
|
||||
*.[kK][eE][yY]
|
||||
*.[pP]12
|
||||
*.[pP][fF][xX]
|
||||
[iI][dD]_[rR][sS][aA]
|
||||
[iI][dD]_[dD][sS][aA]
|
||||
[iI][dD]_[eE][cC][dD][sS][aA]
|
||||
[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK]
|
||||
[iI][dD]_[eE][dD]25519
|
||||
[iI][dD]_[eE][dD]25519_[sS][kK]
|
||||
|
||||
# This repository's own entries, kept after the canonical content above.
|
||||
*.log
|
||||
*.out
|
||||
*.test
|
||||
bin/
|
||||
node_modules/
|
||||
vendor/
|
||||
data/
|
||||
.env
|
||||
*.exe
|
||||
/dnswatcher
|
||||
|
||||
@@ -17,7 +17,6 @@ linters:
|
||||
disable:
|
||||
# Genuinely incompatible with project patterns
|
||||
- exhaustruct # Requires all struct fields
|
||||
- exhaustruct_v5 # Requires all struct fields (successor to exhaustruct)
|
||||
- godot # Requires comments to end with periods
|
||||
- wrapcheck # Too verbose for internal packages
|
||||
- varnamelen # Short names like db, id are idiomatic Go
|
||||
|
||||
+4
-1
@@ -1,2 +1,5 @@
|
||||
bin/
|
||||
data/
|
||||
node_modules/
|
||||
yarn.lock
|
||||
.claude/
|
||||
static/css/tailwind.min.css
|
||||
|
||||
+50
-84
@@ -1,102 +1,68 @@
|
||||
# Lint phase, built alone by script/lint. The linter is invoked directly
|
||||
# rather than through `make lint`, which is itself a docker build and
|
||||
# would recurse into a daemon that does not exist in a build step.
|
||||
# golangci/golangci-lint:v2.14.0 (Debian-based), 2026-10-06
|
||||
FROM golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f AS lint
|
||||
# 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. For the same reason this stage
|
||||
# runs only the Go half of `make fmt-check`; script/cibuild runs the
|
||||
# markdown half after this build.
|
||||
# script/cibuild and script/docker name this stage in --no-cache-filter.
|
||||
# golangci/golangci-lint:v2.12.2 (Debian-based), 2026-08-10
|
||||
FROM golangci/golangci-lint:v2.12.2@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240 AS lint
|
||||
|
||||
WORKDIR /src
|
||||
COPY go.mod go.sum ./
|
||||
RUN go mod download
|
||||
|
||||
COPY . .
|
||||
|
||||
RUN script/fmt-check-go
|
||||
RUN golangci-lint run --config .golangci.yml ./...
|
||||
|
||||
# Test phase, built alone by script/test. -race needs cgo and so a C
|
||||
# compiler, which the Debian Go image ships and the alpine one does not.
|
||||
# The tests query live DNS (TESTING.md), so this step needs the network.
|
||||
# -count=1 keeps Go's test result cache out of both runs, as TESTING.md
|
||||
# requires. -timeout 90s is a backstop above the 60-second cap on the
|
||||
# suite. The rerun with -v only shows details: the build fails however
|
||||
# it ends, because the first run already failed.
|
||||
# golang 1.25.7-trixie, 2026-10-06
|
||||
FROM golang@sha256:2b174ffcf56c7ad0c47d30d2630693265639ddf2a5141149c2da34db921791b4 AS test
|
||||
# The file permission tests skip themselves as root, so the tests run as
|
||||
# an ordinary user, whose home directory holds Go's build cache.
|
||||
RUN useradd --create-home tester
|
||||
USER tester
|
||||
WORKDIR /src
|
||||
COPY go.mod go.sum ./
|
||||
RUN go mod download
|
||||
COPY . .
|
||||
RUN go test -count=1 -race -timeout 90s -cover ./... || \
|
||||
{ echo "--- Rerunning with -v for details ---"; \
|
||||
go test -count=1 -race -timeout 90s -v ./...; exit 1; }
|
||||
|
||||
# Markdown formatting with prettier, at the version package.json and
|
||||
# yarn.lock pin, so it is never installed on the host. script/fmt-check
|
||||
# builds the fmt-check stage and script/fmt the fmt-out stage; the image
|
||||
# does not depend on any of these stages, so a plain `docker build .`
|
||||
# skips them.
|
||||
# node:22-bookworm-slim, 2026-09-05
|
||||
FROM node@sha256:83f487e0a63425e5b4d146fb5e5be574bcbe1b7b843d3ebafdd95eaf7767a7e5 AS nodedeps
|
||||
# prettier lives outside /src, so the COPY of the repo cannot overwrite
|
||||
# it and node_modules is not in the tree prettier walks.
|
||||
WORKDIR /tools
|
||||
COPY package.json yarn.lock ./
|
||||
RUN yarn install --frozen-lockfile --non-interactive --no-progress
|
||||
ENV PATH="/tools/node_modules/.bin:${PATH}"
|
||||
WORKDIR /src
|
||||
|
||||
# --config rather than discovery: a missing .prettierrc is then an error
|
||||
# instead of prettier's defaults, under which every wrap passes.
|
||||
# --no-editorconfig so .prettierrc alone sets the style.
|
||||
FROM nodedeps AS fmt-check
|
||||
COPY . .
|
||||
RUN prettier --config .prettierrc --no-editorconfig --check "**/*.md"
|
||||
|
||||
# Only the markdown is copied out, with its paths, so the export cannot
|
||||
# put anything else back over the working tree.
|
||||
FROM nodedeps AS fmt
|
||||
COPY . .
|
||||
RUN prettier --config .prettierrc --no-editorconfig --write "**/*.md" && \
|
||||
mkdir -p /out && \
|
||||
find . -name '*.md' -type f -exec cp --parents '{}' /out/ ';'
|
||||
|
||||
FROM scratch AS fmt-out
|
||||
COPY --from=fmt /out/ /
|
||||
|
||||
# Build stage. Nothing is wanted from the lint and test phases; the
|
||||
# copies are what make BuildKit build them first, so this stage cannot
|
||||
# run unless lint and test passed.
|
||||
# Build stage
|
||||
# script/cibuild and script/docker name this stage in --no-cache-filter.
|
||||
# golang 1.25-alpine, 2026-02-28
|
||||
FROM golang@sha256:f6751d823c26342f9506c03797d2527668d095b0a15f1862cddb4d927a7a4ced AS builder
|
||||
COPY --from=lint /src/go.sum /dev/null
|
||||
COPY --from=test /src/go.sum /dev/null
|
||||
RUN apk add --no-cache git
|
||||
# A tar-stream context keeps the sender's file owners, which git refuses.
|
||||
|
||||
RUN apk add --no-cache git make gcc musl-dev binutils-gold
|
||||
|
||||
# A build context sent as a tar archive keeps its files' owners, and git
|
||||
# refuses to read a checkout owned by another user. Trust this one
|
||||
# whoever owns it.
|
||||
RUN git config --system --add safe.directory /src
|
||||
|
||||
# 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 . .
|
||||
|
||||
# The VERSION build arg when one is given (script/docker and
|
||||
# script/cibuild pass one), otherwise `git describe --tags --always` on
|
||||
# the .git in the build context. With .git present, a version that is
|
||||
# still empty, dev or unknown fails the build: git is missing or could
|
||||
# not read the checkout.
|
||||
ARG VERSION
|
||||
RUN VERSION="${VERSION:-$(git describe --tags --always)}"; \
|
||||
if [ -e .git ]; then \
|
||||
case "$VERSION" in ""|dev|unknown) \
|
||||
echo "version is '$VERSION' although .git is present" >&2; \
|
||||
exit 1 ;; \
|
||||
esac; \
|
||||
fi; \
|
||||
CGO_ENABLED=0 go build -trimpath \
|
||||
-ldflags="-s -w -X main.Version=${VERSION}" \
|
||||
-o /src/bin/dnswatcher ./cmd/dnswatcher/
|
||||
# Run the tests - build fails if any test fails
|
||||
RUN make test
|
||||
|
||||
# Runtime stage, and the last one: a plain `docker build .` builds this
|
||||
# stage's chain and nothing else.
|
||||
# Version stamped into the binary: the VERSION build arg when one is
|
||||
# given and not empty (script/docker passes one), otherwise what
|
||||
# `git describe` says of the .git in the build context, so a plain
|
||||
# `docker build .` of a clone stamps its tag or short commit. The build
|
||||
# arg reaches make through the environment.
|
||||
ARG VERSION
|
||||
|
||||
# A context that carries .git, as a directory or as a file, must yield a
|
||||
# real version: one that is empty, `dev` or `unknown` cannot be traced
|
||||
# back to a commit.
|
||||
RUN version="$(make version)"; \
|
||||
if [ -e .git ]; then \
|
||||
case "$version" in \
|
||||
"" | dev | unknown) \
|
||||
echo "version is \"$version\" although the build context carries .git" >&2; \
|
||||
exit 1 ;; \
|
||||
esac; \
|
||||
fi
|
||||
|
||||
RUN make build
|
||||
|
||||
# Runtime stage
|
||||
# alpine 3.21, 2026-02-28
|
||||
FROM alpine@sha256:c3f8e73fdb79deaebaa2037150150191b9dcbfba68b4a46d70103204c53f4709
|
||||
|
||||
|
||||
@@ -0,0 +1,54 @@
|
||||
# prettier over the markdown, in a container, so it is never installed
|
||||
# on the host. script/fmt-check-markdown builds the fmt-check stage;
|
||||
# script/fmt builds fmt-out and takes the formatted files back.
|
||||
|
||||
# node:22-bookworm-slim, 2026-09-05
|
||||
FROM node:22-bookworm-slim@sha256:83f487e0a63425e5b4d146fb5e5be574bcbe1b7b843d3ebafdd95eaf7767a7e5 AS nodedeps
|
||||
|
||||
# prettier lives outside /src so that a `COPY . .` of the repo cannot
|
||||
# overwrite it, and so that node_modules never appears in the tree
|
||||
# prettier is about to walk.
|
||||
WORKDIR /tools
|
||||
|
||||
# package.json pins the version and yarn.lock pins the bytes:
|
||||
# --frozen-lockfile installs exactly the lockfile's resolution and fails
|
||||
# if package.json disagrees with it, so the tool cannot float between
|
||||
# runs. yarn is the one in the image above.
|
||||
COPY package.json yarn.lock ./
|
||||
RUN yarn install --frozen-lockfile --non-interactive --no-progress
|
||||
|
||||
ENV PATH="/tools/node_modules/.bin:${PATH}"
|
||||
|
||||
WORKDIR /src
|
||||
|
||||
# Read-only markdown check. Must match $stage in
|
||||
# script/fmt-check-markdown.
|
||||
FROM nodedeps AS fmt-check
|
||||
|
||||
COPY . .
|
||||
|
||||
# --config, not discovery: a .prettierrc that failed to arrive would
|
||||
# otherwise leave prettier on its defaults, where proseWrap is "preserve"
|
||||
# and every wrap this check exists to enforce passes. Missing the file is
|
||||
# a hard error instead. --no-editorconfig so that .prettierrc alone sets
|
||||
# the style.
|
||||
RUN prettier --config .prettierrc --no-editorconfig --check "**/*.md"
|
||||
|
||||
# Write path. Not a check: script/fmt builds this and takes the files.
|
||||
FROM nodedeps AS fmt
|
||||
|
||||
COPY . .
|
||||
|
||||
RUN prettier --config .prettierrc --no-editorconfig --write "**/*.md"
|
||||
|
||||
# Only the markdown leaves, with its paths intact, so that the export
|
||||
# below cannot put anything else back over the caller's working tree.
|
||||
RUN mkdir -p /out && cd /src && \
|
||||
find . -name '*.md' -type f -exec cp --parents '{}' /out/ ';'
|
||||
|
||||
# Export target: `docker build --target fmt-out --output type=local`
|
||||
# writes /out's tree into a directory on the client, which is how
|
||||
# script/fmt gets formatted markdown back without a bind mount.
|
||||
# Must match $stage in script/fmt.
|
||||
FROM scratch AS fmt-out
|
||||
COPY --from=fmt /out/ /
|
||||
@@ -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 ./...
|
||||
@@ -2,9 +2,9 @@
|
||||
|
||||
BINARY := dnswatcher
|
||||
# VERSION given on the command line (`make build VERSION=...`) or in the
|
||||
# environment wins over what `git describe` says of this checkout. An
|
||||
# empty one counts as not given; `override` is what replaces an empty
|
||||
# command-line value.
|
||||
# environment, which is how the Dockerfile's VERSION build arg arrives,
|
||||
# wins over what `git describe` says of this checkout. An empty one counts
|
||||
# as not given; `override` is what replaces an empty command-line value.
|
||||
ifeq ($(VERSION),)
|
||||
override VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
|
||||
endif
|
||||
@@ -25,7 +25,7 @@ setup:
|
||||
build:
|
||||
go build -ldflags "$(LDFLAGS)" -o bin/$(BINARY) ./cmd/dnswatcher
|
||||
|
||||
# Prints the version `make build` stamps.
|
||||
# Prints the version `make build` stamps; the Dockerfile checks it.
|
||||
version:
|
||||
@echo "$(VERSION)"
|
||||
|
||||
|
||||
@@ -78,9 +78,8 @@ notification endpoint set, changes show only on the dashboard; see
|
||||
answer NXDOMAIN, that it does not exist, has no nameservers and is shown as
|
||||
not existing (see Web Dashboard and HTTP API). A domain that exists but has no
|
||||
delegation of its own, such as `octocat.github.io`, has no nameservers either.
|
||||
When the parent zone's servers do not answer, or the lookup of the domain's
|
||||
own records (below) fails, the check fails and the set from the previous check
|
||||
is kept.
|
||||
When the parent zone's servers do not answer, the check fails and the set from
|
||||
the previous check is kept.
|
||||
- Any change triggers a notification:
|
||||
- NS added to or removed from that set. A domain that had nameservers on the
|
||||
previous check and no longer exists gets one with all of them removed.
|
||||
@@ -100,18 +99,11 @@ notification endpoint set, changes show only on the dashboard; see
|
||||
records, stored per nameserver. Their changes are notified as a hostname's
|
||||
are, as a record change, NS query failure, NS recovery, inconsistency or CNAME
|
||||
address change, in a message that starts `Domain:` where a hostname's starts
|
||||
`Hostname:`. A nameserver removed from the domain's delegation gets only the
|
||||
NS change notification above. A domain listed in
|
||||
`DNSWATCHER_SKIP_RECORD_NOTIFICATIONS` gets no record change or inconsistency
|
||||
notification. A domain with no delegation of its own has these records asked
|
||||
at the servers of the zone it is in, as a hostname has. When none of those
|
||||
servers answers, the lookup of its NS record set fails, and they are saved as
|
||||
failed and notified as a hostname's are (see below). A nameserver the domain's
|
||||
records were asked at on the previous check but not on this one gets a
|
||||
hostname's NS change notification (see below), unless it was in the domain's
|
||||
delegation on the previous check, as when that delegation is withdrawn. A
|
||||
domain that does not exist has none: they are not asked for, and those saved
|
||||
by an earlier check are removed without a notification.
|
||||
`Hostname:`. A domain listed in `DNSWATCHER_SKIP_RECORD_NOTIFICATIONS` gets no
|
||||
record change or inconsistency notification. A domain with no delegation of
|
||||
its own has these records asked at the servers of the zone it is in, as a
|
||||
hostname has. A domain that does not exist has none: they are not asked for,
|
||||
and those saved by an earlier check are removed without a notification.
|
||||
|
||||
### DNS Hostname Monitoring (Subdomains)
|
||||
|
||||
@@ -123,13 +115,7 @@ notification endpoint set, changes show only on the dashboard; see
|
||||
trace moves from a name to its parent only when the servers asked answer that
|
||||
the name has no delegation of its own, or does not exist. When they do not
|
||||
answer, the check fails and the hostname's records from the previous check are
|
||||
kept, unless they are the nameservers the previous check saved for the
|
||||
hostname. Each of those is then saved as failed, with the reason, as a
|
||||
domain's nameservers are when none of them answers, so it gets an NS query
|
||||
failure notification, and an NS recovery notification when it answers again
|
||||
(see below). A trace that gets no answer before it reaches them, as when the
|
||||
host running dnswatcher loses its network, fails the check without a
|
||||
notification.
|
||||
kept.
|
||||
- Queries **each** authoritative nameserver independently for **all** record
|
||||
types: A, AAAA, CNAME, MX, TXT, SRV, CAA, NS.
|
||||
- Each record type is a query of its own. When a nameserver answers some types
|
||||
@@ -170,10 +156,6 @@ notification endpoint set, changes show only on the dashboard; see
|
||||
- **NS recovery**: A previously-unreachable nameserver starts responding
|
||||
again. Its records are not compared with those from before it failed, so a
|
||||
change made while it was failing is not reported as a record change.
|
||||
- **NS change**: A nameserver of the zone the hostname is in on the previous
|
||||
check is not one now, whether or not it answered. One notification lists
|
||||
every such nameserver on a `Removed:` line. Nothing is sent for a
|
||||
nameserver that joins the zone.
|
||||
- **Inconsistency detected**: Two nameservers return different record sets
|
||||
for the same hostname and did not already differ on the previous check.
|
||||
Every pair of nameservers is compared. The alert is sent once for each
|
||||
@@ -231,14 +213,8 @@ notification endpoint set, changes show only on the dashboard; see
|
||||
- Certificate CN, issuer, or SANs changed (replacement detected, reports old
|
||||
and new CN and issuer).
|
||||
- TLS connection failure to a previously-reachable IP:443 (handshake error,
|
||||
timeout, or connection refused when port 443 closed after the port check
|
||||
that found it open).
|
||||
timeout, connection refused after previously succeeding).
|
||||
- TLS recovery: a previously-failing IP:443 now completes a handshake again.
|
||||
- A port check that finds port 443 closed removes the certificate entries for
|
||||
that IP address, without a notification of its own: the port change
|
||||
notification reports the closed port. When the port opens again, the next TLS
|
||||
check saves the certificate as new, without a certificate change or recovery
|
||||
notification.
|
||||
|
||||
### Notifications
|
||||
|
||||
@@ -261,9 +237,7 @@ includes:
|
||||
|
||||
- **DNS record changes**: Which hostname or domain, which nameserver, what
|
||||
record type, old values, new values.
|
||||
- **DNS NS changes**: Which domain, which nameservers were added to or removed
|
||||
from its delegation. For a hostname, or a domain with no delegation of its
|
||||
own, which nameservers left the zone it is in.
|
||||
- **DNS NS changes**: Which domain, which nameservers were added/removed.
|
||||
- **NS address changes**: Which domain, which nameserver, its old and new
|
||||
addresses.
|
||||
- **CNAME address changes**: Which hostname or domain, the old and new addresses
|
||||
@@ -308,10 +282,8 @@ clears them.
|
||||
port entry left with no name goes, so the dashboard and `/api/v1/status` no
|
||||
longer list or count it. The first check's port checks remove the port entries
|
||||
of addresses no configured name has.
|
||||
- Each port check also removes, without a notification, the certificate entries
|
||||
for an address whose port 443 it found closed, and those for an address their
|
||||
name no longer resolves to, except while none of the name's nameservers
|
||||
answer.
|
||||
- Each port check also removes the certificate entries for an address their name
|
||||
no longer resolves to, except while none of the name's nameservers answer.
|
||||
|
||||
### Web Dashboard
|
||||
|
||||
@@ -451,7 +423,7 @@ following precedence (highest to lowest):
|
||||
|
||||
| Variable | Description | Default |
|
||||
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
|
||||
| `PORT` | HTTP listen port; a port that cannot be bound, such as one already in use, stops startup | `8080` |
|
||||
| `PORT` | HTTP listen port | `8080` |
|
||||
| `DNSWATCHER_DEBUG` | Enable debug logging | `false` |
|
||||
| `DNSWATCHER_DATA_DIR` | Directory for state file | `/var/lib/dnswatcher` |
|
||||
| `DNSWATCHER_TARGETS` | Comma-separated DNS names (auto-classified via PSL) | `""` |
|
||||
@@ -465,7 +437,7 @@ following precedence (highest to lowest):
|
||||
| `DNSWATCHER_SENTRY_DSN` | Sentry DSN for error reporting | `""` |
|
||||
| `DNSWATCHER_MAINTENANCE_MODE` | Only sets `maintenanceMode` in the health check response; changes nothing else | `false` |
|
||||
| `DNSWATCHER_METRICS_USERNAME` | Basic auth username for /metrics, which is served only when this is set | `""` |
|
||||
| `DNSWATCHER_METRICS_PASSWORD` | Basic auth password for /metrics; required when `DNSWATCHER_METRICS_USERNAME` is set, and startup stops without it | `""` |
|
||||
| `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
|
||||
@@ -491,16 +463,6 @@ or empty variable (`DNSWATCHER_DNS_INTERVAL=`) means the default. If either is
|
||||
set to anything else, including a bare number or a zero or negative duration,
|
||||
dnswatcher refuses to start with an error naming the variable and the value.
|
||||
|
||||
**`PORT` and `DNSWATCHER_TLS_EXPIRY_WARNING`** take a whole number: 1 to 65535
|
||||
for `PORT`, and a number of days, 1 or more, for
|
||||
`DNSWATCHER_TLS_EXPIRY_WARNING`. `DNSWATCHER_DEBUG`,
|
||||
`DNSWATCHER_MAINTENANCE_MODE` and `DNSWATCHER_SEND_TEST_NOTIFICATION` take
|
||||
`true` or `false`; `1`, `t`, `T`, `TRUE` and `True` also mean true, and `0`,
|
||||
`f`, `F`, `FALSE` and `False` also mean false. An unset or empty variable means
|
||||
the default. Any other value, such as `PORT=http`,
|
||||
`DNSWATCHER_TLS_EXPIRY_WARNING=7d` or `DNSWATCHER_DEBUG=yes`, makes dnswatcher
|
||||
refuse to start with an error naming the variable and the value.
|
||||
|
||||
**`DNSWATCHER_SENTRY_DSN` reports crashes in HTTP requests to Sentry.** When it
|
||||
is set, a panic in an HTTP request handler is sent to Sentry, and the request
|
||||
still gets a `500 Internal Server Error` answer. Nothing else is sent to Sentry:
|
||||
@@ -674,20 +636,10 @@ for A, AAAA and CNAME, the previous check's list is kept, or `null` when no
|
||||
earlier check saved one. A state file without it loads, and the first check
|
||||
after that saves it without a notification.
|
||||
|
||||
A port entry's key is its address and port, and a certificate entry's key its
|
||||
address, port 443 and hostname, joined by colons. An IPv6 address is written in
|
||||
brackets in these keys, as in `[2001:db8::1]:443` and
|
||||
`[2001:db8::1]:443:www.example.com`. `/api/v1/status` and the dashboard show the
|
||||
same keys.
|
||||
|
||||
A port entry's `hostnames` lists every name that resolves to its address,
|
||||
domains included. A port entry in the older format, with one `hostname` instead
|
||||
of the `hostnames` list, loads as a list of that one name.
|
||||
|
||||
A state file that leaves out any of `domains`, `hostnames`, `ports` and
|
||||
`certificates`, or holds `null` for one, loads with that section empty. A file
|
||||
holding `{}` loads as empty state.
|
||||
|
||||
---
|
||||
|
||||
## Entrypoints
|
||||
@@ -704,42 +656,48 @@ provide:
|
||||
- `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) by building the
|
||||
`Dockerfile`'s test phase, which queries live DNS. `-count=1` keeps Go's test
|
||||
result cache out. Failures are rerun with `-v` automatically, and the build
|
||||
- `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 by building the `Dockerfile`'s lint phase,
|
||||
on the digest-pinned `golangci-lint` image, so a successful build is a clean
|
||||
lint. The linter is never installed or run on the host, and Docker is the only
|
||||
prerequisite.
|
||||
- `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) and all Markdown
|
||||
(prettier). goimports runs with `go run` at a pinned commit, never from your
|
||||
`PATH`. prettier runs inside Docker, in a stage of the `Dockerfile` on a
|
||||
`PATH`. prettier runs inside Docker, built from `Dockerfile.fmt` on a
|
||||
digest-pinned node image, at the version pinned by `package.json` and
|
||||
`yarn.lock`; it is never installed on the host.
|
||||
- `script/fmt-check` — check formatting (read-only) with the same tools, failing
|
||||
on any file `script/fmt` would change: gofmt and goimports on the host,
|
||||
prettier inside Docker
|
||||
on any file `script/fmt` would change. It runs the two scripts below.
|
||||
- `script/fmt-check-go` — the gofmt and goimports half, on the host. The
|
||||
`Dockerfile` lint stage runs it.
|
||||
- `script/fmt-check-markdown` — the prettier half, inside Docker, forced to
|
||||
execute on every run with `--no-cache-filter`
|
||||
- `script/check` — run test, lint, and fmt-check
|
||||
- `script/docker` — build the Docker image tagged via `script/projectname`, with
|
||||
the version from `git describe` passed as `--build-arg VERSION`
|
||||
- `script/cibuild` — CI entrypoint: `script/bootstrap`, then `script/check`,
|
||||
then the image build `script/docker` does, which runs the lint and test phases
|
||||
again
|
||||
`--no-cache-filter=lint,builder` so the lint stage and the builder stage,
|
||||
which runs the tests, run on every invocation, and with the version from
|
||||
`git describe` passed as `--build-arg VERSION`
|
||||
- `script/cibuild` — CI entrypoint: `docker build` with
|
||||
`--no-cache-filter=lint,builder`, so the lint stage and the builder stage,
|
||||
which runs the tests, run on every invocation, because a cached build lints
|
||||
nothing and queries no DNS; then `script/fmt-check-markdown`
|
||||
- `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
|
||||
|
||||
Linting and testing are phases of the `Dockerfile`, and the image is built only
|
||||
when both pass. Every `docker build` in `script/` passes `--no-cache`, because a
|
||||
cached build lints nothing and queries no DNS.
|
||||
|
||||
## Building
|
||||
|
||||
```sh
|
||||
make build # Build binary to bin/dnswatcher
|
||||
make version # Print the version make build stamps
|
||||
make test # Run tests with race detector in Docker (requires docker)
|
||||
make test # Run tests with race detector
|
||||
make lint # Run golangci-lint in Docker (requires docker)
|
||||
make fmt # Format code and Markdown (requires docker)
|
||||
make check # Run all checks (test, lint, fmt-check)
|
||||
@@ -754,20 +712,21 @@ the environment, otherwise from `git describe --tags --always --dirty`, and
|
||||
`dev` without git metadata. An empty `VERSION` counts as not given. The version
|
||||
appears in the startup log and in the health check response.
|
||||
|
||||
The image takes it from `git describe --tags --always` on the `.git` the build
|
||||
context carries, so a plain `docker build .` of a clone stamps the commit it was
|
||||
built from; a clone without tags stamps the short commit. A clone made with
|
||||
`--depth 1` carries at most a tag on its own commit, so such a clone of an
|
||||
untagged commit stamps the short commit. In a build from a directory,
|
||||
`.dockerignore` keeps out `.git/config` and every submodule's git config, which
|
||||
`git describe` does not need and which can hold a credential. Docker does not
|
||||
apply `.dockerignore` to a context sent as a tar archive, as upaas sends it, so
|
||||
that context carries `.git/config` into the build. It also keeps its files'
|
||||
owners, so git in the build trusts the checkout whoever owns it. A non-empty
|
||||
`--build-arg VERSION=...` takes precedence; `make docker` passes the version
|
||||
`git describe` gives on the host. The build fails when the context carries
|
||||
`.git`, as a directory or as a file, and the version comes out empty, `dev` or
|
||||
`unknown`.
|
||||
The image takes it the same way, from the `.git` the build context carries, so a
|
||||
plain `docker build .` of a clone stamps the commit it was built from; a clone
|
||||
without tags stamps the short commit. A clone made with `--depth 1` carries at
|
||||
most a tag on its own commit, so such a clone of an untagged commit stamps the
|
||||
short commit. In a build from a directory, `.dockerignore` keeps out
|
||||
`.git/config`, which `git describe` does not need and which can hold a
|
||||
credential. Docker does not apply `.dockerignore` to a context sent as a tar
|
||||
archive, as upaas sends it, so that context carries `.git/config` into the
|
||||
build. It also keeps its files' owners, so git in the build trusts the checkout
|
||||
whoever owns it. A non-empty `--build-arg VERSION=...` takes precedence;
|
||||
`make docker` passes the version `git describe` gives on the host. The build
|
||||
fails when the context carries `.git`, as a directory or as a file, and the
|
||||
version comes out empty, `dev` or `unknown`. `.dockerignore` must list no
|
||||
tracked file: git in the build would see it as deleted and mark the version
|
||||
`-dirty`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
+88
-351
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Repository Policies
|
||||
last_modified: 2026-10-04
|
||||
last_modified: 2026-08-07
|
||||
---
|
||||
|
||||
This document covers repository structure, tooling, and workflow standards. Code
|
||||
@@ -60,28 +60,17 @@ style conventions are in separate documents:
|
||||
prerequisite since nvm requires bash. yarn is then pinned via
|
||||
`corepack prepare yarn@<version> --activate`. Never install "latest" or "lts";
|
||||
always exact versions. `script/cibuild` runs the CI build: it changes to the
|
||||
repo root, runs `script/bootstrap`, runs `script/check`, and builds the image
|
||||
with the version; the Gitea workflow calls it. **`script/cibuild` runs
|
||||
`script/bootstrap` first**, because the workflow checks out the repo and runs
|
||||
nothing else, while `script/fmt-check` runs the formatter on the host: on a
|
||||
pristine checkout with nothing installed the run dies there, after the
|
||||
containerised gates have passed. **The bootstrap alone is not enough**:
|
||||
`script/bootstrap` installs node and yarn under nvm and leaves neither on the
|
||||
`PATH` of the shell that called it, so a bare `yarn` still exits 127. The host
|
||||
entrypoints that need yarn — `script/fmt` and `script/fmt-check` — therefore
|
||||
source nvm for the pinned node version before invoking it, exactly as
|
||||
`script/bootstrap`'s own install step does. A runner carrying nothing but
|
||||
docker and git then gets through `script/check`. Four further scripts are our
|
||||
own extensions to the standard: `script/check` runs `script/test`,
|
||||
`script/lint` and `script/fmt-check`; `script/precommit` is what the git
|
||||
pre-commit hook runs, and it calls `script/check`; `script/install-precommit`
|
||||
installs the git pre-commit hook (the `make hooks` target shims to it); and
|
||||
`script/projectname` (literally that filename) simply outputs the project's
|
||||
name. Scripts that need the name call `script/projectname` — e.g.
|
||||
`script/docker` assembles its image tag from it — so those scripts stay
|
||||
byte-identical across all repos. Repo-type-specific pre-commit extras (e.g.
|
||||
`go mod tidy` verification in Go repos) belong in `script/precommit`, not in
|
||||
the hook itself. Model scripts are at
|
||||
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).
|
||||
@@ -100,198 +89,87 @@ style conventions are in separate documents:
|
||||
contributor should be able to understand the entire development workflow by
|
||||
reading the Makefile.
|
||||
|
||||
- Every repo should have a `Dockerfile`, and it carries the repo's gates: a
|
||||
`lint` phase and a `test` phase, with the final stage depending on both so the
|
||||
image cannot be built unless they pass. For non-server repos the final stage
|
||||
brings up a development environment; for server repos it is the runtime image.
|
||||
The gate phases and the build stage start from their pinned base images and
|
||||
install what those images lack either inline, as the canonical Go `Dockerfile`
|
||||
below does for `git`, or by running `script/bootstrap`, as the `prompts`
|
||||
repo's own `Dockerfile` does for its yarn packages. The development
|
||||
environment stage installs development prerequisites by running
|
||||
`script/bootstrap` rather than duplicating its installs inline. A stage that
|
||||
runs `script/bootstrap` COPYs `script/` and the dependency manifests
|
||||
(`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it.
|
||||
- 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.
|
||||
|
||||
- **Linting and testing run in Docker, as phases of the `Dockerfile`.** There is
|
||||
no separate lint file. `script/lint` and `script/test` each build one phase
|
||||
and nothing else:
|
||||
- **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.
|
||||
|
||||
```sh
|
||||
docker build --no-cache --target lint -t "$(script/projectname)-lint" .
|
||||
docker build --no-cache --target test -t "$(script/projectname)-test" .
|
||||
```
|
||||
|
||||
**A stage that is not the last one in the file is built only when the final
|
||||
stage's chain depends on it, or when `--target` names it.** That is why the
|
||||
two gates are always invoked by name here, and why the final stage carries a
|
||||
`COPY --from=` of a harmless file from each of them: without that edge a
|
||||
plain `docker build .` builds the last stage alone and exits 0 having linted
|
||||
and tested nothing.
|
||||
|
||||
**Every `docker build` in `script/` is tagged**, here and in
|
||||
`script/cibuild` and `script/docker`. An untagged build leaves a dangling
|
||||
image behind on every invocation, on every developer host and every CI
|
||||
runner; a tagged one replaces the previous image.
|
||||
|
||||
Inside a phase the tool is invoked directly — `golangci-lint`, `go test`,
|
||||
`eslint`, `prettier` — never through `make lint` or `script/test`, which are
|
||||
themselves a `docker build` and would recurse into a daemon that does not
|
||||
exist in a build step. Formatting is the exception and stays on the host:
|
||||
`script/fmt` writes the working tree, and `script/fmt-check` is its
|
||||
read-only twin.
|
||||
|
||||
**No lint verdict may come from a host invocation of the linter.** On a
|
||||
shared host golangci-lint reads a result cache keyed on file content rather
|
||||
than location, so a second checkout of the same content is served the first
|
||||
one's findings, and a host-global lock in `$TMPDIR` makes concurrent runs
|
||||
exit non-zero with `parallel golangci-lint is running` — a status a caller
|
||||
cannot tell from real findings. Both have produced wrong verdicts in this
|
||||
org, in both directions. A container has its own cache, its own `TMPDIR` and
|
||||
a digest-pinned binary, so neither is reachable.
|
||||
|
||||
- **Any build that runs checks is built with `--no-cache`.** Docker invalidates
|
||||
a `COPY` layer only when the copied content changes, so on an unchanged tree
|
||||
the check `RUN` is served from cache, nothing executes, and the build still
|
||||
exits 0. Every `docker build` in `script/` therefore passes `--no-cache`:
|
||||
`script/lint`, `script/test`, `script/cibuild` and `script/docker` are the
|
||||
four, and there is no fifth — `script/check` runs the two gate phases and
|
||||
`script/fmt-check`, and builds no image of its own. A bare `docker build .` is
|
||||
not evidence that anything ran: a sub-second build reporting success is a
|
||||
cache hit, not a result. Never invalidate by pruning — `docker builder prune`
|
||||
and friends destroy a build cache shared with every other build on the host.
|
||||
When a check is added or changed, prove it works by planting a defect it must
|
||||
catch and watching the run fail on it, then revert the defect. A green run
|
||||
alone shows neither that the check ran nor that it covers what it should.
|
||||
|
||||
- **The gate phases are separate stages, and the build stage depends on both.**
|
||||
The lint phase is based on the `golangci/golangci-lint` image (pinned by
|
||||
hash), so lint failures surface in seconds rather than after a full compile,
|
||||
and the test phase is based on the Debian Go image. The canonical Go repo
|
||||
`Dockerfile`:
|
||||
The standard pattern for a Go repo Dockerfile is:
|
||||
|
||||
```dockerfile
|
||||
# Lint phase
|
||||
# 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 golangci-lint run --config .golangci.yml ./...
|
||||
RUN make fmt-check
|
||||
RUN make lint
|
||||
|
||||
# Test phase. -race needs cgo and so a C compiler, which the Debian Go
|
||||
# image ships and the alpine one does not.
|
||||
# golang:1.x, YYYY-MM-DD
|
||||
FROM golang@sha256:... AS test
|
||||
WORKDIR /src
|
||||
COPY go.mod go.sum ./
|
||||
RUN go mod download
|
||||
COPY . .
|
||||
RUN go test -timeout 90s -race -cover ./... || \
|
||||
{ echo "--- Rerunning with -v for details ---"; \
|
||||
go test -timeout 90s -race -v ./...; exit 1; }
|
||||
|
||||
# Build stage. Nothing is wanted from either phase above; the copies
|
||||
# are what make BuildKit build them first, so this stage cannot run
|
||||
# unless lint and test passed.
|
||||
# Build stage
|
||||
# golang:1.x-alpine, YYYY-MM-DD
|
||||
FROM golang@sha256:... AS builder
|
||||
COPY --from=lint /src/go.sum /dev/null
|
||||
COPY --from=test /src/go.sum /dev/null
|
||||
RUN apk add --no-cache git
|
||||
# A tar-stream context keeps the sender's file owners, which git refuses.
|
||||
RUN git config --system --add safe.directory /src
|
||||
WORKDIR /src
|
||||
|
||||
# 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
|
||||
|
||||
# The VERSION build arg when one is given, otherwise
|
||||
# `git describe --tags --always` on the .git in the build context. With
|
||||
# .git present, a version that is still empty, dev or unknown fails the
|
||||
# build: git is missing or could not read the checkout.
|
||||
ARG VERSION
|
||||
RUN VERSION="${VERSION:-$(git describe --tags --always)}"; \
|
||||
if [ -e .git ]; then \
|
||||
case "$VERSION" in ""|dev|unknown) \
|
||||
echo "version is '$VERSION' although .git is present" >&2; \
|
||||
exit 1 ;; \
|
||||
esac; \
|
||||
fi; \
|
||||
CGO_ENABLED=0 go build -trimpath \
|
||||
-ldflags="-s -w -X main.Version=${VERSION}" \
|
||||
-o /app ./cmd/app/
|
||||
ARG VERSION=dev
|
||||
RUN CGO_ENABLED=0 go build -trimpath \
|
||||
-ldflags="-s -w -X main.Version=${VERSION}" \
|
||||
-o /app ./cmd/app/
|
||||
|
||||
# Runtime stage, and the last one
|
||||
# Runtime stage
|
||||
FROM alpine@sha256:...
|
||||
COPY --from=builder /app /usr/local/bin/app
|
||||
ENTRYPOINT ["app"]
|
||||
```
|
||||
|
||||
Key points:
|
||||
- The lint phase uses the `golangci/golangci-lint` image directly (it has
|
||||
both Go and the linter), so nothing needs installing.
|
||||
- `COPY --from=<phase> /src/go.sum /dev/null` is a no-op copy whose only
|
||||
purpose is the ordering edge. BuildKit runs stages in parallel by default,
|
||||
and a stage nothing depends on is not built at all, so without these two
|
||||
lines a red gate would not fail the build.
|
||||
- Keep the runtime stage last, and if you add a stage after it, give it the
|
||||
same two copies. A plain `docker build .` builds the last stage's chain
|
||||
and nothing else.
|
||||
- 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 phase must
|
||||
(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`.
|
||||
- If the project requires CGO or system libraries for linting, install them
|
||||
in the lint phase. The `golangci/golangci-lint` image is Debian-based and
|
||||
has no `apk`, so install with `apt-get` under the Debian package name
|
||||
(`libvips-dev`, where alpine says `vips-dev`), and delete the package
|
||||
lists in the same `RUN`, so the layer does not keep them:
|
||||
|
||||
```dockerfile
|
||||
RUN apt-get update \
|
||||
&& apt-get install -y --no-install-recommends libvips-dev \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
```
|
||||
|
||||
- `.dockerignore` lets `.git` into the build context. It keeps out every git
|
||||
`config` at any depth (`**/.git/config`, `**/.git/modules/**/config`): the
|
||||
repository's own, each submodule's under `.git/modules/`, and that of a
|
||||
submodule keeping its own `.git` directory. `git describe` does not need
|
||||
them, and each can hold a credential: a password in a remote URL, or the
|
||||
token the CI checkout step stores there. A submodule whose name has a
|
||||
`config` segment (`config`, `deploy/config`, `config/lib`) loses its whole
|
||||
git directory to `**/.git/modules/**/config`, and Go's version stamping
|
||||
then fails the build: give it a name without that segment
|
||||
(`git submodule add --name`). The stage that compiles has `git` (the
|
||||
Debian Go image has it; an alpine one needs `apk add --no-cache git`) and
|
||||
takes the version from the `VERSION` build argument when one is given,
|
||||
otherwise from `git describe --tags --always`. That gives the tag on a
|
||||
tagged commit; on a later commit, the tag, the number of commits since it
|
||||
and the short commit (`v1.2.3-4-gabc1234`); and the short commit when no
|
||||
tag is reachable. The stage that compiles also marks its working directory
|
||||
safe for git (`git config --system --add safe.directory /src`): a context
|
||||
sent as a tar stream keeps the sender's file owners, and git refuses a
|
||||
checkout owned by another user, so the version would come out empty.
|
||||
`ARG VERSION` has no default, and the build fails if the context carries
|
||||
`.git` and the version still comes out empty, `dev` or `unknown`. A plain
|
||||
`docker build .` with no build arguments must succeed; a Dockerfile that
|
||||
refuses an empty build argument drops that refusal and keeps the argument.
|
||||
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` on push, and checks out the repo as its only other step.
|
||||
That script bootstraps, runs the gate phases, and then builds the image, so a
|
||||
successful run means every check passed; a bare `docker build .` does not
|
||||
carry the same guarantee, because its gate phases may come from the cache. The
|
||||
image build is uncached and so runs the gate phases a second time. That is the
|
||||
price of the rule above, and it is worth paying: the image that ships is built
|
||||
from a run of its own gates rather than from a cache entry. A separate
|
||||
workflow limited to `main` by a `branches` list under `on: push` cannot be
|
||||
checked by review: to try a change to it, add the feature branch to that list
|
||||
and push, then remove the branch from the list again before merging. Keep any
|
||||
job in it that publishes behind `if: github.ref_name == 'main'`, so the run
|
||||
from the feature branch publishes nothing.
|
||||
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
|
||||
@@ -315,17 +193,15 @@ style conventions are in separate documents:
|
||||
suite that exceeds it fails. Under 20 seconds is the target. A suite between
|
||||
20 and 60 seconds is still green, but the overage must be filed as an
|
||||
improvement bug against that repo. Add a 90-second timeout to the test
|
||||
invocation (`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.
|
||||
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.
|
||||
|
||||
- **The test command 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 command lives in the
|
||||
`test` phase of the `Dockerfile`, since `script/test` builds that phase; the
|
||||
Makefile form below is the same pattern for any repo-local invocation:
|
||||
- **`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:
|
||||
@@ -338,26 +214,11 @@ style conventions are in separate documents:
|
||||
|
||||
```makefile
|
||||
test:
|
||||
@go test -count=1 -timeout 90s -race -cover ./... || \
|
||||
@go test -timeout 90s -race -cover ./... || \
|
||||
{ echo "--- Rerunning with -v for details ---"; \
|
||||
go test -count=1 -timeout 90s -race -v ./...; exit 1; }
|
||||
go test -timeout 90s -race -v ./...; exit 1; }
|
||||
```
|
||||
|
||||
`-count=1` is required on both invocations: it defeats Go's test _result_
|
||||
cache, so neither run can report a stored pass in place of running the
|
||||
tests. It leaves the build cache alone, so it costs the runtime of the suite
|
||||
and no recompilation.
|
||||
|
||||
That cache is Go's own, separate from Docker's layer cache. Go stores a
|
||||
passing result in its cache directory (`GOCACHE`), and when the same tests
|
||||
run again on unchanged code it prints that result, marked `(cached)`,
|
||||
without running them. That matters on a developer's machine, where this
|
||||
target runs and the directory lasts from one run to the next. The `test`
|
||||
phase of the `Dockerfile` needs no `-count=1`: its base image holds no
|
||||
result for this repo's tests and nothing before its `go test` step runs a
|
||||
test, so there is nothing to replay. `--no-cache` (above) is what makes that
|
||||
step run on an unchanged tree.
|
||||
|
||||
Python example:
|
||||
|
||||
```makefile
|
||||
@@ -383,84 +244,10 @@ style conventions are in separate documents:
|
||||
must be in `.gitignore`. No exceptions.
|
||||
|
||||
- `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
|
||||
editor files (`.swp`, `*~`), in-repo agent scratch directories (`.claude/`),
|
||||
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. These patterns are written to `.gitignore`'s own
|
||||
semantics, in which an unanchored pattern already matches at every depth; they
|
||||
are not a `.dockerignore` and must not be transplanted into one unmodified.
|
||||
|
||||
- **`.dockerignore` does not use `.gitignore` semantics, and copying patterns
|
||||
across unmodified leaves secrets in the build context.** Docker matches with
|
||||
`moby/patternmatcher`: `filepath.Match` semantics plus a `**` extension, so
|
||||
`*` does not cross `/` and a pattern without a leading `**/` is anchored at
|
||||
the build-context root. A `.dockerignore` listing `.env`, `*.pem` and `*.key`
|
||||
therefore excludes only the copies at the repository root, while `config/.env`
|
||||
and `certs/server.key` still reach the context and can land in an image layer
|
||||
— which is more dangerous than a short file with no secret patterns at all,
|
||||
because it reads as solved and stops anyone looking. Give every
|
||||
depth-independent pattern the `**/` prefix and leave only genuinely
|
||||
root-anchored entries unprefixed: `.claude`, and the repo's own host-built
|
||||
binary, written `/myapp` and never `**/myapp`, which would also match
|
||||
`cmd/myapp/` and delete the package directory from the context. Matching is
|
||||
case-sensitive, and an ALL-CAPS twin per pattern still misses `Server.Key`, so
|
||||
secret names use character ranges — `**/*.[kK][eE][yY]`, `**/*.[pP][eE][mM]`,
|
||||
and likewise for `.envrc` and the extensionless SSH keys. Where such a pattern
|
||||
also catches something the build needs, re-include it with a negation
|
||||
(`!docs/example.env`); deleting the pattern reopens the exposure for every
|
||||
other file it covers. Fetch the standard `.dockerignore` from
|
||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` and extend
|
||||
it with the repo's own artifacts.
|
||||
|
||||
- **In-repo agent scratch belongs in both files, written to each file's own
|
||||
semantics.** `.claude/` holds one worktree per in-flight agent — an entire
|
||||
additional checkout of the repo — so under `COPY . .` the build context
|
||||
inflates by a multiple of the repo and another session's unreviewed work can
|
||||
be copied into an image layer. In `.gitignore` the entry is `.claude/`,
|
||||
unanchored. In `.dockerignore` it is `.claude`, anchored and with **no** `**/`
|
||||
prefix, because the prefixed form would also delete any nested directory of
|
||||
that name from the build. Anchoring carries a known gap that the canonical
|
||||
`.dockerignore` states in its own comment, since consuming repos receive the
|
||||
file and not the tracker: the directory is created in the agent's working
|
||||
directory, so a repo running agents in subdirectories still ships
|
||||
`services/api/.claude/` and must add its own anchored entry there.
|
||||
|
||||
- **A plain `docker build .` of a clone stamps the version that
|
||||
`git describe --tags --always` gives**, derived from the `.git` in the build
|
||||
context as the canonical `Dockerfile` above shows. Without its failure check,
|
||||
a missing `git` or an unreadable checkout would leave `-X main.Version=` empty
|
||||
and the build would still exit 0. `script/docker` and `script/cibuild` pass
|
||||
the version they compute on the host; it takes precedence. They do this
|
||||
byte-identically across repos:
|
||||
|
||||
```sh
|
||||
# Own line: a failing command substitution inside an argument does not
|
||||
# trip `set -e`, so the inline form degrades to an empty constant.
|
||||
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
|
||||
[ -n "$version" ] || version="unknown"
|
||||
docker build --no-cache \
|
||||
--build-arg VERSION="$version" \
|
||||
-t "$(script/projectname)" .
|
||||
```
|
||||
|
||||
`--always` makes an untagged repo yield an abbreviated commit hash rather
|
||||
than failing, and the `[ -n "$version" ]` line is the single place the
|
||||
fallback is applied — a live check that fires on a build from an export with
|
||||
no `.git` and on a repository with no commits yet. Do not fold it into the
|
||||
substitution as `|| echo unknown`, which makes the guard unreachable. The
|
||||
Dockerfile's side is `ARG VERSION` in the stage that compiles, declared
|
||||
there because `ARG` is stage-scoped; passing `VERSION` to a repo whose
|
||||
Dockerfile declares no such `ARG` is ignored and costs nothing, which is why
|
||||
the scripts stay byte-identical. One consequence for CI: the standard
|
||||
checkout action clones shallow and fetches no tags, so a repo that embeds a
|
||||
tag-derived version must set `fetch-depth: 0` on its checkout step.
|
||||
|
||||
- **Verify `.dockerignore` by enumerating the image, not by reading the
|
||||
patterns.** Plant files at the root _and_ at least two directories deep, build
|
||||
a probe image that does `COPY . .`, and list what actually landed
|
||||
(`docker run --rm --entrypoint find IMAGE /app`). The `transferring context`
|
||||
size is not a substitute: a nested secret is a few bytes, and BuildKit
|
||||
transfers only the delta from the previous build.
|
||||
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
|
||||
@@ -476,56 +263,12 @@ style conventions are in separate documents:
|
||||
- Make all changes on a feature branch. You can do whatever you want on a
|
||||
feature branch.
|
||||
|
||||
- `.golangci.yml` is standardized. The vendored copy in a consuming repo must
|
||||
_NEVER_ be modified by an agent: fetch it from
|
||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml` and keep it
|
||||
byte-identical, so that no repo can quietly loosen its own linting. Linter
|
||||
configuration changes are made to the canonical copy in the `prompts` repo and
|
||||
reach consuming repos by re-vendoring; an agent may open a PR against
|
||||
canonical, which only the user merges. One list is exempt from byte-identity,
|
||||
because it cannot be written once for every repo: the `deny` list of the
|
||||
`test-support` depguard rule, where a repo names its own test-support packages
|
||||
by full import path. A repo adds entries there and changes nothing else, and a
|
||||
re-vendor carries its entries forward. The canonical golangci-lint version is
|
||||
v2.14.0 (released 2026-09-24), pinned as the digest of the lint phase's base
|
||||
image
|
||||
(`golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f`,
|
||||
which reports `2.14.0 built with go1.27.0 from 114493f9`). A module's `go`
|
||||
directive must not name a newer Go minor version than the one golangci-lint
|
||||
was built with, or golangci-lint refuses to lint it: this release lints
|
||||
`go 1.27.1` but not `go 1.28`. That digest is the only pin, since no repo
|
||||
installs golangci-lint on the host. A repo sets the lint phase digest to the
|
||||
one named here and re-vendors `.golangci.yml` in the same commit, whichever of
|
||||
the two prompted the change: the canonical copy can name linters that an older
|
||||
golangci-lint rejects, and a newer golangci-lint can add linters that
|
||||
`default: all` switches on until the canonical copy disables them.
|
||||
|
||||
- **`script/bootstrap` installs a pinned tool by comparing versions, never by
|
||||
testing presence.** An `if ! command -v <tool>; then install; fi` guard tests
|
||||
`PATH` only, so on an already-provisioned machine the pin is inert and a
|
||||
version bump is a silent no-op — while the Dockerfile, installing into a clean
|
||||
image, gets the pinned version, so a local `make check` and `make docker` can
|
||||
disagree about what the tool even is. The canonical form:
|
||||
- compares the installed version against the pin over the **whole** version
|
||||
token; a parser that stops at the first `-` reports `2.12.2` for a host
|
||||
running `2.12.2-rc1` and skips the install;
|
||||
- treats absent, non-zero, empty or unrecognised `--version` output as a
|
||||
mismatch, so the failure direction is a redundant install and never a
|
||||
skipped one;
|
||||
- after installing, re-resolves the binary the way callers do — `hash -r`,
|
||||
then through `PATH`, not through the directory the installer wrote to —
|
||||
and fails naming the resolved path, since an install that a shadowing
|
||||
binary hides succeeds while changing nothing any caller sees;
|
||||
- is actually called, and prints the version on both success paths: a
|
||||
function defined and never invoked has the same exit status and the same
|
||||
empty output as one that worked.
|
||||
|
||||
Keep it POSIX sh: no arrays, no `[[`, no `grep -P`.
|
||||
|
||||
A Go tool a repo needs on the host is installed with `go install` pinned to
|
||||
a commit hash (`go install <package>@<commit hash>`). It is never tracked as
|
||||
a `go.mod` tool dependency or through a `tools.go` file, either of which
|
||||
pulls the tool's own dependencies into the repo's `go.mod` and `go.sum`.
|
||||
- `.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).
|
||||
@@ -639,14 +382,12 @@ style conventions are in separate documents:
|
||||
settings.
|
||||
|
||||
- Avoid putting files in the repo root unless necessary. Root should contain
|
||||
only project-level config files (`README.md`, `AGENTS.md`, `Makefile`,
|
||||
`Dockerfile`, `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`,
|
||||
and language-specific config). Everything else goes in a subdirectory.
|
||||
Canonical subdirectory names:
|
||||
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; thin only: one `main.go` per binary whose
|
||||
body is a single call into `internal/` or `pkg/`, no project logic in
|
||||
`cmd/`
|
||||
- `cmd/` — Go command entrypoints
|
||||
- `configs/` — configuration templates and examples
|
||||
- `deploy/` — deployment manifests (k8s, compose, terraform)
|
||||
- `docs/` — documentation and markdown (README.md stays in root)
|
||||
@@ -673,7 +414,3 @@ style conventions are in separate documents:
|
||||
- Go: `go.mod`, `go.sum`, `.golangci.yml`
|
||||
- JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
|
||||
- Python: `pyproject.toml`
|
||||
|
||||
- Guidance for coding agents lives in one `AGENTS.md` at the repository root. It
|
||||
is never committed under a file or directory named after one agent tool, such
|
||||
as `CLAUDE.md` or `.claude/`, and never split into separate memory files.
|
||||
|
||||
+3
-3
@@ -38,7 +38,7 @@ works correctly in production.
|
||||
responses
|
||||
- **Do not add `-short` flags** to skip slow tests
|
||||
- **Do not increase `-timeout`** to hide hanging queries
|
||||
- **Do not remove `-count=1` from the test phase of the `Dockerfile`** — 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 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
|
||||
|
||||
@@ -10,42 +10,15 @@
|
||||
|
||||
# Status
|
||||
|
||||
pre-1.0. Work lands on `next` by PR. Open work for 1.0 is tracked on the 1.0
|
||||
milestone: https://git.eeqj.de/sneak/dnswatcher/milestone/7
|
||||
pre-1.0. No git tags. Work lands on `next` by PR. Open work for 1.0 is tracked
|
||||
on the 1.0 milestone: https://git.eeqj.de/sneak/dnswatcher/milestone/7
|
||||
|
||||
# Next Step
|
||||
|
||||
1.0 tracking issue: https://git.eeqj.de/sneak/dnswatcher/issues/66
|
||||
trial run of the finished image: https://git.eeqj.de/sneak/dnswatcher/issues/149
|
||||
|
||||
# Completed Steps
|
||||
|
||||
- 2026-10-13: a hostname or a domain whose zone's nameservers all stop answering
|
||||
gets an NS Failure for each, then an NS Recovery (closes #284).
|
||||
- 2026-10-13: an IPv6 address is written in brackets before its port, as in
|
||||
`[2001:db8::1]:443`, in keys and Port Change notifications (closes #270).
|
||||
- 2026-10-13: `TODO.md` names only open issues as next and future steps, and its
|
||||
Status says nothing about git tags (closes #281).
|
||||
- 2026-10-13: a port check that finds port 443 closed removes that address's
|
||||
certificate entries, so none is left shown as `ok` (closes #265).
|
||||
- 2026-10-13: a state file holding `{}`, or leaving out a section, loads with
|
||||
that section empty; the first check no longer crashes on it (closes #267).
|
||||
- 2026-10-13: a stop before the first scan completes sends no startup
|
||||
notification; a scan that ran to the end still sends it (closes #271).
|
||||
- 2026-10-13: a nameserver leaving a domain's delegation sends only NS Change;
|
||||
one leaving a hostname's zone sends NS Change, not NS Failure (closes #262).
|
||||
- 2026-10-13: `DNSWATCHER_METRICS_USERNAME` set without
|
||||
`DNSWATCHER_METRICS_PASSWORD` stops startup (closes #268).
|
||||
- 2026-10-13: a save syncs the state file to disk before renaming it into place,
|
||||
so a crash cannot leave it empty and stop the next start (closes #264).
|
||||
- 2026-10-13: a `PORT` that cannot be bound stops startup with an error naming
|
||||
the address, instead of running without the HTTP server (closes #266).
|
||||
- 2026-10-13: a bad `PORT`, `DNSWATCHER_TLS_EXPIRY_WARNING` or true/false
|
||||
setting stops startup instead of being read as 0 or false (closes #269).
|
||||
- 2026-10-13: a check saving the state while the dashboard or `/api/v1/status`
|
||||
is read cannot crash the process (closes #261).
|
||||
- 2026-10-06: canonical files re-fetched from `sneak/prompts` at `dd4027b`; lint
|
||||
and test are phases of the `Dockerfile`, every scripted build uncached (closes
|
||||
#257).
|
||||
- 2026-10-05: a name listed in `DNSWATCHER_SKIP_RECORD_NOTIFICATIONS` gets no
|
||||
Record Change or Inconsistency notification; a name listed there that is not
|
||||
in `DNSWATCHER_TARGETS` stops startup (closes #255).
|
||||
@@ -207,4 +180,6 @@ milestone: https://git.eeqj.de/sneak/dnswatcher/milestone/7
|
||||
|
||||
# Future Steps
|
||||
|
||||
- DNSSEC validation, after 1.0: https://git.eeqj.de/sneak/dnswatcher/issues/59
|
||||
- 1.0 readiness: run it with a real config and read the logs:
|
||||
https://git.eeqj.de/sneak/dnswatcher/issues/66
|
||||
- review toward 1.0: https://git.eeqj.de/sneak/dnswatcher/issues/144
|
||||
|
||||
+14
-126
@@ -6,7 +6,6 @@ import (
|
||||
"fmt"
|
||||
"log/slog"
|
||||
"slices"
|
||||
"strconv"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
@@ -25,9 +24,6 @@ const (
|
||||
defaultTLSExpiryWarning = 7
|
||||
)
|
||||
|
||||
// maxPort is the highest TCP port number.
|
||||
const maxPort = 65535
|
||||
|
||||
// ErrNoTargets is returned when no monitoring targets are configured.
|
||||
var ErrNoTargets = errors.New(
|
||||
"no monitoring targets configured: set DNSWATCHER_TARGETS environment variable",
|
||||
@@ -44,30 +40,6 @@ var ErrInvalidInterval = errors.New(
|
||||
// lists a name that is not in DNSWATCHER_TARGETS.
|
||||
var ErrNotInTargets = errors.New("name is not in DNSWATCHER_TARGETS")
|
||||
|
||||
// ErrInvalidPort is returned when PORT is set but is not a whole number
|
||||
// from 1 to 65535. An empty value counts as unset and means the default.
|
||||
var ErrInvalidPort = errors.New("port must be a whole number from 1 to 65535")
|
||||
|
||||
// ErrInvalidTLSExpiryWarning is returned when DNSWATCHER_TLS_EXPIRY_WARNING
|
||||
// is set but is not a whole number, 1 or more. An empty value counts as unset
|
||||
// and means the default.
|
||||
var ErrInvalidTLSExpiryWarning = errors.New(
|
||||
"TLS expiry warning must be a whole number of days, 1 or more",
|
||||
)
|
||||
|
||||
// ErrInvalidBool is returned when DNSWATCHER_DEBUG,
|
||||
// DNSWATCHER_MAINTENANCE_MODE or DNSWATCHER_SEND_TEST_NOTIFICATION is set
|
||||
// but is not a value strconv.ParseBool accepts. An empty value counts as
|
||||
// unset and means the default.
|
||||
var ErrInvalidBool = errors.New("value must be true or false")
|
||||
|
||||
// ErrNoMetricsPassword is returned when DNSWATCHER_METRICS_USERNAME is set and
|
||||
// DNSWATCHER_METRICS_PASSWORD is empty. Basic Auth on /metrics would otherwise
|
||||
// let in anyone who sends the username with an empty password.
|
||||
var ErrNoMetricsPassword = errors.New(
|
||||
"DNSWATCHER_METRICS_PASSWORD must be set when DNSWATCHER_METRICS_USERNAME is set",
|
||||
)
|
||||
|
||||
// Params contains dependencies for Config.
|
||||
type Params struct {
|
||||
fx.In
|
||||
@@ -115,10 +87,6 @@ func New(_ fx.Lifecycle, params Params) (*Config, error) {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
if cfg.MetricsUsername != "" && cfg.MetricsPassword == "" {
|
||||
return nil, ErrNoMetricsPassword
|
||||
}
|
||||
|
||||
configureDebugLogging(cfg, params)
|
||||
|
||||
return cfg, nil
|
||||
@@ -159,9 +127,16 @@ func buildConfig(
|
||||
log *slog.Logger,
|
||||
params *Params,
|
||||
) (*Config, error) {
|
||||
err := readConfigFile(log)
|
||||
err := viper.ReadInConfig()
|
||||
if err != nil {
|
||||
return nil, err
|
||||
var notFound viper.ConfigFileNotFoundError
|
||||
if !errors.As(err, ¬Found) {
|
||||
log.Error("config file malformed", "error", err)
|
||||
|
||||
return nil, fmt.Errorf(
|
||||
"config file malformed: %w", err,
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
dnsInterval, err := parseInterval("DNS_INTERVAL")
|
||||
@@ -186,34 +161,9 @@ func buildConfig(
|
||||
return nil, err
|
||||
}
|
||||
|
||||
port, err := parsePort()
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
tlsExpiryWarning, err := parseTLSExpiryWarning()
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
debug, err := parseBool("DEBUG")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
maintenanceMode, err := parseBool("MAINTENANCE_MODE")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
sendTestNotification, err := parseBool("SEND_TEST_NOTIFICATION")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
cfg := &Config{
|
||||
Port: port,
|
||||
Debug: debug,
|
||||
Port: viper.GetInt("PORT"),
|
||||
Debug: viper.GetBool("DEBUG"),
|
||||
DataDir: viper.GetString("DATA_DIR"),
|
||||
Domains: domains,
|
||||
Hostnames: hostnames,
|
||||
@@ -223,12 +173,12 @@ func buildConfig(
|
||||
NtfyTopic: viper.GetString("NTFY_TOPIC"),
|
||||
DNSInterval: dnsInterval,
|
||||
TLSInterval: tlsInterval,
|
||||
TLSExpiryWarning: tlsExpiryWarning,
|
||||
TLSExpiryWarning: viper.GetInt("TLS_EXPIRY_WARNING"),
|
||||
SentryDSN: viper.GetString("SENTRY_DSN"),
|
||||
MaintenanceMode: maintenanceMode,
|
||||
MaintenanceMode: viper.GetBool("MAINTENANCE_MODE"),
|
||||
MetricsUsername: viper.GetString("METRICS_USERNAME"),
|
||||
MetricsPassword: viper.GetString("METRICS_PASSWORD"),
|
||||
SendTestNotification: sendTestNotification,
|
||||
SendTestNotification: viper.GetBool("SEND_TEST_NOTIFICATION"),
|
||||
params: params,
|
||||
log: log,
|
||||
}
|
||||
@@ -236,21 +186,6 @@ func buildConfig(
|
||||
return cfg, nil
|
||||
}
|
||||
|
||||
// readConfigFile reads the config file, if there is one.
|
||||
func readConfigFile(log *slog.Logger) error {
|
||||
err := viper.ReadInConfig()
|
||||
if err != nil {
|
||||
var notFound viper.ConfigFileNotFoundError
|
||||
if !errors.As(err, ¬Found) {
|
||||
log.Error("config file malformed", "error", err)
|
||||
|
||||
return fmt.Errorf("config file malformed: %w", err)
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// parseInterval reads the DNSWATCHER_-prefixed setting key as a duration. A
|
||||
// value that does not parse, or is zero or negative, is an error naming the
|
||||
// variable and the value; an unset variable has its default from setupViper.
|
||||
@@ -267,53 +202,6 @@ func parseInterval(key string) (time.Duration, error) {
|
||||
return interval, nil
|
||||
}
|
||||
|
||||
// parsePort reads PORT, which has no DNSWATCHER_ prefix, as a port number. A
|
||||
// value that is not a whole number from 1 to 65535 is an error naming the
|
||||
// variable and the value; an unset variable has its default from setupViper.
|
||||
func parsePort() (int, error) {
|
||||
value := viper.GetString("PORT")
|
||||
|
||||
port, err := strconv.Atoi(value)
|
||||
if err != nil || port < 1 || port > maxPort {
|
||||
return 0, fmt.Errorf("invalid PORT %q: %w", value, ErrInvalidPort)
|
||||
}
|
||||
|
||||
return port, nil
|
||||
}
|
||||
|
||||
// parseTLSExpiryWarning reads DNSWATCHER_TLS_EXPIRY_WARNING as a number of
|
||||
// days. A value that is not a whole number, 1 or more, is an error naming the
|
||||
// variable and the value; an unset variable has its default from setupViper.
|
||||
func parseTLSExpiryWarning() (int, error) {
|
||||
value := viper.GetString("TLS_EXPIRY_WARNING")
|
||||
|
||||
days, err := strconv.Atoi(value)
|
||||
if err != nil || days < 1 {
|
||||
return 0, fmt.Errorf(
|
||||
"invalid DNSWATCHER_TLS_EXPIRY_WARNING %q: %w",
|
||||
value, ErrInvalidTLSExpiryWarning,
|
||||
)
|
||||
}
|
||||
|
||||
return days, nil
|
||||
}
|
||||
|
||||
// parseBool reads the DNSWATCHER_-prefixed setting key as true or false. A
|
||||
// value strconv.ParseBool does not accept is an error naming the variable and
|
||||
// the value; an unset variable has its default from setupViper.
|
||||
func parseBool(key string) (bool, error) {
|
||||
value := viper.GetString(key)
|
||||
|
||||
result, err := strconv.ParseBool(value)
|
||||
if err != nil {
|
||||
return false, fmt.Errorf(
|
||||
"invalid DNSWATCHER_%s %q: %w", key, value, ErrInvalidBool,
|
||||
)
|
||||
}
|
||||
|
||||
return result, nil
|
||||
}
|
||||
|
||||
func parseAndValidateTargets() ([]string, []string, error) {
|
||||
domains, hostnames, err := ClassifyTargets(
|
||||
parseCSV(viper.GetString("TARGETS")),
|
||||
|
||||
@@ -116,7 +116,7 @@ func TestNew_OnlyEmptyCSVSegments(t *testing.T) {
|
||||
}
|
||||
|
||||
// TestNew_InvalidIntervalStopsStartup checks values that must stop startup;
|
||||
// TestNew_DefaultValues and TestNew_EmptyValueMeansDefault check that an
|
||||
// TestNew_DefaultValues and TestNew_EmptyIntervalMeansDefault check that an
|
||||
// unset or empty interval means the default.
|
||||
func TestNew_InvalidIntervalStopsStartup(t *testing.T) {
|
||||
variables := []string{"DNSWATCHER_DNS_INTERVAL", "DNSWATCHER_TLS_INTERVAL"}
|
||||
@@ -144,107 +144,16 @@ func TestNew_InvalidIntervalStopsStartup(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
func TestNew_EmptyValueMeansDefault(t *testing.T) {
|
||||
func TestNew_EmptyIntervalMeansDefault(t *testing.T) {
|
||||
viper.Reset()
|
||||
t.Setenv("DNSWATCHER_TARGETS", "example.com")
|
||||
t.Setenv("DNSWATCHER_DNS_INTERVAL", "")
|
||||
t.Setenv("DNSWATCHER_TLS_INTERVAL", "")
|
||||
t.Setenv("PORT", "")
|
||||
t.Setenv("DNSWATCHER_TLS_EXPIRY_WARNING", "")
|
||||
t.Setenv("DNSWATCHER_DEBUG", "")
|
||||
t.Setenv("DNSWATCHER_MAINTENANCE_MODE", "")
|
||||
t.Setenv("DNSWATCHER_SEND_TEST_NOTIFICATION", "")
|
||||
|
||||
cfg, err := config.New(nil, newTestParams(t))
|
||||
require.NoError(t, err)
|
||||
assert.Equal(t, time.Hour, cfg.DNSInterval)
|
||||
assert.Equal(t, 12*time.Hour, cfg.TLSInterval)
|
||||
assert.Equal(t, 8080, cfg.Port)
|
||||
assert.Equal(t, 7, cfg.TLSExpiryWarning)
|
||||
assert.False(t, cfg.Debug)
|
||||
assert.False(t, cfg.MaintenanceMode)
|
||||
assert.False(t, cfg.SendTestNotification)
|
||||
}
|
||||
|
||||
// TestNew_InvalidNumberOrBoolStopsStartup checks values that must stop
|
||||
// startup; TestNew_EnvironmentOverrides, the two tests after this one and
|
||||
// TestNew_EmptyValueMeansDefault check values that must not.
|
||||
func TestNew_InvalidNumberOrBoolStopsStartup(t *testing.T) {
|
||||
notBools := []string{"yes", "on", "2", "tRUE"}
|
||||
tests := []struct {
|
||||
variable string
|
||||
values []string
|
||||
want error
|
||||
}{
|
||||
{
|
||||
variable: "PORT",
|
||||
values: []string{"notaport", "0", "-1", "65536", "8080.5"},
|
||||
want: config.ErrInvalidPort,
|
||||
},
|
||||
{
|
||||
variable: "DNSWATCHER_TLS_EXPIRY_WARNING",
|
||||
values: []string{"abc", "7d", "0", "-5"},
|
||||
want: config.ErrInvalidTLSExpiryWarning,
|
||||
},
|
||||
{
|
||||
variable: "DNSWATCHER_DEBUG",
|
||||
values: notBools,
|
||||
want: config.ErrInvalidBool,
|
||||
},
|
||||
{
|
||||
variable: "DNSWATCHER_MAINTENANCE_MODE",
|
||||
values: notBools,
|
||||
want: config.ErrInvalidBool,
|
||||
},
|
||||
{
|
||||
variable: "DNSWATCHER_SEND_TEST_NOTIFICATION",
|
||||
values: notBools,
|
||||
want: config.ErrInvalidBool,
|
||||
},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
for _, value := range tt.values {
|
||||
t.Run(tt.variable+"="+value, func(t *testing.T) {
|
||||
viper.Reset()
|
||||
t.Setenv("DNSWATCHER_TARGETS", "example.com")
|
||||
t.Setenv(tt.variable, value)
|
||||
|
||||
_, err := config.New(nil, newTestParams(t))
|
||||
require.ErrorIs(t, err, tt.want)
|
||||
require.ErrorContains(t, err, tt.variable)
|
||||
require.ErrorContains(t, err, strconv.Quote(value))
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestNew_LowestNumbersAndOtherSpellingsOfTrue(t *testing.T) {
|
||||
viper.Reset()
|
||||
t.Setenv("DNSWATCHER_TARGETS", "example.com")
|
||||
t.Setenv("PORT", "1")
|
||||
t.Setenv("DNSWATCHER_TLS_EXPIRY_WARNING", "1")
|
||||
t.Setenv("DNSWATCHER_DEBUG", "1")
|
||||
t.Setenv("DNSWATCHER_MAINTENANCE_MODE", "T")
|
||||
t.Setenv("DNSWATCHER_SEND_TEST_NOTIFICATION", "True")
|
||||
|
||||
cfg, err := config.New(nil, newTestParams(t))
|
||||
require.NoError(t, err)
|
||||
assert.Equal(t, 1, cfg.Port)
|
||||
assert.Equal(t, 1, cfg.TLSExpiryWarning)
|
||||
assert.True(t, cfg.Debug)
|
||||
assert.True(t, cfg.MaintenanceMode)
|
||||
assert.True(t, cfg.SendTestNotification)
|
||||
}
|
||||
|
||||
func TestNew_HighestPort(t *testing.T) {
|
||||
viper.Reset()
|
||||
t.Setenv("DNSWATCHER_TARGETS", "example.com")
|
||||
t.Setenv("PORT", "65535")
|
||||
|
||||
cfg, err := config.New(nil, newTestParams(t))
|
||||
require.NoError(t, err)
|
||||
assert.Equal(t, 65535, cfg.Port)
|
||||
}
|
||||
|
||||
func TestNew_DebugEnablesDebugLogging(t *testing.T) {
|
||||
@@ -354,24 +263,6 @@ func TestNew_SkipRecordNotificationsNotInTargetsStopsStartup(t *testing.T) {
|
||||
require.ErrorContains(t, err, `"www.example.net"`)
|
||||
}
|
||||
|
||||
// TestNew_MetricsUsernameWithoutPasswordStopsStartup checks an unset and an
|
||||
// empty password; TestNew_EnvironmentOverrides checks a username with one.
|
||||
func TestNew_MetricsUsernameWithoutPasswordStopsStartup(t *testing.T) {
|
||||
viper.Reset()
|
||||
t.Setenv("DNSWATCHER_TARGETS", "example.com")
|
||||
t.Setenv("DNSWATCHER_METRICS_USERNAME", "prom")
|
||||
|
||||
_, err := config.New(nil, newTestParams(t))
|
||||
require.ErrorIs(t, err, config.ErrNoMetricsPassword, "password unset")
|
||||
require.ErrorContains(t, err, "DNSWATCHER_METRICS_PASSWORD")
|
||||
|
||||
viper.Reset()
|
||||
t.Setenv("DNSWATCHER_METRICS_PASSWORD", "")
|
||||
|
||||
_, err = config.New(nil, newTestParams(t))
|
||||
require.ErrorIs(t, err, config.ErrNoMetricsPassword, "password empty")
|
||||
}
|
||||
|
||||
func TestNew_CustomDNSIntervalDuration(t *testing.T) {
|
||||
viper.Reset()
|
||||
t.Setenv("DNSWATCHER_TARGETS", "example.com")
|
||||
|
||||
@@ -2,23 +2,6 @@ package resolver
|
||||
|
||||
import "errors"
|
||||
|
||||
// NoAnswerError is returned when the walk to a name's nameservers
|
||||
// reached a zone through a referral and none of that zone's
|
||||
// nameservers, Nameservers as the referral names them, answered. Err
|
||||
// says why they did not.
|
||||
type NoAnswerError struct {
|
||||
Nameservers []string
|
||||
Err error
|
||||
}
|
||||
|
||||
func (e *NoAnswerError) Error() string {
|
||||
return e.Err.Error()
|
||||
}
|
||||
|
||||
func (e *NoAnswerError) Unwrap() error {
|
||||
return e.Err
|
||||
}
|
||||
|
||||
// Sentinel errors returned by the resolver.
|
||||
var (
|
||||
// ErrNoNameservers is returned when no authoritative NS
|
||||
|
||||
@@ -31,11 +31,9 @@ func NewWithQueryTimeout(log *slog.Logger, timeout time.Duration) *Resolver {
|
||||
func (r *Resolver) FollowDelegation(
|
||||
ctx context.Context,
|
||||
domain string,
|
||||
zone string,
|
||||
nameservers []string,
|
||||
servers []string,
|
||||
) ([]string, error) {
|
||||
return r.followDelegation(ctx, domain, zone, nameservers, servers)
|
||||
return r.followDelegation(ctx, domain, servers)
|
||||
}
|
||||
|
||||
// FindAuthoritativeNameserversFrom exports findAuthoritativeNameservers
|
||||
|
||||
@@ -204,24 +204,20 @@ func glueIPs(nsNames []string, glue map[string][]net.IP) []string {
|
||||
return ips
|
||||
}
|
||||
|
||||
// followDelegation follows referrals to domain from servers, the
|
||||
// addresses of the servers of zone, and returns the NS set of domain's
|
||||
// delegation. nameservers are the names a referral gave the servers of
|
||||
// zone; the walk to a name's nameservers starts at the root servers, the
|
||||
// servers of zone ".", which no referral names. When the servers of the
|
||||
// zone domain is in answer that domain does not exist, the error is
|
||||
// ErrNXDomain. When they answer that it has no delegation of its own,
|
||||
// followDelegation follows referrals from servers, the root servers, to
|
||||
// domain and returns the NS set of domain's delegation. When the servers
|
||||
// of the zone domain is in answer that domain does not exist, the error
|
||||
// is ErrNXDomain. When they answer that it has no delegation of its own,
|
||||
// because it is not the zone's apex, the set is empty and there is no
|
||||
// error. Any other error means that no such answer came; it is a
|
||||
// *NoAnswerError when the servers that did not answer are those of a
|
||||
// zone a referral named.
|
||||
// error. Any other error means that no such answer came.
|
||||
func (r *Resolver) followDelegation(
|
||||
ctx context.Context,
|
||||
domain string,
|
||||
zone string,
|
||||
nameservers []string,
|
||||
servers []string,
|
||||
) ([]string, error) {
|
||||
// servers are the root servers, the servers of zone ".".
|
||||
zone := "."
|
||||
|
||||
var withoutAddresses []string
|
||||
|
||||
for range maxDelegation {
|
||||
@@ -232,12 +228,6 @@ func (r *Resolver) followDelegation(
|
||||
resp, err := r.queryZone(
|
||||
ctx, servers, withoutAddresses, zone, domain, dns.TypeNS, 0,
|
||||
)
|
||||
|
||||
// A query that ctx cut short says nothing about the servers.
|
||||
if err != nil && len(nameservers) > 0 && checkCtx(ctx) == nil {
|
||||
return nil, &NoAnswerError{Nameservers: nameservers, Err: err}
|
||||
}
|
||||
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
@@ -266,7 +256,6 @@ func (r *Resolver) followDelegation(
|
||||
return r.resolveNSIterative(ctx, domain)
|
||||
}
|
||||
|
||||
nameservers = authNS
|
||||
servers, withoutAddresses = referralNameservers(resp)
|
||||
zone = referralZone(resp)
|
||||
}
|
||||
@@ -637,8 +626,7 @@ func (r *Resolver) resolveARecord(
|
||||
// them. When the servers asked answer that the name has no delegation
|
||||
// of its own, or does not exist, it tries each parent name in turn, so
|
||||
// it returns the nameservers of the zone the name is in. When they do
|
||||
// not answer, it returns the error and tries no parent name; when a
|
||||
// referral named them, the error is a *NoAnswerError naming them.
|
||||
// not answer, it returns the error and tries no parent name.
|
||||
func (r *Resolver) FindAuthoritativeNameservers(
|
||||
ctx context.Context,
|
||||
domain string,
|
||||
@@ -667,7 +655,7 @@ func (r *Resolver) findAuthoritativeNameservers(
|
||||
|
||||
candidate := strings.Join(labels[i:], ".") + "."
|
||||
|
||||
nsNames, err := r.followDelegation(ctx, candidate, ".", nil, servers)
|
||||
nsNames, err := r.followDelegation(ctx, candidate, servers)
|
||||
if err != nil && !errors.Is(err, ErrNXDomain) {
|
||||
return nil, err
|
||||
}
|
||||
@@ -1079,7 +1067,7 @@ func (r *Resolver) LookupNS(
|
||||
}
|
||||
|
||||
return r.followDelegation(
|
||||
ctx, dns.Fqdn(strings.ToLower(domain)), ".", nil, rootServerList(),
|
||||
ctx, dns.Fqdn(strings.ToLower(domain)), rootServerList(),
|
||||
)
|
||||
}
|
||||
|
||||
|
||||
@@ -121,9 +121,7 @@ func TestFindAuthoritativeNameservers_DelegatedSubdomain(
|
||||
// delegation of its own, so the lookup returns that walk's error, about
|
||||
// www.google.com, and tries no parent name: trying google.com and com
|
||||
// would end in ErrNoNameservers, or in the error of a walk for one of
|
||||
// them. The servers that did not answer are those the walk started at,
|
||||
// which no referral named, so the error is no NoAnswerError, as when
|
||||
// the host running dnswatcher has lost its network.
|
||||
// them.
|
||||
func TestFindAuthoritativeNameservers_NoAnswer(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
@@ -136,9 +134,6 @@ func TestFindAuthoritativeNameservers_NoAnswer(t *testing.T) {
|
||||
require.NotErrorIs(t, err, resolver.ErrNoNameservers)
|
||||
assert.Contains(t, err.Error(), "query www.google.com. @"+noAnswerAddress)
|
||||
assert.Empty(t, nameservers)
|
||||
|
||||
var noAnswer *resolver.NoAnswerError
|
||||
assert.NotErrorAs(t, err, &noAnswer)
|
||||
}
|
||||
|
||||
func TestFindAuthoritativeNameservers_ReturnsSorted(
|
||||
@@ -959,34 +954,12 @@ func TestFollowDelegation_NoAnswer(t *testing.T) {
|
||||
r := resolver.NewWithQueryTimeout(slog.Default(), 100*time.Millisecond)
|
||||
|
||||
nameservers, err := r.FollowDelegation(
|
||||
t.Context(), "google.com.", ".", nil, []string{noAnswerAddress},
|
||||
t.Context(), "google.com.", []string{noAnswerAddress},
|
||||
)
|
||||
require.Error(t, err)
|
||||
assert.Empty(t, nameservers)
|
||||
}
|
||||
|
||||
// TestFollowDelegation_NoAnswerAfterReferral starts the walk for
|
||||
// www.example.net at the servers of example.net as a referral names
|
||||
// them, ns1.example.net and ns2.example.net, at 192.0.2.1, where nothing
|
||||
// answers. The error is a NoAnswerError naming them, which the watcher
|
||||
// compares with the nameservers it saved for the name.
|
||||
func TestFollowDelegation_NoAnswerAfterReferral(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
r := resolver.NewWithQueryTimeout(slog.Default(), 100*time.Millisecond)
|
||||
nameservers := []string{"ns1.example.net.", "ns2.example.net."}
|
||||
|
||||
_, err := r.FollowDelegation(
|
||||
t.Context(), "www.example.net.", "example.net.", nameservers,
|
||||
[]string{noAnswerAddress},
|
||||
)
|
||||
|
||||
var noAnswer *resolver.NoAnswerError
|
||||
require.ErrorAs(t, err, &noAnswer)
|
||||
assert.Equal(t, nameservers, noAnswer.Nameservers)
|
||||
assert.Contains(t, err.Error(), "query www.example.net. @"+noAnswerAddress)
|
||||
}
|
||||
|
||||
// TestResolveNSIterative_NoDelegationOfItsOwn walks to the nameservers
|
||||
// of www.google.com as the fallback walk does. As in
|
||||
// TestLookupNS_NoDelegationOfItsOwn, the set is empty, with no error.
|
||||
|
||||
@@ -13,8 +13,8 @@ import (
|
||||
const RequestTimeout time.Duration = requestTimeout
|
||||
|
||||
// SetListenPort overrides the port Run binds. A test uses it to hand
|
||||
// Run an unbindable port, so that Run stores its http.Server and then
|
||||
// returns an error without listening.
|
||||
// Run an unbindable port so ListenAndServe fails immediately and Run
|
||||
// returns after storing its http.Server.
|
||||
func SetListenPort(s *Server, port int) {
|
||||
s.port = port
|
||||
}
|
||||
|
||||
@@ -6,7 +6,6 @@ import (
|
||||
"errors"
|
||||
"fmt"
|
||||
"log/slog"
|
||||
"net"
|
||||
"net/http"
|
||||
"time"
|
||||
|
||||
@@ -113,7 +112,7 @@ func New(
|
||||
}
|
||||
|
||||
lifecycle.Append(fx.Hook{
|
||||
OnStart: func(ctx context.Context) error {
|
||||
OnStart: func(_ context.Context) error {
|
||||
srv.startupTime = time.Now()
|
||||
|
||||
err := srv.enableSentry()
|
||||
@@ -121,7 +120,9 @@ func New(
|
||||
return err
|
||||
}
|
||||
|
||||
return srv.Run(ctx)
|
||||
go srv.Run()
|
||||
|
||||
return nil
|
||||
},
|
||||
OnStop: func(ctx context.Context) error {
|
||||
return srv.Shutdown(ctx)
|
||||
@@ -148,10 +149,8 @@ func newHTTPServer(
|
||||
}
|
||||
}
|
||||
|
||||
// Run binds the listen port, then serves HTTP on it in a new goroutine
|
||||
// and returns. A port that cannot be bound is returned as an error, so
|
||||
// that startup stops instead of running without the HTTP server.
|
||||
func (s *Server) Run(ctx context.Context) error {
|
||||
// Run starts the HTTP server.
|
||||
func (s *Server) Run() {
|
||||
s.SetupRoutes()
|
||||
|
||||
listenAddr := fmt.Sprintf(":%d", s.port)
|
||||
@@ -159,21 +158,10 @@ func (s *Server) Run(ctx context.Context) error {
|
||||
|
||||
s.log.Info("http server starting", "addr", listenAddr)
|
||||
|
||||
lc := &net.ListenConfig{}
|
||||
|
||||
listener, err := lc.Listen(ctx, "tcp", listenAddr)
|
||||
if err != nil {
|
||||
return fmt.Errorf("starting http server: %w", err)
|
||||
err := s.httpServer.ListenAndServe()
|
||||
if err != nil && !errors.Is(err, http.ErrServerClosed) {
|
||||
s.log.Error("http server error", "error", err)
|
||||
}
|
||||
|
||||
go func() {
|
||||
err := s.httpServer.Serve(listener)
|
||||
if err != nil && !errors.Is(err, http.ErrServerClosed) {
|
||||
s.log.Error("http server error", "error", err)
|
||||
}
|
||||
}()
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// Shutdown gracefully shuts down the server, then sends the error
|
||||
|
||||
@@ -1,8 +1,6 @@
|
||||
package server_test
|
||||
|
||||
import (
|
||||
"net"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/spf13/viper"
|
||||
@@ -60,13 +58,15 @@ func buildServer(t *testing.T) *server.Server {
|
||||
}
|
||||
|
||||
// TestRunWiresSocketTimeouts pins that the http.Server the running
|
||||
// server actually serves — the one Run builds and serves on the port
|
||||
// it binds — carries every socket-level timeout, plus the two
|
||||
// server actually serves — the one Run builds and hands to
|
||||
// ListenAndServe — carries every socket-level timeout, plus the two
|
||||
// relationships the values must satisfy.
|
||||
//
|
||||
// Run is given an unbindable port: it builds and stores s.httpServer,
|
||||
// then the bind fails and Run returns the error without ever
|
||||
// listening. Nothing here measures elapsed time.
|
||||
// Run is driven to completion with an unbindable port: it builds and
|
||||
// stores s.httpServer, then ListenAndServe fails at once and Run
|
||||
// returns without ever listening. The assertions run in the same
|
||||
// goroutine after Run returns, so reading s.httpServer is free of any
|
||||
// data race. Nothing here measures elapsed time.
|
||||
//
|
||||
// ReadTimeout must be at least ReadHeaderTimeout. net/http reads the
|
||||
// headers under ReadHeaderTimeout, then sets the read deadline for the
|
||||
@@ -84,10 +84,7 @@ func TestRunWiresSocketTimeouts(t *testing.T) {
|
||||
srv := buildServer(t)
|
||||
server.SetListenPort(srv, -1)
|
||||
|
||||
err := srv.Run(t.Context())
|
||||
if err == nil {
|
||||
t.Fatal("Run bound port -1")
|
||||
}
|
||||
srv.Run()
|
||||
|
||||
hs := server.HTTPServerOf(srv)
|
||||
if hs == nil {
|
||||
@@ -136,38 +133,3 @@ func TestRunWiresSocketTimeouts(t *testing.T) {
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
func TestPortInUseStopsStartup(t *testing.T) {
|
||||
// Bound on every address, as Run binds, so that Run's bind fails.
|
||||
lc := &net.ListenConfig{}
|
||||
|
||||
taken, err := lc.Listen(t.Context(), "tcp", ":0")
|
||||
if err != nil {
|
||||
t.Fatalf("binding a port for the test: %v", err)
|
||||
}
|
||||
|
||||
defer func() { _ = taken.Close() }()
|
||||
|
||||
_, port, err := net.SplitHostPort(taken.Addr().String())
|
||||
if err != nil {
|
||||
t.Fatalf("reading the bound port: %v", err)
|
||||
}
|
||||
|
||||
viper.Reset()
|
||||
t.Setenv("DNSWATCHER_TARGETS", "example.com")
|
||||
t.Setenv("DNSWATCHER_DATA_DIR", t.TempDir())
|
||||
t.Setenv("PORT", port)
|
||||
|
||||
app := newServerApp(fx.Invoke(func(*server.Server) {}))
|
||||
|
||||
err = app.Start(t.Context())
|
||||
if err == nil {
|
||||
_ = app.Stop(t.Context())
|
||||
|
||||
t.Fatal("startup succeeded on a port that is already bound")
|
||||
}
|
||||
|
||||
if !strings.Contains(err.Error(), ":"+port) {
|
||||
t.Errorf("startup error does not name port %s: %v", port, err)
|
||||
}
|
||||
}
|
||||
|
||||
+4
-52
@@ -4,10 +4,8 @@ package state
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"log/slog"
|
||||
"maps"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"slices"
|
||||
@@ -216,24 +214,6 @@ func (s *State) Load() error {
|
||||
return fmt.Errorf("parsing state file: %w", err)
|
||||
}
|
||||
|
||||
// A section the file leaves out, or holds as null, loads empty: the
|
||||
// setters write into these maps, and writing into a nil map panics.
|
||||
if snapshot.Domains == nil {
|
||||
snapshot.Domains = make(map[string]*DomainState)
|
||||
}
|
||||
|
||||
if snapshot.Hostnames == nil {
|
||||
snapshot.Hostnames = make(map[string]*HostnameState)
|
||||
}
|
||||
|
||||
if snapshot.Ports == nil {
|
||||
snapshot.Ports = make(map[string]*PortState)
|
||||
}
|
||||
|
||||
if snapshot.Certificates == nil {
|
||||
snapshot.Certificates = make(map[string]*CertificateState)
|
||||
}
|
||||
|
||||
// A state file saved before each record value was stored once can
|
||||
// hold a hostname's CNAME once for every record type asked for.
|
||||
// Each value is kept once, so the first check does not see a
|
||||
@@ -272,20 +252,10 @@ func (s *State) Save() error {
|
||||
return fmt.Errorf("creating data directory: %w", err)
|
||||
}
|
||||
|
||||
// Atomic write: write to temp file, then rename. The temp file is
|
||||
// synced before the rename and the directory after it, or a crash
|
||||
// can leave the renamed state file empty.
|
||||
// Atomic write: write to temp file, then rename
|
||||
tmpPath := path + ".tmp"
|
||||
|
||||
//nolint:gosec // path is from trusted config
|
||||
tmpFile, err := os.OpenFile(
|
||||
tmpPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, filePermissions,
|
||||
)
|
||||
if err == nil {
|
||||
_, err = tmpFile.Write(data)
|
||||
err = errors.Join(err, tmpFile.Sync(), tmpFile.Close())
|
||||
}
|
||||
|
||||
err = os.WriteFile(tmpPath, data, filePermissions)
|
||||
if err != nil {
|
||||
return fmt.Errorf("writing temp state file: %w", err)
|
||||
}
|
||||
@@ -295,35 +265,17 @@ func (s *State) Save() error {
|
||||
return fmt.Errorf("renaming state file: %w", err)
|
||||
}
|
||||
|
||||
dir, err := os.Open(filepath.Dir(path))
|
||||
if err == nil {
|
||||
err = errors.Join(dir.Sync(), dir.Close())
|
||||
}
|
||||
|
||||
if err != nil {
|
||||
return fmt.Errorf("syncing data directory: %w", err)
|
||||
}
|
||||
|
||||
s.log.Debug("state saved to disk", "path", path)
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// GetSnapshot returns a copy of the current snapshot, with copies of
|
||||
// its maps, so that a caller can range over them while the state is
|
||||
// written. The entries in the maps are not copied: an entry saved in the
|
||||
// state must be replaced, never changed in place.
|
||||
// GetSnapshot returns a copy of the current snapshot.
|
||||
func (s *State) GetSnapshot() Snapshot {
|
||||
s.mu.RLock()
|
||||
defer s.mu.RUnlock()
|
||||
|
||||
snap := *s.snapshot
|
||||
snap.Domains = maps.Clone(snap.Domains)
|
||||
snap.Hostnames = maps.Clone(snap.Hostnames)
|
||||
snap.Ports = maps.Clone(snap.Ports)
|
||||
snap.Certificates = maps.Clone(snap.Certificates)
|
||||
|
||||
return snap
|
||||
return *s.snapshot
|
||||
}
|
||||
|
||||
// SetDomainState updates the state for a domain.
|
||||
|
||||
@@ -618,53 +618,6 @@ func TestSaveAtomicWrite(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestSaveOverLeftoverTempFile verifies that a temp file left by a
|
||||
// crash, longer than the state Save writes, leaves nothing of itself in
|
||||
// the state file, and that no temp file remains after Save.
|
||||
func TestSaveOverLeftoverTempFile(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
dir := t.TempDir()
|
||||
statePath := filepath.Join(dir, "state.json")
|
||||
tmpPath := statePath + ".tmp"
|
||||
|
||||
err := os.WriteFile(tmpPath, []byte(strings.Repeat("x", 64*1024)), 0o600)
|
||||
if err != nil {
|
||||
t.Fatalf("writing leftover temp file: %v", err)
|
||||
}
|
||||
|
||||
s := state.NewForTestWithDataDir(dir)
|
||||
|
||||
populateState(t, s)
|
||||
|
||||
err = s.Save()
|
||||
if err != nil {
|
||||
t.Fatalf("Save() error: %v", err)
|
||||
}
|
||||
|
||||
//nolint:gosec // test file with known path
|
||||
data, err := os.ReadFile(statePath)
|
||||
if err != nil {
|
||||
t.Fatalf("reading state file: %v", err)
|
||||
}
|
||||
|
||||
var snap state.Snapshot
|
||||
|
||||
err = json.Unmarshal(data, &snap)
|
||||
if err != nil {
|
||||
t.Fatalf("state file is not complete JSON: %v", err)
|
||||
}
|
||||
|
||||
if len(snap.Domains) != 2 {
|
||||
t.Errorf("state file has %d domains, want 2", len(snap.Domains))
|
||||
}
|
||||
|
||||
_, err = os.Stat(tmpPath)
|
||||
if !os.IsNotExist(err) {
|
||||
t.Error("temp file should not exist after save")
|
||||
}
|
||||
}
|
||||
|
||||
// TestLoadMissingFile verifies that loading a nonexistent file is not an error.
|
||||
func TestLoadMissingFile(t *testing.T) {
|
||||
t.Parallel()
|
||||
@@ -695,58 +648,6 @@ func TestLoadMissingFile(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestLoadFileWithoutSections loads a state file holding {}, and files
|
||||
// that each leave out one section. Every section loads as an empty map.
|
||||
// TestFirstCheckAfterLoadingFileWithoutSections in the watcher tests
|
||||
// runs the first check after such a load.
|
||||
func TestLoadFileWithoutSections(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
file string
|
||||
}{
|
||||
{"no sections", `{}`},
|
||||
{"no domains", `{"hostnames": {}, "ports": {}, "certificates": {}}`},
|
||||
{"no hostnames", `{"domains": {}, "ports": {}, "certificates": {}}`},
|
||||
{"no ports", `{"domains": {}, "hostnames": {}, "certificates": {}}`},
|
||||
{"no certificates", `{"domains": {}, "hostnames": {}, "ports": {}}`},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
dir := t.TempDir()
|
||||
|
||||
err := os.WriteFile(
|
||||
filepath.Join(dir, "state.json"), []byte(tt.file), 0o600,
|
||||
)
|
||||
if err != nil {
|
||||
t.Fatalf("writing state file: %v", err)
|
||||
}
|
||||
|
||||
s := state.NewForTestWithDataDir(dir)
|
||||
|
||||
err = s.Load()
|
||||
if err != nil {
|
||||
t.Fatalf("Load() error: %v", err)
|
||||
}
|
||||
|
||||
want := state.Snapshot{
|
||||
Domains: map[string]*state.DomainState{},
|
||||
Hostnames: map[string]*state.HostnameState{},
|
||||
Ports: map[string]*state.PortState{},
|
||||
Certificates: map[string]*state.CertificateState{},
|
||||
}
|
||||
|
||||
if got := s.GetSnapshot(); !reflect.DeepEqual(got, want) {
|
||||
t.Errorf("loaded %#v, want %#v", got, want)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestLoadCorruptFile verifies that a corrupt state file returns an error.
|
||||
func TestLoadCorruptFile(t *testing.T) {
|
||||
t.Parallel()
|
||||
@@ -1094,8 +995,7 @@ func TestPortStateUnmarshalJSON_BothFormats(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestGetSnapshot_ReturnsCopy verifies that the maps in the snapshot
|
||||
// GetSnapshot returns are not the state's own.
|
||||
// TestGetSnapshot_ReturnsCopy verifies that GetSnapshot returns a value copy.
|
||||
func TestGetSnapshot_ReturnsCopy(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
@@ -1105,67 +1005,15 @@ func TestGetSnapshot_ReturnsCopy(t *testing.T) {
|
||||
|
||||
snap := s.GetSnapshot()
|
||||
|
||||
const added = "added.example.com"
|
||||
|
||||
snap.Domains[added] = &state.DomainState{}
|
||||
snap.Hostnames[added] = &state.HostnameState{}
|
||||
snap.Ports[added] = &state.PortState{}
|
||||
snap.Certificates[added] = &state.CertificateState{}
|
||||
|
||||
if _, ok := s.GetDomainState(added); ok {
|
||||
t.Error("the snapshot's Domains map is the state's own")
|
||||
// Mutate the returned snapshot's map.
|
||||
snap.Domains["mutated.example.com"] = &state.DomainState{
|
||||
Nameservers: []string{"ns1.mutated.com."},
|
||||
}
|
||||
|
||||
if _, ok := s.GetHostnameState(added); ok {
|
||||
t.Error("the snapshot's Hostnames map is the state's own")
|
||||
}
|
||||
|
||||
if _, ok := s.GetPortState(added); ok {
|
||||
t.Error("the snapshot's Ports map is the state's own")
|
||||
}
|
||||
|
||||
if _, ok := s.GetCertificateState(added); ok {
|
||||
t.Error("the snapshot's Certificates map is the state's own")
|
||||
}
|
||||
}
|
||||
|
||||
// TestGetSnapshot_WhileWritten ranges over snapshots while another
|
||||
// goroutine writes the state, as the dashboard does while a check runs.
|
||||
// Under -race it fails when a snapshot's maps are the state's own.
|
||||
func TestGetSnapshot_WhileWritten(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
s := state.NewForTestWithDataDir(t.TempDir())
|
||||
|
||||
const writes = 1000
|
||||
|
||||
written := make(chan struct{})
|
||||
|
||||
go func() {
|
||||
defer close(written)
|
||||
|
||||
for range writes {
|
||||
s.SetDomainState("example.com", &state.DomainState{})
|
||||
s.SetHostnameState(testHostname, &state.HostnameState{})
|
||||
s.SetPortState(testIPv4+":443", &state.PortState{})
|
||||
s.SetCertificateState(
|
||||
testIPv4+":443:"+testHostname, &state.CertificateState{},
|
||||
)
|
||||
}
|
||||
}()
|
||||
|
||||
for {
|
||||
select {
|
||||
case <-written:
|
||||
return
|
||||
default:
|
||||
}
|
||||
|
||||
// json.Marshal ranges over each of the snapshot's maps.
|
||||
_, err := json.Marshal(s.GetSnapshot())
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
// The original domain data should still be accessible.
|
||||
_, ok := s.GetDomainState("example.com")
|
||||
if !ok {
|
||||
t.Error("original domain should still exist")
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -83,30 +83,6 @@ func TestCancelledCheckSavesNothing(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestStopBeforeFirstScanSendsNoStartupNotification runs a watcher with
|
||||
// the startup notification on and its context already cancelled, so the
|
||||
// first scan is cut short before its lookup is sent. The scan did not
|
||||
// complete, so no startup notification may be sent.
|
||||
func TestStopBeforeFirstScanSendsNoStartupNotification(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
cfg := defaultTestConfig(t)
|
||||
cfg.Hostnames = []string{testHost}
|
||||
cfg.SendTestNotification = true
|
||||
|
||||
w, deps := newTestWatcher(t, cfg)
|
||||
|
||||
ctx, cancel := context.WithCancel(t.Context())
|
||||
cancel()
|
||||
|
||||
w.Run(ctx)
|
||||
|
||||
notifications := deps.notifier.getNotifications()
|
||||
if len(notifications) != 0 {
|
||||
t.Errorf("sent %v, want no notifications", notifications)
|
||||
}
|
||||
}
|
||||
|
||||
// newLoggingWatcher returns a watcher for a domain and a hostname, with
|
||||
// the real resolver, that writes what it logs at warning level or above
|
||||
// into the returned buffer.
|
||||
|
||||
@@ -122,34 +122,6 @@ func (w *Watcher) RunTLSChecks(ctx context.Context) {
|
||||
w.runTLSChecks(ctx)
|
||||
}
|
||||
|
||||
// CheckHostnameResult exports checkHostnameResult for testing.
|
||||
func (w *Watcher) CheckHostnameResult(
|
||||
ctx context.Context,
|
||||
hostname string,
|
||||
results map[string]*resolver.NameserverResponse,
|
||||
err error,
|
||||
) bool {
|
||||
return w.checkHostnameResult(ctx, hostname, results, err)
|
||||
}
|
||||
|
||||
// CheckDomainResult exports checkDomainResult for testing.
|
||||
func (w *Watcher) CheckDomainResult(
|
||||
ctx context.Context,
|
||||
domain string,
|
||||
nameservers []string,
|
||||
err error,
|
||||
) {
|
||||
w.checkDomainResult(ctx, domain, nameservers, err)
|
||||
}
|
||||
|
||||
// FailedNameservers exports failedNameservers for testing.
|
||||
func FailedNameservers(
|
||||
err error,
|
||||
prev *state.HostnameState,
|
||||
) map[string]*resolver.NameserverResponse {
|
||||
return failedNameservers(err, prev)
|
||||
}
|
||||
|
||||
// BuildHostnameState exports buildHostnameState for testing.
|
||||
func BuildHostnameState(
|
||||
results map[string]*resolver.NameserverResponse,
|
||||
|
||||
@@ -20,10 +20,7 @@ type DNSResolver interface {
|
||||
) ([]string, error)
|
||||
|
||||
// LookupAllRecords queries all record types for a hostname,
|
||||
// returning each nameserver's response keyed by nameserver. When
|
||||
// the walk to the nameservers reached a zone through a referral and
|
||||
// none of that zone's nameservers answered, the error is a
|
||||
// *resolver.NoAnswerError naming them.
|
||||
// returning each nameserver's response keyed by nameserver.
|
||||
LookupAllRecords(
|
||||
ctx context.Context,
|
||||
hostname string,
|
||||
|
||||
@@ -1,83 +0,0 @@
|
||||
package watcher_test
|
||||
|
||||
import (
|
||||
"maps"
|
||||
"slices"
|
||||
"testing"
|
||||
|
||||
"sneak.berlin/go/dnswatcher/internal/state"
|
||||
"sneak.berlin/go/dnswatcher/internal/watcher"
|
||||
)
|
||||
|
||||
// TestIPv6AddressInBrackets runs the port checks, not the watcher's
|
||||
// first, on hostname state built here for a hostname at an IPv6 address
|
||||
// whose port 443 the previous check found closed. It is open now. Then
|
||||
// it runs the TLS checks and the port checks again. The port and
|
||||
// certificate keys and the Port Change notification write the address
|
||||
// in brackets, so its last group cannot be read as the port, and the
|
||||
// second port checks keep the certificate entry, whose address they read
|
||||
// back from its key. When a last port check finds port 443 closed, the
|
||||
// certificate entry is removed. Nothing is looked up.
|
||||
func TestIPv6AddressInBrackets(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
const aaaaType = "AAAA"
|
||||
|
||||
cfg := defaultTestConfig(t)
|
||||
cfg.Hostnames = []string{host}
|
||||
|
||||
deps := newTestDeps(t, cfg)
|
||||
w := watcher.NewForTest(
|
||||
cfg, deps.state, nil,
|
||||
deps.portChecker, deps.tlsChecker, deps.notifier,
|
||||
)
|
||||
w.SetFirstRun(false)
|
||||
|
||||
deps.state.SetHostnameState(host, saved(
|
||||
map[string]*state.NameserverRecordState{
|
||||
nsA: answered(map[string][]string{aaaaType: {"2001:db8::1"}}),
|
||||
},
|
||||
))
|
||||
deps.state.SetPortState("[2001:db8::1]:443", &state.PortState{
|
||||
Hostnames: []string{host},
|
||||
})
|
||||
|
||||
w.CheckAllPorts(t.Context())
|
||||
w.RunTLSChecks(t.Context())
|
||||
w.CheckAllPorts(t.Context())
|
||||
|
||||
snap := deps.state.GetSnapshot()
|
||||
|
||||
gotPorts := slices.Sorted(maps.Keys(snap.Ports))
|
||||
wantPorts := []string{"[2001:db8::1]:443", "[2001:db8::1]:80"}
|
||||
|
||||
if !slices.Equal(gotPorts, wantPorts) {
|
||||
t.Errorf("port entries %v, want %v", gotPorts, wantPorts)
|
||||
}
|
||||
|
||||
gotCerts := slices.Sorted(maps.Keys(snap.Certificates))
|
||||
wantCerts := []string{"[2001:db8::1]:443:www.example.net"}
|
||||
|
||||
if !slices.Equal(gotCerts, wantCerts) {
|
||||
t.Errorf("certificate entries %v, want %v", gotCerts, wantCerts)
|
||||
}
|
||||
|
||||
title := "Port Change: [2001:db8::1]:443"
|
||||
want := `Hostnames: www.example.net
|
||||
Address: [2001:db8::1]:443
|
||||
Port now open`
|
||||
|
||||
got := deps.notifier.getNotifications()
|
||||
if len(got) != 1 || got[0].Title != title || got[0].Message != want {
|
||||
t.Errorf("sent %v, want one %q with message:\n%s", got, title, want)
|
||||
}
|
||||
|
||||
deps.portChecker.closed = true
|
||||
|
||||
w.CheckAllPorts(t.Context())
|
||||
|
||||
gotCerts = slices.Sorted(maps.Keys(deps.state.GetSnapshot().Certificates))
|
||||
if len(gotCerts) != 0 {
|
||||
t.Errorf("certificate entries %v with port 443 closed, want none", gotCerts)
|
||||
}
|
||||
}
|
||||
@@ -5,6 +5,7 @@ import (
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"sneak.berlin/go/dnswatcher/internal/config"
|
||||
"sneak.berlin/go/dnswatcher/internal/state"
|
||||
"sneak.berlin/go/dnswatcher/internal/watcher"
|
||||
)
|
||||
@@ -73,19 +74,21 @@ b.ns.example.net.: 192.0.2.2`,
|
||||
func TestDomainRecordNotificationsNameTheDomain(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
cfg := defaultTestConfig(t)
|
||||
cfg.Domains = []string{domain}
|
||||
|
||||
deps := newTestDeps(t, cfg)
|
||||
w := watcher.NewForTest(cfg, deps.state, nil, nil, nil, deps.notifier)
|
||||
notifier := &mockNotifier{}
|
||||
w := watcher.NewForTest(
|
||||
&config.Config{Domains: []string{domain}},
|
||||
nil, nil, nil, nil, notifier,
|
||||
)
|
||||
|
||||
// nsA's address changes, which also makes it differ from nsC; nsB
|
||||
// fails; nsC answers again.
|
||||
// fails; nsC answers again; nsD is gone.
|
||||
nsD := "d.ns.example.net."
|
||||
w.DetectHostnameChanges(t.Context(), domain,
|
||||
saved(map[string]*state.NameserverRecordState{
|
||||
nsA: answered(map[string][]string{"A": {ip1}}),
|
||||
nsB: answered(map[string][]string{"A": {ip1}}),
|
||||
nsC: failed(),
|
||||
nsD: answered(map[string][]string{"A": {ip1}}),
|
||||
}),
|
||||
saved(map[string]*state.NameserverRecordState{
|
||||
nsA: answered(map[string][]string{"A": {ip2}}),
|
||||
@@ -99,17 +102,18 @@ func TestDomainRecordNotificationsNameTheDomain(t *testing.T) {
|
||||
t.Context(), domain, cnameState(ip1), cnameState(ip2),
|
||||
)
|
||||
|
||||
// NS Failure is sent for nsB failing and for nsD being gone.
|
||||
want := map[string]int{
|
||||
"Record Change": 1,
|
||||
"Inconsistency": 1,
|
||||
"NS Failure": 1,
|
||||
"NS Failure": 2,
|
||||
"NS Recovery": 1,
|
||||
"CNAME Address Change": 1,
|
||||
}
|
||||
|
||||
sent := make(map[string]int)
|
||||
|
||||
for _, n := range deps.notifier.getNotifications() {
|
||||
for _, n := range notifier.getNotifications() {
|
||||
kind, _, _ := strings.Cut(n.Title, ":")
|
||||
sent[kind]++
|
||||
|
||||
@@ -124,89 +128,6 @@ func TestDomainRecordNotificationsNameTheDomain(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// nsB, which answered, and nsC, which did not, are no longer among the
|
||||
// nameservers. One NS Change lists both, for the hostname and for the
|
||||
// configured apex domain with no delegation of its own. Nothing is sent
|
||||
// for the domain whose delegation on the previous check listed them:
|
||||
// the check of its delegation sends its NS Change.
|
||||
func TestRemovedNameserversAreAnNSChange(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
target string
|
||||
// The domain's nameservers saved by the previous check.
|
||||
delegation []string
|
||||
// The NS Change sent, or "" for none.
|
||||
want string
|
||||
}{
|
||||
{
|
||||
name: "hostname",
|
||||
target: host,
|
||||
want: `Hostname: www.example.net
|
||||
Removed: b.ns.example.net., c.ns.example.net.`,
|
||||
},
|
||||
{
|
||||
name: "domain with no delegation of its own",
|
||||
target: domain,
|
||||
delegation: []string{},
|
||||
want: `Domain: example.net
|
||||
Removed: b.ns.example.net., c.ns.example.net.`,
|
||||
},
|
||||
{
|
||||
name: "domain whose delegation listed them",
|
||||
target: domain,
|
||||
delegation: []string{nsA, nsB, nsC},
|
||||
},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
cfg := defaultTestConfig(t)
|
||||
cfg.Domains = []string{domain}
|
||||
|
||||
deps := newTestDeps(t, cfg)
|
||||
w := watcher.NewForTest(
|
||||
cfg, deps.state, nil, nil, nil, deps.notifier,
|
||||
)
|
||||
|
||||
deps.state.SetDomainState(domain, &state.DomainState{
|
||||
Nameservers: tt.delegation,
|
||||
})
|
||||
|
||||
prev := saved(map[string]*state.NameserverRecordState{
|
||||
nsA: answered(map[string][]string{"A": {ip1}}),
|
||||
nsB: answered(map[string][]string{"A": {ip1}}),
|
||||
nsC: failed(),
|
||||
})
|
||||
current := saved(map[string]*state.NameserverRecordState{
|
||||
nsA: answered(map[string][]string{"A": {ip1}}),
|
||||
})
|
||||
|
||||
w.DetectHostnameChanges(t.Context(), tt.target, prev, current)
|
||||
|
||||
got := deps.notifier.getNotifications()
|
||||
|
||||
if tt.want == "" {
|
||||
if len(got) != 0 {
|
||||
t.Errorf("sent %v, want nothing", got)
|
||||
}
|
||||
|
||||
return
|
||||
}
|
||||
|
||||
title := "NS Change: " + tt.target
|
||||
if len(got) != 1 || got[0].Title != title ||
|
||||
got[0].Message != tt.want {
|
||||
t.Errorf("sent %v, want one %q with message:\n%s",
|
||||
got, title, tt.want)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// The startup notification counts the configured domains and hostnames,
|
||||
// although the state's hostnames also hold the apex domain's own
|
||||
// records. Nothing is looked up: the watcher has no resolver.
|
||||
|
||||
@@ -2,7 +2,6 @@ package watcher_test
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"fmt"
|
||||
"log/slog"
|
||||
"strings"
|
||||
@@ -15,10 +14,6 @@ import (
|
||||
"sneak.berlin/go/dnswatcher/internal/watcher"
|
||||
)
|
||||
|
||||
// errNoReply is why a walk that got no reply from a zone's servers
|
||||
// failed.
|
||||
var errNoReply = errors.New("all servers failed: i/o timeout")
|
||||
|
||||
// answered is what a check saves for a nameserver that answered with
|
||||
// these records.
|
||||
func answered(records map[string][]string) *state.NameserverRecordState {
|
||||
@@ -188,134 +183,6 @@ func TestNSFailureAlertNamesHostnameNameserverAndReason(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestZoneNameserversAllStopAnswering runs three checks of host from
|
||||
// the point where its lookup has returned. On the first, nsA and nsB,
|
||||
// the nameservers of its zone, answer. On the second, the lookup fails
|
||||
// with the error the walk to them returns when neither answers (see
|
||||
// the resolver's TestFollowDelegation_NoAnswerAfterReferral), given
|
||||
// here because no live zone has nameservers that never answer. For a
|
||||
// hostname it is the lookup of its records that fails, and for a domain
|
||||
// with no delegation of its own the lookup of its delegation. Both are
|
||||
// saved as failed, with the reason, and each gets an NS Failure. On the
|
||||
// third, both answer, and each gets an NS Recovery. A domain's records
|
||||
// are checked as a hostname's, so its first and third checks are too.
|
||||
func TestZoneNameserversAllStopAnswering(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
records := map[string][]string{"A": {ip1}}
|
||||
bothAnswer := map[string]*resolver.NameserverResponse{
|
||||
nsA: response(records), nsB: response(records),
|
||||
}
|
||||
noAnswer := &resolver.NoAnswerError{
|
||||
Nameservers: []string{nsA, nsB}, Err: errNoReply,
|
||||
}
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
isDomain bool
|
||||
}{
|
||||
{"hostname", false},
|
||||
{"domain with no delegation of its own", true},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
cfg := defaultTestConfig(t)
|
||||
if tt.isDomain {
|
||||
cfg.Domains = []string{host}
|
||||
} else {
|
||||
cfg.Hostnames = []string{host}
|
||||
}
|
||||
|
||||
// The watcher is given each lookup's result, so it has no
|
||||
// resolver.
|
||||
deps := newTestDeps(t, cfg)
|
||||
w := watcher.NewForTest(
|
||||
cfg, deps.state, nil,
|
||||
deps.portChecker, deps.tlsChecker, deps.notifier,
|
||||
)
|
||||
w.SetFirstRun(false)
|
||||
|
||||
w.CheckHostnameResult(t.Context(), host, bothAnswer, nil)
|
||||
|
||||
if tt.isDomain {
|
||||
w.CheckDomainResult(t.Context(), host, nil, noAnswer)
|
||||
} else {
|
||||
w.CheckHostnameResult(t.Context(), host, nil, noAnswer)
|
||||
}
|
||||
|
||||
current, _ := deps.state.GetHostnameState(host)
|
||||
|
||||
for _, ns := range []string{nsA, nsB} {
|
||||
got := current.RecordsByNameserver[ns]
|
||||
if got.Status != failed().Status || got.Error != errNoReply.Error() {
|
||||
t.Errorf(
|
||||
"%s saved with status %q, error %q; want %q, %q",
|
||||
ns, got.Status, got.Error, failed().Status, errNoReply,
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
if n := countNotifications(deps, "NS Failure: "+host); n != 2 {
|
||||
t.Errorf("sent %d NS Failure notifications, want 2", n)
|
||||
}
|
||||
|
||||
w.CheckHostnameResult(t.Context(), host, bothAnswer, nil)
|
||||
|
||||
if n := countNotifications(deps, "NS Recovery: "+host); n != 2 {
|
||||
t.Errorf("sent %d NS Recovery notifications, want 2", n)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestFailedNameserversOnlyForThoseOfThePreviousCheck gives
|
||||
// FailedNameservers lookup errors after a check in which nsA and nsB
|
||||
// answered. Only an error that names both makes them failed.
|
||||
func TestFailedNameserversOnlyForThoseOfThePreviousCheck(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
records := map[string][]string{"A": {ip1}}
|
||||
bothAnswered := saved(map[string]*state.NameserverRecordState{
|
||||
nsA: answered(records), nsB: answered(records),
|
||||
})
|
||||
noAnswer := func(nameservers ...string) error {
|
||||
return &resolver.NoAnswerError{Nameservers: nameservers, Err: errNoReply}
|
||||
}
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
err error
|
||||
prev *state.HostnameState
|
||||
wantFailed bool
|
||||
}{
|
||||
{"both did not answer", noAnswer(nsA, nsB), bothAnswered, true},
|
||||
{
|
||||
"the servers of a parent zone did not answer",
|
||||
noAnswer(nsC), bothAnswered, false,
|
||||
},
|
||||
{
|
||||
"the zone's delegation lists only nsA now",
|
||||
noAnswer(nsA), bothAnswered, false,
|
||||
},
|
||||
{"no root server answered", errNoReply, bothAnswered, false},
|
||||
{"no previous check", noAnswer(nsA, nsB), nil, false},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
got := watcher.FailedNameservers(tt.err, tt.prev)
|
||||
if (got != nil) != tt.wantFailed {
|
||||
t.Errorf("returned %v, want failed: %v", got, tt.wantFailed)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestNameserverThatNeverAnswers asks a nameserver address where
|
||||
// nothing answers, 192.0.2.1, and checks what the watcher saves for it.
|
||||
// The deadline outlasts the resolver's first two-second try, as in the
|
||||
|
||||
@@ -2,9 +2,7 @@ package watcher_test
|
||||
|
||||
import (
|
||||
"maps"
|
||||
"net"
|
||||
"slices"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"sneak.berlin/go/dnswatcher/internal/state"
|
||||
@@ -174,7 +172,7 @@ func TestCertificateStateForAnAddressGone(t *testing.T) {
|
||||
"A": {ip1}, "AAAA": {ip6},
|
||||
}),
|
||||
}),
|
||||
[]string{ip1 + ":443:" + host, "[" + ip6 + "]:443:" + host},
|
||||
[]string{ip1 + ":443:" + host, ip6 + ":443:" + host},
|
||||
},
|
||||
{
|
||||
"no nameserver answered",
|
||||
@@ -184,7 +182,7 @@ func TestCertificateStateForAnAddressGone(t *testing.T) {
|
||||
[]string{
|
||||
ip1 + ":443:" + host,
|
||||
ip2 + ":443:" + host,
|
||||
"[" + ip6 + "]:443:" + host,
|
||||
ip6 + ":443:" + host,
|
||||
},
|
||||
},
|
||||
}
|
||||
@@ -207,8 +205,7 @@ func TestCertificateStateForAnAddressGone(t *testing.T) {
|
||||
|
||||
for _, ip := range []string{ip1, ip2, ip6} {
|
||||
deps.state.SetCertificateState(
|
||||
net.JoinHostPort(ip, "443")+":"+host,
|
||||
&state.CertificateState{Status: "ok"},
|
||||
ip+":443:"+host, &state.CertificateState{Status: "ok"},
|
||||
)
|
||||
}
|
||||
|
||||
@@ -225,67 +222,3 @@ func TestCertificateStateForAnAddressGone(t *testing.T) {
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestCertificateStateForAPortClosed runs the port checks on hostname
|
||||
// and port state built here for a configured hostname at ip1, whose
|
||||
// port 443 the previous check found open and whose certificate entry
|
||||
// is ok. The port is closed now: the certificate entry is removed, and
|
||||
// only the Port Change is notified. When the port opens again, the next
|
||||
// TLS check saves the certificate as new and notifies nothing about it.
|
||||
// Nothing is looked up.
|
||||
func TestCertificateStateForAPortClosed(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
cfg := defaultTestConfig(t)
|
||||
cfg.Hostnames = []string{host}
|
||||
|
||||
deps := newTestDeps(t, cfg)
|
||||
w := watcher.NewForTest(
|
||||
cfg, deps.state, nil,
|
||||
deps.portChecker, deps.tlsChecker, deps.notifier,
|
||||
)
|
||||
w.SetFirstRun(false)
|
||||
|
||||
certKey := ip1 + ":443:" + host
|
||||
|
||||
deps.state.SetHostnameState(host, saved(
|
||||
map[string]*state.NameserverRecordState{
|
||||
nsA: answered(map[string][]string{"A": {ip1}}),
|
||||
},
|
||||
))
|
||||
deps.state.SetPortState(ip1+":443", &state.PortState{
|
||||
Open: true, Hostnames: []string{host},
|
||||
})
|
||||
deps.state.SetCertificateState(certKey, &state.CertificateState{
|
||||
CommonName: host, Status: "ok",
|
||||
})
|
||||
deps.portChecker.closed = true
|
||||
|
||||
w.CheckAllPorts(t.Context())
|
||||
|
||||
if _, ok := deps.state.GetCertificateState(certKey); ok {
|
||||
t.Errorf("certificate entry %s kept with port 443 closed", certKey)
|
||||
}
|
||||
|
||||
sent := deps.notifier.getNotifications()
|
||||
if title := "Port Change: " + ip1 + ":443"; len(sent) != 1 ||
|
||||
sent[0].Title != title {
|
||||
t.Errorf("sent %v, want one %q", sent, title)
|
||||
}
|
||||
|
||||
deps.portChecker.closed = false
|
||||
|
||||
w.CheckAllPorts(t.Context())
|
||||
w.RunTLSChecks(t.Context())
|
||||
|
||||
cert, ok := deps.state.GetCertificateState(certKey)
|
||||
if !ok || cert.Status != "ok" {
|
||||
t.Errorf("certificate entry %s after port 443 opened: %+v", certKey, cert)
|
||||
}
|
||||
|
||||
for _, n := range deps.notifier.getNotifications() {
|
||||
if strings.HasPrefix(n.Title, "TLS") {
|
||||
t.Errorf("sent %v, want no TLS notification", n)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
+48
-163
@@ -6,10 +6,8 @@ import (
|
||||
"fmt"
|
||||
"log/slog"
|
||||
"maps"
|
||||
"net"
|
||||
"slices"
|
||||
"sort"
|
||||
"strconv"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
@@ -135,12 +133,7 @@ func (w *Watcher) Run(ctx context.Context) {
|
||||
|
||||
w.cleanupRemovedTargets()
|
||||
w.RunOnce(ctx)
|
||||
|
||||
// RunOnce returns as usual when shutdown cuts the scan short, and
|
||||
// the startup notification says the scan completed.
|
||||
if ctx.Err() == nil {
|
||||
w.maybeSendTestNotification(ctx)
|
||||
}
|
||||
w.maybeSendTestNotification(ctx)
|
||||
|
||||
dnsTicker := time.NewTicker(w.config.DNSInterval)
|
||||
tlsTicker := time.NewTicker(w.config.TLSInterval)
|
||||
@@ -291,25 +284,12 @@ func (w *Watcher) logFailedLookup(
|
||||
w.log.Error(msg, args...)
|
||||
}
|
||||
|
||||
// checkDomain looks up domain's delegation and checks domain with it
|
||||
// (see checkDomainResult).
|
||||
func (w *Watcher) checkDomain(
|
||||
ctx context.Context,
|
||||
domain string,
|
||||
) {
|
||||
nameservers, err := w.resolver.LookupNS(ctx, domain)
|
||||
|
||||
w.checkDomainResult(ctx, domain, nameservers, err)
|
||||
}
|
||||
|
||||
// checkDomainResult finishes a check of domain from nameservers and err,
|
||||
// what the lookup of its delegation returned.
|
||||
func (w *Watcher) checkDomainResult(
|
||||
ctx context.Context,
|
||||
domain string,
|
||||
nameservers []string,
|
||||
err error,
|
||||
) {
|
||||
// A domain that does not exist has no nameservers.
|
||||
nxdomain := errors.Is(err, resolver.ErrNXDomain)
|
||||
if nxdomain {
|
||||
@@ -324,12 +304,6 @@ func (w *Watcher) checkDomainResult(
|
||||
"error", err,
|
||||
)
|
||||
|
||||
// For a domain with no delegation of its own, the servers that
|
||||
// did not answer can be those of the zone it is in, at which
|
||||
// its records are asked. They are then saved as failed, as a
|
||||
// hostname's are.
|
||||
w.checkHostnameResult(ctx, domain, nil, err)
|
||||
|
||||
return
|
||||
}
|
||||
|
||||
@@ -348,20 +322,6 @@ func (w *Watcher) checkDomainResult(
|
||||
ctx, nameservers, prevAddresses,
|
||||
)
|
||||
|
||||
// A domain that does not exist has no records of its own: none are
|
||||
// asked for, and those saved by an earlier check are removed.
|
||||
// Otherwise the apex domain's records are also checked and saved as
|
||||
// a hostname's, so that the port and TLS checks find its addresses.
|
||||
// Notifications about them name it as a domain (see nameLine). When
|
||||
// their lookup fails, the check fails as when the NS lookup does, so
|
||||
// the saved delegation and the saved records come from the same
|
||||
// check, as detectNSDisappearances needs.
|
||||
if nxdomain {
|
||||
w.state.DeleteHostnameState(domain)
|
||||
} else if !w.checkHostname(ctx, domain) {
|
||||
return
|
||||
}
|
||||
|
||||
if hasPrev && !w.firstRun {
|
||||
w.detectNSChanges(ctx, domain, prev.Nameservers, nameservers)
|
||||
w.detectNSAddressChanges(ctx, domain, prevAddresses, addresses)
|
||||
@@ -373,6 +333,19 @@ func (w *Watcher) checkDomainResult(
|
||||
NXDomain: nxdomain,
|
||||
LastChecked: now,
|
||||
})
|
||||
|
||||
// A domain that does not exist has no records of its own: none are
|
||||
// asked for, and those saved by an earlier check are removed.
|
||||
if nxdomain {
|
||||
w.state.DeleteHostnameState(domain)
|
||||
|
||||
return
|
||||
}
|
||||
|
||||
// The apex domain's records are also checked and saved as a
|
||||
// hostname's, so that the port and TLS checks find its addresses.
|
||||
// Notifications about them name it as a domain (see nameLine).
|
||||
w.checkHostname(ctx, domain)
|
||||
}
|
||||
|
||||
func (w *Watcher) detectNSChanges(
|
||||
@@ -483,12 +456,10 @@ func (w *Watcher) detectNSAddressChanges(
|
||||
}
|
||||
}
|
||||
|
||||
// checkHostname looks up hostname's records and checks them (see
|
||||
// checkHostnameResult). It reports whether it saved them.
|
||||
func (w *Watcher) checkHostname(
|
||||
ctx context.Context,
|
||||
hostname string,
|
||||
) bool {
|
||||
) {
|
||||
results, err := w.resolver.LookupAllRecords(ctx, hostname)
|
||||
if err != nil {
|
||||
w.logFailedLookup(
|
||||
@@ -497,70 +468,15 @@ func (w *Watcher) checkHostname(
|
||||
"hostname", hostname,
|
||||
"error", err,
|
||||
)
|
||||
|
||||
return
|
||||
}
|
||||
|
||||
return w.checkHostnameResult(ctx, hostname, results, err)
|
||||
}
|
||||
|
||||
// checkHostnameResult finishes a check of hostname from results and err,
|
||||
// what the lookup of its records returned, and reports whether it saved
|
||||
// them. When the lookup failed, it saves nothing, unless the nameservers
|
||||
// that did not answer are those of the previous check (see
|
||||
// failedNameservers).
|
||||
func (w *Watcher) checkHostnameResult(
|
||||
ctx context.Context,
|
||||
hostname string,
|
||||
results map[string]*resolver.NameserverResponse,
|
||||
err error,
|
||||
) bool {
|
||||
prev, _ := w.state.GetHostnameState(hostname)
|
||||
|
||||
if err != nil {
|
||||
results = failedNameservers(err, prev)
|
||||
if results == nil {
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
w.updateHostnameState(
|
||||
ctx, hostname, buildHostnameState(results, prev, time.Now().UTC()),
|
||||
)
|
||||
|
||||
return true
|
||||
}
|
||||
|
||||
// failedNameservers returns a failed response for each nameserver in
|
||||
// prev, a name's state from the previous check, with err as the reason,
|
||||
// when err says that the walk to the name's nameservers reached their
|
||||
// zone and none of them answered. For any other error, as when the walk
|
||||
// got no answer before it reached their zone, or when prev is nil, it
|
||||
// returns nil.
|
||||
func failedNameservers(
|
||||
err error,
|
||||
prev *state.HostnameState,
|
||||
) map[string]*resolver.NameserverResponse {
|
||||
var noAnswer *resolver.NoAnswerError
|
||||
if !errors.As(err, &noAnswer) || prev == nil {
|
||||
return nil
|
||||
}
|
||||
|
||||
saved := slices.Sorted(maps.Keys(prev.RecordsByNameserver))
|
||||
if !slices.Equal(noAnswer.Nameservers, saved) {
|
||||
return nil
|
||||
}
|
||||
|
||||
results := make(map[string]*resolver.NameserverResponse)
|
||||
|
||||
for _, ns := range saved {
|
||||
results[ns] = &resolver.NameserverResponse{
|
||||
Nameserver: ns,
|
||||
Records: make(map[string][]string),
|
||||
Status: resolver.StatusError,
|
||||
Error: err.Error(),
|
||||
}
|
||||
}
|
||||
|
||||
return results
|
||||
}
|
||||
|
||||
// updateHostnameState finishes a check of hostname from newState, built
|
||||
@@ -856,53 +772,28 @@ func (w *Watcher) detectRecordChanges(
|
||||
}
|
||||
}
|
||||
|
||||
// detectNSDisappearances sends one NS Change listing the nameservers of
|
||||
// the previous check that are no longer those of the zone hostname is
|
||||
// in. For a configured apex domain it leaves out those of the domain's
|
||||
// saved delegation, which detectNSChanges notifies when they are removed
|
||||
// from it. checkDomain saves a new delegation only after this runs, and
|
||||
// only together with the records, so the saved delegation and the
|
||||
// nameservers in prev come from the same check.
|
||||
func (w *Watcher) detectNSDisappearances(
|
||||
ctx context.Context,
|
||||
hostname string,
|
||||
prev, current *state.HostnameState,
|
||||
) {
|
||||
var delegation []string
|
||||
|
||||
if w.isDomain(hostname) {
|
||||
if domainState, ok := w.state.GetDomainState(hostname); ok {
|
||||
delegation = domainState.Nameservers
|
||||
for ns, prevNS := range prev.RecordsByNameserver {
|
||||
if _, ok := current.RecordsByNameserver[ns]; ok || prevNS.Status != statusOK {
|
||||
continue
|
||||
}
|
||||
|
||||
msg := fmt.Sprintf(
|
||||
"%s\nNameserver: %s disappeared",
|
||||
w.nameLine(hostname), ns,
|
||||
)
|
||||
|
||||
w.notify.SendNotification(
|
||||
ctx,
|
||||
"NS Failure: "+hostname,
|
||||
msg,
|
||||
"error",
|
||||
)
|
||||
}
|
||||
|
||||
var removed []string
|
||||
|
||||
for ns := range prev.RecordsByNameserver {
|
||||
_, ok := current.RecordsByNameserver[ns]
|
||||
if !ok && !slices.Contains(delegation, ns) {
|
||||
removed = append(removed, ns)
|
||||
}
|
||||
}
|
||||
|
||||
if len(removed) == 0 {
|
||||
return
|
||||
}
|
||||
|
||||
slices.Sort(removed)
|
||||
|
||||
msg := fmt.Sprintf(
|
||||
"%s\nRemoved: %s",
|
||||
w.nameLine(hostname),
|
||||
strings.Join(removed, ", "),
|
||||
)
|
||||
|
||||
w.notify.SendNotification(
|
||||
ctx,
|
||||
"NS Change: "+hostname,
|
||||
msg,
|
||||
"warning",
|
||||
)
|
||||
}
|
||||
|
||||
// detectNSFailures notifies when a nameserver that answered on the
|
||||
@@ -1052,8 +943,7 @@ func (w *Watcher) checkAllPorts(ctx context.Context) {
|
||||
|
||||
// Phase 3: Remove port state entries that no longer have
|
||||
// any hostname referencing them, and certificate entries for
|
||||
// an address whose port 443 is closed or that their name no
|
||||
// longer has.
|
||||
// an address their name no longer has.
|
||||
w.cleanupStalePorts(associations)
|
||||
w.cleanupStaleCertificates()
|
||||
}
|
||||
@@ -1074,7 +964,7 @@ func (w *Watcher) buildPortAssociations() map[string][]string {
|
||||
ips := w.collectIPs(name)
|
||||
for _, ip := range ips {
|
||||
for _, port := range monitoredPorts {
|
||||
key := net.JoinHostPort(ip, strconv.Itoa(port))
|
||||
key := fmt.Sprintf("%s:%d", ip, port)
|
||||
if assoc[key] == nil {
|
||||
assoc[key] = make(map[string]bool)
|
||||
}
|
||||
@@ -1099,15 +989,18 @@ func (w *Watcher) buildPortAssociations() map[string][]string {
|
||||
return result
|
||||
}
|
||||
|
||||
// parsePortKey splits an "ip:port" key, written by net.JoinHostPort,
|
||||
// into its components.
|
||||
// parsePortKey splits an "ip:port" key into its components.
|
||||
func parsePortKey(key string) (string, int) {
|
||||
ip, port, err := net.SplitHostPort(key)
|
||||
if err != nil {
|
||||
lastColon := strings.LastIndex(key, ":")
|
||||
if lastColon < 0 {
|
||||
return key, 0
|
||||
}
|
||||
|
||||
p, err := strconv.Atoi(port)
|
||||
ip := key[:lastColon]
|
||||
|
||||
var p int
|
||||
|
||||
_, err := fmt.Sscanf(key[lastColon+1:], "%d", &p)
|
||||
if err != nil {
|
||||
return ip, 0
|
||||
}
|
||||
@@ -1137,21 +1030,13 @@ func (w *Watcher) cleanupStalePorts(
|
||||
}
|
||||
|
||||
// cleanupStaleCertificates removes the certificate entries for an
|
||||
// address whose port 443 was found closed, and for an address their
|
||||
// name no longer resolves to. An entry saved for a name none of whose
|
||||
// nameservers answered is kept unless its port is closed: that name's
|
||||
// addresses are not known, not gone.
|
||||
// address their name no longer resolves to. An entry saved for a name
|
||||
// none of whose nameservers answered is kept: that name's addresses are
|
||||
// not known, not gone.
|
||||
func (w *Watcher) cleanupStaleCertificates() {
|
||||
for _, key := range w.state.GetAllCertificateKeys() {
|
||||
ip, hostname := parseCertKey(key)
|
||||
|
||||
ps, ok := w.state.GetPortState(net.JoinHostPort(ip, strconv.Itoa(tlsPort)))
|
||||
if ok && !ps.Open {
|
||||
w.state.DeleteCertificateState(key)
|
||||
|
||||
continue
|
||||
}
|
||||
|
||||
if slices.Contains(w.collectIPs(hostname), ip) ||
|
||||
w.noNameserverAnswered(hostname) {
|
||||
continue
|
||||
@@ -1260,7 +1145,7 @@ func (w *Watcher) checkSinglePort(
|
||||
return
|
||||
}
|
||||
|
||||
key := net.JoinHostPort(ip, strconv.Itoa(port))
|
||||
key := fmt.Sprintf("%s:%d", ip, port)
|
||||
now := time.Now().UTC()
|
||||
prev, hasPrev := w.state.GetPortState(key)
|
||||
|
||||
@@ -1322,7 +1207,7 @@ func (w *Watcher) checkTLSForHostname(
|
||||
ips := w.collectIPs(hostname)
|
||||
|
||||
for _, ip := range ips {
|
||||
portKey := net.JoinHostPort(ip, strconv.Itoa(tlsPort))
|
||||
portKey := fmt.Sprintf("%s:%d", ip, tlsPort)
|
||||
|
||||
ps, ok := w.state.GetPortState(portKey)
|
||||
if !ok || !ps.Open {
|
||||
@@ -1346,7 +1231,7 @@ func (w *Watcher) checkTLSCert(
|
||||
return
|
||||
}
|
||||
|
||||
certKey := net.JoinHostPort(ip, strconv.Itoa(tlsPort)) + ":" + hostname
|
||||
certKey := fmt.Sprintf("%s:%d:%s", ip, tlsPort, hostname)
|
||||
now := time.Now().UTC()
|
||||
prev, hasPrev := w.state.GetCertificateState(certKey)
|
||||
|
||||
|
||||
@@ -4,7 +4,6 @@ import (
|
||||
"context"
|
||||
"fmt"
|
||||
"log/slog"
|
||||
"net"
|
||||
"os"
|
||||
"slices"
|
||||
"strings"
|
||||
@@ -140,22 +139,6 @@ func (m *mockNotifier) getNotifications() []notification {
|
||||
return result
|
||||
}
|
||||
|
||||
// cancelOnNotify is a mockNotifier that calls cancel at each
|
||||
// notification, as if shutdown cut the check short there.
|
||||
type cancelOnNotify struct {
|
||||
*mockNotifier
|
||||
|
||||
cancel context.CancelFunc
|
||||
}
|
||||
|
||||
func (n cancelOnNotify) SendNotification(
|
||||
ctx context.Context,
|
||||
title, message, priority string,
|
||||
) {
|
||||
n.mockNotifier.SendNotification(ctx, title, message, priority)
|
||||
n.cancel()
|
||||
}
|
||||
|
||||
// --- Helpers to build a Watcher and run its checks against live DNS ---
|
||||
|
||||
type testDeps struct {
|
||||
@@ -478,54 +461,6 @@ func TestDomainPortAndTLSChecks(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestFirstCheckAfterLoadingFileWithoutSections loads a state file
|
||||
// holding {}, and one that leaves out the certificates section, and runs
|
||||
// the first check. It saves domain, hostname, port and certificate
|
||||
// entries; a section loaded as nil made it panic.
|
||||
func TestFirstCheckAfterLoadingFileWithoutSections(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
file string
|
||||
}{
|
||||
{"no sections", `{}`},
|
||||
{"no certificates", `{"domains": {}, "hostnames": {}, "ports": {}}`},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
cfg := defaultTestConfig(t)
|
||||
cfg.Domains = []string{testSmallDomain}
|
||||
|
||||
_, deps := runChecks(t, cfg, func(deps *testDeps) {
|
||||
err := os.WriteFile(cfg.StatePath(), []byte(tt.file), 0o600)
|
||||
if err != nil {
|
||||
t.Fatalf("writing the state file: %v", err)
|
||||
}
|
||||
|
||||
err = deps.state.Load()
|
||||
if err != nil {
|
||||
t.Fatalf("loading the state file: %v", err)
|
||||
}
|
||||
})
|
||||
|
||||
snap := deps.state.GetSnapshot()
|
||||
if len(snap.Domains) == 0 || len(snap.Hostnames) == 0 ||
|
||||
len(snap.Ports) == 0 || len(snap.Certificates) == 0 {
|
||||
t.Errorf(
|
||||
"saved %d domain, %d hostname, %d port and %d "+
|
||||
"certificate entries, want at least one of each",
|
||||
len(snap.Domains), len(snap.Hostnames),
|
||||
len(snap.Ports), len(snap.Certificates),
|
||||
)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestNSChangeDetection(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
@@ -623,11 +558,6 @@ func TestDomainThatDoesNotExist(t *testing.T) {
|
||||
// nameservers and without nxdomain, and its records, asked at the
|
||||
// codeberg.page servers, are saved. Those are testSmallDomain's two
|
||||
// nameservers; github.io, the zone of the README's example, has eight.
|
||||
// The previous check saved a delegation to oldNS1, now withdrawn, and
|
||||
// records asked at oldNS1. A first check is cut short at its first
|
||||
// notification, as shutdown would, and a second runs in full: across
|
||||
// them the NS Change of its delegation removes oldNS1, and no other NS
|
||||
// Change lists it again.
|
||||
func TestDomainWithNoDelegationOfItsOwn(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
@@ -639,30 +569,9 @@ func TestDomainWithNoDelegationOfItsOwn(t *testing.T) {
|
||||
var deps *testDeps
|
||||
|
||||
livednstest.Retry(t, "watcher checks", func(ctx context.Context) error {
|
||||
deps = newTestDeps(t, cfg)
|
||||
var w *watcher.Watcher
|
||||
|
||||
firstCtx, cancel := context.WithCancel(ctx)
|
||||
defer cancel()
|
||||
|
||||
w := watcher.NewForTest(
|
||||
cfg,
|
||||
deps.state,
|
||||
resolver.NewFromLogger(slog.Default()),
|
||||
deps.portChecker,
|
||||
deps.tlsChecker,
|
||||
cancelOnNotify{mockNotifier: deps.notifier, cancel: cancel},
|
||||
)
|
||||
|
||||
deps.state.SetDomainState(domain, &state.DomainState{
|
||||
Nameservers: []string{oldNS1},
|
||||
})
|
||||
deps.state.SetHostnameState(domain, saved(
|
||||
map[string]*state.NameserverRecordState{
|
||||
oldNS1: answered(map[string][]string{"A": {oldIP}}),
|
||||
},
|
||||
))
|
||||
|
||||
w.RunOnce(firstCtx)
|
||||
w, deps = newTestWatcher(t, cfg)
|
||||
|
||||
err := checkOnce(ctx, w, deps)
|
||||
|
||||
@@ -684,22 +593,6 @@ func TestDomainWithNoDelegationOfItsOwn(t *testing.T) {
|
||||
if _, ok := deps.state.GetHostnameState(domain); !ok {
|
||||
t.Errorf("no records saved for %s", domain)
|
||||
}
|
||||
|
||||
title := "NS Change: " + domain
|
||||
want := "Domain: " + domain + "\nAdded: \nRemoved: " + oldNS1
|
||||
|
||||
var changes []notification
|
||||
|
||||
for _, n := range deps.notifier.getNotifications() {
|
||||
if n.Title == title {
|
||||
changes = append(changes, n)
|
||||
}
|
||||
}
|
||||
|
||||
if len(changes) != 1 || changes[0].Message != want {
|
||||
t.Errorf("sent %v, want one %q with message:\n%s",
|
||||
changes, title, want)
|
||||
}
|
||||
}
|
||||
|
||||
func TestNSAddressChangeDetection(t *testing.T) {
|
||||
@@ -825,8 +718,7 @@ func TestPortStateChange(t *testing.T) {
|
||||
|
||||
hs, _ := deps.state.GetHostnameState(testHost)
|
||||
assertNotified(
|
||||
t, deps, "Port Change: "+net.JoinHostPort(addresses(hs)[0], "443"),
|
||||
"warning",
|
||||
t, deps, "Port Change: "+addresses(hs)[0]+":443", "warning",
|
||||
)
|
||||
}
|
||||
|
||||
@@ -1033,12 +925,11 @@ func TestDNSRunsBeforePortAndTLSChecks(t *testing.T) {
|
||||
|
||||
// Port and TLS checks must use the addresses this check found.
|
||||
for _, ip := range addresses(snap.Hostnames[testHost]) {
|
||||
portKey := net.JoinHostPort(ip, "80")
|
||||
if _, ok := snap.Ports[portKey]; !ok {
|
||||
t.Error("port check used stale DNS: missing " + portKey)
|
||||
if _, ok := snap.Ports[ip+":80"]; !ok {
|
||||
t.Error("port check used stale DNS: missing " + ip + ":80")
|
||||
}
|
||||
|
||||
certKey := net.JoinHostPort(ip, "443") + ":" + testHost
|
||||
certKey := ip + ":443:" + testHost
|
||||
if _, ok := snap.Certificates[certKey]; !ok {
|
||||
t.Error("TLS check used stale DNS: missing " + certKey)
|
||||
}
|
||||
@@ -1158,7 +1049,7 @@ func TestSendTestNotification_Disabled(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
func TestNSChangeAndRecovery(t *testing.T) {
|
||||
func TestNSFailureAndRecovery(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
cfg := defaultTestConfig(t)
|
||||
@@ -1168,7 +1059,7 @@ func TestNSChangeAndRecovery(t *testing.T) {
|
||||
|
||||
// The saved state has every nameserver live DNS lists as one that
|
||||
// did not answer, and, as answering, one that live DNS does not
|
||||
// list, which the check then finds removed.
|
||||
// list, which then disappears.
|
||||
_, deps := runChecks(t, cfg, func(deps *testDeps) {
|
||||
byNameserver := map[string]*state.NameserverRecordState{
|
||||
oldNS1: answered(map[string][]string{"A": {oldIP}}),
|
||||
@@ -1180,7 +1071,7 @@ func TestNSChangeAndRecovery(t *testing.T) {
|
||||
deps.state.SetHostnameState(testHost, saved(byNameserver))
|
||||
})
|
||||
|
||||
assertNotified(t, deps, "NS Change: "+testHost, "warning")
|
||||
assertNotified(t, deps, "NS Failure: "+testHost, "error")
|
||||
assertNotified(t, deps, "NS Recovery: "+testHost, "success")
|
||||
|
||||
// A nameserver that did not answer has no records to compare, so
|
||||
|
||||
+8
-8
@@ -3,12 +3,12 @@
|
||||
# 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 not installed here: script/fmt and script/fmt-check run
|
||||
# it with `go run` at a pinned commit.
|
||||
# goimports is not installed here: script/fmt and script/fmt-check-go
|
||||
# run it with `go run` at a pinned commit.
|
||||
# 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. Nor is prettier: script/fmt and script/fmt-check run
|
||||
# it in a stage of the Dockerfile.
|
||||
# working docker. Nor is prettier: script/fmt and
|
||||
# script/fmt-check-markdown run it in a container from Dockerfile.fmt.
|
||||
set -eu
|
||||
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
||||
@@ -67,12 +67,12 @@ main() {
|
||||
if missing make; then pkg_install gnumake make make make; fi
|
||||
if missing go; then pkg_install go golang go go; fi
|
||||
|
||||
# Testing, linting and the markdown formatter run via docker only.
|
||||
# Warn, don't fail: make build works without it.
|
||||
# Linting and the markdown formatter run via docker only. Warn,
|
||||
# don't fail: building and testing work without it.
|
||||
if missing docker; then
|
||||
echo "bootstrap: WARNING: docker not found; install it to" \
|
||||
"run make test, make lint, make fmt, make fmt-check," \
|
||||
"make check and make docker." >&2
|
||||
"run make lint, make fmt, make fmt-check, make check" \
|
||||
"and make docker." >&2
|
||||
fi
|
||||
|
||||
go mod download
|
||||
|
||||
+12
-17
@@ -1,10 +1,14 @@
|
||||
#!/bin/sh
|
||||
# script/cibuild: run the CI build. It bootstraps first: a CI runner
|
||||
# checks out and runs this and nothing else, and script/fmt-check runs
|
||||
# the formatter on the host, which a pristine checkout cannot do.
|
||||
# --no-cache for the same reason as script/docker: the gate phases the
|
||||
# final stage depends on are RUN steps, and a cached one is a check that
|
||||
# did not run.
|
||||
# script/cibuild: run the CI build. The Dockerfile's lint stage runs
|
||||
# the Go half of make fmt-check and golangci-lint; its builder stage
|
||||
# runs make test and make build. The markdown half of make fmt-check
|
||||
# runs after that build, as its own build of Dockerfile.fmt, because
|
||||
# there is no docker inside a docker build.
|
||||
#
|
||||
# --no-cache-filter=lint,builder runs both stages on every invocation;
|
||||
# otherwise an unchanged tree is served from the layer cache and passes
|
||||
# without linting or querying live DNS. script/fmt-check-markdown busts
|
||||
# its own cache the same way.
|
||||
set -eu
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
||||
@@ -12,17 +16,8 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
|
||||
|
||||
main() {
|
||||
cd "$ROOT"
|
||||
"$SCRIPT_DIR/bootstrap"
|
||||
"$SCRIPT_DIR/check"
|
||||
# Own line: a failing command substitution inside an argument does
|
||||
# not trip `set -e`, so the inline form degrades silently to an
|
||||
# empty constant. The VERSION build argument takes precedence over
|
||||
# the version a build stage derives from the .git in the context.
|
||||
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
|
||||
[ -n "$version" ] || version="unknown"
|
||||
docker build --no-cache \
|
||||
--build-arg VERSION="$version" \
|
||||
-t "$("$SCRIPT_DIR/projectname")" .
|
||||
docker build --no-cache-filter=lint,builder .
|
||||
"$SCRIPT_DIR/fmt-check-markdown"
|
||||
}
|
||||
|
||||
main "$@"
|
||||
|
||||
+8
-6
@@ -1,8 +1,10 @@
|
||||
#!/bin/sh
|
||||
# script/docker: build the Docker image tagged with the project name.
|
||||
# Identical in all repos; the tag comes from script/projectname.
|
||||
# --no-cache because the gate phases the final stage depends on are RUN
|
||||
# steps, and a cached one is a check that did not run.
|
||||
# The tag comes from script/projectname.
|
||||
#
|
||||
# --no-cache-filter=lint,builder runs the lint stage and the builder
|
||||
# stage (make test) on every invocation; otherwise an unchanged tree is
|
||||
# served from the layer cache without linting or querying live DNS.
|
||||
set -eu
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
||||
@@ -12,11 +14,11 @@ main() {
|
||||
cd "$ROOT"
|
||||
# Own line: a failing command substitution inside an argument does
|
||||
# not trip `set -e`, so the inline form degrades silently to an
|
||||
# empty constant. The VERSION build argument takes precedence over
|
||||
# the version a build stage derives from the .git in the context.
|
||||
# empty constant. The VERSION build arg takes precedence over what
|
||||
# the build would derive from the .git in its context.
|
||||
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
|
||||
[ -n "$version" ] || version="unknown"
|
||||
docker build --no-cache \
|
||||
docker build --no-cache-filter=lint,builder \
|
||||
--build-arg VERSION="$version" \
|
||||
-t "$("$SCRIPT_DIR/projectname")" .
|
||||
}
|
||||
|
||||
+14
-7
@@ -1,6 +1,6 @@
|
||||
#!/bin/sh
|
||||
# script/fmt: format all files (writes). Go with gofmt and goimports on
|
||||
# the host, markdown with prettier in the Dockerfile's fmt stage.
|
||||
# the host, markdown with the prettier pinned by Dockerfile.fmt.
|
||||
#
|
||||
# goimports runs with `go run` at a pinned commit, never from PATH, so
|
||||
# every machine formats with the same version and nothing installs it.
|
||||
@@ -8,15 +8,21 @@
|
||||
# The markdown pass is a `docker build --output type=local` rather than a
|
||||
# `docker run -v`, so it needs no bind mount and behaves the same against
|
||||
# a remote daemon; the formatted documents come back out of the build and
|
||||
# are copied over the tree here. --output writes files and makes no
|
||||
# image, so there is nothing to tag.
|
||||
# are copied over the tree here.
|
||||
#
|
||||
# Unlike script/fmt-check-markdown this does not bust the cache: it is
|
||||
# not a gate, and any edit to a document changes the COPY layer above the
|
||||
# prettier step, so a cached result is a result over this exact tree.
|
||||
set -eu
|
||||
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
||||
|
||||
# goimports v0.42.0, 2026-08-07. Must match script/fmt-check.
|
||||
# goimports v0.42.0, 2026-08-07. Must match script/fmt-check-go.
|
||||
GOIMPORTS_REF="golang.org/x/tools/cmd/goimports@009367f5c17a8d4c45a961a3a509277190a9a6f0"
|
||||
|
||||
# Must match the export stage name in Dockerfile.fmt.
|
||||
stage=fmt-out
|
||||
|
||||
die() {
|
||||
echo "script/fmt: $*" >&2
|
||||
exit 1
|
||||
@@ -30,9 +36,10 @@ main() {
|
||||
tmp="$(mktemp -d "${TMPDIR:-/tmp}/dnswatcher-fmt.XXXXXX")"
|
||||
trap 'rm -rf "$tmp"' EXIT INT TERM
|
||||
|
||||
docker build --no-cache \
|
||||
--target fmt-out \
|
||||
--output "type=local,dest=$tmp/out" .
|
||||
docker build \
|
||||
--target "$stage" \
|
||||
--output "type=local,dest=$tmp/out" \
|
||||
-f Dockerfile.fmt .
|
||||
|
||||
# An empty export means prettier was handed nothing, which must not
|
||||
# read as "already formatted".
|
||||
|
||||
+4
-27
@@ -1,37 +1,14 @@
|
||||
#!/bin/sh
|
||||
# script/fmt-check: check formatting (read-only). Same tools and scope
|
||||
# as script/fmt, but fails instead of writing and names what it would
|
||||
# change: the Go on the host, the markdown with prettier in the
|
||||
# Dockerfile's fmt-check stage.
|
||||
#
|
||||
# --no-cache because a cached check layer is a check that did not run.
|
||||
# The tag makes each build replace the previous image instead of leaving
|
||||
# a dangling one behind.
|
||||
# as script/fmt, but fails instead of writing: the Go on the host, the
|
||||
# markdown with prettier in a container.
|
||||
set -eu
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
||||
ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
|
||||
|
||||
# goimports v0.42.0, 2026-08-07. Must match script/fmt.
|
||||
GOIMPORTS_REF="golang.org/x/tools/cmd/goimports@009367f5c17a8d4c45a961a3a509277190a9a6f0"
|
||||
|
||||
main() {
|
||||
cd "$ROOT"
|
||||
files="$(gofmt -s -l .)"
|
||||
if [ -n "$files" ]; then
|
||||
echo "gofmt: files not formatted:" >&2
|
||||
echo "$files" >&2
|
||||
exit 1
|
||||
fi
|
||||
files="$(go run "$GOIMPORTS_REF" -l .)"
|
||||
if [ -n "$files" ]; then
|
||||
echo "goimports: files not formatted:" >&2
|
||||
echo "$files" >&2
|
||||
exit 1
|
||||
fi
|
||||
docker build --no-cache \
|
||||
--target fmt-check \
|
||||
-t "$("$SCRIPT_DIR/projectname")-fmt-check" .
|
||||
"$SCRIPT_DIR/fmt-check-go"
|
||||
"$SCRIPT_DIR/fmt-check-markdown"
|
||||
}
|
||||
|
||||
main "$@"
|
||||
|
||||
Executable
+31
@@ -0,0 +1,31 @@
|
||||
#!/bin/sh
|
||||
# script/fmt-check-go: fail unless every Go source is formatted the way
|
||||
# script/fmt would leave it, and name the files that are not. Read-only.
|
||||
#
|
||||
# Its own script because the Dockerfile's lint stage runs this half
|
||||
# alone: there is no docker inside a docker build to run the markdown
|
||||
# half in.
|
||||
set -eu
|
||||
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
||||
|
||||
# goimports v0.42.0, 2026-08-07. Must match script/fmt.
|
||||
GOIMPORTS_REF="golang.org/x/tools/cmd/goimports@009367f5c17a8d4c45a961a3a509277190a9a6f0"
|
||||
|
||||
main() {
|
||||
cd "$ROOT"
|
||||
files="$(gofmt -s -l .)"
|
||||
if [ -n "$files" ]; then
|
||||
echo "gofmt: files not formatted:" >&2
|
||||
echo "$files" >&2
|
||||
exit 1
|
||||
fi
|
||||
files="$(go run "$GOIMPORTS_REF" -l .)"
|
||||
if [ -n "$files" ]; then
|
||||
echo "goimports: files not formatted:" >&2
|
||||
echo "$files" >&2
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
main "$@"
|
||||
Executable
+29
@@ -0,0 +1,29 @@
|
||||
#!/bin/sh
|
||||
# script/fmt-check-markdown: fail unless every .md is formatted the way
|
||||
# script/fmt would leave it. Read-only.
|
||||
#
|
||||
# prettier is never installed on the host: it runs in a container built
|
||||
# from Dockerfile.fmt, pinned by package.json and yarn.lock.
|
||||
# --no-cache-filter is here for the reason script/lint gives: a cached
|
||||
# build checks nothing.
|
||||
#
|
||||
# Its own script because script/cibuild runs this half alone, after the
|
||||
# Dockerfile's lint stage has checked the Go.
|
||||
set -eu
|
||||
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
||||
|
||||
# Must match the markdown check stage name in Dockerfile.fmt.
|
||||
stage=fmt-check
|
||||
|
||||
main() {
|
||||
cd "$ROOT"
|
||||
docker build \
|
||||
--progress=plain \
|
||||
--no-cache-filter="$stage" \
|
||||
--target "$stage" \
|
||||
-f Dockerfile.fmt \
|
||||
.
|
||||
}
|
||||
|
||||
main "$@"
|
||||
+17
-12
@@ -1,23 +1,28 @@
|
||||
#!/bin/sh
|
||||
# script/lint: run the linter. Linting is a phase of the Dockerfile and
|
||||
# this builds that phase alone; the linter is never installed or run on
|
||||
# a developer host, where a shared result cache and a host-global lock
|
||||
# make its answer untrustworthy.
|
||||
# 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.
|
||||
#
|
||||
# The phase is not the last stage in the file, so it is built only when
|
||||
# --target names it. --no-cache because a cached lint layer is a lint
|
||||
# that did not run. The tag makes each build replace the previous image
|
||||
# instead of leaving a dangling one behind.
|
||||
# --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
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
||||
ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
||||
|
||||
main() {
|
||||
cd "$ROOT"
|
||||
docker build --no-cache \
|
||||
docker build \
|
||||
--progress=plain \
|
||||
--no-cache-filter=lint \
|
||||
--target lint \
|
||||
-t "$("$SCRIPT_DIR/projectname")-lint" .
|
||||
-f Dockerfile.lint \
|
||||
.
|
||||
}
|
||||
|
||||
main "$@"
|
||||
|
||||
+26
-10
@@ -1,19 +1,35 @@
|
||||
#!/bin/sh
|
||||
# script/test: run the test suite. Testing is a phase of the Dockerfile
|
||||
# and this builds that phase alone, on the same terms as script/lint:
|
||||
# --target because a phase that is not the last stage is built only when
|
||||
# named, --no-cache because a cached test layer is a test that did not
|
||||
# run, and a tag so each build replaces the previous image.
|
||||
# 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
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
||||
ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
||||
|
||||
main() {
|
||||
cd "$ROOT"
|
||||
docker build --no-cache \
|
||||
--target test \
|
||||
-t "$("$SCRIPT_DIR/projectname")-test" .
|
||||
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 "$@"
|
||||
|
||||
Reference in New Issue
Block a user