developer
504512f247
The console could not see local zones at all. `blocklist.local_zones` compiled a store that nothing read back: there was no API for a zone, its records, its delegations or the file a record came from, and no way to change one without editing YAML and reloading. The Domains page is the blocklist's inline rules, not local data, so nothing in the console covered the half of the server that answers authoritatively from disk. There is now a Zones page and the endpoints behind it: `GET /api/zones`, `POST`/`PUT`/`DELETE /api/zones/records`, `POST`/`DELETE /api/zones/delegations` and `DELETE /api/zones?zone=`. **The console owns one directory and nothing else.** `blocklist.managed_zones` holds one `<apex>.zone` per zone, with that zone's SOA, apex NS set and the records added there, and it is compiled by the same `localzone.Load` as the operator's files — so a record added from the console is served on the next query, with no reload and no restart. Files in `blocklist.local_zones` are listed and shown read-only and are never rewritten; the key defaults to empty, so a deployment that never sets it gets a zone browser and no zone writes. Which file a record came from is now part of the store (`zone.files`, keyed by the index the store already uses), so the snapshot can say "console" or "your file" per record; the query path does not read it. **The writer proves its own output.** A record is validated by the project's own master-file parser, so `www` means `www.<zone>` and a bare CNAME target is completed exactly as it would be in a zone file; the file is rendered, and the rendering is re-parsed and compared with the records it meant to write before the file is renamed into place. A writer bug that dropped a record would otherwise present as a zone that silently stopped answering. A zone that cannot answer is refused rather than created: no SOA means no NXDOMAIN or NODATA authority, and no apex NS means nothing is delegated and no server is named. The SOA's primary follows the apex NS set — a zone whose SOA names a server outside its own NS set hands out a referral no resolver can follow — and the serial moves on every write. **A delegation takes the names under it, so a record below a cut is refused.** The store answers those names as delegated without reading the zone file, which would make the record data that looks alive and never answers. `DELETE /api/zones?zone=` exists for the same reason from the other side: a zone the console created is a real zone, so it says NXDOMAIN for what it does not hold, and deleting a record is not what gives a name back to upstream. It is refused for a zone that also has records outside the managed directory, because removing that file would remove none of the zone. **Two bugs the work turned up.** `engine.applyConfig` published local-record metrics only when `blocklist.local_zones` was non-empty, so a zone the console created was served but never counted; the gate is now the store's own record count. And the record-value renderer fell back to `RR.String()` for every type it did not know, which is the whole line rather than the RDATA — it wrote a name and a TTL into the value column for DHCID, LOC, SSHFP and SVCB, and would have fed that back as a record value on the next edit. Every write recompiles the store and flushes the cache. Which names changed is not knowable from the API, and a cached upstream answer for a name the zone now answers is simply wrong, so the flush is blunt on purpose. The wire shapes are type aliases in `internal/api` rather than copies, so there is one set of json tags, and `TestZoneEndpointKeySets` pins the key set at every level with a record and a delegation actually present — an empty list only proves the envelope. `TestZoneWritesNeedAManagedDirectory` pins the read-only default, and `TestZoneConsoleRoundTrip` walks the whole thing: a record added through the API is answered authoritatively on the next query, a cut stops the parent answering below it, and deleting the zone hands the name back. Verified against a running instance built from this tree: records and wildcards answer with `aa`, relative names are qualified, a record below a cut is refused with a message that says why, and the file on disk is a zone file an operator can read. The console page is typechecked and built; the browser was not available in this round, so it has not been looked at.
The console
Vite + React + TypeScript + Tailwind, built into internal/web/dist and served
by the Go binary from an //go:embed. There is no separate deployment: the
binary is the console.
Day-to-day
make web-check # npx tsc -b --noEmit && npm run build (what CI runs)
make web-dev # Vite dev server, proxying /api to 127.0.0.1:8080
make web # production build into internal/web/dist
For make web-dev to show anything, a fancy-dns has to be listening on
127.0.0.1:8080 with the API key the console sends. deploy/config.example.yaml
binds there, but on port 53; rewrite the ports (or use make smoke, which does
it for you) before starting it.
Two traps that have cost time, both from AGENTS.md:
tsc -breplays cached diagnostics fromnode_modules/.tmp/*.tsbuildinfo. After a large editrm -f node_modules/.tmp/*.tsbuildinfo, or you will read errors that no longer exist and miss ones that do.npm run buildemptiesinternal/web/distand deletes its.gitkeep. Restore it (git checkout -- internal/web/dist/.gitkeep). The Go build still works while the directory is empty, so a console rebuild in the middle of someone else'sgo buildis not fatal — but the commit is.
The API contract
src/lib/types.ts is a hand-written mirror of the Go json tags in
internal/api and internal/app/hooks.go. apiFetch ends in
JSON.parse(text) as T, so the compiler checks the console against its own
declarations and nothing else: a field that loses its json tag, or a response
a struct never had, shows up as an empty table in a browser and nowhere else.
That is not hypothetical — a round of this found the Sources table, the ACL
group cards and both Save buttons broken exactly that way.
So, when you touch either side:
- Go: add or keep the
jsontag.internal/apphas contract tests that assert the exact key set of every admin endpoint; they are the spec, and a rename fails them. - Console: change the interface in the same commit. If the server is wrong,
fix the server — do not "adapt" in the client, and do not paper a mismatch
over with
as any, an optional field or a?? 0default. Those casts are precisely what hides drift. - Never rename a field on one side only. The dashboard, the ServiceMonitor queries and the Grafana panels are consumers of the same JSON.
The durable fix is to generate types.ts from the Go structs, or to publish an
OpenAPI document from the server and generate from that. It is in the plan at
the end of STATUS.md.
What is checked
npx tsc -b --noEmit (strict, with noUnusedLocals) and oxlint (two rules:
react/rules-of-hooks and react/only-export-components). There is no test
runner and no component test — the console's correctness rests entirely on its
types, which are only as good as the mirror above. Adding vitest and a handful
of tests for lib/format.ts (the percent/latency/duration formatters, which
have already shipped a units bug) is cheap and worth doing.