nxdns/CHANGELOG.md

Changelog

All notable changes to nxdns are recorded here. The format follows Keep a Changelog, and the project uses Semantic Versioning.

Sections are written by hand. Nothing here is generated from commit messages: the point of the file is to say what changed for an operator, which a commit subject rarely does.

[0.0.13] - 2026-08-27

The upstream query budget becomes one honest deadline. A busy network no longer blames a healthy standby for running out of time, and a query burst no longer queues invisibly until everything answers SERVFAIL at once.

Fixed

• The per-query upstream budget is now one absolute deadline, spent by everything that blocks. Waiting for a free slot on a saturated upstream now spends the query's upstream.total_timeout_ms budget just like the exchange itself, instead of being invisible to it — under a burst, queries used to wait out their whole budget in the queue and then start attempts they could never finish. An attempt near the end of the budget runs truncated, and when a truncated attempt runs out of time that is evidence about the budget, not the upstream: it no longer counts against that upstream's health or success rate, and the query log no longer names an upstream that was given no fair chance. A field incident produced 279 rows blaming a standby whose health counters read zero for zero; those rows now attribute nothing.
• A query no longer blocks behind a saturated upstream while another has capacity. Admission sweeps the upstreams in priority order and takes the first free slot; priority now means the order among upstreams that can be admitted right now, and a query blocks only when nothing has capacity — on the highest-priority eligible upstream, bounded by the remaining budget.
• Conditional forward zones spend upstream.read_timeout_ms once per query. A UDP attempt, a truncated answer and the TCP retry now share the one budget instead of taking a fresh one each, so a slow zone resolver can no longer stretch a single query to several times the configured timeout.

Added

• nxdns_upstream_budget_exhausted_total. A pool-wide counter of queries whose budget ran out — in the queue or mid-attempt — before any upstream answered. It carries no per-upstream label on purpose: running out of budget is a fact about the pool.
• A configuration with more than 64 enabled upstreams is rejected at validation with a clear message, instead of tripping an internal limit at startup.

[0.0.12] - 2026-08-27

Overview stops re-reading the whole query log. One endpoint, one snapshot, pre-aggregated buckets — a 30-day view now costs the same on a month of history as on a day of it. Read the upgrade note first: it resets your query history.

Changed

• Upgrading resets your query history. The query-log schema gains the aggregate tables described below, and querylog.db is never migrated: the first start after the upgrade sets the old file aside (kept on disk next to the new one, named with the reason) and begins a fresh log. Settings, groups, blocklists and every other configuration are untouched.
• The Overview is served by one endpoint, GET /api/overview. It replaces GET /api/stats, /api/stats/timeseries, /api/stats/types, /api/stats/routes and /api/stats/clients, which are gone. The five panels now come from a single database snapshot, so they can no longer disagree with each other, and the page shows one loading and one error state instead of five.
• Query statistics are pre-aggregated as they are written. The query log now maintains 30-minute aggregate tables in the same transaction that stores the rows, and the 24-hour, 7-day and 30-day views read those instead of scanning every logged query. The cost of opening the Overview no longer grows with the size of the log: measured at three million rows, the 30-day view went from roughly eight-tenths of a second of scanning to under fifty milliseconds, at the price of about ten percent on each background write batch and ~1.5 MB of disk. The server also keeps the most recent response per period in memory and serves repeat polls from it while nothing has changed — until new queries land, retention prunes, or the period's time window rolls forward — so on a quiet network most of the steady 30-second refreshes do no database work at all.

The Overview charts move to visx and grow up: one hover treatment across all four, honest labels, and maintained d3 math under the app's own rendering.

Changed

• The Overview charts are drawn with visx. The hand-written chart layout code is replaced by visx 4.0.0 primitives — maintained d3 math for the scales, ticks, stacking and arcs — while the rendering, colours and themes stay the app's own. The charts read as before, with four behaviour improvements: all four charts now share the same hover treatment (the per-client chart and both donuts gain the tooltip and dimming the query timeline already had, so pointing at a ring segment names it, its count and its share), an open tooltip follows a data refresh instead of showing stale counts, and it retires cleanly when the time window rolls. The admin bundle grows by about 68 KB and stays under its size budget.
• The query timeline's third series is called "Allowed". What the chart called "Other" is every query that was neither blocked nor served from cache — answered upstream, from a local record or a forward zone — so it is now named for what it is rather than for the subtraction that produces it. It stays on the chart even in a window where nothing was allowed, alongside Blocked and Cached: all three name a kind of answer a query can get, and a period where every query was blocked or cached is worth seeing.
• The client chart drops "Other" in a window where it counted nothing. That series aggregates the clients outside the top eight, so when it counts nothing there is nothing being aggregated, and a legend entry, a tooltip row and a table column that exist only to say "zero" are noise. The named clients stay even at zero, because a client that went quiet is a fact about the window.

[0.0.10] - 2026-08-24

