fancy-dns/STATUS.md

fancy-dns — status and continuation plan

AGENTS.md holds the decisions, invariants and working rules. This file holds state and the plan. History is in git log; the old per-round fix lists were removed because each fix is explained in its commit and pinned by a test.

Last updated after the round that added client-group validation. The cluster-object architecture, the separate console and the web UI are deployed.

What exists

Two binaries, one repository:

Binary	Does	Talks to
fancy-dns	The resolver: UDP/TCP/DoT/DoH, cache, blocklists, ACL groups, local zones, access log, metrics, a read-only admin API. Reads DNSZone, ClientGroup, BlockList, AddressOverride and DomainRule objects with a watch (-kube) and keeps a snapshot so it can start without the cluster.	Upstreams; optionally the Kubernetes API and Valkey.
fancy-dns-console	The web UI and the edit API. The only writer of the cluster objects; authenticates (API key, basic, OIDC with PKCE); proxies every other /api route to the resolver. Not on the DNS path.	The resolver's admin API and the Kubernetes API.

Operational docs: README.md (reference), deploy/MIGRATION.md (ConfigMap deployment to cluster objects), deploy/OUTSIDE-CLUSTER.md (a backup resolver and console on a node outside the cluster), deploy/compose/README.md (file-configured Docker backup).

Verified

make check (gofmt, vet, compile, go test -race ./...) passes on every package. The web console typechecks and oxlint reports no errors; the remaining warnings are set-state-in-effect in AppShell, Login, Domains and Zones and an unused parameter in ui/Select.tsx. The console has no test runner, so a UI change is verified by tsc and by looking at it.

This round

• Client-group validation. POST /api/clients/validate (console only) checks a group without saving it. It applies the same checks as a save, now reported per field and all at once (kubesource.CheckGroupAll, kubesource.FieldError), then runs acl.Analyze, which explains the group in plain English and warns about legal-but-unintended settings: a group buried under a wider one (and the reverse: a save that buries a later group), CIDRs with host bits or a huge range, an allowlist, block_only, a rate limit of 0 under a default limit, unknown upstreams, domain patterns that never match, tags with a dot. test_ip says which group an address would land in. Tests: internal/acl/explain_test.go, internal/console/validate_test.go.
• Clients page. Rebuilt around that endpoint: templates for the common cases, sections ("Which devices?", "What happens to their queries?", advanced), live validation with errors next to the field, a "What this group will do" panel, and a try-an-address box. The "Match any client" switch is gone: the console cannot store a catch-all group (match.any alone is refused for cluster objects), so it could only produce an error.
• The old help text was wrong, in ways that mattered. It said allow_domains "skip the blocklists"; in fact a non-empty list is allowlist-only mode (everything else is blocked). It said block_only means "no recursion"; in fact it is identical to allow. It suggested .lan as a reverse-DNS suffix, which never matched anything (see the next item). It said tags match "ECS/DNS tag metadata"; they are labels of the client's reverse name. README's acl table is corrected to match.
• matchPTR rejected a suffix with a leading dot. .lan. was compared at a label boundary that the leading dot had already consumed, so it matched nothing. A leading dot now means "anything under". Pinned in TestMatchPTRLabelBoundary. This changes which clients a group with such a suffix matches (from nobody to the intended ones).
• Docs. This file, deploy/OUTSIDE-CLUSTER.md, and removal of the dead qlog and managed_zones references from README, the Compose config, and a comment in internal/api/zones.go.

Decisions waiting for you

1. block_only. Decided: removed from the UI. It did exactly what allow does. The API and CRD still accept it so stored objects keep working; the console shows it only on a group that already has it, and the validator warns.
2. Catch-all group. Decided: no change. "Everyone else" is the default policy in the resolver's YAML (acl.default_policy). The console does not set it and cluster objects are never catch-alls.
3. The pinned behaviours below, one at a time.

Pinned, not fixed

Each has a test that fails when it changes and says what to do then.

• Unknown config keys are silently ignored (TestLoadIgnoresUnknownKeys).
• Auth config is frozen at startup. api.base_path, trusted_proxies and the authenticator are read once; a reload re-reads CORS only (TestPinnedWrittenAuthConfigIsNotAppliedUntilRestart, TestCORSOriginsAreReadAtHandlerBuild).
• DoH clients behind an Ingress all look like the proxy, because DoH deliberately ignores X-Forwarded-For (TestDoHClientIdentityIsTheProxyNotTheForwardedForHeader).
• api.cors_origins: ["*"] echoes the request's Origin with credentials (TestCORSWildcardEchoesTheOrigin, TestCORSPreflight).
• A partial bind failure is invisible to the admin API (TestStartReportsAPartialFailureButServes).
• A question-less message is answered on UDP and drops the connection on TCP/DoT (TestUDPQuestionlessMessageReachesTheEngine).
• doh.sent is never bumped (TestCountersFollowTheEngineOutcome).

The README's "Known inconsistencies" section lists more dead config keys and stale line references; its line numbers have drifted and have not been re-audited.

Plan, in order

1. Resolve the decisions above.
2. Stop hand-writing the console's types. web/src/lib/types.ts is hand-written and apiFetch ends in JSON.parse(text) as T; the Go contract tests make the server authoritative today, but only because someone compared them once. Generate the types from the Go structs (or emit an OpenAPI document). internal/app/dump_shapes_test.go (DUMP_SHAPES=1) is the stopgap.
3. Test the console package beyond validation. internal/console has one test file (the validator). The cluster-consistent merge in handleClients and putACL is the part that has caused lost updates before.
4. Decide whether the shutdown grace belongs in config. main hard-codes 15s for Stop, of which 250ms is the UDP drain, and the Kubernetes terminationGracePeriodSeconds is a second copy of the same number.
5. Look at the Zones and Clients pages in a browser. Neither the Zones page nor this round's Clients page has been seen rendered by the person who wrote it; both are typechecked and built only.
6. Re-audit README "Known inconsistencies" against the code.

Commands

• make check-go: the inner loop (~1s): gofmt, vet, compile (no npm).
• make check: check-go plus go test -race ./...; what CI runs.
• make smoke: boots the real binary with the console embedded and checks the API, metrics and auth.
• make web-check: console typecheck and production build.
• make build: both binaries with the console embedded (needs npm).
• make bench: cache and blocklist benchmarks.

Test-hygiene traps

These are in AGENTS.md (TXT strings over 255 bytes, EDNS0_NSID is hex, dns.NewRR needs a TTL, closing a stop channel after wg.Wait(), counting goroutines by stack, tsc -b replaying cached diagnostics, vite build deleting internal/web/dist/.gitkeep). One more from this round: a Go test that needs a Kubernetes client should use dynamic/fake with NewSimpleDynamicClientWithCustomListKinds and list every GVR in kubesource.allGVRs, or a List panics.