ftr - Fast TraceRoute

ftr Improvement Plan

Plan from a full-project review (code, docs, CI, and a feature-gap analysis against SwiftFTR 0.13.0) against Rust best practices as of mid-2026. Sections are stack-ranked — top is next; each is a shippable unit. Delete sections as they merge (git has the history).

Context: ftr is in maintenance mode (SwiftFTR is the primary macOS client), but has external users (GitHub stars, crates.io, APT repo, one open issue — #22 requesting IPv6). The v0.8.0 release (PRs #23–#35) covered docs accuracy, correctness fixes, dependency updates, CI/supply-chain hardening, IPv6 validation spikes, the breaking API cleanup, edition 2024, system DNS resolvers, and the tests lint-debt payoff; what remains is below.

Follow-ups from landed work (small, independent)

• DNS: TCP fallback on truncated (TC) responses (DnsError::Truncated exists; nothing retries over TCP). Windows system-resolver discovery (GetAdaptersAddresses). Automatic DNS-config change watching to complement dns::refresh_system_dns() — macOS via notify(3) on com.apple.system.SystemConfiguration.dns_configuration (Chromium’s approach, https://issues.chromium.org/issues/40182831; the c-ares maintainers catalog per-platform equivalents in c-ares/c-ares#613), Linux via inotify on resolv.conf. #[non_exhaustive] on ReverseDnsError/DnsRecord (skipped in #33 to avoid cross-PR conflicts).
• Releases: adopt crates.io Trusted Publishing (OIDC) — requires one-time configuration on crates.io by the maintainer, then swap the token step in release.yml for rust-lang/crates-io-auth-action. Restructure the two-phase draft-release flow so tagging can’t leave crates.io/APT silently unpublished. Add macOS release artifacts (brew tap currently builds from source).
• Coverage: make the llvm-cov job blocking once it proves stable (it kept continue-on-error: true at introduction).
• criterion is held at 0.7 because 0.8 declares rust-version = 1.86 — bump together with the next MSRV raise.
• Unprivileged macOS traceroute: macos.rs only implements raw ICMP (root-gated by Darwin), but macOS supports unprivileged SOCK_DGRAM ICMP — SwiftFTR does full traceroutes without root this way, and the v6 spike proved DGRAM receives Time Exceeded unprivileged (docs/IPV6_DESIGN.md). Add a DGRAM fallback like Linux’s; falls out naturally from IPv6 integration, which needs the DGRAM path anyway. Remember Darwin demuxes v4 DGRAM ICMP by identifier (SwiftFTR’s 0.8.0 regression) but does NOT for v6.

Dependency diet (standing theme + a ladder of PRs)

Maintainer directive (2026-07-17): as an overall theme, reduce the size and complexity of the dependency tree — SwiftFTR’s zero-third-party-deps is the aspiration. Every new dependency needs justification; prefer hand-rolled minimal implementations for narrow needs (the 0.7.0 hickory/reqwest/pnet replacements are the model). Baseline 2026-07-17: 78 transitive crates from 10 direct (macOS; Linux adds vendored OpenSSL). Ladder, biggest win first:

• Kill ureq + TLS (32 crates, 40% of the tree): its sole use is the HTTPS public-IP fallback. STUN stays primary (it reflects the probing socket’s true public mapping). Replace the HTTPS fallback with a STUN server (or trivial UDP address-echo) on the Network Weather DigitalOcean droplet — infrastructure we control, same protocol, zero TLS. Maintainer ruling (2026-07-17): DNS whoami techniques (Akamai/Cloudflare/Google) are NOT acceptable — the reported address is the recursive resolver’s egress, not the client’s, whenever queries traverse a forwarding resolver, and port-53 interception corrupts even direct queries. (Cloudflare’s cdn-cgi/trace endpoints are useful only if an HTTPS fallback survives.) Also removes the vendored-OpenSSL Linux build and the TLS provider fragility (a runtime panic lived there until PR #39).
• getrandom (3 crates): only seeds STUN transaction IDs and DNS query IDs — std::hash::RandomState per-process entropy hashed with a counter suffices for these non-crypto IDs (document the security posture: DNS ID is anti-spoofing defense-in-depth alongside source-port randomization).
• ip_network + ip_network_table (3 crates): ASN cache longest-prefix match over a few hundred prefixes — a sorted-Vec binary search or small hand-rolled trie replaces it.
• serde + serde_json (9 crates incl. proc-macro build deps): ftr only serializes (JSON output); a small hand-rolled JSON emitter with correct string escaping covers it. TODO.md already contemplates this.
• clap (19 crates): 16 flags; a minimal parser (or lexopt-style single-crate) with hand-written –help. Trade-off: loses completions and polish — do last, only if the theme still has appetite.
• thiserror (8 crates, build-time syn/quote): mechanical hand-written Display/Error impls. Low value per churn — optional.
• tokio stays: the async API is the product; consumers depend on it.

Do NOT batch these with feature work; each rung is its own PR with before/after cargo tree counts in the body.

Performance & reliability (two PRs)

• Replace 1ms busy-poll receive loops (linux.rs, macos.rs, bsd.rs) with tokio AsyncFd readiness — the dominant avoidable CPU cost; also fixes detached receiver tasks outliving the trace (tie receivers to the engine’s JoinSet), removes env::var("CI") reads inside poll loops, and the per-packet throwaway struct allocations.
• Consider shared-socket receive demux instead of socket-per-probe. Unique ICMP identifier per concurrent socket, validated on Echo Reply AND on the id embedded in Time Exceeded/Unreachable payloads (see docs/IPV6_DESIGN.md — mandatory for v6 on Darwin, and SwiftFTR’s 0.8.0 v4 regression).
• Drop redundant double-locking: outer tokio::RwLock around internally locked AsnCache/RdnsCache; make RdnsCache::get not take a write lock per read.
• Testing hardening: proptest + cargo-fuzz targets for src/socket/icmp.rs (reject IHL < 5 while at it) and the DNS parser; unit tests for the unsafe recvmsg/CMSG path (linux) and Windows reply-struct reinterpret; gate live- network tests behind an env var and serialize them (SwiftFTR’s NetworkTestGate pattern) instead of letting them flake CI.

IPv6: polish + remaining validation

IPv6 traceroute ships on every supported platform as of 0.10.0 (macOS, Linux, BSD in 0.9.0 via PRs #38–#43; Windows in 0.10.0 via #50), each live-validated on real hardware/VMs with external v6. Remaining:

• Deferred live validation (needs privileged access we couldn’t script): router-originated ICMPv6 Time Exceeded observed first-hand on FreeBSD (the FreeBSD VM has external v6, but raw sockets need root and the test ftr user isn’t in wheel; run from console or pw group mod wheel -m ftr, then ftr -6 2001:4860:4860::8888). OpenBSD’s VM has no external v6, so its live multi-hop trace needs a v6-connected host. macOS root-mode RAW-vs-DGRAM comparison (sudo cargo run --release --example spike_traceroute6).
• CI gap that keeps biting: clippy runs only on Ubuntu, so windows.rs and bsd*.rs dead-code/lints surface only when someone compiles those targets (three separate cleanups so far). Add windows-target (and ideally a BSD-target) clippy --all-targets cross-check to CI.
• Polish: NAT64/DNS64 handling review (AI_V4MAPPED-style synthesis for v4 literals on v6-only networks); first-class zone-scoped (fe80::%if) targets; hop-level zone display.

Feature ports from SwiftFTR (optional, by appetite)

Stack-ranked by fit for a traceroute tool with external users:

• Streaming trace API — impl Stream<Item = StreamingHop> emitting hops in arrival order with a re-probe phase for rate-limited routers. Best library-consumer win; SwiftFTR’s StreamingTrace is the reference.
• UDP 5-tuple multipath/ECMP discovery — ftr on Linux already has unprivileged UDP traceroute, so true Dublin/Paris-style flow variation is more attainable here than it was for SwiftFTR (which shipped ICMP-ID variation and documented it under-discovers, deferring UDP to its roadmap). A differentiating feature, not just parity.
• TCP/UDP connectivity probes — connected-UDP trick (ICMP unreachable surfaces as ECONNREFUSED, no privileges) and non-blocking TCP connect. Small, self-contained.
• Bufferbloat/RPM testing — probably out of scope for ftr; it drags in HTTP load generation and third-party endpoints. Skip unless a user asks.