Configuration goes live: when the database owns the configuration, saving a setting reconfigures the running process instead of asking for a restart. The restart-required set shrinks to the listen sockets and the admin interface switch.

Changed

• Almost every settings change now applies while the server runs. When the database owns the configuration, saving a setting takes effect immediately — the blocking response, upstream timeouts, cache size, rate limits, session lifetime, log level and destination, blocklist update schedule, privacy flags, disk thresholds and the query-log buffer all reconfigure the running process, exactly as Pi-hole and AdGuard Home do. Nothing is written to the database unless the running server already accepted it, so the API can never report a value the process refused. The restart-required set shrinks from every scalar key to the twelve that genuinely need one: listen addresses and ports, and turning the admin interface itself on or off. The admin pages drop their restart notices for everything else, and an upstream edit — the loudest offender — now applies to the next query. A configuration file still works the way it always has: edit the file, restart the process.
• The release cut refuses to ship an undisclosed query-log schema change. zig build cut now compares the querylog.db schema fingerprint of the previous release tag against this tree's, and when they differ it requires the changelog section for the version being cut to state that the upgrade discards the stored query history. 0.0.9 changed the schema and its announcement did not mention it; the file is never migrated, so that upgrade silently threw every logged query away.

[0.0.9] - 2026-08-22

Query provenance: every logged query becomes exactly explainable — what the policy decided, what matched, where the answer came from and what the client saw. The handler records all of it as the reply goes out, query_log stores it, and a detail page reads one query back in the order the pipeline decided it. Read the upgrade note below first: it resets your query history.

Added

• Every logged query has a detail page. A row in Activity now links to /activity/queries/{id}, which explains that one query in the order it was decided: the request, the group it was matched under, the policy verdict with the rule that produced it and the blocklist source that rule came from, any CNAME uncloaking or safe-search rewrite, the route the answer took — blocked, local, forward zone, upstream or cache — and what the client got back, RCODE and duration included. GET /api/queries/{id} serves the same object; an id that retention has already deleted is a 404. The live view carries the same provenance for the queries it streams, so a query is explainable as it happens as well as afterwards.
• Query Log, Live and Lookup are one Activity page. /activity is the single surface for what nxdns answered: History reads the stored log, Live reads the stream, and both show the same seven columns — Time, Domain, Client, Type, Result, Route, Duration. The mode and every filter live in the URL, so an investigation is one link that shows the recipient exactly what you were looking at, and an absolute time range stays that range instead of drifting as the day goes on. A new Result column says what the client actually got — Blocked, NOERROR, SERVFAIL and the rest — with the Route column beside it saying how the answer was produced, which is the pair the old Status column could not show: a blocked name is answered with NOERROR, and reading only the code made a block look like a success. Both unhappy cases are marked by weight and shape as well as colour. Switching between History and Live keeps your filters, and leaving Live closes the stream instead of holding a viewer slot open. A live row that the log has not written yet opens its own provenance in place — no invented row id — and the open detail stays put while the 500-row buffer scrolls past underneath it. Domain testing moves to /activity/test as Current policy simulation, worded so it can never be misread as an account of a query that already happened.
• Diagnostics can be scoped to an absolute window. /diagnostics?since=…&until=… now validates and applies both bounds to the active and resolved lists, and the page states the window it is showing with a way to clear it. A query's detail page links here with the five minutes either side of that query, which is where the underlying failure text for a SERVFAIL lives.
• The query log and the stats endpoints say how far back the history goes. GET /api/queries and all five /api/stats* endpoints each carry a coverage object: available_since, the first second the file can answer for, and complete, whether the window you asked for begins inside it. A period that starts before the query log does now says so instead of charting the missing part as zero — which is what a recreate, a retention pass or a fresh install would otherwise look like.
• Three new period breakdowns: GET /api/stats/types, /api/stats/routes and /api/stats/clients. They take the same period parameter as /api/stats and report over the same UTC-aligned window, so every panel of one page describes the same span. types counts queries per DNS type, with the queries that recorded no type kept as their own row instead of dropped — the numeric type only, since naming types is the admin's job and a second table in the server would drift out of agreement with it. routes counts queries by how they were answered, grouping upstream rows by the answering resolver and forward-zone rows by the zone, with blocked, cache, local and rejected answers carrying no source. clients returns one bucketed series per client, aligned exactly like /api/stats/timeseries so the two charts share an x-axis: the eight busiest clients in the window are named and everything else sums into an other series, which is always present and always the same length as the named ones.
• /metrics says whether an upstream is queueing. Five new per-upstream series, labelled by index and redacted url like the existing ones: nxdns_upstream_in_flight and nxdns_upstream_slots are the exchanges in flight against an upstream and the ceiling they cannot cross, nxdns_upstream_queued_total and nxdns_upstream_queued_seconds_total count the exchanges that had to wait for a slot and the time they spent waiting — including the ones that were cancelled while waiting, which is exactly the query that ends in SERVFAIL — and nxdns_upstream_reuse_recoveries_total counts the stale DoT connections that were redialled, so connection churn is a number instead of log noise. The two queue counters are approximate: they are sampled when a query is admitted, not measured as a queue length. /api/health is unchanged.
• Each of those responses is read atomically. Every window-bounded read — the five stats endpoints and GET /api/queries — now takes its rows and its coverage watermark inside one SQLite read transaction. A retention pass that runs mid-response can no longer hand back rows from before the prune tagged with an available_since from after it, and the clients breakdown ranks and buckets from one database state rather than two. The transaction is a deferred read, so it never blocks the query logger or retention.

