feat: rework engine and CLI for dnstraverse parity
Port the traversal engine to the Ruby dnstraverse model so behaviour and output match dns.squish.net: - dns: single RD=0 query path (RD=1 only for upstream root discovery), per-run packet cache, EDNS0 512-fallback with warnings, UDP->TCP on truncation; fix --retries 0 and --root-server IP-literal handling; drop all hardcoded 127.0.0.1:53 resolvers - traverse: hierarchical per-branch InfoCache, 7-step response classification with the full 10-status vocabulary, bailiwick partitioning, strictly-deeper lame-referral rule, refid grammar with .0 resolve subtrees and childset digits, per-IP branching at 1/n weight, cache-based glue resolution with noglue/loop dead ends, CNAME restarts from the deepest cached zone, fast-mode memoization, probability aggregation with Ruby-identical stats keys (sums to 1.0) - output: byte-for-byte reference text format pinned by a golden test, reference CLI defaults, working --quiet/--show-X=false, TTY-aware colour, deduplicated deterministic JSON - web: adapt API/SPA to the new engine, SSE events carry refid/status, fix subscribe/snapshot duplicate-event race and a statusCls TDZ bug, align SPA type list with the backend - delete the old engine and dead code (net -4,350 lines) Verified against live runs of the reference Ruby engine across five domains (answers, NXDOMAIN, null MX, CNAME restart, glueless resolve) with no divergences beyond the documented typo fixes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Gary Hansen
co-authored by
Claude Fable 5
Claude Fable 5
parent
af15c9c2d4
commit
d71c7fbef2
@@ -80,7 +80,7 @@ exploredns --quiet www.example.com
|
||||
# Debug mode
|
||||
exploredns --debug www.example.com
|
||||
|
||||
# Library-level debug (very verbose)
|
||||
# Debug plus library-level diagnostics
|
||||
exploredns --dd www.example.com
|
||||
|
||||
# Force TCP
|
||||
@@ -102,45 +102,44 @@ Usage:
|
||||
exploredns [flags] <domain>
|
||||
|
||||
Query Options:
|
||||
--type <TYPE> Record type to query (default: A)
|
||||
--type <TYPE> Record type to query (default: a)
|
||||
Supported: A, AAAA, NS, CNAME, MX, TXT, SOA, PTR, ANY
|
||||
--root-server <IP> Override the root server IP address
|
||||
--all-root-servers Query all 13 root server sets (default: false)
|
||||
--root-aaaa Include IPv6 addresses for root servers (default: false)
|
||||
--follow-aaaa Only follow AAAA addresses for referrals (default: false)
|
||||
--root-server <HOST> Initial root server, hostname or IP literal
|
||||
(default: ask the upstream resolver for one root)
|
||||
--all-root-servers Traverse from all root servers (default: false)
|
||||
--root-aaaa Include IPv6 root addresses (not implemented yet)
|
||||
--follow-aaaa Only follow AAAA for referrals (not implemented yet)
|
||||
--dns-upstream <ADDR> Upstream resolver (host:port) for root discovery
|
||||
(default: system resolver)
|
||||
|
||||
Transport Options:
|
||||
--udp-size <N> EDNS0 UDP buffer size, 512–4096 (default: 2048)
|
||||
--udp-size <N> EDNS0 UDP buffer size, 512–4096; 512 turns EDNS0 off
|
||||
(default: 2048)
|
||||
--allow-tcp Fall back to TCP on truncation (default: true)
|
||||
--always-tcp Always use TCP (requires --allow-tcp)
|
||||
--retries <N> Per-server retry count, 0–10 (default: 2)
|
||||
--retries <N> Number of 2s retries before timing out, 0–10 (default: 2)
|
||||
|
||||
Traversal Options:
|
||||
--max-depth <N> Maximum referral depth, 1–100 (default: 20)
|
||||
--fast / --fast=false Share glue cache across branches (default: true)
|
||||
--fast / --fast=false Fast mode; turn off to be more accurate (default: true)
|
||||
|
||||
Output Options:
|
||||
--json Emit results as JSON instead of text
|
||||
--verbose, -v Show extra detail in text output
|
||||
--debug, -d Enable application debug messages (stderr)
|
||||
--dd Enable library-level debug messages (very verbose)
|
||||
--quiet, -q Suppress header and supplementary information
|
||||
--show-progress Show live traversal progress (default: true)
|
||||
--no-show-progress Hide traversal progress
|
||||
--show-resolves Show glue-resolution steps (default: true)
|
||||
--no-show-resolves Hide glue-resolution steps
|
||||
--show-servers Show which servers were queried (default: true)
|
||||
--no-show-servers Hide server list
|
||||
--show-versions Show DNS server software versions (default: true)
|
||||
--no-show-versions Hide server versions
|
||||
--show-all-stats Show query statistics (default: true)
|
||||
--no-show-all-stats Hide statistics
|
||||
--show-results Show per-branch query results (default: true)
|
||||
--no-show-results Hide per-branch results
|
||||
--show-summary-results Show deduplicated summary section (default: true)
|
||||
--no-show-summary-results Hide summary section
|
||||
--json Emit a single JSON document instead of text
|
||||
--verbose, -v Verbose progress ([qname] and <bailiwick> shown)
|
||||
-d, --debug Print debug diagnostics to stderr
|
||||
-dd Like -d plus library-level debug
|
||||
--quiet, -q Suppress the header block
|
||||
--show-progress Show traversal progress (default: true)
|
||||
--show-resolves Show glue-resolution progress (default: false)
|
||||
--show-servers Show servers encountered (default: false)
|
||||
--show-versions Show server version fingerprints (default: true)
|
||||
--show-all-stats Show statistics after every node (default: false)
|
||||
--show-results Show the results (default: true)
|
||||
--show-summary-results Show the summary results (default: true)
|
||||
```
|
||||
|
||||
Every `--show-X` flag can be negated with `--show-X=false` or `--no-show-X`.
|
||||
|
||||
---
|
||||
|
||||
## Web Interface
|
||||
@@ -253,15 +252,22 @@ Completed jobs are kept in memory for one hour before being purged.
|
||||
|
||||
### Text (default)
|
||||
|
||||
Coloured, hierarchical tree output showing each traversal branch, the servers
|
||||
queried, referrals followed, and final answers. Disable colour by setting the
|
||||
`NO_COLOR` environment variable.
|
||||
dnstraverse-style output: a header block (settings, initial root, query;
|
||||
suppressed by `--quiet`), progress lines (`<refid> <server> (<ips>)` with
|
||||
` -- resolving` and ` -- completed earlier (<refid>)` markers), a `Results:`
|
||||
section of aggregated outcomes with probabilities (`Answer from`, `No glue
|
||||
at`, `Lame referral from`, error/exception wording), and a `Summary Results:`
|
||||
section grouping outcomes by status and answer content. `--show-servers`
|
||||
adds the sorted list of servers encountered. Colour is used only when stdout
|
||||
is a terminal and the `NO_COLOR` environment variable is unset.
|
||||
|
||||
### JSON (`--json`)
|
||||
|
||||
Structured JSON array of traversal results. Suitable for piping into `jq` or
|
||||
ingesting into other tools. Each element contains the referral metadata, the
|
||||
responding server, the response type, and the decoded DNS records.
|
||||
A single JSON document — `{domain, qtype, root, results, summary, servers}` —
|
||||
emitted once at the end of the run with deterministic ordering. Each
|
||||
aggregated outcome appears exactly once in `results`; `summary` groups
|
||||
probabilities by status and by distinct answer RRset; `servers` is present
|
||||
with `--show-servers`. Suitable for piping into `jq`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user