# ttl Roadmap

## Market Context

**mtr is the de facto standard** for interactive traceroute but hasn't seen major feature development in years. **trippy** (Rust) is the main modern alternative but focuses on a different feature set.

**Key advantages ttl already has:**
- ECMP path enumeration with per-flow/per-packet classification (`--flows`)
- NAT detection (source port rewrite analysis)
- ICMP rate limit detection (distinguish rate limiting from real loss)
- Route flap and asymmetric routing detection
- TTL manipulation detection (transparent proxies, middleboxes)
- Path MTU discovery (`--pmtud`)
- IX detection via PeeringDB
- Animated session replay
- Dual-stack `--resolve-all` (trace IPv4 and IPv6 simultaneously)

---

## Completed (v0.1.x - v0.6.x)

- [x] ICMP Echo probing with TTL sweep
- [x] IPv4 and IPv6 support with extension header handling
- [x] Real-time TUI with ratatui (11 built-in themes)
- [x] Hop statistics (loss, min/avg/max, stddev, jitter, percentiles)
- [x] Reverse DNS resolution (parallel lookups)
- [x] MPLS label detection (RFC 4884/4950 ICMP extensions)
- [x] JSON, CSV, and report export formats
- [x] Session replay from saved JSON
- [x] Multiple simultaneous targets (`ttl 8.8.8.8 1.1.1.1`)
- [x] NAT detection (source port rewrite analysis)
- [x] Paris/Dublin traceroute (`--flows` for ECMP path enumeration)
- [x] UDP probing (`-p udp`) and TCP SYN probing (`-p tcp`)
- [x] Protocol auto-detection (`-p auto`, default)
- [x] ASN lookup (Team Cymru DNS), GeoIP (MaxMind), IX detection (PeeringDB)
- [x] Terminal injection protection (sanitize external data)
- [x] Terminal state cleanup on error/panic

## Completed (v0.7.x - v0.12.x)

- [x] Interface binding (`--interface`, `--recv-any`)
- [x] Shell completions (`--completions bash/zsh/fish/powershell`)
- [x] Settings modal (theme, display mode, PeeringDB API key)
- [x] Target list overlay for multi-target mode
- [x] Autosize columns (auto/compact/wide with `w` key cycling)
- [x] Linux binary compatibility (musl libc for broad distro support)

## Completed (v0.13.x - v0.14.x)

- [x] Path MTU discovery (`--pmtud`) with binary search
- [x] Packet size control (`--size`) with DF flag
- [x] DSCP/ToS marking (`--dscp`) for QoS policy testing
- [x] ICMP rate limit detection with TUI indicators
- [x] Route flap detection (primary responder IP changes)
- [x] Asymmetric routing detection (forward vs return path hops)
- [x] TTL manipulation detection (transparent proxies, middleboxes)
- [x] First-hop gateway detection via kernel APIs (netlink/sysctl)
- [x] Rate limiting (`--rate`) for slow links
- [x] Source IP selection (`--source-ip`)
- [x] Update notifications (checks GitHub releases, install-method-aware)
- [x] FreeBSD support (experimental, raw sockets)

## Completed (v0.15.x - v0.19.1)