Removed

• The upstream-history subsystem and GET /api/upstream/health are gone. nxdns recorded every upstream exchange into per-minute aggregates in querylog.db so the dashboard could show each upstream's counts, success rate and last failure over the selected period. The Overview replacement drops that table, which left a writer whose only reader was its own failure signal, so the whole subsystem goes: the accumulator and its flush task, the upstream_targets and upstream_minute tables, the /api/upstream/health endpoint, the retention pass over the minute rows, and the four nxdns_upstream_history_* and one nxdns_retention_upstream_rows_pruned_total Prometheus metrics. What replaces it: /api/health says how many upstreams are available of how many enabled, /metrics keeps the live per-upstream nxdns_upstream_up and nxdns_upstream_success_rate series, and a failing upstream is a Diagnostics episode (upstream.exchange) with its own error text and duration. Ranged per-upstream counts are not replaced. Existing upstream_history.write diagnostics entries stay readable; nothing writes new ones, and any that were still open when you upgrade are closed at the first start.
• /queries, /queries/{id}, /live and /lookup are gone, and bookmarks to them break. There is no redirect and no alias: the paths simply stop resolving, and the app shows its not-found page. Everything those pages did is on /activity, /activity/queries/{id} and /activity/test. Three navigation entries collapse into one, "Activity". The API is untouched — /api/queries, /api/queries/{id}, /api/queries/live and /api/lookup all answer exactly as before.
• The Status column, and the block reason on every row. The reason a query was blocked was repeated on each of a hundred rows and pushed the answer the client saw off the table. Result and Route replace it; the exact rule, the blocklist source and the historical group stay one click away on the query's detail page, which is the only place they were ever readable.

Changed

