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>
2026-07-07 21:42:06 +10:00
parent af15c9c2d4
commit d71c7fbef2
53 changed files with 6685 additions and 9366 deletions
@@ -2,10 +2,10 @@ package dns

 import (
 	"context"
+	"errors"
 	"fmt"
 	"net"
 	"strings"
-	"time"

 	"github.com/miekg/dns"
 )
@@ -26,15 +26,22 @@ func (rs *RootServer) AllIPs(includeAAAA bool) []net.IP {
 }

 type RootDiscoveryConfig struct {
-	// Server overrides which root server to use as the traversal starting point.
-	// When empty, a root server is discovered via the upstream resolver.
+	// Server overrides which root server to use as the traversal starting
+	// point. It accepts a hostname (resolved to A via the upstream resolver)
+	// or an IP literal (used directly, no lookup).
 	Server string
-	// Resolver is the upstream DNS resolver used to resolve root server names.
-	// When empty, the system resolver from /etc/resolv.conf is used.
-	// Format: "host:port" (e.g. "8.8.8.8:53" or "1.1.1.1:53").
+	// Resolver is the upstream DNS resolver used to discover and resolve
+	// root server names. When empty, the system resolver configuration is
+	// used. Format: "host:port" (e.g. "8.8.8.8:53" or "1.1.1.1:53").
 	Resolver    string
 	AllRoots    bool
 	IncludeAAAA bool
+	// Query controls transport parameters (retries, timeout, TCP fallback)
+	// for discovery queries. nil means DefaultQueryConfig.
+	Query *QueryConfig
+	// Exchange overrides the wire exchange; nil means the real network.
+	// Tests inject a mock here so discovery is network-free.
+	Exchange ExchangeFunc
 }

 func DefaultRootDiscoveryConfig() *RootDiscoveryConfig {
@@ -49,31 +56,59 @@ func DiscoverRoots(ctx context.Context, cfg *RootDiscoveryConfig) ([]RootServer,
 		cfg = DefaultRootDiscoveryConfig()
 	}

-	resolver := resolverFromConfig(cfg)
+	// --root-server with an IP literal: use it directly, never look it up.
+	if cfg.Server != "" {
+		if ip := net.ParseIP(cfg.Server); ip != nil {
+			rs := RootServer{Name: cfg.Server}
+			if ip.To4() != nil {
+				rs.IPv4 = []net.IP{ip}
+			} else {
+				rs.IPv6 = []net.IP{ip}
+			}
+			return []RootServer{rs}, nil
+		}
+	}
+
+	resolver, err := resolverFromConfig(cfg)
+	if err != nil {
+		if cfg.Server != "" {
+			return nil, err
+		}
+		return rootHintsFallback(cfg, err)
+	}

 	if cfg.Server != "" {
-		return discoverRootOverride(ctx, resolver, cfg.Server, cfg.IncludeAAAA)
+		return resolveRootServer(ctx, cfg, resolver, cfg.Server)
 	}

 	if cfg.AllRoots {
-		servers, err := discoverAllRoots(ctx, resolver, cfg.IncludeAAAA)
+		servers, err := discoverAllRoots(ctx, cfg, resolver)
 		if err != nil {
-			return filterHints(RootHints, cfg.IncludeAAAA), nil
+			return rootHintsFallback(cfg, err)
 		}
 		return servers, nil
 	}

-	servers, err := discoverSingleRoot(ctx, resolver, cfg.IncludeAAAA)
+	servers, err := discoverSingleRoot(ctx, cfg, resolver)
 	if err != nil {
-		hints := filterHints(RootHints, cfg.IncludeAAAA)
-		if len(hints) > 0 {
-			return hints[:1], nil
-		}
-		return nil, err
+		return rootHintsFallback(cfg, err)
 	}
 	return servers, nil
 }

