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
2026-07-07 21:42:06 +10:00
co-authored by Claude Fable 5
parent af15c9c2d4
commit d71c7fbef2
53 changed files with 6685 additions and 9366 deletions
+21 -19
View File
@@ -1,27 +1,29 @@
// Package traverse implements the core DNS traversal engine for ExploreDNS.
// Package traverse implements the core DNS traversal engine for ExploreDNS,
// a Go port of the Ruby dnstraverse engine (dns.squish.net).
//
// The traversal engine starts from the DNS root servers and iteratively
// follows every referral it receives, building a complete picture of the
// delegation path for a domain. Unlike a standard recursive resolver, which
// stops at the first authoritative answer, the traversal engine explores every
// branch so that delegation mismatches, lame delegations, or split authorities
// are all visible in the output.
// The traversal starts from a synthetic "rootroot" node (never displayed)
// with one child per root server, and explores every branch of the
// delegation instead of stopping at the first authoritative answer, so lame
// delegations, missing glue and split authorities are all visible.
//
// # Architecture
//
// A Traverser maintains a stack of Referral objects. Each Referral
// represents a pending query to a specific set of nameservers for a specific
// name and record type. The engine pops referrals one at a time, sends the
// query, classifies the response, and pushes any child referrals back onto the
// stack.
//
// When a referral contains nameserver names but no glue records (IP addresses),
// the engine resolves them via a secondary traversal before continuing.
// A Traverser runs an explicit stack loop over Referral nodes. Each Referral
// queries every IP address of one nameserver for one qname/qclass/qtype,
// classifies each response (DecodedQuery, ServerResponse) and creates one
// child per NS name for referral/restart statuses — including glueless
// nameservers, which get their own resolve subtree (refid ".0." components)
// queried from this branch's cache, never a system resolver. Post-order
// stack markers fold the statistics upwards once all children finished:
// every leaf outcome carries a probability, and the probabilities at the
// root sum to 1.0.
//
// # Caching
//
// An InfoCache stores discovered glue records. In fast mode (default) a
// single root cache is shared across all branches so that glue discovered in
// one branch is immediately available to sibling branches. Disable fast mode
// (TraverserConfig.Fast = false) for fully independent branch resolution.
// Two caches cooperate: the packet-level cache in internal/dns sends each
// (server IP, question, udpsize) at most once per run, and the hierarchical
// per-branch InfoCache holds the in-bailiwick records each response is
// allowed to contribute. Fast mode (default) additionally memoises completed
// referrals so identical subtrees are reported as "completed earlier"
// instead of being walked again.
package traverse