• Configuration is three task-shaped pages, and a file-managed server says so once. Groups, Blocklists, Rules, Local DNS, Upstreams and Settings — six navigation entries and six routes — become /configuration/protection, /configuration/resolution and /configuration/system under one labelled "Configuration" group. Protection is group-centred: pick a group and read its safe search, its blocklist sources, its rules and how many clients it filters, with the shared blocklist catalogue and "Update now" on a second tab. Resolution holds the upstream pool, local records and forward zones; System holds the settings sections, the restart-required annotations and "Reload certificates". The tab and the selected group are URL state, so the view you are reading is a link, and the six old paths stop resolving — no redirect, no alias. When a configuration file owns the server, these pages are no longer forms with everything greyed out: they render as definition lists and tables with the exact ZON key beside each value, a note saying which file to edit, and no input, checkbox, Add, Edit, Delete or Save anywhere — while runtime actions that do not touch the file (update blocklists now, reload certificates, pause and resume, deleting an observed client) stay ordinary working buttons. A new GET /api/config/status is the one place that answers who owns the configuration and whether a restart is pending; the admin never guesses from a 403, and until the endpoint answers nothing is editable. restart_pending is now the server's own state rather than a banner one browser tab remembered: it is set by the upstream and settings changes that need a restart, it survives a page reload, another tab sees it within a minute, and only restarting the process clears it. GET /api/settings loses its authority object, which said the same thing twice. Clients keeps its own top-level page, because naming an unknown device is operations, not configuration: the list is address, name, group and first/last seen, ?group= filters it to one group, and each row opens /clients/{id} — the client's identity and where its name came from, the group whose policy it follows with a link to that group, and a link into Activity for its last 24 hours.
• The Dashboard is now Overview, and it takes Pi-hole's layout. / redirects to /overview, and the page answers one question — what the resolver did over a period you choose — instead of laying out six widgets. The 1h/24h/7d/30d period is URL state (/overview?period=1h), so the view you are reading is a link you can send. Top to bottom: four neutral stat tiles — queries, blocked with its share, distinct clients, average response time — each linking into the rows behind its number; the query-volume timeline split blocked, cached and other; a new per-client chart on the same axis, the busiest clients named — by their registered or reverse-DNS name where they have one, exactly as the query tables name them — and the rest summed as "other"; and two donuts, query types and how queries were answered, with each upstream and forward zone named separately. Colours follow the identity of a client, a type or a route rather than its rank, so one client overtaking another between refreshes does not repaint the page. Each donut is drawn as decoration with a visible legend beside it and a table a screen reader reads instead of the graphic. All five panels describe one window — matched on the period, both bounds and the coverage watermark together — so a refresh that straddles a bucket boundary, or a retention pass mid-page, can never put a headline count above a chart of a different span. Panels load, fail and retry on their own: a failing donut leaves the charts standing. A period with nothing in it says "No queries in this period." rather than drawing an empty frame.
• The five health conditions moved to Diagnostics, and the nav item says when to look. Protection, Upstreams, Query history, Diagnostics and Storage are now a compact strip at the top of /diagnostics, above the episodes that explain them, instead of a status list on the landing page. Each states its state in words and an icon as well as colour. A healthy condition is quiet; a degraded one is highlighted and links to what can fix it: protection to Blocklists, no reachable upstream to Upstreams, and a losing or failed query log or a low or critical disk to this same page filtered to the component that failed, with any time window cleared so the filter cannot hide the episodes it points at. Dropped rows are reported with the time of the newest drop, so a loss stays visible after the box recovers. When a health poll fails, the conditions on screen are labelled as the last reading that arrived rather than passing for the current state, and a Retry sits beside them. The Diagnostics navigation item carries a badge with the number of open episodes; it shows a plain "!" when the rollup is degraded with nothing open, and also when the last health poll failed, because an unknown must not look like good news. The badge is absent only when health answered and there was nothing to report.
• Pause moved to the sidebar, and the header indicator is gone. The header carries nothing but the menu button and Log out. Pause and Resume sit at the foot of the navigation sidebar, above the version label, in both the desktop rail and the phone drawer — one global runtime action in the one place that belongs to the resolver rather than to whichever page you are on. The control still appears beside the detail of a query that was blocked, which is the other place the action answers what you are looking at. The control says what it is doing as well as what it offers: Pause while filtering is on, and while it is off, "Paused until 14:05" — or plain "Paused" when the pause has no end — above the Resume button, on every page. "Resume" on its own would name an action without naming the state it ends, and with the header indicator gone no other page could tell you filtering was off. Both controls read the same protection condition, so they cannot disagree, and a pause or resume is reflected immediately rather than at the next poll. Nothing offers to pause while protection is unavailable, since pausing a resolver with no filter snapshot changes nothing.
• GET /api/health changed shape completely. The body is now status plus five condition objects — protection, upstreams, query_history, diagnostics and disk — and status is degraded when, and only when, one of them is in a degrading state: protection unavailable, upstreams unavailable, query history losing or failed, diagnostics unavailable, or disk low or critical. Nothing can degrade the rollup without appearing in the response any more; the old hidden upstream-history contribution was the reason for the rewrite. A paused protection is reported and does not degrade, because it is a choice you made rather than a fault. queries_dropped and writer_failed fold into query_history, which also carries last_drop_s, the time of the newest dropped row; refreshes_gated and snapshot_generation leave the body and stay in /metrics, as do the disk db_bytes, log_bytes and sample_failures fields. The disk monitor's warn state is reported as low, because warn reads as a log level rather than as a quantity of disk. This is a breaking change to a documented endpoint, taken pre-v0.1 rather than carried.
• Upgrading resets your query history a second time. Dropping the upstream_targets and upstream_minute tables changes the querylog.db schema fingerprint, and that file is never migrated, so the first start after this release sets the old one aside as querylog.db.schema-changed-<unix seconds> and creates a fresh one — exactly as the provenance change above does, and in the same start. config.db is untouched.
• GET /api/stats no longer reports cached. The standalone cache card is gone from Overview, so the totals field behind it has no consumer. Cache hits stay visible in the query-volume timeline's blocked/cached/other split, in GET /api/stats/timeseries, and in nxdns_cache_hits_total.
• GET /api/queries rows changed shape. Each row gains qclass, rcode, policy_action, policy_reason and route_kind, and block_reason is gone: the reason a query was blocked is now one of a closed set of values rather than a formatted string. No table column shows it — the reason is read on the query's detail page, and by an API client from policy_reason on the row. blocked, cache_hit, upstream and every other existing field are unchanged.
• Upgrading resets your query history. The query_log table gains the provenance columns below, and querylog.db is never migrated (it holds expendable log rows, so a schema change replaces the file instead of upgrading it). On the first start after the upgrade the old file is set aside as querylog.db.schema-changed-<unix seconds> and a fresh one is created. Nothing else is touched: config.db keeps your configuration and your diagnostics history. The recreate files a resolved query_log.recreated diagnostics entry naming the file that was kept and the timestamp the new history begins at, and a new querylog_meta table records that coverage start, so the dashboard can say "history is available from ..." instead of charting an empty range as zero. The set-aside file is a working SQLite database and can be deleted once you have decided you do not want it.
• logging.query_log_buffer_max now accepts 1 to 37449, down from 1 to 1000000. The queued entry carries every new provenance field by value and is about four times as wide as before — 1792 bytes against 432 — so the meaningful bound is bytes rather than entries. The ceiling is computed at compile time from the width of the entry so that the queue's worst case stays within 64 MiB, and it moves whenever that width does. The default of 10000 is unchanged and costs about 17 MiB. A configuration above the new ceiling is rejected at startup with the ceiling in the message.
• Group and blocklist source names are now capped at 64 bytes. Both are copied into every query-log row that mentions them, so an unbounded name was an unbounded cost per row. A longer name is rejected as GroupNameTooLong or SourceNameTooLong.
• The query log returns to SQLite's default checkpoint cadence. 0.0.8 stretched wal_autocheckpoint on every read-write querylog.db connection from the 1000-page default to 8192 pages, on the expectation that it would cut about 130 MiB a day of checkpoint writeback on the deployed Pi. Field measurement on that Pi showed no measurable effect on daily disk writes, so all it bought was a roughly five-hour power-loss durability window in place of the default's ~40 minutes. No pragma is issued any more: the cadence is SQLite's 1000 pages, about 4 MiB, and the ~40-minute boundary is back.
• The admin bundle now has a ceiling the build enforces. npm run build fails if admin/dist/assets totals more than 800,000 bytes — it is 708,352 today — and prints the largest chunks when it does. The bundle is embedded in the server binary and served to your LAN, so an accidental dependency arriving in it is a regression every other check would have passed. Alongside it the redesign's closure sweep removed the last code the new pages left behind: an unused API client call and type, and the features/queries directory renamed to features/provenance now that no page lives there. The investigation links that carry a time window out of a query detail are pinned by their own tests, including one that a link's emitted bounds survive the Activity page's validation unchanged. Nothing an operator uses changed.