- [x] Animated replay (`--replay file --animate`) with speed control
- [x] Probe event recording for replay accuracy
- [x] TUI refresh rate increased to 60fps (#17)
- [x] Jumbo frame support (`--size` up to 9216, `--jumbo` for PMTUD)
- [x] Immediate sent counting (mtr parity — increments at probe send, not response)
- [x] Dual-stack `--resolve-all` (trace IPv4 and IPv6 simultaneously)
- [x] FreeBSD ICMP socket fix (RAW sockets, not DGRAM)
- [x] Last RTT column in main table (mtr parity — `Loss% Snt Last Avg Min Max StdDev`)
- [x] JAvg and JMax columns in Wide display mode
- [x] Wider ASN column for full AS name visibility
- [x] ECMP classification: per-flow vs per-packet detection with primary_ratio heuristic (#46)
- [x] Paths column reflects actual responder count for per-packet ECMP (#46)
- [x] `E` indicator for ECMP detected vs `!` for route flap (#46)
- [x] Effective flow capability: `--flows` + ICMP warns and collapses to single-flow (#46)
- [x] Receiver flow attribution hardening: unknown flows only match when unambiguous (#46)
- [x] NetBSD platform support (experimental, raw sockets, IPv6 PMTUD only) (#47)
- [x] NetBSD UDP source IP auto-detection (fixes EHOSTUNREACH on DGRAM sockets) (#47)
- [x] Update checker: non-blocking `try_recv()` polling in TUI (replaces blocking `recv_timeout(1s)`)
- [x] Update checker: first-run immediate network check (`interval(Duration::ZERO)`)
- [x] Interactive replay controls (seek, speed, progress bar) shipped in v0.19.0
- [x] Pre-commit hooks (`.pre-commit-config.yaml` for `cargo fmt`/`clippy`/`test`)
- [x] CI: `cargo clippy --all-targets -- -D warnings` on Linux, macOS, and FreeBSD
- [x] hickory-resolver 0.26 upgrade (closes RUSTSEC-2026-0118 and RUSTSEC-2026-0119)

## Completed (v0.20.0)

- [x] Trace diffing (`--diff before.json after.json`): added/lost hops, path changes, latency shifts; `--json` for machine-readable output
- [x] Streaming JSON output (`--stream-json`): line-delimited probe events + per-target summary, composable with jq/grep
- [x] Daemon mode (`--daemon`) with graceful SIGTERM shutdown (clean `docker stop`)
- [x] Prometheus/OpenMetrics exporter (`--prometheus :9090`) with `/healthz` for orchestration
- [x] Official Dockerfile + multi-arch (amd64/arm64) GHCR images (`ghcr.io/lance0/ttl`)
- [x] Interactive target selection: `ttl` with no args opens an empty session; `o` adds targets mid-session with runtime engine/receiver spawning
- [x] IX prefix lookup via binary radix trie (O(prefix_len) instead of O(n) linear scan)
- [x] New `aarch64-unknown-linux-musl` release artifact

---

## Planned Features

### Next — ECMP Improvements

**Why this matters:** Per-packet load balancing (common on Arista, Juniper, Cisco) is undercounted by the current flow-primary model. Users see 8 responders in the detail view but "Paths: 1" in the main table. Related: #46

- [x] Detect per-packet vs per-flow ECMP (primary_ratio heuristic per flow)
- [x] Paths column reflects actual responder count for per-packet ECMP
- [x] Separate indicators: `E` for ECMP detected vs `!` for route flap
- [x] Warn when `--flows > 1` with effective ICMP probing (`-p icmp`, or `-p auto` when auto-select resolves to ICMP)
- [x] Define `-p auto` warning semantics for multi-target/mixed-family runs (warn if any target resolves to effective ICMP, avoid duplicate spam)
- [x] Track effective flow capability at runtime (requested `--flows` vs effective protocol) and use it for flap detection + NAT/Paths column visibility
- [x] Add CLI/TUI hint that flow-based ECMP detection is meaningful with UDP/TCP probes
- [x] Keep Paths value + highlight + host indicator driven by one shared ECMP classification (avoid count/style drift)
- [x] Handle out-of-range returned src ports as unknown flow (not forced flow 0) to avoid false per-flow attribution behind NAT/CGNAT
- [x] Update indicator/UI budget for new `E` marker (host width autosize currently assumes `" !~^"`)
- [x] Update user-facing indicator docs/help (`E` vs `!`) in CLI help + docs pages
- [x] Add tests for per-packet ECMP classification, `-p auto` ICMP warning behavior, and out-of-range src-port flow attribution
- [x] #46 acceptance: per-packet ECMP no longer presents as misleading `Paths: 1` when many responders are observed
- [x] #46 acceptance: `E` (ECMP) and `!` (route flap) are no longer conflated in the same scenario
- [ ] Paris strategy for UDP (`--strategy paris` — fixed 5-tuple, checksum encodes sequence) *(follow-on after #46 core fix)*
- [ ] Dublin strategy for UDP (`--strategy dublin` — IP ID field encodes sequence) *(follow-on after #46 core fix)*

---

## Future Ideas

*Prioritized by effort vs user impact. Quick wins first, then bigger lifts.*

### Quick Wins (low effort, high impact)
- [x] **Progress indicator in replay** — show position in timeline during animated replay
- [x] **Interactive replay** — step through events, jump to time, speed control
- [x] **Last metric semantics** — documented as primary-responder-most-recent; TUI/CSV aligned
- [x] **IPv6 RAW payload fallback tests** — unit tests for IPv6 Echo Reply and Time Exceeded parsing
- [x] **Main table layout tests** — verify header/cell/width count parity across Auto/Compact/Wide × single-flow/multi-flow modes

### Medium Effort (moderate effort, high impact)
- [ ] **PCAP export** — write probe/response packets to .pcap for Wireshark analysis
- [x] **IX lookup performance** — radix trie for O(prefix_len) instead of O(n) linear scan
- [ ] **Customizable columns** — choose which stats to display in TUI
- [x] **Container image** — pre-built multi-arch image on GHCR for CI/monitoring pipelines

### Larger Projects (high effort, high impact)
- [ ] **ICMP checksum flow variation** — Paris traceroute for ICMP (vary checksum to create distinct flows). Neither ttl nor trippy implements this today. Requires platform-specific raw socket work (kernel checksum offloading on Linux, IP_HDRINCL). **Note:** Real-world value may be limited — Arista hardware flow-hashing platforms don't use ICMP checksum as entropy, so this approach won't create distinct flows on most switch hardware. TCP/UDP remain the reliable methods for multi-path detection. May still be useful on software load balancers.
- [ ] **BGP & routing integration** — looking glass queries, AS path display, RPKI/ROA validation
- [ ] **Baseline comparison** — save baseline, alert on latency/loss/path deviations
- [ ] **Continuous logging mode** — log path changes over hours/days
- [ ] **Historical data storage** — SQLite/file-based path history

### Nice to Have
- [ ] **Custom keybindings** — user-configurable key mappings
- [ ] **World map visualization** — ASCII/Unicode geographic path display
- [ ] **Advanced protocol testing** — TCP MSS clamping, ECN, fragmentation testing
- [ ] **Multi-path validation** — verify all ECMP paths are functional

---

## Pre-1.0 Requirements

### Code Quality
- [ ] Library API stabilization (stable `lib.rs` for third-party integrations)
- [ ] Comprehensive documentation for library consumers
- [ ] Semantic versioning commitment

### Testing
- [x] Integration tests for probe-receive-state pipeline
- [x] Property-based/fuzz tests for packet parsing (correlate.rs)
- [x] RAW payload fallback unit tests (IPv4)
- [x] IPv6 RAW payload fallback unit tests
- [x] Concurrent multi-target stress tests

---

## Low Priority

### Windows Native
- [ ] Basic ICMP traceroute (Npcap or Winsock raw sockets)
- [ ] TUI compatibility with Windows Terminal
- [ ] Pre-built binaries

*Rationale: Massive Npcap effort. WSL2 works well. Revisit if demand warrants.*

### Bidirectional Probing
- [ ] Remote agent for measuring both directions
- [ ] One-way delay estimation (detect latency asymmetry)

*Rationale: Requires deploying an agent on the remote side, which changes the tool's simplicity model.*

### Advanced Network Analysis
- [ ] Bandwidth/capacity estimation (pathchar-style probing)
- [ ] SNMP integration (query router interface stats)
- [ ] Network topology learning (build graph from multiple traces)

*Rationale: These push ttl toward being a full network management tool. Better served by purpose-built tools.*

---

## Competitive Landscape

| Tool | Language | ECMP | MTU Discovery | Rate Limit Detection | TUI | Active Development |
|------|----------|------|---------------|---------------------|-----|-------------------|
| mtr | C | No | No | No | Yes | Maintenance |
| trippy | Rust | Yes (UDP) | No | No | Yes | Active |
| traceroute | C | No | Yes | No | No | Maintenance |
| tracepath | C | No | Yes | No | No | Maintenance |
| **ttl** | Rust | Yes (per-flow + per-packet) | Yes | Yes | Yes | Active |

---

## Scope Creep / Non-Goals

ttl is a **CLI traceroute tool**. The following are explicitly out of scope:

- **Web/mobile UI** — this is a CLI tool, SSH into a box
- **Shareable URLs / hosted trace service** — JSON files are the sharing format
- **Webhook/event streaming** — use `--stream-json | curl` instead
- **Monitor mode with alerting** — use Smokeping/Nagios for long-running monitoring
- **Modular output plugins** — Unix pipes are the plugin system
- **Hop privacy mode** (mask IPs for screenshots) — users can redact manually
- **Multi-language TUI** (i18n) — English-only is fine for CLI tools
- **Full packet capture** — use tcpdump/wireshark
- **Bandwidth testing** — use [xfr](https://github.com/lance0/xfr) or iperf
- **Port scanning** — use nmap
- **Enterprise collaboration platform** — not a SaaS product

If you need these features, combine ttl with purpose-built tools.

---

## Known Limitations

See [KNOWN_ISSUES.md](KNOWN_ISSUES.md) for documented edge cases and limitations.

---

## Infrastructure

- [x] GitHub Actions CI (build, test, clippy, FreeBSD)
- [x] Binary releases (Linux x86_64/aarch64, macOS x86_64/aarch64)
- [x] Homebrew formula (`brew install lance0/tap/ttl`)
- [x] Curl installer (`install.sh`)
- [x] Dependabot (Cargo + GitHub Actions)
- [x] AUR package (`ttl-bin`, community-maintained)
- [x] Gentoo package (`net-analyzer/ttl`, official repository)
- [x] Container image on GHCR (`ghcr.io/lance0/ttl`, multi-arch, published on release)
- [ ] Docker Hub mirror (optional — needs registry credentials; GHCR covers the use case)

---

## Contributing

See issues labeled `good first issue` for entry points. PRs welcome for any roadmap item.
