milestone 17: real deadlines, validator holes, upstream editor, trusted proxies, contract samples, badvers

docs/reference/files-and-directories.md

@@ -140,9 +140,25 @@ file is also sampled by the disk monitor.
 
 | Path | What it is | Mode |
 | --- | --- | --- |
-| `logging.file_path` (default `/var/log/nxdns/nxdns.log`) | The live process log. Opened for append; created when it does not exist. | `0666 & ~umask` — nxdns never chmods it |
+| `logging.file_path` (default `/var/log/nxdns/nxdns.log`) | The live process log. Opened write-only and written at a tracked offset; created when it does not exist. | `0666 & ~umask` — nxdns never chmods it |
 | `<file_path>.1` … `<file_path>.<max_files - 1>` | Rotated generations, newest first. | Inherited from the live file they were renamed from |
 
+**Do not point external logrotate at this file.** nxdns owns the rotation of
+its own log. There is no append mode in Zig 0.16, so the writer reads the file
+length once when it opens the file and then writes every line at an offset it
+tracks in the process. A rotator that moves the file behind it breaks that
+offset, and nxdns does not notice until the next restart:
+
+- With `copytruncate` the offset survives the truncation, so the next line
+  lands where it would have without it. The file regrows with a sparse,
+  NUL-filled prefix as long as the log that was just rotated away.
+- With rename-and-create nxdns keeps writing to the renamed inode. The new
+  file stays empty, the renamed one grows without bound, and
+  `logging.max_size_mb` bounds nothing on disk.
+
+If an external rotator has to own the file, set `logging.output = .stderr` and
+let the collector capture the stream instead.
+
 The log file is the one path here nxdns does not set a mode on. `config.db` and
 `querylog.db` are chmodded to 0600 whatever the umask; the log file is left at
 whatever the umask gives it. Under the shipped unit that is 0600, because