Fixed

• A burst of concurrent queries no longer resolves one at a time, and no longer ends in SERVFAIL. The pool held an upstream for the whole of an exchange, so every query against one upstream waited for the one before it, and the DoT client dialled a fresh TCP connection and ran a full TLS handshake for each query on top of that. Thirty concurrent names against one DoT upstream resolved as a staircase at about 92 ms per query on a Pi, and the queries at the back of the queue burned the five-second total budget waiting and were answered SERVFAIL — with nothing on any surface saying a queue existed. Two changes fix it: each upstream now runs up to eight exchanges at once, each on its own leaf client behind a semaphore, so a query waits for a free slot rather than for the whole upstream; and a DoT client keeps its TLS session open across exchanges instead of handshaking per query. A reused connection that the resolver closed while it was idle is detected at use — never by a keepalive timer — and redialled once, and that redial is invisible to health and to Diagnostics because an idle close is normal, not a fault. The slot count is compiled, not configured: there is no new knob.
• A UDP reply that has to be truncated keeps the answer's RCODE. When an answer does not fit the client's UDP buffer, nxdns replaces it with an empty reply carrying the TC bit, which tells the client to retry over TCP. That replacement was always built as NOERROR, whatever the answer said — so an oversized NXDOMAIN reached the client as a success, and an EDNS extended RCODE above 15 lost the eight upper bits it needs an OPT record to carry. The truncated reply now carries the full twelve-bit code the answer had, split across the header and the reply's OPT record where the code needs it, and the query-log row records the code the client actually saw. The retry over TCP always returned the right RCODE; this was the UDP answer that preceded it.

[0.0.8] - 2026-08-21

One constant, chosen from the 0.0.7 field numbers: the checkpoint cadence was the last first-order write cost on the Pi's SD card.

Changed

• The query log checkpoints its write-ahead log every 32 MiB instead of every 4 MiB. Batching the writer in 0.0.7 took the deployed Pi from about 0.5 to 0.281 GiB of writes a day, and about 130 MiB of what is left is checkpoint writeback: SQLite's 1000-page default trips roughly every 40 minutes and rewrites the same hot index and interior pages into querylog.db each time. Every read-write connection to querylog.db now sets wal_autocheckpoint to 8192 pages, which stretches that to roughly five hours and cuts those in-place rewrites about eightfold, for an expected total near 190 MiB a day. The price is durability under power loss or a kernel panic. At synchronous = NORMAL a commit does not fsync, so the checkpoint is the only guaranteed durability boundary, and it now sits about five hours of query rows and upstream-history minutes back rather than 40 minutes. Kernel writeback normally makes the real loss far smaller than that, but nothing guarantees it. A process crash or a clean stop still loses nothing that was committed, and the database is never left inconsistent: recovery replays the longest valid prefix of the log. The querylog.db-wal file is expected to sit near 32 MiB rather than capped there, since a long-running reader can hold a checkpoint off and let it overshoot, and the daily retention pass still truncates it. config.db is unchanged.

[0.0.7] - 2026-08-20

Operational failures get a page of their own, and the query log stops wearing out the disk it lives on: the deployed Pi was writing half a gigabyte a day to store two megabytes of query rows, one transaction per query. Both came out of running 0.0.6 on real hardware.

Added