+// rootHintsFallback returns the builtin IANA hints when the upstream resolver
+// cannot provide roots (one entry unless AllRoots).
+func rootHintsFallback(cfg *RootDiscoveryConfig, err error) ([]RootServer, error) {
+	hints := filterHints(RootHints, cfg.IncludeAAAA)
+	if len(hints) == 0 {
+		return nil, err
+	}
+	if cfg.AllRoots {
+		return hints, nil
+	}
+	return hints[:1], nil
+}
+
 // filterHints returns a copy of hints with IPv6 addresses stripped when includeAAAA is false.
 func filterHints(hints []RootServer, includeAAAA bool) []RootServer {
 	out := make([]RootServer, len(hints))
@@ -86,88 +121,114 @@ func filterHints(hints []RootServer, includeAAAA bool) []RootServer {
 	return out
 }

-func discoverRootOverride(ctx context.Context, resolver, server string, includeAAAA bool) ([]RootServer, error) {
-	nsMsg, err := queryResolver(ctx, resolver, ".", dns.TypeNS)
+// discoverSingleRoot mirrors get_a_root in traverser.rb: ask the upstream
+// resolver for the root NS set, prefer glue from the additional section, and
+// only fall back to explicit A/AAAA lookups when no glue was supplied.
+func discoverSingleRoot(ctx context.Context, cfg *RootDiscoveryConfig, resolver string) ([]RootServer, error) {
+	names, nsMsg, err := rootNSNames(ctx, cfg, resolver)
 	if err != nil {
-		return nil, fmt.Errorf("query root NS records: %w", err)
+		return nil, err
 	}

-	nsSet := extractNSRecords(nsMsg.Answer)
-	if len(nsSet) == 0 {
-		nsSet = extractNSNames(nsMsg.Ns)
-	}
-
-	normalized := normalizeServerName(server)
-	for _, name := range nsSet {
-		if normalizeServerName(name) == normalized {
-			return resolveRootServer(ctx, resolver, name, includeAAAA)
+	for _, name := range names {
+		rs := rootFromAdditional(nsMsg, name, cfg.IncludeAAAA)
+		if len(rs.AllIPs(cfg.IncludeAAAA)) > 0 {
+			return []RootServer{singleAddress(rs)}, nil
 		}
 	}

-	return resolveRootServer(ctx, resolver, server, includeAAAA)
+	var lastErr error
+	for _, name := range names {
+		servers, err := resolveRootServer(ctx, cfg, resolver, name)
+		if err != nil {
+			lastErr = err
+			continue
+		}
+		return []RootServer{singleAddress(servers[0])}, nil
+	}
+
+	if lastErr == nil {
+		lastErr = errors.New("no address could be found for any root server")
+	}
+	return nil, lastErr
 }

-func discoverSingleRoot(ctx context.Context, resolver string, includeAAAA bool) ([]RootServer, error) {
-	nsMsg, err := queryResolver(ctx, resolver, ".", dns.TypeNS)
-	if err != nil {
-		return nil, fmt.Errorf("query root NS records: %w", err)
+// singleAddress narrows rs to its first address, mirroring get_a_root in
+// traverser.rb (add[0]/ans2[0]): the single-root start point is exactly one
+// (name, IP) pair even when the upstream supplies more (or duplicate) glue.
+func singleAddress(rs RootServer) RootServer {
+	if len(rs.IPv4) > 0 {
+		return RootServer{Name: rs.Name, IPv4: rs.IPv4[:1]}
 	}
-
-	nsSet := extractNSRecords(nsMsg.Answer)
-	if len(nsSet) == 0 {
-		nsSet = extractNSNames(nsMsg.Ns)
+	if len(rs.IPv6) > 0 {
+		return RootServer{Name: rs.Name, IPv6: rs.IPv6[:1]}
 	}
-
-	if len(nsSet) == 0 {
-		return nil, fmt.Errorf("no root NS records found in response")
-	}
-
-	pick := nsSet[0]
-	return resolveRootServer(ctx, resolver, pick, includeAAAA)
+	return rs
 }

-func discoverAllRoots(ctx context.Context, resolver string, includeAAAA bool) ([]RootServer, error) {
-	nsMsg, err := queryResolver(ctx, resolver, ".", dns.TypeNS)
+// discoverAllRoots mirrors find_all_roots in traverser.rb: it returns one
+// RootServer per root NS name with its full address set, so the traversal can
+// branch per root. Roots with no resolvable address are skipped.
+func discoverAllRoots(ctx context.Context, cfg *RootDiscoveryConfig, resolver string) ([]RootServer, error) {
+	names, nsMsg, err := rootNSNames(ctx, cfg, resolver)
 	if err != nil {
-		return nil, fmt.Errorf("query root NS records: %w", err)
-	}
-
-	nsSet := extractNSRecords(nsMsg.Answer)
-	if len(nsSet) == 0 {
-		nsSet = extractNSNames(nsMsg.Ns)
-	}
-
-	if len(nsSet) == 0 {
-		return nil, fmt.Errorf("no root NS records found in response")
+		return nil, err
 	}

 	var servers []RootServer
-	for _, name := range nsSet {
-		resolved, err := resolveRootServer(ctx, resolver, name, includeAAAA)
-		if err != nil {
-			servers = append(servers, RootServer{Name: name})
-			continue
+	for _, name := range names {
+		rs := rootFromAdditional(nsMsg, name, cfg.IncludeAAAA)
+		if len(rs.AllIPs(cfg.IncludeAAAA)) == 0 {
+			resolved, err := resolveRootServer(ctx, cfg, resolver, name)
+			if err != nil {
+				continue
+			}
+			rs = resolved[0]
 		}
-		servers = append(servers, resolved...)
+		servers = append(servers, rs)
 	}

 	if len(servers) == 0 {
-		return nil, fmt.Errorf("failed to resolve any root servers")
+		return nil, errors.New("failed to resolve any root servers")
 	}

 	return servers, nil
 }

-func resolveRootServer(ctx context.Context, resolver, name string, includeAAAA bool) ([]RootServer, error) {
+func rootNSNames(ctx context.Context, cfg *RootDiscoveryConfig, resolver string) ([]string, *dns.Msg, error) {
+	nsMsg, err := queryUpstream(ctx, cfg, resolver, ".", dns.TypeNS)
+	if err != nil {
+		return nil, nil, fmt.Errorf("query root NS records: %w", err)
+	}
+
+	names := extractNSRecords(nsMsg.Answer)
+	if len(names) == 0 {
+		names = extractNSNames(nsMsg.Ns)
+	}
+	if len(names) == 0 {
+		return nil, nil, errors.New("no root NS records found in response")
+	}
+	return names, nsMsg, nil
+}
+
+func rootFromAdditional(msg *dns.Msg, name string, includeAAAA bool) RootServer {
+	rs := RootServer{Name: name, IPv4: additionalIPs(msg, name, dns.TypeA)}
+	if includeAAAA {
+		rs.IPv6 = additionalIPs(msg, name, dns.TypeAAAA)
+	}
+	return rs
+}
+
+func resolveRootServer(ctx context.Context, cfg *RootDiscoveryConfig, resolver, name string) ([]RootServer, error) {
 	var ipv4 []net.IP
-	aMsg, err := queryResolver(ctx, resolver, name, dns.TypeA)
+	aMsg, err := queryUpstream(ctx, cfg, resolver, name, dns.TypeA)
 	if err == nil {
 		ipv4 = extractIPsFromAnswer(aMsg.Answer, dns.TypeA)
 	}

 	var ipv6 []net.IP
-	if includeAAAA {
-		aaaaMsg, err := queryResolver(ctx, resolver, name, dns.TypeAAAA)
+	if cfg.IncludeAAAA {
+		aaaaMsg, err := queryUpstream(ctx, cfg, resolver, name, dns.TypeAAAA)
 		if err == nil {
 			ipv6 = extractIPsFromAnswer(aaaaMsg.Answer, dns.TypeAAAA)
 		}
@@ -180,47 +241,53 @@ func resolveRootServer(ctx context.Context, resolver, name string, includeAAAA b
 	return []RootServer{{Name: name, IPv4: ipv4, IPv6: ipv6}}, nil
 }

-// resolverFromConfig returns the upstream DNS resolver address to use.
-// If cfg.Resolver is set, it is used directly. Otherwise the system resolver
-// is read from /etc/resolv.conf. Falls back to 127.0.0.1:53 if neither is available.
-func resolverFromConfig(cfg *RootDiscoveryConfig) string {
+// resolverFromConfig returns the upstream DNS resolver address to use:
+// cfg.Resolver when set, otherwise the system resolver configuration. There
+// is deliberately no hardcoded address fallback.
+func resolverFromConfig(cfg *RootDiscoveryConfig) (string, error) {
 	if cfg != nil && cfg.Resolver != "" {
-		return cfg.Resolver
+		return cfg.Resolver, nil
 	}
 	return systemResolver()
 }

-// systemResolver returns the first nameserver from the system DNS configuration.
-// This is Unix-only: it reads /etc/resolv.conf, which does not exist on Windows.
-// On Windows (or any system without /etc/resolv.conf) the fallback 127.0.0.1:53 applies.
-func systemResolver() string {
+// systemResolver returns the first nameserver from the system DNS
+// configuration. This is Unix-only: it reads /etc/resolv.conf, which does not
+// exist on Windows; there the caller falls back to the builtin root hints.
+func systemResolver() (string, error) {
 	cc, err := dns.ClientConfigFromFile("/etc/resolv.conf")
-	if err != nil || len(cc.Servers) == 0 {
-		return "127.0.0.1:53"
+	if err != nil {
+		return "", fmt.Errorf("read system resolver config: %w", err)
 	}
-	return net.JoinHostPort(cc.Servers[0], cc.Port)
+	if len(cc.Servers) == 0 {
+		return "", errors.New("no nameservers found in system resolver config")
+	}
+	return net.JoinHostPort(cc.Servers[0], cc.Port), nil
 }

-func queryResolver(ctx context.Context, resolverAddr, name string, qtype uint16) (*dns.Msg, error) {
-	c := &dns.Client{
-		Net:          "udp",
-		ReadTimeout:  5 * time.Second,
-		WriteTimeout: 5 * time.Second,
+// queryUpstream asks the upstream resolver with recursion desired — the only
+// RD=1 path in the program — using the same retry/TCP-fallback machinery as
+// traversal queries.
+func queryUpstream(ctx context.Context, cfg *RootDiscoveryConfig, resolverAddr, name string, qtype uint16) (*dns.Msg, error) {
+	var qcfg *QueryConfig
+	var exchange ExchangeFunc
+	if cfg != nil {
+		qcfg = cfg.Query
+		exchange = cfg.Exchange
 	}
-	if deadline, ok := ctx.Deadline(); ok {
-		c.ReadTimeout = time.Until(deadline)
-		c.WriteTimeout = time.Until(deadline)
+	qcfg = qcfg.withDefaults()
+	if exchange == nil {
+		exchange = realExchange
 	}

 	m := new(dns.Msg)
 	m.SetQuestion(dns.Fqdn(name), qtype)
 	m.RecursionDesired = true
-
-	r, _, err := c.ExchangeContext(ctx, m, resolverAddr)
-	if err != nil {
-		return nil, fmt.Errorf("resolver exchange %s %s: %w", name, QNameType(qtype), err)
+	if qcfg.UDPSize > MinEDNS0UDPSize() {
+		m.SetEdns0(uint16(qcfg.UDPSize), false)
 	}
-	return r, nil
+
+	return exchangeWithRetry(ctx, exchange, resolverAddr, m, qcfg)
 }

 func extractNSRecords(rrs []dns.RR) []string {
@@ -259,6 +326,23 @@ func extractIPsFromAnswer(rrs []dns.RR, qtype uint16) []net.IP {
 	return ips
 }

-func normalizeServerName(name string) string {
-	return strings.TrimSuffix(strings.ToLower(name), ".")
+// additionalIPs returns glue addresses for name from the additional section.
+func additionalIPs(msg *dns.Msg, name string, qtype uint16) []net.IP {
+	var ips []net.IP
+	for _, rr := range msg.Extra {
+		if !strings.EqualFold(rr.Header().Name, name) {
+			continue
+		}
+		switch v := rr.(type) {
+		case *dns.A:
+			if qtype == dns.TypeA {
+				ips = append(ips, v.A)
+			}
+		case *dns.AAAA:
+			if qtype == dns.TypeAAAA {
+				ips = append(ips, v.AAAA)
+			}
+		}
+	}
+	return ips
 }