diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index 1915cc8..7e3990f 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -136,3 +136,83 @@ jobs: exit 1 fi done + + docker: + runs-on: ubuntu-24.04 + + steps: + - uses: actions/checkout@v4 + + - name: Set up Zig + uses: mlugg/setup-zig@v2 + with: + version: ${{ env.ZIG_VERSION }} + + - name: Set up Node + uses: actions/setup-node@v4 + with: + node-version: ${{ env.NODE_VERSION }} + cache: npm + cache-dependency-path: web/package-lock.json + + - name: Build the web UI + working-directory: web + run: | + npm ci + npm run build + + - name: Build static musl executables + run: zig build cross -Dweb-dist=web/dist -Doptimize=ReleaseSafe + + - name: Build the image + run: docker build -t nxdns:ci -f deploy/docker/Dockerfile . + + - name: Smoke test the container + run: | + set -euo pipefail + + docker run --rm nxdns:ci version + + mkdir -p etc-nxdns + cat > etc-nxdns/config.zon <<'EOF' + .{ + .groups = .{ .{ .name = "default" } }, + .upstreams = .{ .{ .url = "https://cloudflare-dns.com/dns-query" } }, + } + EOF + + cid=$(docker run -d --name nxdns-smoke \ + -p 127.0.0.1:8080:8080 \ + -v "$PWD/etc-nxdns:/etc/nxdns:ro" \ + nxdns:ci) + trap 'docker rm -f nxdns-smoke >/dev/null 2>&1 || true' EXIT + + # The published port works when the job runs on the docker host or in + # DinD; the container IP covers a runner that shares the daemon over + # a mounted socket. + ip=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$cid") + healthy="" + for _ in $(seq 1 30); do + if [ "$(docker inspect -f '{{.State.Running}}' "$cid")" != "true" ]; then + echo "container exited during startup" + docker logs "$cid" || true + exit 1 + fi + if curl -fsS "http://127.0.0.1:8080/api/health" \ + || { [ -n "$ip" ] && curl -fsS "http://$ip:8080/api/health"; }; then + healthy=1 + break + fi + sleep 1 + done + if [ -z "$healthy" ]; then + echo "no /api/health response within 30 seconds" + docker logs "$cid" || true + exit 1 + fi + + docker stop -t 30 nxdns-smoke + exit_code=$(docker inspect -f '{{.State.ExitCode}}' nxdns-smoke) + echo "exit code after SIGTERM: $exit_code" + docker logs nxdns-smoke || true + test "$exit_code" -eq 0 diff --git a/PLAN.md b/PLAN.md index 06d321f..f279cd4 100644 --- a/PLAN.md +++ b/PLAN.md @@ -54,7 +54,7 @@ Serves a household LAN (≈2–20 devices). Portfolio-grade public repo with ext Zig 0.16 stdlib is built on the `std.Io` interface: `std.Io.net` owns networking (`std.net` in its old form is gone) and `std.http.Client` requires an `io: Io`. Therefore: - **`Io` is the injected platform abstraction.** Every component that does I/O takes `io: Io`. No project-owned wrapper interfaces around it — a second abstraction over an abstraction with one consumer is waste. -- **Backend: `std.Io.Threaded` by default** — the mature, debuggable path; at ≤20 devices throughput is a non-issue. `std.Io.Evented` (io_uring) is selectable via config flag; the code is backend-agnostic by construction, so this is a switch, not a refactor. +- **Backend: `std.Io.Threaded`** — the mature, debuggable path; at ≤20 devices throughput is a non-issue. The originally planned io_uring config flag was dropped in milestone 11: `std.Io.Evented` at Zig 0.16.0 stubs the networking a server needs — listen, accept, connect, lookup, and stream reads/writes return `error.NetworkDown` (`Uring.zig` netListenIp/netAccept/netConnectIp/netRead/netWrite) — so a selectable backend would boot a dead server. The code stays backend-agnostic by construction; revisit when std ships working evented networking. - No hand-written thread pool. `Io` async/concurrent/Group covers task management. - Core domain modules (`dns`, `filter`, `cache`) stay pure: no `Io`, no sockets — bytes in, bytes out. Only servers, upstream clients, and storage touch `Io`. @@ -476,7 +476,6 @@ Periodic delete of rows older than `retention_days`; scheduled checkpoint/VACUUM .{ .upstream = .{ .servers = .{ "https://cloudflare-dns.com/dns-query", "tls://dns.google:853" }, - .connect_timeout_ms = 2000, .read_timeout_ms = 3000, }, .dns = .{ @@ -683,7 +682,7 @@ Exit: documented deployment works end-to-end on the Pi 5. | B | Rule kinds: exact, parent-walk, wildcard. Regex permanently out of scope | | C | In scope: local DoH/DoT server, local records, conditional forwarding. Out: HTTP/2, DoQ, DHCP, DNSSEC, clustering | | D | mbedTLS (vendored) terminates server TLS; stdlib TLS for upstream client | -| E | `std.Io` injected everywhere; `Threaded` default backend, io_uring via flag; no custom thread pool | +| E | `std.Io` injected everywhere; `Threaded` backend (io_uring flag dropped in m11 — Evented networking is stubbed at 0.16.0); no custom thread pool | | F | Config format: ZON via `std.zon`; DB is truth; export/import for backup + host moves | | G | SQLite vendored amalgamation + own thin wrapper | | H | Two DBs: `config.db` (precious) + `querylog.db` (expendable, self-contained, client IP as text) | diff --git a/README.md b/README.md new file mode 100644 index 0000000..9f4bdc9 --- /dev/null +++ b/README.md @@ -0,0 +1,72 @@ +# nxdns + +A self-hosted DNS sinkhole for a household LAN, written in Zig 0.16. One +static musl binary, SQLite for state, a Raspberry Pi 5 as the reference +target. It answers your network's DNS, blocks what you tell it to, and shows +you what asked for what. + +## Features + +- Blocklist filtering: subscribe to hosts/domain lists, plus your own allow + and block rules with wildcard support (`*.example.com`) +- Per-client policy groups: different filtering for the kids' tablet and + your workstation +- Local DNS records and conditional forwarding for internal zones +- Encrypted upstreams: DNS-over-HTTPS and DNS-over-TLS with failover +- Built-in DoH and DoT server endpoints, with certificate hot-reload +- Bounded in-memory DNS cache with TTL-respecting expiry +- Query log with retention limits, live-streamed over SSE +- Web UI (embedded in the binary) and a REST API with a served OpenAPI spec +- Prometheus-style `/metrics`, per-client rate limiting, disk-full + self-protection + +## Quickstart (docker compose) + +Build the binary and image, seed a minimal configuration, start it: + +```sh +(cd web && npm ci && npm run build) +zig build cross -Dweb-dist=web/dist -Doptimize=ReleaseSafe + +cd deploy/docker +mkdir -p etc-nxdns +cat > etc-nxdns/config.zon <<'EOF' +.{ + .groups = .{ .{ .name = "default" } }, + .upstreams = .{ .{ .url = "https://cloudflare-dns.com/dns-query" } }, + .web = .{ .password = "choose-a-real-password" }, +} +EOF +docker compose up -d +``` + +DNS is on port 53, the web UI on . The config file +seeds the database on first boot only; from then on the database is the +truth and changes go through the UI, the API, or `nxdns export` / +`nxdns import`. Full install instructions, including the systemd path and +the Pi 5 recipe, are in [docs/operator.md](docs/operator.md). + +## Building from source + +Requires [Zig 0.16.0](https://ziglang.org/download/) and Node.js 24 (for +the web UI). C dependencies (SQLite, mbedTLS) are vendored and built by +`zig build`. + +```sh +(cd web && npm ci && npm run build) # web UI -> web/dist +zig build -Dweb-dist=web/dist # native binary -> zig-out/bin/nxdns +zig build cross -Dweb-dist=web/dist -Doptimize=ReleaseSafe + # static x86_64 + aarch64 musl binaries +zig build test --summary all # unit tests +``` + +## Documentation + +- [docs/operator.md](docs/operator.md) — install, configure, back up, + upgrade, troubleshoot +- [docs/architecture.md](docs/architecture.md) — module map and design +- [docs/config-reference.md](docs/config-reference.md) — every + configuration field +- [docs/api.md](docs/api.md) — REST API, auth and SSE +- [PLAN.md](PLAN.md) and [specs/](specs/) — scope, design decisions and + per-milestone contracts diff --git a/build.zig b/build.zig index 8bfd2e5..6667877 100644 --- a/build.zig +++ b/build.zig @@ -61,6 +61,9 @@ pub fn build(b: *std.Build) void { tests.root_module.addAnonymousImport("test_fixtures", .{ .root_source_file = b.path("tests/fixtures/fixtures.zig"), }); + tests.root_module.addAnonymousImport("docs_files", .{ + .root_source_file = b.path("docs/docs.zig"), + }); tests.root_module.addAnonymousImport("web_assets", .{ .root_source_file = web_assets }); const test_step = b.step("test", "Run the test suite"); test_step.dependOn(&b.addRunArtifact(tests).step); diff --git a/deploy/docker/.dockerignore b/deploy/docker/.dockerignore new file mode 100644 index 0000000..018d4a4 --- /dev/null +++ b/deploy/docker/.dockerignore @@ -0,0 +1,6 @@ +# The Dockerfile copies only zig-out/cross out of the repository-root context, +# and BuildKit transfers only referenced paths. This file guards the classic +# (non-BuildKit) builder, which would otherwise send the whole tree: copy it to +# the repository root as .dockerignore before building without BuildKit. +* +!zig-out/cross diff --git a/deploy/docker/Dockerfile b/deploy/docker/Dockerfile new file mode 100644 index 0000000..21f2e0a --- /dev/null +++ b/deploy/docker/Dockerfile @@ -0,0 +1,33 @@ +# The binary is NOT compiled here. Build it first, from the repository root: +# +# (cd web && npm ci && npm run build) +# zig build cross -Dweb-dist=web/dist -Doptimize=ReleaseSafe +# +# then build the image with the repository root as context: +# +# docker build -t nxdns -f deploy/docker/Dockerfile . +# +# The builder stage stages the CA bundle (upstream DoH/DoT verification rescans +# the system store; a scratch image without one breaks every TLS upstream) and +# maps the buildx TARGETARCH onto the zig cross-target directory. + +FROM alpine:3.22 AS builder +RUN apk add --no-cache ca-certificates +ARG TARGETARCH +COPY zig-out/cross /cross +RUN mkdir -p /rootfs/etc/ssl/certs /rootfs/etc/nxdns /rootfs/var/lib/nxdns \ + && cp /etc/ssl/certs/ca-certificates.crt /rootfs/etc/ssl/certs/ \ + && case "${TARGETARCH:-amd64}" in \ + amd64) cp /cross/x86_64-linux-musl/nxdns /rootfs/nxdns ;; \ + arm64) cp /cross/aarch64-linux-musl/nxdns /rootfs/nxdns ;; \ + *) echo "unsupported TARGETARCH '${TARGETARCH}'" >&2; exit 1 ;; \ + esac \ + && chown 65532:65532 /rootfs/var/lib/nxdns + +FROM scratch +COPY --from=builder /rootfs/ / +USER 65532:65532 +VOLUME /var/lib/nxdns +EXPOSE 53/udp 53/tcp 8080 443 853 +ENTRYPOINT ["/nxdns"] +CMD ["run"] diff --git a/deploy/docker/compose.yaml b/deploy/docker/compose.yaml new file mode 100644 index 0000000..c19d62c --- /dev/null +++ b/deploy/docker/compose.yaml @@ -0,0 +1,31 @@ +services: + nxdns: + image: nxdns + build: + context: ../.. + dockerfile: deploy/docker/Dockerfile + restart: unless-stopped + # First boot needs ./etc-nxdns/config.zon with a `default` group and at + # least one enabled upstream, or the container exits with code 2. The file + # seeds the database once; after that the database is the truth and the + # file is ignored. + volumes: + - ./etc-nxdns:/etc/nxdns:ro + - nxdns-data:/var/lib/nxdns + ports: + - "53:53/udp" + - "53:53/tcp" + - "8080:8080" + # DoH/DoT listeners, off by default in the config: + # - "443:443" + # - "853:853" + # Per-network-namespace sysctl: lets uid 65532 bind port 53 inside the + # container without CAP_NET_BIND_SERVICE. + sysctls: + net.ipv4.ip_unprivileged_port_start: 0 + # Do not point the host's resolv.conf at nxdns itself: the container's own + # lookups (upstream DoH/DoT hostnames) would then depend on the service + # they are trying to start. + +volumes: + nxdns-data: diff --git a/deploy/systemd/nxdns.service b/deploy/systemd/nxdns.service new file mode 100644 index 0000000..29c662c --- /dev/null +++ b/deploy/systemd/nxdns.service @@ -0,0 +1,49 @@ +[Unit] +Description=nxdns DNS sinkhole +Documentation=https://git.mial.net/mokhtar/nxdns +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple +User=nxdns +Group=nxdns +ExecStart=/usr/local/bin/nxdns run + +# nxdns logs to stderr by default; systemd captures it into the journal. +StateDirectory=nxdns +StateDirectoryMode=0700 +LogsDirectory=nxdns +ConfigurationDirectory=nxdns + +# Port 53 (and 443/853 when the DoH/DoT listeners are enabled). +AmbientCapabilities=CAP_NET_BIND_SERVICE +CapabilityBoundingSet=CAP_NET_BIND_SERVICE + +NoNewPrivileges=yes +ProtectSystem=strict +ProtectHome=yes +PrivateTmp=yes +PrivateDevices=yes +ProtectKernelTunables=yes +ProtectKernelModules=yes +ProtectKernelLogs=yes +ProtectControlGroups=yes +ProtectClock=yes +ProtectHostname=yes +ProtectProc=invisible +RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX +RestrictNamespaces=yes +RestrictRealtime=yes +RestrictSUIDSGID=yes +LockPersonality=yes +MemoryDenyWriteExecute=yes +UMask=0077 +SystemCallFilter=@system-service +SystemCallArchitectures=native + +Restart=on-failure +RestartSec=2 + +[Install] +WantedBy=multi-user.target diff --git a/deploy/systemd/sysusers.conf b/deploy/systemd/sysusers.conf new file mode 100644 index 0000000..67d340c --- /dev/null +++ b/deploy/systemd/sysusers.conf @@ -0,0 +1 @@ +u nxdns - "nxdns DNS sinkhole" diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..728286b --- /dev/null +++ b/docs/api.md @@ -0,0 +1,169 @@ +# nxdns REST API + +nxdns serves its admin API itself, on `web.bind:web.port` (default port 8080), +as plain HTTP. TLS termination, where an operator wants it, belongs to a +reverse proxy in front; the session cookie deliberately omits the `Secure` +attribute so the supported plain-HTTP LAN deployment works. + +This page is orientation. The machine-readable contract is +`src/web/openapi.yaml`, which the running server hands out unauthenticated at +`GET /api/openapi.yaml`. When this page and the yaml disagree, the yaml wins. + +## Conventions + +- All request and response bodies are JSON (`application/json`), except + `/metrics` (Prometheus text format), `/api/openapi.yaml` (YAML) and + `/api/queries/live` (`text/event-stream`). +- Field names are snake_case, matching settings keys and SQL column names. +- Every error response carries the envelope `{"error": ""}`. The + message is operator-facing text; internal detail never reaches the wire — + a 500 body is generic and the cause goes to the server log. +- Request bodies are strict: an unknown field is a 400, a body over 1 MiB is + a 413. +- A request whose path matches but whose method does not answers 405 with an + `Allow` header. An unknown `/api` path is a JSON 404; unknown non-`/api` + paths fall through to the embedded SPA (`index.html`), so client-side + routing works. +- Item routes (`{id}`) match a positive integer id only. +- Mutations to groups, blocklists, rules, local records, forward zones, + clients and client prefixes take effect live. Upstreams and `/api/settings` + are restart-required. + +## Authentication + +Cookie sessions, in memory, no accounts — one operator password. + +- Authentication is on exactly when `web.password_hash` is set. When no + password is set, every route is open and `POST /api/auth/login` answers + `{"authenticated": true, "auth_required": false}` without setting a cookie. +- `POST /api/auth/login` takes `{"password": "..."}`. A correct password + answers 200 with a `Set-Cookie` for `nxdns_session` + (`HttpOnly; SameSite=Lax; Path=/`, `Max-Age` = the session TTL). A wrong + password is a 401; a stored hash the server cannot read is a 500, never a + 401. Login attempts spend rate-limit tokens like any other request, and + argon2id verification is deliberately slow. +- Every route whose auth policy is `session` answers + 401 `{"error": "authentication required"}` without a valid cookie. +- Sessions live `web.session_ttl_hours` (default 24) from login; use does not + extend the lifetime. The table holds 32 sessions; a 33rd login evicts the + least recently used. Nothing is persisted — a server restart logs every + operator out. +- Changing the password through `PUT /api/settings` revokes every live + session immediately; the new password applies without a restart. +- `POST /api/auth/logout` ends the cookie's session and clears the cookie. + It answers 200 whether or not the session was live. + +## Rate limiting + +A token bucket per client address: capacity and refill are both +`web.api_rate_limit_per_min` (default 300) per minute, so a page-load burst +up to the capacity is admitted and the long-run rate holds. + +- An over-budget request answers 429 `{"error": "rate limited"}` with a + `Retry-After` header giving the seconds until a token is available + (rounded up, never zero). +- Loopback addresses (127.0.0.0/8 and ::1) are exempt while + `web.api_localhost_exempt` is true (the default). +- Exempt routes, which never consult a bucket: `/metrics` and `/api/health` + (a Prometheus scrape must never see 429) and `/api/queries/live` (one + long-lived stream must not drain its address's bucket; it is bounded by + the SSE connection cap instead). +- The limiter tracks at most 4096 addresses. When the table is full and no + slot is reclaimable, requests from unknown addresses are refused with 429. + +## Live query stream (SSE) + +`GET /api/queries/live` is server-sent events over chunked transfer, +`Content-Type: text/event-stream`, `Cache-Control: no-store`. + +- The stream opens with `retry: 3000`, so a browser `EventSource` reconnects + on its own after a drop. +- Each query is one frame: `event: query` and a single `data:` line of JSON. + The payload carries the `GET /api/queries` row fields minus `id` (a live + entry precedes persistence): `ts`, `domain`, `client_ip`, `qtype`, + `blocked`, `block_reason`, `response_time_us`, `cache_hit`, `upstream`. +- A `: ping` comment heartbeat goes out after 15 s of quiet, keeping + middleboxes from reaping the idle connection. +- Each subscriber buffers up to 64 entries. A client too slow for the query + rate overflows its buffer and the server ends the stream cleanly after + delivering what the buffer held — queries are never held back for a slow + reader. There is no gap marker: on reconnect, re-sync through + `GET /api/queries`, which has the missed rows. +- Connections per client address are capped at + `web.sse_max_connections_per_ip` (default 3); over the cap is a 429. The + cap binds loopback too. The server holds at most 32 concurrent streams in + total; when all slots are taken, the answer is a 503. + +## Operations + +Auth `open` means no session required; `session` means a valid session +cookie is required whenever a password is set. Rate limit `counted` spends a +token; `exempt` never consults the limiter. + +| Method | Path | Auth | Rate limit | Purpose | +|---|---|---|---|---| +| GET | `/metrics` | open | exempt | Prometheus metrics | +| GET | `/api/health` | open | exempt | Health rollup | +| GET | `/api/version` | open | counted | Build and uptime | +| GET | `/api/openapi.yaml` | open | counted | This API's OpenAPI document | +| POST | `/api/auth/login` | open | counted | Log in | +| POST | `/api/auth/logout` | session | counted | Log out | +| GET | `/api/queries` | session | counted | Query log page | +| GET | `/api/queries/live` | session | exempt | Live query stream (server-sent events) | +| GET | `/api/stats` | session | counted | Totals for a period | +| GET | `/api/stats/timeseries` | session | counted | Bucketed counts for a period | +| GET | `/api/lookup` | session | counted | Explain a domain | +| GET | `/api/upstream/health` | session | counted | Upstream pool health | +| GET | `/api/groups` | session | counted | List groups | +| POST | `/api/groups` | session | counted | Create a group | +| GET | `/api/groups/{id}` | session | counted | Read a group | +| PUT | `/api/groups/{id}` | session | counted | Update a group | +| DELETE | `/api/groups/{id}` | session | counted | Delete a group | +| GET | `/api/groups/{id}/sources` | session | counted | Blocklist sources assigned to a group | +| PUT | `/api/groups/{id}/sources` | session | counted | Replace the assignment | +| GET | `/api/blocklists` | session | counted | List blocklist sources | +| POST | `/api/blocklists` | session | counted | Add a blocklist source | +| POST | `/api/blocklists/update` | session | counted | Refresh every enabled source now | +| GET | `/api/blocklists/{id}` | session | counted | Read a blocklist source | +| PUT | `/api/blocklists/{id}` | session | counted | Update a blocklist source | +| DELETE | `/api/blocklists/{id}` | session | counted | Delete a blocklist source | +| GET | `/api/rules` | session | counted | List rules | +| POST | `/api/rules` | session | counted | Create a rule | +| GET | `/api/rules/{id}` | session | counted | Read a rule | +| PUT | `/api/rules/{id}` | session | counted | Update a rule | +| DELETE | `/api/rules/{id}` | session | counted | Delete a rule | +| GET | `/api/local-records` | session | counted | List local DNS records | +| POST | `/api/local-records` | session | counted | Create a local record | +| GET | `/api/local-records/{id}` | session | counted | Read a local record | +| PUT | `/api/local-records/{id}` | session | counted | Update a local record | +| DELETE | `/api/local-records/{id}` | session | counted | Delete a local record | +| GET | `/api/forward-zones` | session | counted | List forward zones | +| POST | `/api/forward-zones` | session | counted | Create a forward zone | +| GET | `/api/forward-zones/{id}` | session | counted | Read a forward zone | +| PUT | `/api/forward-zones/{id}` | session | counted | Update a forward zone | +| DELETE | `/api/forward-zones/{id}` | session | counted | Delete a forward zone | +| GET | `/api/clients` | session | counted | List clients | +| GET | `/api/clients/{id}` | session | counted | Read a client | +| PUT | `/api/clients/{id}` | session | counted | Rename or regroup a client | +| DELETE | `/api/clients/{id}` | session | counted | Forget a client | +| GET | `/api/client-prefixes` | session | counted | List client prefixes | +| PUT | `/api/client-prefixes` | session | counted | Replace the prefix table | +| GET | `/api/upstreams` | session | counted | List upstream resolvers | +| POST | `/api/upstreams` | session | counted | Add an upstream | +| GET | `/api/upstreams/{id}` | session | counted | Read an upstream | +| PUT | `/api/upstreams/{id}` | session | counted | Update an upstream | +| DELETE | `/api/upstreams/{id}` | session | counted | Delete an upstream | +| GET | `/api/pause` | session | counted | Read the pause state | +| POST | `/api/pause` | session | counted | Pause or resume blocking | +| GET | `/api/settings` | session | counted | Read the scalar settings | +| PUT | `/api/settings` | session | counted | Update settings | +| POST | `/api/certs/reload` | session | counted | Reload the TLS certificates from disk | + +There is no `POST /api/clients`: client rows come from DNS activity or +import, never from the API. + +## Schemas + +Request and response schemas for every operation live in the OpenAPI +document: `src/web/openapi.yaml` in the repository, or +`GET /api/openapi.yaml` from a running server. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..b321ced --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,182 @@ +# Architecture + +nxdns is a self-hosted DNS sinkhole for a household LAN: one static Zig binary +that answers DNS on UDP/TCP 53 (optionally DoH and DoT), filters against +blocklists, and serves an embedded admin SPA over HTTP. This document is a map +of the source tree and the few design rules that hold everywhere. + +## Module map + +Top-level files: + +| File | Role | +|---|---| +| `src/main.zig` | Process shell: writers, argv, dispatch, exit code. | +| `src/cli.zig` | Every command body (`run`, `check`, `export`, `import`, `version`, `help`); takes its writers as parameters so tests capture output without a process. | +| `src/app.zig` | The composition root: everything `nxdns run` owns, built in order. Nothing else constructs a collaborator. | +| `src/version.zig` | Build-time version strings. | +| `src/tests.zig` | Test root; imports each file directly. | + +Directories: + +| Directory | Role | +|---|---| +| `src/dns/` | Pure DNS wire format: header, names, questions, records, whole packets, EDNS(0)/ECS (`edns.zig`), enums and limits (`types.zig`). No allocation, no `std.Io` beyond writing to a caller's writer. | +| `src/filter/` | Blocklist pipeline: line parsers (hosts, domains, ABP), the compiler that turns a downloaded list into `.list`/`.wild` bodies, `domain_set.zig` (exact-match set, no Bloom filter), `matcher.zig` (the immutable snapshot every query evaluates against), per-group `rules.zig`, `wildcard.zig`, `safesearch.zig`, blocked-response synthesis (`response.zig`). Two I/O edges live here too: `fetcher.zig` (HTTP download) and `manager.zig` (files + DB + snapshot swap). | +| `src/local/` | Local DNS records and conditional forward zones: immutable lookup tables built once from DB rows (`records.zig`, `forward_zones.zig`), plus the plain UDP/TCP client for LAN resolvers (`forward_client.zig`). | +| `src/cache/` | `dns_cache.zig`: bounded in-memory TTL cache of whole response messages, keyed by the question. The clock arrives as a parameter. | +| `src/upstream/` | Upstream resolution: shared vocabulary and the `Client` interface (`transport.zig`), DoH client (RFC 8484), DoT client (RFC 7858), per-endpoint health/backoff (`health.zig`), and `pool.zig` — priority-ordered sequential failover that is itself a `transport.Client`, so the handler sees one interface. | +| `src/server/` | The serving side: UDP/TCP/DoH/DoT listeners, `handler.zig` (the whole query pipeline), `cert_store.zig` (refcounted TLS cert holder), `rate_limiter.zig`, `pause.zig`, `clients.zig` (client auto-materialisation), `local_tables.zig` (published local-answer tables), `query_sink.zig` (log/SSE fanout), `shutdown.zig` (SIGINT/SIGTERM → one `std.Io.Event`). | +| `src/storage/` | SQLite ownership: `db.zig` is the only file that calls SQLite, `config_schema.zig` + `migrations.zig` for `config.db`, `querylog_schema.zig` (open-or-recreate), async query `logger.zig`, `retention.zig`, `disk_monitor.zig`, and one repository per table under `repositories/`. | +| `src/config/` | The one configuration model (`model.zig`), the pure validator (`validate.zig`), `import.zig`/`export.zig` (ZON ⇄ `config.db`, byte-stable round trip), `bootstrap.zig` (first-start seeding — a policy wrapper over import). | +| `src/web/` | The admin HTTP layer: `server.zig` (listener), `router.zig`/`routes.zig`, one file per resource under `handlers/`, `auth.zig` (sessions), `sse.zig` (live query fanout), `static.zig` (embedded SPA), `metrics.zig` (Prometheus), `openapi.zig` (served contract), `api_limiter.zig`, `http_util.zig`. | +| `src/platform/` | OS and TLS edges: IP address values, the `std.log` sink (`logging.zig`), `statfs.zig` (free-space query via libc), client TLS over `std.crypto.tls` (`tls_client.zig`), server TLS over vendored Mbed TLS (`tls_server.zig`). | + +The SPA source lives in `web/` at the repo root; the build embeds its `dist/` +output as the `web_assets` module (`-Dweb-dist`). + +``` +main.zig ── cli.zig ── app.zig (composition root) + │ injects std.Io + collaborators + ┌──────────────────────┴───────────────────────┐ + │ server/ web/ upstream/ storage/ │ I/O edge + │ platform/ config/{import,export,bootstrap} │ + ├──────────────────────────────────────────────┤ + │ dns/ filter/* local/* cache/ │ pure core: + │ config/{model,validate} │ bytes in, bytes out + └──────────────────────────────────────────────┘ + * except filter/{fetcher,manager}.zig and local/forward_client.zig, + which are those directories' named I/O edges +``` + +## The purity rule + +`dns/`, `filter/`, `local/` and `cache/` take bytes and return bytes: no +`std.Io`, no sockets, no clocks hidden inside (AGENTS.md). Anything that needs +a timestamp takes it as a parameter — the cache, the rate limiter and the +pause flag all work this way, so every decision is testable without a backend. +The exceptions are deliberate and few: `filter/fetcher.zig` downloads lists, +`filter/manager.zig` owns the compiled files, the DB columns and the snapshot +swap, and `local/forward_client.zig` speaks UDP/TCP to a LAN resolver. The +decision path a query takes through these directories allocates nothing and +opens nothing. + +## std.Io injection + +There is one `std.Io` in the process. `main` receives it through +`std.process.Init` — on the standard start path this is the Threaded backend +(`std.Io.Threaded`, constructed in the stdlib's start code) — and hands it to +`cli.Runner`, from which `app.zig` threads it into every collaborator as a +parameter. No module constructs its own event loop or reads an ambient clock; +tests build their own `std.Io.Threaded` instance and pass it the same way. +The one deliberate exception is `storage/db.zig`: SQLite performs its own file +I/O through its VFS, so that file takes no `std.Io` at all. + +## Life of one query + +The pipeline in `src/server/handler.zig` (its order is PLAN §4; the stages +below are the code's actual call chain — `Handler.handle` then `Context.run`): + +``` +UDP/53 TCP/53 DoH DoT (src/server/{udp,tcp,doh,dot}_server.zig) + └──────┴──────┴────┘ + │ raw query bytes, listener-owned buffers + ▼ + handler.handle + ├─ header parse (too short / QR set → counted drop) + ├─ rate limit (over budget → REFUSED) + ├─ packet + EDNS validation (FORMERR / NOTIMP) + ├─ client tracking, group lookup (snapshot.groupForClient) + │ + ├─ local records ────────────────► authoritative answer + ├─ forward zones ─► cache ─► LAN resolver ─► answer + │ + └─ upstream path + ├─ filter snapshot evaluate ─► blocked? synthesized block reply + ├─ safe-search rewrite (per group) + ├─ cache get ─► hit? answer + ├─ upstream pool: priority failover across DoH/DoT endpoints + ├─ CNAME uncloak: walk the answer's chain, re-evaluate each target + └─ cache put + ▼ + reply bytes ─► listener sends + │ + └─► QuerySink ─► SSE hub (GET /api/queries/live) + └─► async logger ─► querylog.db +``` + +Local records win over forward zones, and both win over filtering: a name +nxdns answers itself never reaches a blocklist. Pause suspends filtering only; +local records, forward zones, cache, upstream and the query log keep running. +`handle` returns no error union — every failure is either a DNS response the +client can act on or a counted drop. The query path never waits on the +database: `QuerySink` copies the entry, the SSE hub gets it first, and one +writer task owns the `querylog.db` handle behind an `std.Io.Queue`. + +## Storage + +Two databases with opposite contracts: + +- **`config.db` is the truth.** Schema DDL is carried verbatim by + `migrations.zig` as step 1; a schema change is a new migration step, applied + inside one transaction. `nxdns import` replaces its whole content atomically + (`BEGIN IMMEDIATE`; a failed import changes nothing), `nxdns export` renders + it back as canonical ZON, byte-identical across round trips. A config file + seeds the DB exactly once at first start (`config/bootstrap.zig`); the DB is + truth thereafter. +- **`querylog.db` is expendable.** It is never migrated: its schema carries a + fingerprint derived from the DDL text, and a mismatch at open replaces the + file (`storage/querylog_schema.zig`). Retention deletes old rows daily and + periodically rewrites the file; `config.db` is walled off from that churn. + +## Web stack + +`web/server.zig` runs one `std.http.Server` per connection over its own accept +loop, with fixed pre-allocated connection slots, optionally behind TLS. The +SPA is embedded at build time: `static.zig` serves the `web_assets` module — +bytes, content type, strong ETag, and a pre-compressed `.gz` sibling where it +paid off — via a linear scan, no filesystem at runtime. `GET /api/queries/live` +is server-sent events over chunked transfer, fed by the same `QuerySink` the +logger reads. Routing is a flat table (`routes.zig`) matched linearly; the +OpenAPI YAML is hand-written, embedded and served at `GET /api/openapi.yaml`, +kept honest by tests that assert every served route appears in it. + +Auth (`web/auth.zig`): the operator's password is verified against an argon2id +PHC string (`web.password_hash` — the plaintext is hashed on import and never +stored). A successful login mints a 256-bit token carried in a cookie; the +in-memory session table holds only SHA-256 digests of tokens, compared in +constant time, capped at 32 sessions with LRU eviction. Nothing is persisted — +a restart logs everyone out. Monitoring endpoints (health, version, metrics), +the served OpenAPI contract and login itself are unauthenticated; everything +else requires the cookie, and +the API has its own token-bucket rate limiter. + +## DoH, DoT and certificate hot-reload + +`server/doh_server.zig` (RFC 8484 over HTTP/1.1 + TLS) and +`server/dot_server.zig` (RFC 7858) mirror the plain listeners' shape. Server +TLS terminates in Mbed TLS (`platform/tls_server.zig`), exposing plaintext as +`std.Io.Reader`/`std.Io.Writer`. + +Certificates hot-reload through `server/cert_store.zig`: one refcounted +`CertStore` per endpoint owns the published TLS context generation; listeners +`acquire` it per connection and `release` it when the connection ends, so a +reload never frees a context mid-handshake. Reload publishes nothing on +failure — both PEM files are read and a whole new context built before +anything swaps, and any failure leaves the old generation serving. A watcher +polls mtime+size of both files every 30 s; `POST /api/certs/reload` triggers +the same path on demand and reports the per-endpoint outcome as its payload. + +## Failure visibility + +Every failure mode must be visible, and the surface is counters, not log +lines (AGENTS.md). The handler counts every outcome — drops, FORMERR, +SERVFAIL, blocked, truncated, cache hits, paused and unfiltered queries — in +atomics; listeners count dropped datagrams instead of queueing them +unboundedly. `GET /metrics` renders all of it as Prometheus text 0.0.4, and +`GET /api/health` rolls it up for a monitor (always 200: "degraded" is a fact +about the box, not a failed request). The disk monitor classifies free space +against thresholds and gates non-essential writes; the query logger holds its +batches while writes are disallowed. `std.log` is reserved for failures +nobody else records, with upstream-error deduplication so a flapping resolver +cannot fill a disk. diff --git a/docs/config-reference.md b/docs/config-reference.md new file mode 100644 index 0000000..35b312b --- /dev/null +++ b/docs/config-reference.md @@ -0,0 +1,451 @@ +# Configuration reference + +Every section, field and collection nxdns accepts, with its type, default, +unit, validation rule and the subsystem that consumes it. Source of truth: +`src/config/model.zig` (the model and defaults), `src/config/validate.zig` +(the rules), `src/config/{bootstrap,import,export}.zig` (the lifecycle). + +## How configuration works + +The database is the truth; the file is a seed. + +- On `nxdns run`, the configuration file (default `/etc/nxdns/config.zon`, + overridable with `--config`) is imported into `config.db` **once**: only + when the file exists and the database has never been configured. On every + later start the file is ignored and the database is used as it is + (`src/config/bootstrap.zig`). A file that exists but is unreadable, + unparseable or invalid fails the start — nxdns never falls back to silent + defaults over a file the operator wrote. +- After the seed, changes are made through the web API (or `nxdns import + --force`), never by editing the file. Editing the file after first boot has + no effect. +- `nxdns export` renders the database back as canonical ZON: fixed two-line + header, every default emitted, deterministic ordering, no timestamps. The + round trip `export` → `import` → `export` is byte-identical. With `--out + FILE` the write is atomic and the file is created mode 0600, because the + export carries `web.password_hash`. +- `nxdns import FILE` replaces the whole database content in one transaction. + Without `--force` it refuses a database that already has content + (`error.DatabaseNotEmpty`); a failed import leaves the database untouched. +- `nxdns check` validates without writing. Source selection order: an + explicit `--config FILE` wins; otherwise `config.db` in the data directory + if it exists; otherwise the default config file path if it exists; + otherwise "nothing to check" (exit 2). `check` also verifies TLS + certificate/key readability and, from the command line, probes each enabled + upstream with a real query. + +Absent fields keep their defaults — in the file and in the database. A +settings key stored in the database that the running binary does not know is +warned about and ignored, never an error, so a downgrade cannot brick a +config database. + +## What is not in the file + +Storage paths are process arguments, not configuration: + +- `--data-dir DIR` (default `/var/lib/nxdns`) holds `config.db` and + `querylog.db`. The directory is created mode 0700; both databases and their + WAL sidecars are forced to mode 0600. +- `--config FILE` (default `/etc/nxdns/config.zon`) names the seed file. +- `--web-dev DIR` (`run` only) serves the web interface from a directory + instead of the embedded assets. + +## File format + +The file is ZON: a top-level anonymous struct whose fields are the sections +and collections below. Enum values are written as ZON enum literals +(`.level = .err`, `.response = .nxdomain`). Strings are double-quoted. The +file may be at most 4 MiB (`ConfigTooLarge` beyond that). A syntax error is +reported with its line and column. + +One serialization quirk: the log level `error` is the Zig keyword `error`, +so the ZON/model tag is `.err` while the database stores the operator-facing +word `"error"`. `err` is not accepted as database text, and `error` is not a +ZON tag — the file says `.err`, the settings API says `"error"`. + +## Scalar sections + +The "Key" column is the settings key as stored in the database +(`section.field`); in the file the same field lives inside its section block, +e.g. `.dns = .{ .port = 53 }`. + +### upstream + +Timeouts for talking to upstream resolvers. + +| Key | Type | Default | Unit | Validation | Consumed by | +|---|---|---|---|---|---| +| `upstream.read_timeout_ms` | u32 | 3000 | ms | 100–120000 | read deadline on conditional-forward-zone exchanges (`src/server/handler.zig` via `app.zig`) | +| `upstream.total_timeout_ms` | u32 | 5000 | ms | 100–120000, and at least `read_timeout_ms` | per-query budget of the upstream pool (`src/upstream/pool.zig`) — the whole attempt including the connect; also the `nxdns check` probe deadline | + +### dns + +The plain DNS listener (UDP + TCP). + +| Key | Type | Default | Unit | Validation | Consumed by | +|---|---|---|---|---|---| +| `dns.bind_ipv4` | string | `"0.0.0.0"` | IP address | must parse as an IPv4 address | UDP/TCP listener bind (`src/app.zig`) | +| `dns.bind_ipv6` | string | `"::"` | IP address | must parse as an IPv6 address | UDP/TCP listener bind (`src/app.zig`) | +| `dns.port` | u16 | 53 | port | 1–65535 | UDP/TCP listener port | +| `dns.rate_limit` | u32 | 1000 | queries per window | at least 1 | per-client DNS rate limiter (`src/server/rate_limiter.zig`) | +| `dns.rate_window_seconds` | u32 | 60 | seconds | 1–3600 | window of the same limiter | + +### blocking + +What a blocked query gets back. + +| Key | Type | Default | Unit | Validation | Consumed by | +|---|---|---|---|---|---| +| `blocking.response` | enum `.zero` \| `.nxdomain` | `.zero` | — | one of the two tags | blocked-response synthesis (`src/filter/response.zig`): `.zero` answers 0.0.0.0 / `::`, `.nxdomain` answers NXDOMAIN | +| `blocking.ttl` | u32 | 5 | seconds | at most 86400 (0 allowed) | TTL on the synthesized block answer | + +### cache + +| Key | Type | Default | Unit | Validation | Consumed by | +|---|---|---|---|---|---| +| `cache.size` | u32 | 10000 | entries | none; `0` disables caching (put short-circuits — `src/cache/dns_cache.zig` test "a cache of zero entries stores nothing") | DNS answer cache capacity (`src/cache/dns_cache.zig`) | +| `cache.negative_ttl_max` | u32 | 3600 | seconds | at most 86400 | cap on cached negative answers; 0 disables negative caching | + +### web + +The web interface and REST API. + +| Key | Type | Default | Unit | Validation | Consumed by | +|---|---|---|---|---|---| +| `web.enabled` | bool | true | — | — | gates the whole web stack: server, sessions, SSE hub, API limiter (`src/app.zig`) | +| `web.bind` | string | `"0.0.0.0"` | IP address | must parse as an IP address | web listener bind (`src/web/server.zig`) | +| `web.port` | u16 | 8080 | port | 1–65535 | web listener port | +| `web.password` | string | `""` | — | must not be set together with `web.password_hash` | operator input only — see "Authentication" below; never stored, never a settings key | +| `web.password_hash` | string | `""` | — | — | argon2id PHC string verified at login (`src/web/auth.zig`); `""` disables authentication | +| `web.session_ttl_hours` | u16 | 24 | hours | at least 1 | session expiry and cookie Max-Age (`src/web/auth.zig`) | +| `web.api_rate_limit_per_min` | u32 | 300 | requests per minute | at least 1 | API token-bucket limiter (`src/web/api_limiter.zig`) | +| `web.api_localhost_exempt` | bool | true | — | — | loopback requests skip the API limiter | +| `web.sse_max_connections_per_ip` | u16 | 3 | connections | at least 1 | cap on concurrent SSE streams per client IP | + +### doh_server + +The DNS-over-HTTPS listener (server side, for clients on the LAN). + +| Key | Type | Default | Unit | Validation | Consumed by | +|---|---|---|---|---|---| +| `doh_server.enabled` | bool | false | — | — | gates the DoH listener (`src/server/doh_server.zig`) | +| `doh_server.bind` | string | `"0.0.0.0"` | IP address | must parse as an IP address | DoH listener bind | +| `doh_server.port` | u16 | 443 | port | 1–65535 | DoH listener port | +| `doh_server.cert_path` | string | `"/etc/nxdns/cert.pem"` | path | non-empty when enabled | certificate loaded into the hot-reloading `CertStore`; readability is checked by `nxdns check`, not the validator | +| `doh_server.key_path` | string | `"/etc/nxdns/key.pem"` | path | non-empty when enabled | private key for the same; `nxdns check` warns when it is readable beyond its owner | + +### dot_server + +The DNS-over-TLS listener. Same shape as `doh_server`; only the default port +differs. + +| Key | Type | Default | Unit | Validation | Consumed by | +|---|---|---|---|---|---| +| `dot_server.enabled` | bool | false | — | — | gates the DoT listener (`src/server/dot_server.zig`) | +| `dot_server.bind` | string | `"0.0.0.0"` | IP address | must parse as an IP address | DoT listener bind | +| `dot_server.port` | u16 | 853 | port | 1–65535 | DoT listener port | +| `dot_server.cert_path` | string | `"/etc/nxdns/cert.pem"` | path | non-empty when enabled | certificate, shared `CertStore` with hot reload | +| `dot_server.key_path` | string | `"/etc/nxdns/key.pem"` | path | non-empty when enabled | private key for the same | + +### edns + +| Key | Type | Default | Unit | Validation | Consumed by | +|---|---|---|---|---|---| +| `edns.ecs_mode` | enum `.strip` \| `.forward` | `.strip` | — | one of the two tags | EDNS Client Subnet handling in the query path (`src/server/handler.zig`, `src/dns/edns.zig`): `.strip` removes the client subnet before forwarding, `.forward` passes it through | + +### logging + +Process log and query log behavior. + +| Key | Type | Default | Unit | Validation | Consumed by | +|---|---|---|---|---|---| +| `logging.level` | enum `.err` \| `.warn` \| `.info` \| `.debug` | `.info` | — | one of the four tags; stored as `"error"`/`"warn"`/`"info"`/`"debug"` | log threshold (`src/platform/logging.zig`) | +| `logging.retention_days` | u16 | 30 | days | at least 1 | query-log pruning cutoff (`src/storage/retention.zig`) and the client tracker's last-seen cutoff (`src/server/clients.zig`) | +| `logging.query_log_buffer_max` | u32 | 10000 | entries | at least 1 | in-memory query-log ring size and backpressure cap (`src/storage/logger.zig`) | +| `logging.hide_domains` | bool | false | — | — | query log stores a hidden marker instead of the domain | +| `logging.hide_client_ips` | bool | false | — | — | query log stores a hidden marker instead of the client IP | +| `logging.output` | enum `.stderr` \| `.syslog` \| `.file` | `.stderr` | — | one of the three tags | log sink selection (`src/platform/logging.zig`); `.stderr` and `.syslog` both write to stderr (journald captures it), `.file` rotates | +| `logging.file_path` | string | `"/var/log/nxdns/nxdns.log"` | path | when `output` is `.file`: non-empty absolute path | rotating log file; its directory also feeds the disk monitor. The binary does not create the directory | +| `logging.max_size_mb` | u32 | 50 | MiB | at least 1 | rotation trigger for the log file | +| `logging.max_files` | u8 | 5 | files | at least 1 | rotated generations kept | + +### disk + +Free-space thresholds for the data directory. When free space falls below +them, the query-log writer, client tracker and blocklist scheduler are +throttled (`src/storage/disk_monitor.zig`). + +| Key | Type | Default | Unit | Validation | Consumed by | +|---|---|---|---|---|---| +| `disk.min_free_mb` | u32 | 200 | MiB | at least 1, and not above `warn_free_mb` | `critical` threshold | +| `disk.warn_free_mb` | u32 | 500 | MiB | at least 1 | `warn` threshold | + +### blocklist_update + +| Key | Type | Default | Unit | Validation | Consumed by | +|---|---|---|---|---|---| +| `blocklist_update.enabled` | bool | true | — | — | blocklist refresh scheduler (`src/filter/manager.zig`); when false only the startup pass runs | +| `blocklist_update.interval_hours` | u16 | 24 | hours | at least 1 | sleep between refresh passes and the per-source staleness test | + +## Collections + +Collections are ZON lists of structs. Fields without a default are required. +Runtime columns (first/last seen timestamps, per-source download counters) +are deliberately not part of the model: import sets timestamps to the import +time, and export omits them, which is what keeps the round trip byte-stable. + +### groups + +Client groups. A group named `default` is **required**; every client not +assigned elsewhere lands in it, and import guarantees it keeps database id 1. + +| Field | Type | Default | Validation | +|---|---|---|---| +| `name` | string | required | non-empty, unique | +| `safe_search` | bool | false | — | + +Consumed by the filter engine (`src/filter/matcher.zig`); `safe_search` +triggers the safe-search rewrite in the query path. + +### upstreams + +Upstream resolvers. **At least one enabled upstream is required.** + +| Field | Type | Default | Validation | +|---|---|---|---| +| `url` | string | required | `https://` (DoH) or `tls://` (DoT) endpoint; unique | +| `priority` | i32 | 100 | — (lower is tried first) | +| `enabled` | bool | true | — | +| `tls_name` | string | `""` | DoT only — a `tls_name` on an `https://` upstream is an error; must be a valid domain name | + +Consumed by the upstream pool (`src/upstream/pool.zig`): entries are sorted +by ascending priority and tried in order with failover. `tls_name` sets SNI +and the certificate verification name for a `tls://` upstream written as an +IP literal; empty means "verify by the URL host" +(`src/upstream/dot_client.zig`). + +### clients + +Known clients with a fixed group assignment. + +| Field | Type | Default | Validation | +|---|---|---|---| +| `ip` | string | required | IP address; unique after canonicalization (`FD00::1` and `fd00:0:0:0:0:0:0:1` collide) | +| `name` | string | `""` | — (display only, never read by the resolver) | +| `group` | string | `"default"` | must name a declared group | + +Consumed by the filter engine's exact IP → group lookup +(`src/filter/matcher.zig`). + +### client_prefixes + +Group assignment by CIDR prefix, for clients without an exact entry. + +| Field | Type | Default | Validation | +|---|---|---|---| +| `prefix` | string | required | CIDR prefix (`192.168.2.0/24`, `fd00:abcd::/48`); unique after canonicalization | +| `group` | string | `"default"` | must name a declared group | +| `priority` | i32 | 100 | — (ties on match are broken by lower priority) | + +Consumed by the filter engine's longest-prefix match +(`src/filter/matcher.zig`). + +### blocklist_sources + +Downloadable blocklists. + +| Field | Type | Default | Validation | +|---|---|---|---| +| `url` | string | required | `http://` or `https://` URL with a host; unique | +| `name` | string | required | non-empty | +| `enabled` | bool | true | — | +| `is_suggested` | bool | false | — (web UI hint only, never read by the resolver) | + +Consumed by the blocklist manager (`src/filter/manager.zig`): downloaded by +the fetcher, compiled into domain sets; a disabled source is neither +downloaded nor loaded. + +### group_sources + +Which groups consult which blocklist sources. + +| Field | Type | Default | Validation | +|---|---|---|---| +| `group` | string | required | must name a declared group | +| `source_url` | string | required | must name a declared blocklist source's `url`; the (group, source_url) pair is unique | + +Consumed by the filter engine when assembling each group's compiled domain +sets (`src/filter/matcher.zig`). A link to a disabled source is silently +skipped. + +### rules + +Per-group allow/block overrides, checked before the blocklists. + +| Field | Type | Default | Validation | +|---|---|---|---| +| `group` | string | required | must name a declared group | +| `pattern` | string | required | see below | +| `kind` | enum `.exact` \| `.wildcard` | required | — | +| `action` | enum `.allow` \| `.block` | required | — | + +Pattern rules: an `.exact` pattern is a plain domain name and may not contain +`*`; a `.wildcard` pattern must contain at least one label that is exactly +`*` (`*.tracker.example`, or `*` alone), and every other label must be a +legal DNS label. `ads*.example` is not a valid wildcard. + +Consumed by the filter engine's rule sets (`src/filter/rules.zig`). + +### local_records + +Local DNS answers, served without touching any upstream. + +| Field | Type | Default | Validation | +|---|---|---|---| +| `name` | string | required | valid domain name | +| `rtype` | enum `.a` \| `.aaaa` \| `.cname` | required | stored as `A`/`AAAA`/`CNAME` | +| `value` | string | required | IPv4 address for `.a`, IPv6 for `.aaaa`, domain name for `.cname` | +| `ttl` | u32 | 300 | 1–604800 seconds | + +The (name, rtype, value) triple is unique. Consumed by the local records +table in the query path (`src/local/records.zig`). + +### forward_zones + +Zones resolved by a specific resolver instead of the configured upstreams — +for LAN or corporate domains. + +| Field | Type | Default | Validation | +|---|---|---|---| +| `zone` | string | required | valid domain name; unique | +| `resolver` | string | required | `udp://IP:port` or `tcp://IP:port`; the host must be an IP literal and the port is mandatory | + +The resolver host must be an IP literal because resolving the resolver's own +name would be a bootstrap problem. Matching is longest suffix +(`src/local/forward_zones.zig`); the exchange is UDP-then-TCP +(`src/local/forward_client.zig`) with `upstream.read_timeout_ms` as the read +deadline. + +## Authentication: web.password vs web.password_hash + +Exactly one of the two may be set; setting both is refused +(`PasswordAndHashBothSet` — ambiguity in a security setting). + +- `web.password` is operator input only. At import time it is hashed with + argon2id (OWASP parameters: t=2, m=19 MiB, p=1, PHC encoding) into + `web.password_hash` and discarded. It is never stored — there is no + `web.password` settings row, and `nxdns export` always writes + `.password = ""`. +- `web.password_hash` is the stored argon2id PHC string. Supplying it + directly (for example from a previous export) is how a backup restores + authentication without knowing the password. +- Both empty disables web authentication entirely. + +Because the export carries the hash and re-importing an exported file takes +the "password is empty" branch, the export/import round trip preserves the +hash byte-for-byte. + +## Minimal working example + +The smallest file that passes validation: a `default` group and one enabled +upstream. Everything else keeps its default. + +```zon +.{ + .groups = .{ .{ .name = "default" } }, + .upstreams = .{ .{ .url = "https://dns.quad9.net/dns-query" } }, +} +``` + +## Fuller annotated example + +```zon +.{ + // Plain DNS on the standard port, rate-limited per client. + .dns = .{ + .bind_ipv4 = "0.0.0.0", + .bind_ipv6 = "::", + .port = 53, + .rate_limit = 1000, + .rate_window_seconds = 60, + }, + + // Blocked queries answer 0.0.0.0 / :: with a 5 second TTL. + .blocking = .{ .response = .zero, .ttl = 5 }, + + .cache = .{ .size = 10000, .negative_ttl_max = 3600 }, + + // Web UI on 8080. The password is hashed at import and never stored; + // leave .password_hash out when setting .password (they are exclusive). + .web = .{ + .enabled = true, + .port = 8080, + .password = "correct horse battery staple", + .session_ttl_hours = 24, + }, + + // Serve DoT to the LAN. The key file should be mode 0600. + .dot_server = .{ + .enabled = true, + .port = 853, + .cert_path = "/etc/nxdns/cert.pem", + .key_path = "/etc/nxdns/key.pem", + }, + + // Strip EDNS Client Subnet before forwarding (the default). + .edns = .{ .ecs_mode = .strip }, + + // ".err" in the file; the settings API shows it as "error". + .logging = .{ .level = .err, .retention_days = 14 }, + + .blocklist_update = .{ .enabled = true, .interval_hours = 24 }, + + // "default" is mandatory. Additional groups get their own rules, + // blocklists and safe-search flag. + .groups = .{ + .{ .name = "default" }, + .{ .name = "kids", .safe_search = true }, + }, + + // Lower priority is tried first; the second entry is a failover. + // tls_name is needed when a tls:// upstream is written as an IP + // literal, so certificate verification has a DNS name to match. + .upstreams = .{ + .{ .url = "https://dns.quad9.net/dns-query", .priority = 10 }, + .{ .url = "tls://9.9.9.9:853", .priority = 20, .tls_name = "dns.quad9.net" }, + }, + + // Exact client assignments win over prefixes. + .clients = .{ + .{ .ip = "192.168.1.20", .name = "tablet", .group = "kids" }, + }, + .client_prefixes = .{ + .{ .prefix = "192.168.2.0/24", .group = "kids" }, + }, + + .blocklist_sources = .{ + .{ .url = "https://lists.example/ads.txt", .name = "ads" }, + }, + .group_sources = .{ + .{ .group = "kids", .source_url = "https://lists.example/ads.txt" }, + }, + + // Overrides beat blocklists. Wildcards need a label that is exactly "*". + .rules = .{ + .{ .group = "default", .pattern = "allowed.example", .kind = .exact, .action = .allow }, + .{ .group = "kids", .pattern = "*.tracker.example", .kind = .wildcard, .action = .block }, + }, + + // Local names, answered without any upstream. + .local_records = .{ + .{ .name = "nas.lan", .rtype = .a, .value = "192.168.1.5" }, + .{ .name = "www.lan", .rtype = .cname, .value = "nas.lan" }, + }, + + // Everything under corp.lan goes to the LAN resolver directly. + .forward_zones = .{ + .{ .zone = "corp.lan", .resolver = "udp://192.168.1.1:53" }, + }, +} +``` + diff --git a/docs/docs.zig b/docs/docs.zig new file mode 100644 index 0000000..f340b58 --- /dev/null +++ b/docs/docs.zig @@ -0,0 +1,7 @@ +//! Embeds the documentation files the drift tests guard. Module root for the +//! `docs_files` anonymous import (test builds only) — @embedFile paths resolve +//! relative to this file. + +pub const api_md = @embedFile("api.md"); +pub const config_reference_md = @embedFile("config-reference.md"); +pub const operator_md = @embedFile("operator.md"); diff --git a/docs/operator.md b/docs/operator.md new file mode 100644 index 0000000..20b1397 --- /dev/null +++ b/docs/operator.md @@ -0,0 +1,418 @@ +# Operating nxdns + +How to install, configure, back up, upgrade and troubleshoot an nxdns server. +For the meaning of every configuration field, see +[config-reference.md](config-reference.md); for the HTTP API, +[api.md](api.md). + +## Install: systemd + +nxdns ships as one static musl binary. Build it (see +[Building](#building-the-binary)) or take it from CI, then: + +```sh +# 1. The binary. +install -m 0755 nxdns /usr/local/bin/nxdns + +# 2. The service user. Static, not DynamicUser: the TLS key for DoH/DoT +# must be chown-able to a stable uid. +install -m 0644 deploy/systemd/sysusers.conf /usr/lib/sysusers.d/nxdns.conf +systemd-sysusers + +# 3. The unit. +install -m 0644 deploy/systemd/nxdns.service /etc/systemd/system/nxdns.service +systemctl daemon-reload +``` + +Do not create directories by hand. The unit's `StateDirectory=nxdns`, +`LogsDirectory=nxdns` and `ConfigurationDirectory=nxdns` make systemd create +`/var/lib/nxdns` (mode 0700, owned by `nxdns`), `/var/log/nxdns` and +`/etc/nxdns` on first start. + +Write a seed configuration to `/etc/nxdns/config.zon`. The minimum that +starts is one group named `default` and one enabled upstream: + +```zon +.{ + .groups = .{ .{ .name = "default" } }, + .upstreams = .{ .{ .url = "https://cloudflare-dns.com/dns-query" } }, + .web = .{ .password = "choose-a-real-password" }, +} +``` + +Then: + +```sh +systemctl enable --now nxdns +journalctl -u nxdns -f +``` + +nxdns logs to stderr by default and systemd captures that into the journal; +nothing else needs configuring for logs. Port 53 needs +`CAP_NET_BIND_SERVICE`, which the unit grants via `AmbientCapabilities`. + +If port 53 is already taken, see +[Port 53 conflicts](#port-53-is-taken-systemd-resolved). + +### Building the binary + +Requires Zig 0.16.0 and Node.js 24 (for the web UI). From the repository +root: + +```sh +(cd web && npm ci && npm run build) +zig build cross -Dweb-dist=web/dist -Doptimize=ReleaseSafe +``` + +This produces static binaries for both deploy targets: + +- `zig-out/cross/x86_64-linux-musl/nxdns` +- `zig-out/cross/aarch64-linux-musl/nxdns` + +### Raspberry Pi 5 recipe + +The Pi 5 is aarch64. Build on any machine (the cross build needs no +toolchain beyond Zig itself), copy the binary over, then follow the systemd +steps above on the Pi: + +```sh +(cd web && npm ci && npm run build) +zig build cross -Dweb-dist=web/dist -Doptimize=ReleaseSafe +scp zig-out/cross/aarch64-linux-musl/nxdns pi:/tmp/nxdns +scp deploy/systemd/nxdns.service deploy/systemd/sysusers.conf pi:/tmp/ + +# on the Pi, as root: +install -m 0755 /tmp/nxdns /usr/local/bin/nxdns +install -m 0644 /tmp/sysusers.conf /usr/lib/sysusers.d/nxdns.conf +systemd-sysusers +install -m 0644 /tmp/nxdns.service /etc/systemd/system/nxdns.service +systemctl daemon-reload +# write /etc/nxdns/config.zon, then: +systemctl enable --now nxdns +``` + +The binary is statically linked against musl; it has no runtime +dependencies on the Pi. + +## Install: Docker + +The image is built from a binary you compile first; the Dockerfile only +assembles the filesystem. From the repository root: + +```sh +(cd web && npm ci && npm run build) +zig build cross -Dweb-dist=web/dist -Doptimize=ReleaseSafe +docker build -t nxdns -f deploy/docker/Dockerfile . +``` + +or, with compose (which runs the same build with the repository root as +context): + +```sh +cd deploy/docker +docker compose build +``` + +The Dockerfile maps buildx's `TARGETARCH` onto the cross-target directory, +so `docker buildx build --platform linux/arm64` produces the aarch64 image +from the same `zig-out/cross` tree. + +Before the first `docker compose up`, create the seed configuration the +compose file bind-mounts read-only at `/etc/nxdns`: + +```sh +cd deploy/docker +mkdir -p etc-nxdns +$EDITOR etc-nxdns/config.zon # the same minimal seed as the systemd path +``` + +The seed must be readable by uid 65532, the fixed container user; the bind +mount is read-only, so the container cannot adjust permissions itself. +World-readable (0644) is fine when the seed carries no secret; if it holds +`web.password` or `web.password_hash` (a restored export), restrict it instead: +`chown 65532:65532 etc-nxdns/config.zon && chmod 0600 etc-nxdns/config.zon`. + +Without a valid seed — at least a `default` group and one enabled +upstream — the container exits with code 2, because a fresh volume holds an +empty database and an empty database has no upstream to forward to. + +The compose file publishes 53/udp, 53/tcp and 8080, keeps the data in a +named volume mounted at `/var/lib/nxdns`, and sets the per-network-namespace +sysctl `net.ipv4.ip_unprivileged_port_start=0` so the nonroot user +(uid 65532) can bind port 53. Uncomment the 443/853 port mappings when you +enable the DoH or DoT listener. + +Do not point the host's `/etc/resolv.conf` at the nxdns container. The +container resolves its upstream DoH/DoT hostnames through the host's DNS +configuration; pointing that at nxdns itself makes the container's own +lookups depend on the service they are trying to start. + +### Publishing the image to a private registry + +There is deliberately no registry push in CI — credentials and registry +choice are an infrastructure decision, not this repository's. To publish +manually, log in to your registry, tag the local image with the registry's +name, and push: `docker login `, then +`docker tag nxdns //nxdns:`, then +`docker push //nxdns:`. The same works for a +self-hosted Gitea registry such as git.mial.net. + +## First boot and configuration semantics + +The ZON file at `/etc/nxdns/config.zon` (or `--config`) seeds the database +exactly once: + +- **No file:** normal steady state; the database is used as it is. +- **File present, database empty:** the file is imported. A file that is + unreadable, unparseable or invalid is an error (exit 2, every problem + printed) — nxdns never falls back to silent defaults over a file you + wrote. +- **File present, database already configured:** the file is ignored. The + database is the truth from the first successful seed onward. + +After the first boot, editing `config.zon` changes nothing. Change the +configuration through the web UI, the REST API, or the export→edit→import +cycle: + +```sh +nxdns export --out config-backup.zon +$EDITOR config-backup.zon +systemctl stop nxdns +nxdns import config-backup.zon --force +systemctl start nxdns +``` + +`import` without `--force` refuses a database that already has content +(exit 2), so a plain `import` can never clobber a configured server by +accident. + +## Authentication setup + +Set `web.password` in the seed file (or in a file you `import`). At import +time it is hashed with argon2id into `web.password_hash` and discarded; the +plaintext is never stored anywhere. `nxdns export` always writes +`.password = ""` and carries the hash instead, so an exported file +re-imports without knowing the password. Setting both `password` and +`password_hash` in one file is an error (exit 2). To change the password, +export, set `.password` to the new value, clear `.password_hash` to `""`, +and import with `--force`. + +## TLS for the DoH/DoT listeners + +Both listeners are disabled by default. To enable one, set +`doh_server.enabled` / `dot_server.enabled` and point `cert_path` and +`key_path` at a PEM certificate chain and key, conventionally under +`/etc/nxdns`. Ownership depends on how you deploy. + +Under systemd, the service runs as the `nxdns` user: + +```sh +chown nxdns:nxdns /etc/nxdns/cert.pem /etc/nxdns/key.pem +chmod 0644 /etc/nxdns/cert.pem +chmod 0600 /etc/nxdns/key.pem +``` + +Under Docker, the container runs as uid 65532 (fixed in the image) and +`/etc/nxdns` is a read-only bind mount, so the container cannot fix +permissions itself — the host-side files must already be readable by that +uid. It has no name on the host or in the scratch image, so chown it +numerically: + +```sh +cd deploy/docker +chown 65532:65532 etc-nxdns/cert.pem etc-nxdns/key.pem +chmod 0644 etc-nxdns/cert.pem +chmod 0600 etc-nxdns/key.pem +``` + +The key must be readable by the user nxdns runs as and only by its owner: +`nxdns check` prints a WARN for a key with any group or other permission +bits, and a FAIL (exit 2) for a cert or key the user cannot read. A +certificate that fails to load at boot while its listener is enabled exits 2. + +Renewals need no restart. A watcher polls both files every 30 seconds and +swaps the new pair in atomically; in-flight connections finish on the old +certificate. To pick up a renewal immediately — for example from a certbot +deploy hook — call `POST /api/certs/reload` (session-authenticated; see +[api.md](api.md)). A reload that fails to parse leaves the old certificate +serving and reports the error. + +## Backup, restore and upgrades + +**Backup** is one command against a stopped or running server: + +```sh +nxdns export --out /some/backup/nxdns-config.zon +``` + +The write is atomic (temp file + rename) and mode 0600, because the file +carries `web.password_hash` — treat backups as secrets. Without `--out` the +export goes to stdout, where file permissions are your redirect's problem. +The query log is deliberately not part of the backup; it is expendable +history. + +**Restore** onto a fresh data directory or over an existing one: + +```sh +nxdns import /some/backup/nxdns-config.zon --force +``` + +**Upgrades:** install the new binary, restart the service. Schema +migrations run automatically at startup (and before `check`, `export` and +`import`), so a database one schema version behind is upgraded in place. +There is no downgrade path; take an export before upgrading. + +## Data directory layout + +Everything lives under the data directory (default `/var/lib/nxdns`, +override with `--data-dir`), mode 0700: + +| Path | What it is | +| --- | --- | +| `config.db` (+ `-wal`, `-shm`) | The configuration database — the single source of truth, including `web.password_hash`. Mode 0600. Back it up via `nxdns export`. | +| `querylog.db` (+ `-wal`, `-shm`) | The query log. Mode 0600 — it records every domain every client asked for. Expendable: if it is missing or unusable it is recreated empty. | +| `blocklists/` | Compiled blocklist snapshots, two files per source: `.list` (exact domains) and `.wild` (wildcards). `.raw.tmp` / `.list.tmp` / `.wild.tmp` files are transient refresh state. | + +## CLI reference + +``` +nxdns [options] +``` + +Flags take both spellings: `--flag value` and `--flag=value`. + +### `run` + +Serves DNS until SIGINT or SIGTERM. + +| Flag | Meaning | +| --- | --- | +| `--data-dir DIR` | Data directory (default `/var/lib/nxdns`). Created at 0700 if missing. | +| `--config FILE` | Seed configuration file (default `/etc/nxdns/config.zon`). Read only when the database is empty. | +| `--web-dev DIR` | Serve the web interface from DIR instead of the embedded assets, with no cache headers. Development only. | + +### `check` + +Validates the configuration and probes the upstreams. Exit 0 when clean, +2 when it found problems, and it always reports every problem, not just the +first. What it checks, in order: + +1. Which source to check (see [source selection](#check-source-selection)). +2. Full validation — the same rules `import` enforces. +3. For each enabled DoH/DoT listener: cert and key are readable (FAIL if + not), key permissions are owner-only (WARN if not). +4. A live probe: one real A query for `example.com` through every enabled + upstream, using the same failover machinery the server uses. A FAIL line + names the upstream and the concrete cause. This probe leaves the machine, + so `check` needs network access to pass. + +| Flag | Meaning | +| --- | --- | +| `--data-dir DIR` | Data directory to look for `config.db` in. | +| `--config FILE` | Check this file instead of the database. | + +#### check source selection + +- `--config FILE` given explicitly: check that file, nothing else. +- Otherwise, if `/config.db` exists: check the database — the + right default, since the database is the truth on a configured server. +- Otherwise, if the default config file exists: check it. +- Otherwise: "nothing to check", exit 2. + +The first line of output always names which source was checked. + +### `export` + +Writes the configuration as ZON to stdout, or atomically at mode 0600 to +`--out FILE`. `--out` paths are relative to the shell's working directory. + +| Flag | Meaning | +| --- | --- | +| `--data-dir DIR` | Data directory holding `config.db`. | +| `--out FILE` | Write to FILE instead of stdout. | + +### `import FILE` + +Validates FILE and replaces the configuration with it. Prints every +validation problem on failure. Refuses a non-empty database without +`--force`. + +| Flag | Meaning | +| --- | --- | +| `--data-dir DIR` | Data directory holding `config.db` (created if missing). | +| `--force` | Replace a database that already has content. | + +### `version` + +Prints the nxdns version, git commit and Zig version. + +### `help` + +Prints usage. `--help` and `-h` do the same. + +## Exit codes + +| Code | Meaning | +| --- | --- | +| 0 | Success. | +| 1 | Runtime failure — I/O, database, out of memory. | +| 2 | A configuration problem the operator can fix, or a `check` that found one. | +| 64 | Usage error — unknown command or flag, missing argument. | + +## Troubleshooting + +### The service exits with code 2 + +Exit 2 always means a configuration you can fix; `nxdns run` prints the +cause and suggests `nxdns check`, which shows the full list. The usual +causes: + +- Empty database and no seed file, or a seed file with no `default` group + or no enabled upstream. On a fresh install this means `config.zon` is + missing, in the wrong place, or invalid. +- A seed or imported file that fails validation — every problem is printed + with its field name. +- `dns.bind_ipv4` / `dns.bind_ipv6` is not an IP address, or a rate limit + is zero (possible only in a hand-edited database; `import` refuses both). +- A DoH/DoT listener is enabled but its certificate or key is unreadable or + unparseable at boot. +- `import` into a non-empty database without `--force`. + +### Port 53 is taken (systemd-resolved) + +On most systemd distributions, `systemd-resolved` owns a stub listener on +`127.0.0.53:53`, and on some setups binds `0.0.0.0:53`. Turn the stub off +and keep resolved for the host's own lookups: + +```sh +mkdir -p /etc/systemd/resolved.conf.d +printf '[Resolve]\nDNSStubListener=no\n' > /etc/systemd/resolved.conf.d/nxdns.conf +systemctl restart systemd-resolved +``` + +If `/etc/resolv.conf` is a symlink to the stub +(`/run/systemd/resolve/stub-resolv.conf`), repoint it at +`/run/systemd/resolve/resolv.conf` so the host still resolves. Do not point +the host running nxdns at nxdns itself if that host is where nxdns resolves +its upstream DoH/DoT hostnames — that is a bootstrap cycle. + +### Disk is filling up + +The disk monitor samples free space and database sizes once a minute and +classifies the state against `disk.warn_free_mb` and `disk.min_free_mb`. +Below the warn threshold it logs the transition; below `min_free_mb` it +gates every non-essential write: the query logger holds its batches, the +client tracker stops persisting, and the blocklist scheduler skips its +refresh passes. DNS keeps answering throughout — resolution never degrades +because the disk is full. The state and the size gauges are visible on +`/metrics` and in the web UI. Recover space (lower +`logging.retention_days`, or delete `querylog.db` with the service +stopped) and writes resume on the next sample. + +### Blocklists are not filtering + +Serving starts even when no blocklist snapshot loads — a household loses +more from DNS that refuses to start than from a window of unfiltered +answers. The startup journal line says either `blocklist generation N` or +`unfiltered (no blocklist snapshot)`. If it says unfiltered, check the +journal for the download or compile warning that preceded it. diff --git a/specs/milestone-11.md b/specs/milestone-11.md new file mode 100644 index 0000000..49d523a --- /dev/null +++ b/specs/milestone-11.md @@ -0,0 +1,273 @@ +# Milestone 11: packaging, ops and docs (PLAN Phase 10) + +Goal: systemd unit, Dockerfile + compose, and the four docs (operator, architecture, +config-reference, API) — the documented deployment must work end-to-end; docs are +drift-guarded where a guard is cheap and honest. + +## Rulings (binding) + +1. **Layout.** `deploy/systemd/nxdns.service` + `deploy/systemd/sysusers.conf`; + `deploy/docker/{Dockerfile,compose.yaml,.dockerignore}`; `docs/{operator.md, + architecture.md,config-reference.md,api.md}`; `README.md` at the root (the repo has + none; a portfolio repo needs a front door — short: what, why, quickstart, doc links). + PLAN.md:236 sketches docs/ subdirectories; single files need no subdirectories. + +2. **API docs = hand-written `docs/api.md` + drift test.** No renderer is vendored + (redoc/scalar are exactly the dependency liability AGENTS.md refuses), and a + build-time YAML parser for rendering is scope the yaml does not justify — the yaml + itself is already served unauthenticated at `GET /api/openapi.yaml` (routes.zig:49) + and is the exhaustive contract. `docs/api.md` gives human-readable orientation: + auth model (cookie session, login flow), rate limiting, error envelope, SSE + semantics, then one line per operation (method, path, auth, one-sentence purpose) + and a pointer to the yaml for schemas. A drift test asserts every served route + appears textually in api.md (mirror of openapi.zig:34's guard). This satisfies + m8 ruling 3's deferred "docs/api rendering" as the engineering call: rendered = + readable, guarded, in-repo; not = a vendored JS bundle. + +3. **Docs drift guards.** New `src/docs_drift_test.zig` (ORCHESTRATOR-owned, written + after the doc sessions land): (a) every route in `router.routes` appears in + docs/api.md; (b) every settings key from `model.toSettings` (the 44 keys) appears + in docs/config-reference.md; (c) every CLI subcommand name appears in + docs/operator.md. Docs embedded via a `docs_files` anonymous import added in + build.zig (test_fixtures pattern, build.zig:61). Guards are textual-containment + only — cheap, zero false authority. + +4. **systemd unit.** `Type=simple` (no forking, shutdown.zig:35 handles SIGTERM), + `ExecStart=/usr/local/bin/nxdns run`, stderr → journald (logging.zig:301 already + states this; `logging.output=stderr` stays the default). Static system user `nxdns` + via `deploy/systemd/sysusers.conf` (`u nxdns - "nxdns DNS sinkhole"`), NOT + DynamicUser — the TLS key must be chown-able to a stable uid ("TLS keys readable by + service user only", PLAN §19). `StateDirectory=nxdns` (0700 matches cli.zig:226), + `LogsDirectory=nxdns` (covers logging.output=file; the binary does not create the + directory, logging.zig:502), `ConfigurationDirectory=nxdns`. + `AmbientCapabilities=CAP_NET_BIND_SERVICE` + `CapabilityBoundingSet=` the same + (port 53; 443/853 covered by the same cap). Hardening: `NoNewPrivileges=yes`, + `ProtectSystem=strict`, `ProtectHome=yes`, `PrivateTmp=yes`, `PrivateDevices=yes`, + `ProtectKernelTunables/Modules/Logs=yes`, `ProtectControlGroups=yes`, + `ProtectClock=yes`, `ProtectHostname=yes`, `ProtectProc=invisible`, + `RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX`, `RestrictNamespaces=yes`, + `RestrictRealtime=yes`, `RestrictSUIDSGID=yes`, `LockPersonality=yes`, + `MemoryDenyWriteExecute=yes` (static Zig binary, no JIT), `UMask=0077`, + `SystemCallFilter=@system-service`, `SystemCallArchitectures=native`, + `Restart=on-failure`, `RestartSec=2`. No `ReadWritePaths` beyond what + StateDirectory/LogsDirectory grant. Validate with `systemd-analyze verify` if the + build host has it; report honestly if not. + +5. **Docker.** Multi-stage: builder stage only stages `ca-certificates` (upstream + TLS verification rescans the system CA bundle, tls_client.zig:216 — a scratch + image without a bundle breaks every DoH/DoT upstream); final `FROM scratch` with + the static musl binary, `/etc/ssl/certs/ca-certificates.crt`, a nonroot numeric + `USER 65532:65532`, `VOLUME /var/lib/nxdns`, `EXPOSE 53/udp 53/tcp 8080 443 853`, + `ENTRYPOINT ["/nxdns"]`, `CMD ["run"]`. The binary is NOT built inside the + Dockerfile (the repo builds it with zig; the Dockerfile COPYes + `zig-out/cross/$TARGETARCH-…/nxdns` via a build arg or buildx TARGETARCH mapping — + keep it working for both arches). compose.yaml: ports 53:53/udp+tcp and 8080:8080 + (443/853 commented), bind-mount `./etc-nxdns:/etc/nxdns:ro`, named volume for + `/var/lib/nxdns`, `sysctls: net.ipv4.ip_unprivileged_port_start=0` so the nonroot + user binds 53 (per-netns sysctl; documented), `restart: unless-stopped`. First + boot needs a seeded `/etc/nxdns/config.zon` with a `default` group + one enabled + upstream or the container exits 2 (bootstrap.zig:38, app.zig:93) — operator.md and + a compose comment both say so. Do NOT point the host's resolv.conf at nxdns + itself for the container's own lookups. + +6. **CI.** One added job `docker` in ci.yml: after building the x86_64 exe + (ReleaseSafe, with the SPA dist like the cross job), `docker build` the image and + run a container smoke (seed a minimal config.zon; `nxdns version` + boot + one + `dig`-equivalent via the test client or `curl` on 8080/api/health; SIGTERM 0). + No registry push — no publish step exists anywhere in this repo or the infra + repo's CI, and registry credentials are an infra decision outside this repo. + Manual publishing to git.mial.net stays possible and is documented in operator.md + in one paragraph. + +7. **Docs content contracts.** + - operator.md: install (systemd path and docker path, both complete), first boot + + config.zon seeding semantics (file seeds DB once, DB is truth thereafter, + bootstrap.zig:38), auth setup (`web.password` hashed on import, never stored, + export writes ""), TLS cert/key provisioning + 0600 expectations + the reload + API/watcher, backup/restore = `nxdns export`/`import --force` (+ the 0600 export + mode and why), upgrades (schema migration = install + restart, PLAN §20.11), + data-dir layout table, exit codes (0/1/2/64, cli.zig:35), CLI reference (all six + subcommands + flags), troubleshooting (exit 2 causes, `nxdns check` semantics + incl. source-selection order cli.zig:511, disk-full degradation, port 53 + conflicts with systemd-resolved — include the disable recipe). + - architecture.md: module map (the src/ inventory), the purity rule (dns/, filter/, + local/, cache/ take bytes, no Io — AGENTS.md), std.Io injection + Threaded + backend, data flow for one query (listener → handler → filter/cache/local → + upstream → sink/logger), storage split (config.db truth / querylog.db expendable), + web stack (std.http over TLS optional, SPA embedded via web_assets, SSE), cert + hot-reload design (refcounted CertStore), failure-visibility doctrine (counters + + /metrics over log spam). Concise — a map, not a novel. + - config-reference.md: complete — every section/field with type, default, unit, + validation range, and which subsystem consumes it; collections with required + fields; DB-vs-file truth explanation; the `web.password`/`password_hash` + exclusivity; `logging.level=.err` serializes as "error" (model.zig:154). The + explorer inventory in this milestone's research is the skeleton; verify against + model.zig/validate.zig while writing, do not trust the summary blindly. + - api.md: per ruling 2. + - README.md: ≤120 lines; what nxdns is, feature list (honest, shipping features + only), quickstart (docker compose path), build-from-source (zig build, node for + the SPA), doc links, license note if a LICENSE exists (do not invent one). + +8. **No new runtime code.** This milestone adds zero behavior to the binary. The only + src/ change is the orchestrator's docs_drift_test.zig + its build wiring. If a doc + session finds a bug while documenting, it REPORTS it (no fix); the orchestrator + triages. + +9. **Pi 5 end-to-end**: the exit criterion runs on hardware this environment does not + have. The deliverable here is: both suites green, docker smoke green on x86_64, + `systemd-analyze verify` clean (or honestly reported unavailable), aarch64 binary + built and statically verified (existing cross job). The operator doc's Pi 5 recipe + is written to be executed by the user; the spec records this boundary explicitly. + +## Sessions + +U1, U3, U4, U5 parallel; U2 after U1 (documents the artifacts U1 produces); +orchestrator wiring (ruling 3) after U3+U5. + +## Session U1: deploy artifacts + CI + +Owns `deploy/systemd/nxdns.service`, `deploy/systemd/sysusers.conf`, +`deploy/docker/{Dockerfile,compose.yaml,.dockerignore}`, `.gitea/workflows/ci.yml` +(one added job). Rulings 4, 5, 6. Verify: `systemd-analyze verify` (or report +unavailable), local `docker build` + container smoke if the docker daemon is +reachable (report honestly either way), `zig build test` untouched-green. + +## Session U2: operator.md + README.md (after U1) + +Owns `docs/operator.md`, `README.md`. Rulings 7 (operator + README). Reads U1's +artifacts and the runtime/CLI facts from the code (verify against src/cli.zig, +src/app.zig, src/config/bootstrap.zig — not from memory). + +## Session U3: config-reference.md + +Owns `docs/config-reference.md`. Ruling 7. Source of truth: src/config/model.zig + +validate.zig + import/export/bootstrap. Every field, no sampling. + +## Session U4: architecture.md + +Owns `docs/architecture.md`. Ruling 7. Reads module headers; no deep dives needed +beyond what the doc claims. + +## Session U5: api.md + +Owns `docs/api.md`. Rulings 2, 7. Source of truth: src/web/routes.zig (the served +table: method, path, auth, limiter) + openapi.yaml summaries + auth.zig/sse.zig for +the auth and SSE prose. Every route, no sampling. + +## As built + +**U1** delivered per rulings 4-6 with accepted deviations: `StateDirectoryMode=0700` +(systemd defaults 0755; the binary cannot tighten a pre-existing directory) and +`User=nxdns`/`Group=nxdns` added to the unit; the Dockerfile's builder stage also maps +buildx TARGETARCH → cross-target dir and pre-chowns `/var/lib/nxdns` to 65532 (a named +volume seeded from a root-owned image dir would be unwritable on first boot); compose +gained a `build:` block; `deploy/docker/.dockerignore` is documentation-grade under +BuildKit (only a root `.dockerignore` or `Dockerfile.dockerignore` is honored — the +file's header says so). Verified: `systemd-analyze verify` clean modulo the off-host +ExecStart path (an ExecStart=/bin/true copy verifies exit 0); full local docker build + +smoke passed (binds 53 as uid 65532, /api/health ok, SIGTERM exit 0). The CI docker +job probes both 127.0.0.1 and the container IP to survive either runner topology. +Compose expects the operator-created seed at `deploy/docker/etc-nxdns/config.zon` +(minimal: a `default` group + one enabled upstream), else exit 2. + +**U2** delivered docs/operator.md (397 lines; systemd + docker + Pi 5 recipes, seeding +semantics, auth, TLS, backup/restore, data-dir table, full CLI reference, exit codes, +troubleshooting incl. the systemd-resolved DNSStubListener recipe) and README.md +(72 lines, no license section — no LICENSE exists). All facts source-verified. + +**U3** delivered docs/config-reference.md (12 scalar sections, 9 collections, DB-vs-file +truth model, auth section, minimal + annotated examples) and surfaced five code +discrepancies during writing (see fix wave below). + +**U4** delivered docs/architecture.md (module map from the //! headers, purity rule +with the honest exceptions, life-of-one-query pipeline verified against handler.zig, +storage split, web stack, CertStore design, failure-visibility doctrine). Reported one +stale comment (logging.zig:17 cited a moved cli.zig line) — orchestrator fixed the +comment to cite start.zig:724 via std.process.Init. + +**U5** delivered docs/api.md: all 56 operations (matches router.routes.len), auth / +rate-limit / SSE prose, error envelope, openapi.yaml pointer. No code-vs-yaml +discrepancies found. + +**Orchestrator wiring (ruling 3)**: docs/docs.zig (embeds api.md, config-reference.md, +operator.md), `docs_files` anonymous import on the test module in build.zig, +src/docs_drift_test.zig with three containment guards (routes → api.md; toSettings +keys → config-reference.md; the six subcommand names → operator.md), tests.zig import. + +**Fix wave (orchestrator-triaged; ruling 8's no-runtime-code rule lifted for exactly +these)** — U3's five discrepancies, triaged with stdlib evidence: +1. `runtime.io_backend` DELETED end to end (model, settings handler + view, openapi, + web types/SettingsPage/settingsDiff + tests, docs). Nothing consumed it — main uses + init.io (stdlib Threaded, start.zig:724), and 0.16's std.Io.Evented has stubbed + networking (Uring.zig netConnectIp → error.NetworkDown), so PLAN decision E's + "io_uring via flag" is not deliverable at this tag. Re-add when std ships working + evented net. Old DB rows warn-and-ignore via fromSettings' unknown-key path. +2. `upstream.connect_timeout_ms` DELETED. No call site; the pool races the whole + attempt against total_timeout (app.zig sets it from totalTimeout); Threaded panics + on IpAddress.ConnectOptions.timeout != .none; std.http.Client has no knob. The + validate cross-check is now total >= read only. +3. `cache.size` KEPT: 0 is clean documented disabled behavior (put short-circuits; + in-file test "a cache of zero entries stores nothing"). Doc row corrected. +4. `dns.bind_ipv6` TIGHTENED: checkBind generalized to a BindFamily enum; dns.bind_ipv6 + requires an IPv6 literal (an IPv4 wildcard there made the v4 bind AddressInUse get + swallowed with a false "dual-stack" log — silent IPv6 loss). web/TLS binds stay .any. +5. doh/dot `readTimeout(.{})` sites KEPT: they are test fixtures; the real idle budget + is the ruled 10s Options default. The doc claim was wrong and was removed. +Settings key counts after deletion: toSettings emits 43 (incl. web.password_hash); +the API-visible restart-required set is 42 (was 44). + +## Review (Codex, as built) + +Three rounds on one thread; round 3 returned "No findings." + +Round 1 (5 important): stale-DB bind_ipv6 rows bypassed the new validate check at boot +→ app.zig parseBind now enforces the IP family on both dns binds (BadBindAddress, +exit 2, remedy in the message; the v4 side had the symmetric hole); app.zig's tests +were not collected by tests.zig at all — the import line was added and the new test +runs. operator.md's TLS recipe assumed the nxdns host user → Docker path now chowns +65532:65532 numerically host-side (read-only bind mount). PLAN.md still promised the +io_uring flag and connect_timeout_ms → synced (Io bullet records the drop with stdlib +evidence; decision E row; example config). Drift guards were maskable → api.md guard +anchors the full "| METHOD | `pattern` |" row per operation; operator.md guard anchors +the "### `name" reference headings. + +Round 2 (1 important, 1 minor): seed-permission guidance covered only web.password → +now web.password or web.password_hash (a restored export); PLAN.md's "stubs all +networking" overstated 0.16's Uring — now names the stubbed operations precisely. + +Final gates: plain 1171/1284 passed, 113 skipped (integration-gated), 0 failed; +integration 1280/1284, 4 skipped (live-network by design), 0 failed; cross ReleaseSafe +with the SPA dist 18/18; web suite 121/121 with format/lint/typecheck clean. + +## Module layout (new) + +deploy/systemd/{nxdns.service,sysusers.conf}, deploy/docker/{Dockerfile,compose.yaml, +.dockerignore}, docs/{operator,architecture,config-reference,api}.md, README.md, +src/docs_drift_test.zig (orchestrator). + +## File ownership + +U1 deploy/* + ci.yml; U2 docs/operator.md + README.md; U3 docs/config-reference.md; +U4 docs/architecture.md; U5 docs/api.md; orchestrator src/docs_drift_test.zig, +build.zig (docs_files module), src/tests.zig. + +## Acceptance (milestone complete) + +- [ ] All files in the module layout exist with the ruling-7 content contracts met. +- [ ] Docs drift tests pass: route coverage in api.md, settings-key coverage in + config-reference.md, subcommand coverage in operator.md. +- [ ] CI docker job builds the image and the container smoke passes (in CI; locally + if the daemon is available). +- [ ] `systemd-analyze verify deploy/systemd/nxdns.service` clean, or its + unavailability recorded in the U1 report. +- [ ] Both suites 0 failed; cross ReleaseSafe with the SPA dist green. +- [ ] No runtime-behavior changes (git diff over src/ shows only docs_drift_test.zig + + wiring). + +## Anti-requirements + +- No vendored API-doc renderer (redoc/scalar/swagger-ui), no YAML parser. +- No registry publish step; no k3s manifests (the infra repo owns deployment there). +- No SIGHUP/reload feature, no env-var config, no new CLI flags — document what + exists; report gaps instead of filling them. +- No LICENSE invention; no badges or marketing prose in README. diff --git a/src/app.zig b/src/app.zig index a0dfabc..c0c1893 100644 --- a/src/app.zig +++ b/src/app.zig @@ -458,8 +458,8 @@ fn serve(r: cli.Runner, args: cli.RunArgs) !u8 { .reload_fn = reloadManager, }; - const v6_bind = parseBind(r, cfg.dns.bind_ipv6, cfg.dns.port, "dns.bind_ipv6") catch |err| return err; - const v4_bind = parseBind(r, cfg.dns.bind_ipv4, cfg.dns.port, "dns.bind_ipv4") catch |err| return err; + const v6_bind = parseBind(r, cfg.dns.bind_ipv6, cfg.dns.port, "dns.bind_ipv6", .ip6) catch |err| return err; + const v4_bind = parseBind(r, cfg.dns.bind_ipv4, cfg.dns.port, "dns.bind_ipv4", .ip4) catch |err| return err; // IPv6 first, and the order is load-bearing — see `Listeners`. var udp6: ?udp_server.UdpServer = udp_server.UdpServer.bind(gpa, io, v6_bind, &h, .{}) catch |err| bound: { @@ -826,11 +826,66 @@ const Listeners = struct { tcp4: ?net.IpAddress, }; -fn parseBind(r: cli.Runner, text: []const u8, port: u16, field: []const u8) !net.IpAddress { - return net.IpAddress.parse(text, port) catch { +const BindFamily = enum { ip4, ip6 }; + +/// `config/validate.checkBind` enforces the same family rule on import, check +/// and settings PUT — but not on a config.db written before the rule existed, +/// and `serve` loads that DB without re-validating. Boot is the last seam: a +/// cross-family literal here would bind the wrong family's socket and make the +/// real one fail with AddressInUse, silently losing a family. +fn parseBind( + r: cli.Runner, + text: []const u8, + port: u16, + field: []const u8, + family: BindFamily, +) !net.IpAddress { + const addr = net.IpAddress.parse(text, port) catch { r.err.print("{s}: '{s}' is not an IP address\n", .{ field, text }) catch {}; return error.BadBindAddress; }; + const matches = switch (addr) { + .ip4 => family == .ip4, + .ip6 => family == .ip6, + }; + if (!matches) { + const digit: u8 = if (family == .ip4) '4' else '6'; + r.err.print( + "{s}: '{s}' is not an IPv{c} address; re-import the configuration or correct it with a settings PUT\n", + .{ field, text, digit }, + ) catch {}; + return error.BadBindAddress; + } + return addr; +} + +test "parseBind refuses a bind address of the wrong family" { + var out_buf: [8]u8 = undefined; + var err_buf: [256]u8 = undefined; + var out: Writer = .fixed(&out_buf); + var err_writer: Writer = .fixed(&err_buf); + const r: cli.Runner = .{ + .io = std.testing.io, + .gpa = std.testing.allocator, + .out = &out, + .err = &err_writer, + }; + + _ = try parseBind(r, "0.0.0.0", 53, "dns.bind_ipv4", .ip4); + _ = try parseBind(r, "::", 53, "dns.bind_ipv6", .ip6); + + try std.testing.expectError( + error.BadBindAddress, + parseBind(r, "0.0.0.0", 53, "dns.bind_ipv6", .ip6), + ); + try std.testing.expectError( + error.BadBindAddress, + parseBind(r, "::", 53, "dns.bind_ipv4", .ip4), + ); + + const printed = err_writer.buffered(); + try std.testing.expect(std.mem.containsAtLeast(u8, printed, 1, "is not an IPv6 address")); + try std.testing.expect(std.mem.containsAtLeast(u8, printed, 1, "is not an IPv4 address")); } fn reportBind(r: cli.Runner, which: []const u8, addr: net.IpAddress, err: anyerror) anyerror { diff --git a/src/config/model.zig b/src/config/model.zig index 2370343..6f2f8ff 100644 --- a/src/config/model.zig +++ b/src/config/model.zig @@ -18,7 +18,6 @@ const std = @import("std"); const Allocator = std.mem.Allocator; pub const Config = struct { - runtime: Runtime = .{}, upstream: Upstream = .{}, dns: Dns = .{}, blocking: Blocking = .{}, @@ -42,28 +41,7 @@ pub const Config = struct { forward_zones: []const ForwardZone = &.{}, }; -pub const IoBackend = enum { - threaded, - evented, - - pub fn toDb(self: IoBackend) []const u8 { - return switch (self) { - .threaded => "threaded", - .evented => "evented", - }; - } - - pub fn fromDb(text: []const u8) ?IoBackend { - if (std.mem.eql(u8, text, "threaded")) return .threaded; - if (std.mem.eql(u8, text, "evented")) return .evented; - return null; - } -}; - -pub const Runtime = struct { io_backend: IoBackend = .threaded }; - pub const Upstream = struct { - connect_timeout_ms: u32 = 2000, read_timeout_ms: u32 = 3000, total_timeout_ms: u32 = 5000, }; @@ -318,10 +296,6 @@ comptime { assertFits(u32, 1024 * 1024, u64); // MiB conversions } -pub fn connectTimeout(u: Upstream) std.Io.Duration { - return .{ .nanoseconds = @as(i96, u.connect_timeout_ms) * std.time.ns_per_ms }; -} - pub fn readTimeout(u: Upstream) std.Io.Duration { return .{ .nanoseconds = @as(i96, u.read_timeout_ms) * std.time.ns_per_ms }; } @@ -506,8 +480,6 @@ const expected_keys = [_][]const u8{ "logging.output", "logging.query_log_buffer_max", "logging.retention_days", - "runtime.io_backend", - "upstream.connect_timeout_ms", "upstream.read_timeout_ms", "upstream.total_timeout_ms", "web.api_localhost_exempt", @@ -558,8 +530,7 @@ test "toSettings never emits web.password" { test "toSettings and fromSettings round-trip a non-default config" { const gpa = testing.allocator; const original: Config = .{ - .runtime = .{ .io_backend = .evented }, - .upstream = .{ .connect_timeout_ms = 111, .read_timeout_ms = 222, .total_timeout_ms = 333 }, + .upstream = .{ .read_timeout_ms = 222, .total_timeout_ms = 333 }, .dns = .{ .bind_ipv4 = "127.0.0.1", .bind_ipv6 = "::1", @@ -697,7 +668,6 @@ fn expectEnumRoundTrip(comptime E: type) !void { } test "every toDb and fromDb enum pair round-trips over all tags" { - try expectEnumRoundTrip(IoBackend); try expectEnumRoundTrip(BlockResponse); try expectEnumRoundTrip(EcsMode); try expectEnumRoundTrip(LogLevel); @@ -715,10 +685,6 @@ test "RecordType stores the uppercase DDL spelling" { } test "unit conversions" { - try testing.expectEqual( - @as(i96, 2000) * std.time.ns_per_ms, - connectTimeout(.{}).nanoseconds, - ); try testing.expectEqual( @as(i96, 3000) * std.time.ns_per_ms, readTimeout(.{}).nanoseconds, @@ -737,13 +703,12 @@ test "unit conversions" { test "unit conversions at the field maximum do not overflow" { const max_upstream: Upstream = .{ - .connect_timeout_ms = std.math.maxInt(u32), .read_timeout_ms = std.math.maxInt(u32), .total_timeout_ms = std.math.maxInt(u32), }; try testing.expectEqual( @as(i96, std.math.maxInt(u32)) * std.time.ns_per_ms, - connectTimeout(max_upstream).nanoseconds, + readTimeout(max_upstream).nanoseconds, ); try testing.expectEqual( @as(i64, std.math.maxInt(u16)) * 3600, diff --git a/src/config/validate.zig b/src/config/validate.zig index 56dffd9..fcbf101 100644 --- a/src/config/validate.zig +++ b/src/config/validate.zig @@ -199,21 +199,20 @@ const max_rate_window_seconds = 3_600; fn checkScalars(cfg: Config, diags: *Diagnostics) error{OutOfMemory}!void { const up = cfg.upstream; - try checkTimeout(diags, up.connect_timeout_ms, "upstream.connect_timeout_ms"); try checkTimeout(diags, up.read_timeout_ms, "upstream.read_timeout_ms"); try checkTimeout(diags, up.total_timeout_ms, "upstream.total_timeout_ms"); - if (up.total_timeout_ms < up.connect_timeout_ms or up.total_timeout_ms < up.read_timeout_ms) { + if (up.total_timeout_ms < up.read_timeout_ms) { try diags.add( error.BadTimeout, "upstream.total_timeout_ms", .{}, - "total budget {d}ms is below connect {d}ms or read {d}ms", - .{ up.total_timeout_ms, up.connect_timeout_ms, up.read_timeout_ms }, + "total budget {d}ms is below read {d}ms", + .{ up.total_timeout_ms, up.read_timeout_ms }, ); } - try checkBind(diags, cfg.dns.bind_ipv4, "dns.bind_ipv4", true); - try checkBind(diags, cfg.dns.bind_ipv6, "dns.bind_ipv6", false); + try checkBind(diags, cfg.dns.bind_ipv4, "dns.bind_ipv4", .ip4); + try checkBind(diags, cfg.dns.bind_ipv6, "dns.bind_ipv6", .ip6); try checkPort(diags, cfg.dns.port, "dns.port"); if (cfg.dns.rate_limit < 1) { try diags.add(error.BadRateLimit, "dns.rate_limit", .{}, "must be at least 1", .{}); @@ -248,7 +247,7 @@ fn checkScalars(cfg: Config, diags: *Diagnostics) error{OutOfMemory}!void { ); } - try checkBind(diags, cfg.web.bind, "web.bind", false); + try checkBind(diags, cfg.web.bind, "web.bind", .any); try checkPort(diags, cfg.web.port, "web.port"); if (cfg.web.password.len != 0 and cfg.web.password_hash.len != 0) { try diags.add( @@ -339,18 +338,30 @@ fn checkTimeout(diags: *Diagnostics, value: u32, comptime path: []const u8) erro } } +const BindFamily = enum { ip4, ip6, any }; + +/// `dns.bind_ipv4` and `dns.bind_ipv6` each name one socket of the dual-stack +/// pair, so each must be a literal of its own family: an IPv4 wildcard in +/// `bind_ipv6` would bind IPv4 as the "v6" socket and make the real IPv4 bind +/// fail with AddressInUse — the IPv6 service silently disappears. fn checkBind( diags: *Diagnostics, text: []const u8, comptime path: []const u8, - comptime require_ip4: bool, + comptime family: BindFamily, ) error{OutOfMemory}!void { const addr = NetAddress.parse(text) catch { try diags.add(error.BadBindAddress, path, .{}, "'{s}' is not an IP address", .{text}); return; }; - if (require_ip4 and std.meta.activeTag(addr) != NetAddress.ip4) { - try diags.add(error.BadBindAddress, path, .{}, "'{s}' is not an IPv4 address", .{text}); + switch (family) { + .ip4 => if (std.meta.activeTag(addr) != NetAddress.ip4) { + try diags.add(error.BadBindAddress, path, .{}, "'{s}' is not an IPv4 address", .{text}); + }, + .ip6 => if (std.meta.activeTag(addr) != NetAddress.ip6) { + try diags.add(error.BadBindAddress, path, .{}, "'{s}' is not an IPv6 address", .{text}); + }, + .any => {}, } } @@ -359,7 +370,7 @@ fn checkTlsEndpoint( endpoint: model.TlsEndpoint, comptime section: []const u8, ) error{OutOfMemory}!void { - try checkBind(diags, endpoint.bind, section ++ ".bind", false); + try checkBind(diags, endpoint.bind, section ++ ".bind", .any); try checkPort(diags, endpoint.port, section ++ ".port"); if (!endpoint.enabled) return; // Readability of the files is `nxdns check`'s job, not the pure validator's. @@ -1162,11 +1173,11 @@ test "error.BadPort" { test "error.BadTimeout" { var cfg = baseConfig(); - cfg.upstream.connect_timeout_ms = 10; - try expectProblem(cfg, error.BadTimeout, "upstream.connect_timeout_ms"); + cfg.upstream.read_timeout_ms = 10; + try expectProblem(cfg, error.BadTimeout, "upstream.read_timeout_ms"); var budget = baseConfig(); - budget.upstream = .{ .connect_timeout_ms = 4000, .read_timeout_ms = 4000, .total_timeout_ms = 1000 }; + budget.upstream = .{ .read_timeout_ms = 4000, .total_timeout_ms = 1000 }; try expectProblem(budget, error.BadTimeout, "upstream.total_timeout_ms"); } @@ -1214,6 +1225,12 @@ test "error.BadBindAddress" { try expectProblem(web, error.BadBindAddress, "web.bind"); } +test "error.BadBindAddress on an IPv4 literal in dns.bind_ipv6" { + var cfg = baseConfig(); + cfg.dns.bind_ipv6 = "0.0.0.0"; + try expectProblem(cfg, error.BadBindAddress, "dns.bind_ipv6"); +} + test "error.MissingCertPath" { var cfg = baseConfig(); cfg.doh_server = .{ .enabled = true, .cert_path = "" }; diff --git a/src/docs_drift_test.zig b/src/docs_drift_test.zig new file mode 100644 index 0000000..cdd61f0 --- /dev/null +++ b/src/docs_drift_test.zig @@ -0,0 +1,57 @@ +//! Textual-containment guards that keep the hand-written docs honest +//! (milestone-11 ruling 3). They assert presence, not correctness — the same +//! contract as openapi.zig's route guard. + +const std = @import("std"); +const docs = @import("docs_files"); +const routes = @import("web/routes.zig"); +const model = @import("config/model.zig"); + +test "every served operation has its own table row in docs/api.md" { + const gpa = std.testing.allocator; + for (routes.table) |route| { + // Matches one full method + path cell pair ("| GET | `/api/groups` |"), + // so neither a same-path sibling method nor a longer-path prefix can + // satisfy the check for a missing operation. + const needle = try std.fmt.allocPrint(gpa, "| {s} | `{s}` |", .{ + @tagName(route.method), route.pattern, + }); + defer gpa.free(needle); + if (std.mem.indexOf(u8, docs.api_md, needle) == null) { + std.debug.print("operation row missing from docs/api.md: {s}\n", .{needle}); + return error.OperationMissingFromApiDoc; + } + } +} + +test "every settings key appears in docs/config-reference.md" { + const gpa = std.testing.allocator; + var pairs: std.ArrayList(model.SettingPair) = .empty; + defer { + model.freeSettings(gpa, pairs.items); + pairs.deinit(gpa); + } + try model.toSettings(.{}, gpa, &pairs); + for (pairs.items) |pair| { + if (std.mem.indexOf(u8, docs.config_reference_md, pair.key) == null) { + std.debug.print("settings key missing from docs/config-reference.md: {s}\n", .{pair.key}); + return error.SettingsKeyMissingFromConfigDoc; + } + } +} + +test "every cli subcommand has its own reference heading in docs/operator.md" { + const gpa = std.testing.allocator; + const subcommands = [_][]const u8{ "run", "check", "export", "import", "version", "help" }; + for (subcommands) |name| { + // Anchors on the reference-section heading ("### `import FILE`" starts + // with "### `import"), so prose mentions elsewhere cannot mask a + // removed command section. + const needle = try std.fmt.allocPrint(gpa, "### `{s}", .{name}); + defer gpa.free(needle); + if (std.mem.indexOf(u8, docs.operator_md, needle) == null) { + std.debug.print("subcommand heading missing from docs/operator.md: {s}\n", .{needle}); + return error.SubcommandMissingFromOperatorDoc; + } + } +} diff --git a/src/platform/logging.zig b/src/platform/logging.zig index 20ea8dd..febb75f 100644 --- a/src/platform/logging.zig +++ b/src/platform/logging.zig @@ -14,8 +14,9 @@ //! need no `Io` because they read `std.Options.debug_io` (debug.zig:283), they //! are documented as recursive (debug.zig:263-270), and `Io/Threaded.zig` //! implements that recursion per OS thread (Threaded.zig:13787-13796). nxdns -//! runs a `std.Io.Threaded` instance (cli.zig:793), so one task is one thread -//! and the recursion holds. Taking it across the file writes as well keeps the +//! runs on the `std.Io.Threaded` instance the stdlib start code constructs +//! (start.zig:724, handed to `main` via `std.process.Init`), so one task is +//! one thread and the recursion holds. Taking it across the file writes as well keeps the //! file path and the stderr fallback path from interleaving with each other, //! with `std.Progress`, or with a panic dump. //! diff --git a/src/tests.zig b/src/tests.zig index 751334c..7782593 100644 --- a/src/tests.zig +++ b/src/tests.zig @@ -2,6 +2,7 @@ const std = @import("std"); comptime { _ = @import("main.zig"); + _ = @import("app.zig"); _ = @import("version.zig"); _ = @import("dns/types.zig"); _ = @import("dns/header.zig"); @@ -112,6 +113,7 @@ comptime { _ = @import("server/dot_server.zig"); _ = @import("server/doh_server.zig"); _ = @import("web/handlers/certs.zig"); + _ = @import("docs_drift_test.zig"); } extern fn sqlite3_libversion() [*:0]const u8; diff --git a/src/web/handlers/settings.zig b/src/web/handlers/settings.zig index d9b243c..bd0c2f5 100644 --- a/src/web/handlers/settings.zig +++ b/src/web/handlers/settings.zig @@ -189,7 +189,6 @@ fn newPassword(patch: Patch) ?[]const u8 { // the read shape // --------------------------------------------------------------------------- -const RuntimeView = struct { io_backend: []const u8 }; const BlockingView = struct { response: []const u8, ttl: u32 }; const EdnsView = struct { ecs_mode: []const u8 }; @@ -219,7 +218,6 @@ const WebView = struct { }; pub const View = struct { - runtime: RuntimeView, upstream: model.Upstream, dns: model.Dns, blocking: BlockingView, @@ -235,7 +233,6 @@ pub const View = struct { pub fn view(cfg: model.Config) View { return .{ - .runtime = .{ .io_backend = cfg.runtime.io_backend.toDb() }, .upstream = cfg.upstream, .dns = cfg.dns, .blocking = .{ .response = cfg.blocking.response.toDb(), .ttl = cfg.blocking.ttl }, @@ -469,13 +466,11 @@ test "the read shape spells every enum the way the database does" { .logging = .{ .level = .err, .output = .file }, .blocking = .{ .response = .nxdomain }, .edns = .{ .ecs_mode = .forward }, - .runtime = .{ .io_backend = .evented }, }); try testing.expectEqualStrings("error", rendered.logging.level); try testing.expectEqualStrings("file", rendered.logging.output); try testing.expectEqualStrings("nxdomain", rendered.blocking.response); try testing.expectEqualStrings("forward", rendered.edns.ecs_mode); - try testing.expectEqualStrings("evented", rendered.runtime.io_backend); try testing.expect(!rendered.web.auth_enabled); const with_password = view(.{ .web = .{ .password_hash = "$argon2id$v=19$m=19456,t=2,p=1$a$b" } }); diff --git a/src/web/openapi.yaml b/src/web/openapi.yaml index e33cf8a..c3f18d5 100644 --- a/src/web/openapi.yaml +++ b/src/web/openapi.yaml @@ -2088,20 +2088,12 @@ components: Settings: type: object - required: [runtime, upstream, dns, blocking, cache, web, doh_server, dot_server, edns, logging, disk, blocklist_update] + required: [upstream, dns, blocking, cache, web, doh_server, dot_server, edns, logging, disk, blocklist_update] properties: - runtime: - type: object - required: [io_backend] - properties: - io_backend: - type: string - enum: [threaded, evented] upstream: type: object - required: [connect_timeout_ms, read_timeout_ms, total_timeout_ms] + required: [read_timeout_ms, total_timeout_ms] properties: - connect_timeout_ms: { type: integer } read_timeout_ms: { type: integer } total_timeout_ms: { type: integer } dns: @@ -2213,14 +2205,9 @@ components: the write-only `web.password`. `web.password_hash` is rejected as an unknown field. properties: - runtime: - type: object - properties: - io_backend: { type: string } upstream: type: object properties: - connect_timeout_ms: { type: integer } read_timeout_ms: { type: integer } total_timeout_ms: { type: integer } dns: diff --git a/src/web/web_integration_test.zig b/src/web/web_integration_test.zig index 5c7eab7..df3c2f7 100644 --- a/src/web/web_integration_test.zig +++ b/src/web/web_integration_test.zig @@ -525,8 +525,7 @@ const TlsEndpointView = struct { /// response never carries `web.password` or `web.password_hash` (ruling 16). const SettingsView = struct { settings: struct { - runtime: struct { io_backend: []const u8 }, - upstream: struct { connect_timeout_ms: u32, read_timeout_ms: u32, total_timeout_ms: u32 }, + upstream: struct { read_timeout_ms: u32, total_timeout_ms: u32 }, dns: struct { bind_ipv4: []const u8, bind_ipv6: []const u8, diff --git a/web/src/features/settings/SettingsPage.test.tsx b/web/src/features/settings/SettingsPage.test.tsx index cfb0e12..afec37f 100644 --- a/web/src/features/settings/SettingsPage.test.tsx +++ b/web/src/features/settings/SettingsPage.test.tsx @@ -10,8 +10,7 @@ import type { Settings, SettingsPatch } from "@/lib/types"; function baseSettings(): Settings { return { - runtime: { io_backend: "threaded" }, - upstream: { connect_timeout_ms: 2000, read_timeout_ms: 3000, total_timeout_ms: 5000 }, + upstream: { read_timeout_ms: 3000, total_timeout_ms: 5000 }, dns: { bind_ipv4: "0.0.0.0", bind_ipv6: "::", port: 53, rate_limit: 100, rate_window_seconds: 60 }, blocking: { response: "zero", ttl: 300 }, cache: { size: 10000, negative_ttl_max: 300 }, diff --git a/web/src/features/settings/SettingsPage.tsx b/web/src/features/settings/SettingsPage.tsx index 59a9861..c1726f7 100644 --- a/web/src/features/settings/SettingsPage.tsx +++ b/web/src/features/settings/SettingsPage.tsx @@ -33,12 +33,10 @@ const TLS_FIELDS: readonly FieldDef[] = [ ]; const SECTIONS: readonly SectionDef[] = [ - { section: "runtime", title: "Runtime", fields: [{ key: "io_backend", kind: ["threaded", "evented"] }] }, { section: "upstream", title: "Upstream", fields: [ - { key: "connect_timeout_ms", kind: "number" }, { key: "read_timeout_ms", kind: "number" }, { key: "total_timeout_ms", kind: "number" }, ], diff --git a/web/src/lib/settingsDiff.test.ts b/web/src/lib/settingsDiff.test.ts index c4d7369..c514fd7 100644 --- a/web/src/lib/settingsDiff.test.ts +++ b/web/src/lib/settingsDiff.test.ts @@ -3,8 +3,7 @@ import type { Settings } from "@/lib/types"; function baseSettings(): Settings { return { - runtime: { io_backend: "threaded" }, - upstream: { connect_timeout_ms: 2000, read_timeout_ms: 3000, total_timeout_ms: 5000 }, + upstream: { read_timeout_ms: 3000, total_timeout_ms: 5000 }, dns: { bind_ipv4: "0.0.0.0", bind_ipv6: "::", port: 53, rate_limit: 100, rate_window_seconds: 60 }, blocking: { response: "zero", ttl: 300 }, cache: { size: 10000, negative_ttl_max: 300 }, diff --git a/web/src/lib/settingsDiff.ts b/web/src/lib/settingsDiff.ts index ef34628..4c9e0c3 100644 --- a/web/src/lib/settingsDiff.ts +++ b/web/src/lib/settingsDiff.ts @@ -1,7 +1,6 @@ import type { Settings, SettingsPatch } from "@/lib/types"; const SECTIONS = [ - "runtime", "upstream", "dns", "blocking", diff --git a/web/src/lib/types.ts b/web/src/lib/types.ts index d1b83ed..dab3fcb 100644 --- a/web/src/lib/types.ts +++ b/web/src/lib/types.ts @@ -313,11 +313,7 @@ export interface TlsListenerSettings { } export interface Settings { - runtime: { - io_backend: "threaded" | "evented"; - }; upstream: { - connect_timeout_ms: number; read_timeout_ms: number; total_timeout_ms: number; }; @@ -388,7 +384,6 @@ export interface TlsListenerPatch { /** Partial update; `web.password` is write-only, `web.auth_enabled` is never sent. */ export interface SettingsPatch { - runtime?: Partial; upstream?: Partial; dns?: Partial; blocking?: Partial;