• A diagnostics page. Operational failures now land in one curated log instead of only journald: blocklist download failures, certificate reload failures, disk pressure, query-log writer and maintenance failures, upstream exchange and history failures, client tracking failures, listener and configuration problems at boot, and the query-log recreation an upgrade causes. One entry per failing subject — an entry opens on the first failure, counts repeats, and closes itself when the subject recovers; nothing needs dismissing. Each entry says what it means for the service and what to do about it. GET /api/diagnostics serves the log, GET /api/health reports the active counts and degrades while the diagnostics store itself cannot write, and /metrics gains nxdns_diagnostics_active_warnings, nxdns_diagnostics_active_errors and nxdns_diagnostics_write_failures_total. Resolved entries can be purged when you decide the history has served its purpose — one entry from its row or its detail page, or the whole resolved history at once with "Purge all resolved" (DELETE /api/diagnostics/{id} and DELETE /api/diagnostics). An entry that is still failing is the current state of the box, not history, so it has no purge action and the API answers 409.

Changed

• The query log commits once a minute instead of once a query. The writer batched for 100 milliseconds, which at a household's query rate means almost every query got a transaction of its own — and a transaction costs the disk far more than the row it carries. On the deployed Pi that came to roughly 0.5 GiB of writes a day to store 2.3 MB of query rows, the kind of write volume that kills an SD card. The batch window is now logging.query_log_flush_interval_s: 60 seconds by default (the same minute Pi-hole's DBinterval defaults to, for the same reason), anything from 0 to 3600, editable on the settings page. Batches are still capped at 100 rows, so a burst is committed as soon as it fills one rather than waiting out the window, and the in-memory queue, its drop-oldest backpressure and retention are untouched. The price is two kinds of lag: a crash costs about one interval of query history — more if the writer was held back by a full disk or a slow write — and every query-log-backed view — the query-log page, the dashboard totals, the timeseries — is about one interval behind. The live page is not affected; it is fed before the queue. Set the key to 0 for the old write-immediately behavior.

Fixed

• Shutdown no longer races the last query rows to the disk. The query-log writer was stopped by the same cancellation that stopped the DNS listeners, so whether the batch it was holding reached the database depended on which happened to land first, the cancellation or the queue closing. Shutdown now stops and joins the listeners and every other query producer first, then closes the queue, then waits for the writer to finish emptying it — the held batch and everything still queued get written. If free space is below the critical threshold and the disk monitor will not let that final write through, the rows are counted as dropped instead of holding the exit open indefinitely.
• An upstream success rate no longer rounds up to 100.0% while failures stand. One decimal place cannot hold 12,696 successes out of 12,698 attempts: it rounded to 100.0%, so the row claimed perfect reliability next to a failure count of 2. Neither end of the scale is reachable by rounding any more — 100.0% needs an actual absence of failures and 0.0% an actual absence of successes, and a rate a hair off either end shows 99.9% or 0.1% instead.
• A query log set aside by a schema change is no longer named corrupt. Every recreate wrote the old file to querylog.db.corrupt-<unix seconds>, whatever sent it there — including the fingerprint mismatch an upgrade causes, where the file is a healthy database this build simply cannot read. The name is the only account of the reason that outlives the log line, so it read as an accusation and invited operators to delete an intact file. The name now says which of the four cases it hit: querylog.db.corrupt-…, .not-a-database-…, .quick-check-failed-… or .schema-changed-…. The 0.0.6 upgrade produces schema-changed. Nothing else about the recreate changed, and no existing aside file is renamed.

[0.0.6] - 2026-08-17

The period picker now scopes the whole dashboard. The upstream table was the last widget that ignored it, and fixing that meant recording upstream outcomes over time instead of counting them since boot. Read the query-log note below before you upgrade.

Added

• Four metrics for the new upstream-history recorder: nxdns_upstream_history_flushes_total, nxdns_upstream_history_flush_failures_total, nxdns_upstream_history_rows_dropped_total and the nxdns_upstream_history_pending gauge. While a flush to the database keeps failing, GET /api/health reports degraded; it recovers on the next flush that succeeds.

Changed

• Upstream health answers for the selected period. The dashboard's upstream table used to print counters accumulated since process start beside a success rate taken over the last 32 exchanges, which is how "63 failures" and "100.0% success rate" ended up in the same row under a period picker that scoped nothing there. Every upstream outcome is now aggregated into its wall-clock minute and written to querylog.db, and GET /api/upstream/health?period=… serves the selected window: attempts, failures, success rate, and the last failure with its error name, all inside the period, from 31 days of history. A window with no attempts reports no success rate at all instead of a perfect one, and the table shows an em-dash. The in-memory health state that drives failover and backoff is unchanged, as are its /metrics series.
• GET /api/upstream/health changed shape. Gone from each upstream: consecutive_failures, total_successes, total_failures, the last-32 success_rate, last_error and last_error_age_s. Each upstream keeps url, enabled and available and gains a period object with the ranged numbers; the body gains period, since, until and a complete flag that says whether any outcome was known to be dropped inside the window. The removed counters are still exported by /metrics under their existing names. On the dashboard the "Right now" section is gone with them: the upstream table rejoined the ranged part of the page, and the disk card, the one live widget left, is titled "Storage now".
• The query log is recreated on upgrade. Recording upstream history added two tables to the querylog.db schema, and its fingerprint check refuses a database that does not match the shipped definition. On first start this version renames the existing querylog.db aside as querylog.db.corrupt-<unix seconds> in the data directory and creates a fresh one, so query history and stats restart empty. The renamed file is left in place rather than deleted, so removing it is your call. config.db is untouched: no configuration is lost.

[0.0.5] - 2026-08-16

One rendering fix on the 0.0.4 feature, caught the day it shipped.

Changed

• The query tables no longer repeat the learned tag on every row: in the live page and the query log a learned name is just muted, with the address still in the row's tooltip. The clients page keeps the tag, where it appears once per client and says something.

[0.0.4] - 2026-08-16

The names learned in 0.0.3 now show up where queries do: the live page and the query log name each client instead of printing its address.

Added

• Client names in the query tables. The live page and the query log show each query's client by name, with the same precedence as the clients page: a hand-typed name wins, else the learned name (muted, tagged learned), else the bare address. When a name replaces the address, the address stays readable as the row's tooltip. Devices that appear mid-stream show their address first and pick up their name within half a minute.

[0.0.3] - 2026-08-15

Devices name themselves: the clients table asks the router over reverse DNS instead of waiting for the operator to type every name. The CI container gate also moved from workflow shell into a compiled, tested tool, which fixed a latent temp-directory bug shared with the release tool.

Added

• Client names learned over reverse DNS. A client row that carries no hand-typed name gets one from the network: each tracker flush pass takes up to 16 unnamed rows, builds each address's reverse name, matches it against the declared forward_zones, and on a match sends one PTR query to that zone's resolver, storing the answer as a learned name. This requires a conditional forward zone covering the LAN's reverse space — for example 168.192.in-addr.arpa pointed at the router; without one, nothing is sent anywhere. A hand-typed name always wins, learned names never appear in nxdns export and are never set by nxdns import, and each row refreshes once a day (an hour after a failure), so a rename can show stale for up to 24 hours. The API's Client object gains a learned_name field and the clients page shows it.

Changed

• The container CI gate — image build, image-contents assertion against the packaged artifacts, and the startup/shutdown smoke test — moved from workflow shell into tools/container_check.zig, compiled and unit-tested by zig build test and runnable on a laptop against a local docker daemon. The health probe now runs under a real 60-second deadline (the shell loop's "30 seconds" could stretch past three minutes), and the gate's docker objects carry an ownership label so anything a dead runner leaks is discoverable. The version in CI is parsed from build.zig.zon through the zon grammar, once, instead of by two copies of a sed regex.

Fixed

• The release tool's temporary-directory claim was not exclusive: the "create" it relied on succeeds on a directory that already exists, so a stale or concurrent directory could be silently adopted, written into, and deleted on exit. Both the release tool and the new container gate now claim their directories exclusively and retry on collision.

[0.0.2] - 2026-08-14

Configuration can now be a file that every boot converges to, filtering gains regex rules and honors blocklist exception lines, and two refresh bugs that silently kept stale state are fixed. Note the three breaking changes below if you script against nxdns import or run with --config.

Added

• Declarative configuration for IaC. nxdns run --config=<file> makes the file the sole source of configuration: every boot converges the database to it in one transaction, preserving blocklist downloads, compiled lists and client history, so an unchanged file costs zero downloads and zero writes. Bare nxdns run keeps the database (and the web UI) in charge, exactly as before. In file mode the web UI is read-only for configuration and says so; runtime actions (pause, blocklist refresh, certificate reload) stay live. GET /api/settings reports which authority governs the process.
• nxdns import now refuses a file whose application would delete configuration rows, names the tables and counts, and applies it only with the new --allow-delete flag. Additive and edit-in-place imports need no flag.
• Regex rules. Rules gain a third kind, regex, beside exact and wildcard, for per-group allow and block patterns such as ^ad[0-9]+-. The engine is homegrown and linear-time by construction, so no pattern can make matching blow up; backreferences and lookaround do not exist, and a bad pattern is refused at insert time with the limit it hit. Matches appear in /api/lookup and the query log as rule_allow_regex / rule_block_regex. Regex still comes only from you: regex lines in downloaded lists stay counted and skipped.
• Blocklist exception lines are honored. An Adblock-Plus @@||name^ line in a downloaded list now lifts that name — and its subdomains — out of what the attached lists block. Exceptions sit below every rule you wrote: a downloaded list can reopen only a hole another downloaded list dug, never override an operator decision. Each source reports how many it carried.
• Browser-only lines are counted where you can see them. Every source now reports how many of its lines nxdns skipped as syntax with no DNS meaning — cosmetic filters, $-modifier rules — beside the existing skipped-regex count. Both blocklist tables show the number and the UI explains the difference: a list whose skipped-unsupported count dwarfs its domain count is written for browser extensions, and its DNS or hosts variant will block more. Previously such a list compiled to almost nothing and looked clean.

Changed

• Breaking: nxdns run --config <file> changed meaning. It used to seed the database once and then ignore the file; it now makes the file the authority on every boot, which deletes any configuration the file does not declare — including edits made through the web UI since the seed. Before upgrading a unit that carries --config: either drop the flag to keep the database in charge, or adopt file mode with the sequence in the upgrade guide. Order matters there: export the file with the NEW binary (stopped).
• Breaking: 0.0.1 exports are refused by this version. A 0.0.1 nxdns export writes both .password = "" and the stored .password_hash, and this version refuses a file that carries both. This bites any old export — an adoption file or a configuration backup fed to nxdns import alike. Fix an existing export by deleting its .password = "" line (keep the .password_hash line). Take fresh backups with the new binary.
• Breaking: the offline password-change recipe changed. Setting .password = "new" together with .password_hash = "" is now refused (empty password_hash is an explicit "disable authentication", and the two fields cannot both be present). To change the password in the file: set .password and delete the .password_hash line entirely.
• nxdns import --force is renamed --allow-delete.
• A fresh install no longer seeds from /etc/nxdns/config.zon by presence. Use nxdns import once, or run in file mode with --config.
• The admin UI's internals moved to TypeScript 7 and replaced Tailwind with StyleX and React Aria. The visible change is small: selects are real widgets with working keyboard focus; everything else renders as before.
• The config.db schema is a single baseline definition again; numbered migration steps start accumulating at v0.1.

Fixed

• A list switching a name between its exact and wildcard forms never took effect. The compiled-list checksum hashed the exact and wildcard bodies as one unseparated byte stream, so a list carrying a.example and the same list carrying *.a.example produced the same digest, and the refresh kept the old compiled files. The checksum now separates the bodies. Every source recompiles once on its first refresh after the upgrade; no re-download of unchanged content is forced beyond the refresh's normal fetch.
• A refresh could store stale skip counts. When a refresh found the list content unchanged, it wrote the previously stored skip counters back to the database while showing the fresh ones in the UI, and the next restart reverted the numbers to the stale copy. All counters now persist from the fresh compile.
• An Adblock-Plus entry with embedded whitespace (||good.example bad.example^) compiled into an entry no query could ever match. Such lines are now counted as unsupported instead.

[0.0.1] - 2026-08-09

First release. Everything below is new.

Added

• Forwarding DNS server. UDP and TCP listeners with a wire-format parser and encoder written against RFC 1035 and EDNS(0), a bounded worker model, per-client rate limiting and a pause control that stops filtering without stopping resolution.
• Encrypted upstreams. DNS-over-HTTPS and DNS-over-TLS clients over a pool that tracks per-upstream health and fails over, with SNI and certificate verification driven by a per-upstream TLS name.
• DoH and DoT endpoints. nxdns also answers as an encrypted resolver, with a certificate store that reloads on disk changes and through the API, so renewals do not need a restart.
• Blocklist filtering. Subscriptions in hosts, plain-domain and Adblock-Plus-style formats, compiled into a compact matcher; per-group allow and block rules with wildcards; safe-search enforcement.
• Per-client policy groups. Clients are identified by address and assigned to groups, so the filtering a device gets depends on which device it is.
• Local DNS. Local A/AAAA/CNAME/PTR records and conditional forwarding of internal zones to another resolver.
• Cache. A bounded in-memory cache that respects upstream TTLs and expires entries rather than serving them stale.
• Query log. Queries land in SQLite under a retention policy in both rows and days, with disk-full self-protection that degrades instead of corrupting, and a live SSE stream of the same events.
• Web UI and REST API. A React single-page admin UI embedded in the binary, a REST API with a served OpenAPI document, session authentication, API rate limiting and Prometheus-style /metrics.
• Configuration. A ZON configuration file seeds the database on first boot; after that the database is the truth, and nxdns export / nxdns import move configuration in and out. nxdns check validates a file without starting.
• CLI. run, check, export, import, version and help.
• Packaging. A hardened systemd unit with a sysusers fragment, and a FROM scratch container image holding the binary, a CA bundle and the licence files, assembled by a builder stage pinned to alpine:3.22 by digest. Nothing from Alpine ships in the published image except that CA bundle.
• Releases. Tags publish five assets — static musl tarballs for x86_64-linux-musl and aarch64-linux-musl, IMAGE-DIGEST.txt naming the multi-architecture container image by digest, SHA256SUMS.txt over those three, and SHA256SUMS.txt.asc, a detached signature over the checksum file. zig build dist and zig build verify-dist produce and check the same artifacts on a laptop.
• Licensing. EUPL-1.2, with a THIRD-PARTY-NOTICES file in every tarball and image assembled from a reviewed inventory of what the artifacts contain.
• Documentation. A Diátaxis split — tutorial, how-to, reference, explanation — with drift guards that fail the build when the reference pages fall behind the code.