v0.6.0: Enhanced Network Segment Classification

This release introduces significant improvements to how ftr classifies and displays network segments in traceroute paths.

What's New

🎯 Enhanced Network Segment Classification

• TRANSIT and DESTINATION segments: More precise classification replacing the generic "BEYOND" label
• TRANSIT: Networks between ISP and destination, including Internet Exchange Points (IXPs) and peering points
• DESTINATION: Hops within the target's ASN for clear identification of final network

🔍 Improved IXP/Peering Point Detection

• Early destination ASN lookup: Destination ASN is resolved at start for accurate segment classification
• IXP awareness: Public IPs without ASN info are now classified as TRANSIT (likely Internet Exchange Points)
• Sandwich logic: Unknown/Transit hops between same-type segments intelligently inherit that segment type

🎨 Better Output Formatting

• Full destination ASN info: Complete ASN details (number, name, country) displayed in output
• Cleaner end-of-trace: "[No further hops responded; max TTL was X]" message instead of empty lines
• Precise timing: JSON RTT values rounded to 1 decimal place for consistency

Bug Fixes

• Probe timeout fix: Timeout parameter now properly respected (was using hardcoded values)
• ASN name cleanup: No more duplicate country codes (e.g., "GOOGLE, US" → "GOOGLE")
• Socket timeout: Configuration properly propagated from CLI arguments to all socket implementations

Breaking Changes ⚠️

Library API:

• SegmentType::Beyond replaced with Transit and Destination
• TracerouteResult.destination_asn changed from Option<u32> to Option<AsnInfo>

JSON Output:

• Segment labels changed to "TRANSIT" and "DESTINATION"
• destination_asn field now includes full ASN information (asn, name, country_code)

Installation

Windows

Download the appropriate .zip file below:

• ftr-0.6.0-x86_64-pc-windows-msvc.zip for 64-bit Intel/AMD
• ftr-0.6.0-aarch64-pc-windows-msvc.zip for ARM64

Debian/Ubuntu

Download the appropriate .deb package:

• ftr_0.6.0-1_amd64.deb for 64-bit Intel/AMD
• ftr_0.6.0-1_arm64.deb for ARM64

Other platforms

• macOS: brew tap dweekly/ftr && brew install ftr
• Cargo: cargo install ftr (available after this release is published)

Example Output

Text Output

 7 [ISP     ] be3471.ccr41.lax04.atlas.cogentco.com (38.142.11.153) 21.831 ms [AS174 - COGENT]
 8 [ISP     ] be3243.ccr41.lax01.atlas.cogentco.com (154.54.88.166) 18.152 ms [AS174 - COGENT]
 9 [TRANSIT ] equinix-lax.yahoo.com (206.223.116.16) 19.847 ms
10 [TRANSIT ] unknown.yahoo.com (67.195.2.11) 20.122 ms
11 [DESTINATION] ae-4.pat2.pao.yahoo.com (216.115.100.101) 24.539 ms [AS36646 - YAHOO]
12 [DESTINATION] et-1-1-2.msr2.ne1.yahoo.com (216.115.107.76) 23.927 ms [AS36646 - YAHOO]
13 [DESTINATION] et-19-1-0.fab4-1-gdc.ne1.yahoo.com (98.138.105.166) 24.158 ms [AS36646 - YAHOO]
14 [DESTINATION] media-router-fp73.prod.media.vip.ne1.yahoo.com (98.137.148.22) 24.091 ms [AS36646 - YAHOO]

Target: yahoo.com (74.6.231.20) - Destination ASN: AS36646 (YAHOO, US)

JSON Output

{
  "destination_asn": {
    "asn": 36646,
    "name": "YAHOO",
    "country_code": "US"
  },
  "hops": [
    {
      "ttl": 8,
      "segment": "ISP",
      "asn_info": {
        "asn": 174,
        "name": "COGENT", 
        "country_code": "US"
      },
      "rtt_ms": 18.2
    },
    {
      "ttl": 9,
      "segment": "TRANSIT",
      "address": "206.223.116.16",
      "hostname": "equinix-lax.yahoo.com",
      "asn_info": null,
      "rtt_ms": 19.8
    },
    {
      "ttl": 11,
      "segment": "DESTINATION",
      "asn_info": {
        "asn": 36646,
        "name": "YAHOO",
        "country_code": "US"
      },
      "rtt_ms": 24.5
    }
  ]
}

See CHANGELOG.md for complete technical details.

v0.5.0

🎉 Major Release: Service-Oriented API

We're excited to announce ftr v0.5.0, a major release that completely redesigns the library API to be more intuitive, performant, and future-proof. This release introduces a service-oriented architecture that eliminates global state and provides a clean, instance-based API.

✨ Highlights

New Service-Oriented API

The library now uses a handle pattern with the Ftr struct as your main entry point:

use ftr::Ftr;

// Create an instance
let ftr = Ftr::new();

// Simple, intuitive methods
let result = ftr.trace("google.com").await?;
let asn_info = ftr.lookup_asn(ip).await?;
let hostname = ftr.lookup_rdns(ip).await?;
let public_ip = ftr.get_public_ip().await?;

IPv6 Future-Proofing

All APIs now accept IpAddr instead of Ipv4Addr, preparing for future IPv6 support.

True Parallel Execution

• Complete isolation between Ftr instances
• No global state or shared caches
• Tests run at 767% CPU utilization
• 200+ tests complete in 36.8 seconds

🚨 Breaking Changes

This is a major release with breaking API changes. The global functions have been removed in favor of instance methods.

Migration Example

// Old (v0.4.x)
let result = ftr::trace("google.com").await?;

// New (v0.5.0)
let ftr = Ftr::new();
let result = ftr.trace("google.com").await?;

📦 Installation

Cargo

cargo install ftr --version 0.5.0

Debian/Ubuntu

Download the .deb package from the assets below.

Windows

Download the Windows binary for your architecture from the assets below.

📝 Full Changelog

See CHANGELOG.md for the complete list of changes and detailed migration guide.

🙏 Acknowledgments

Thanks to all contributors and users who provided feedback on the API design!

v0.4.0

🚀 ftr v0.4.0 - Async-Only Architecture

Major release completing the transition to fully asynchronous architecture, removing ~4,800 lines of legacy code.

Added Alpine Linux support!

⚡ Breaking Changes

• Library is now async-only - Removed all synchronous implementations
• Eliminated --sync-mode CLI flag
• API requires async/await with tokio runtime
• Removed trace_sync() and related sync functions

🎯 Key Improvements

• Simplified Architecture: Single async implementation path
• Cleaner API: Consolidated into single TracerouteError type
• Smaller Codebase: ~4,800 lines removed
• Better Maintainability: No more dual implementation burden

📦 Installation

macOS (Homebrew)

brew tap dweekly/ftr && brew install ftr

Linux (Debian/Ubuntu/Alpine)

• Debian/Ubuntu: Download .deb package below (amd64 or arm64)
• Alpine: Build from source with cargo install ftr

Windows

Download .zip file below (x86_64 or aarch64)

From Source

cargo install ftr

🔄 Migration for Library Users

Before (v0.3.x):

let result = ftr::trace_sync("8.8.8.8")?;  // Removed

After (v0.4.0):

let result = ftr::trace("8.8.8.8").await?;  // Async only

CLI users: No changes needed, just remove --sync-mode if used.

📝 Full Changelog

See CHANGELOG.md for details.

v0.3.1

🚀 10x Faster Traceroute

ftr v0.3.1 delivers massive performance improvements through our new async implementation:

• 10x faster for short probe timeouts (100ms: 10s → 1s)
• Immediate response processing - no more polling delays
• Platform-optimized async engines for Windows, macOS, Linux, and BSD

Key Improvements

• 🏎️ Windows: 600ms+ faster startup (optimized ICMP API)
• 🍎 macOS: Fixed missing intermediate hops in async mode
• 🐧 Linux/BSD: Full async support with raw sockets
• 🔧 Better defaults: Async mode is now default (use --sync-mode for legacy)

Also Fixed

• Duplicate country codes in ASN display
• --no-enrich flag now works correctly
• Windows timeout handling improvements
• Various CI and test reliability issues

Installation

Windows: Download the .zip for your architecture below
macOS: brew tap dweekly/ftr && brew install ftr
Linux: Download the .deb package below
Cargo: cargo install ftr

---

See CHANGELOG.md for complete details.

v0.3.0: Major Library Refactoring

🚀 ftr v0.3.0 - Major Library Refactoring

This release represents a major transformation of ftr from a monolithic CLI application into a comprehensive Rust library with a clean API, while maintaining full backward compatibility for CLI users.

📦 Installation

macOS

brew tap dweekly/ftr && brew install ftr

Linux (Debian/Ubuntu)

# Add APT repository
sudo curl -sSL https://apt.networkweather.com/networkweather.noarmor.gpg -o /usr/share/keyrings/networkweather-archive-keyring.gpg
ARCH=$(dpkg --print-architecture)
echo "deb [signed-by=/usr/share/keyrings/networkweather-archive-keyring.gpg arch=$ARCH] https://apt.networkweather.com stable main" | sudo tee /etc/apt/sources.list.d/networkweather.list
sudo apt-get update && sudo apt-get install ftr

Cargo

cargo install ftr

✨ Major Changes

📚 Library Refactoring

• Complete transformation from monolithic CLI to modular library architecture
• High-level async API with trace() and trace_with_config() functions
• Comprehensive configuration via TracerouteConfigBuilder with fluent API
• Modular architecture with separate modules for ASN, DNS, public IP, and socket operations
• Full documentation for all public APIs with examples

🛡️ Structured Error Handling

• New TracerouteError enum for programmatic error handling
• InsufficientPermissions error with structured fields
• NotImplemented error for features like TCP traceroute
• Ipv6NotSupported error for IPv6 targets
• Clear, actionable error messages for all error types

⚡ Performance Improvements

• Global thread-safe caching for ASN and DNS lookups
• ASN cache with 24-hour TTL
• DNS cache with 1-hour TTL
• Parallel lookups during hop enrichment
• Significant performance boost for repeated operations

🔒 Type Safety Improvements

• Changed AsnInfo.asn from String to u32 for better type safety
• Added display_asn() helper method for formatting

🖥️ Platform Support

• Added OpenBSD support (identical behavior to FreeBSD)
• Improved platform-specific documentation
• CI optimization for FreeBSD

📖 Testing and Documentation

• Comprehensive unit tests for all modules
• Test coverage for main.rs CLI functionality
• Structured error handling tests with examples
• Documentation reorganization (moved to docs/ folder)
• Updated AGENTS.md with documentation index

📝 Example Library Usage

use ftr::{trace, TracerouteConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Simple trace
    let result = trace("google.com").await?;
    println\!("Found {} hops", result.hop_count());
    
    // Custom configuration
    let config = TracerouteConfig::builder()
        .target("1.1.1.1")
        .max_hops(20)
        .build()?;
    let result = ftr::trace_with_config(config).await?;
    
    Ok(())
}

⚠️ Breaking Changes

• AsnInfo.asn changed from String to u32 (library users only)
• CLI interface remains fully backward compatible

📋 Full Changelog

See CHANGELOG.md for detailed release notes.

🙏 Acknowledgments

Thanks to all contributors and users who provided feedback for this release!

🤖 Generated with Claude Code

v0.2.4

ftr v0.2.4 - FreeBSD Support 🎉

Summary

This release adds full FreeBSD support to ftr, making it a truly cross-platform traceroute tool. FreeBSD users can now enjoy the same fast, parallel traceroute experience with ASN lookups.

✨ New Features

FreeBSD Support

• Full FreeBSD compatibility for versions 13.x and 14.x
• Automatic platform detection with appropriate error messages
• FreeBSD-specific CI/CD using GitHub Actions
• Comprehensive FreeBSD tests including integration and smoke tests

Platform Improvements

• Generic root privilege checking that works across all platforms
• Better error messages when root privileges are required
• Improved warnings for missing dependencies (e.g., ca_root_nss on FreeBSD)

🐛 Bug Fixes

• Fixed IP_HDRINCL socket option for FreeBSD raw ICMP sockets
• Fixed public IP detection failures with helpful error messages
• Updated socket compatibility matrix for accurate platform support

📚 Documentation

• Added comprehensive FreeBSD installation instructions
• Updated platform compatibility documentation
• Added FreeBSD-specific build and runtime requirements
• Improved CI documentation for platform-specific testing

💻 Platform Notes

FreeBSD Requirements

• Root privileges required - FreeBSD doesn't support unprivileged ICMP
• Build dependencies: pkg install -y rust openssl perl5 pkgconf
• Runtime dependencies: pkg install -y ca_root_nss (for HTTPS)
• No DGRAM ICMP support - Uses raw sockets only

Usage on FreeBSD

# Must run as root
sudo ftr example.com

# Or make binary setuid root
sudo chown root:wheel /usr/local/bin/ftr
sudo chmod u+s /usr/local/bin/ftr

🔧 Technical Details

• Added has_non_root_capability() for generic platform capability detection
• Separated FreeBSD from macOS in socket compatibility matrix
• Added platform-specific error messages and suggestions
• Improved CI with conditional root/sudo handling

📦 Installation

FreeBSD

# Build from source
pkg install -y rust openssl perl5 pkgconf ca_root_nss
git clone https://github.com/dweekly/ftr
cd ftr
cargo build --release
sudo cp target/release/ftr /usr/local/bin/

Other Platforms

• macOS: brew install dweekly/ftr/ftr
• Linux: Download .deb packages from release assets
• Windows: Download from releases or build from source
• Cargo: cargo install ftr

🙏 Acknowledgments

Thanks to all contributors and testers who helped make FreeBSD support possible!

Full Changelog

See CHANGELOG.md for detailed changes.

v0.2.3

v0.2.3: Windows Support

This release brings full Windows support to ftr, making it truly cross-platform!

🎉 Major Features

• Windows support (Windows 10/11, including ARM64)
  • Complete Windows ICMP implementation using Windows ICMP API (IcmpCreateFile/IcmpSendEcho)
  • Native integration without requiring Npcap or WinPcap
  • Support for both x64 and ARM64 Windows architectures
  • Automatic Winsock initialization with thread-safe OnceLock pattern
  • Windows-specific error handling and status code mapping

🚀 Improvements

• Dependency updates:
  • Updated tokio from 1.46.1 to 1.47.0
  • Updated windows-sys from 0.59.0 to 0.60.2
• Enhanced CI/CD:
  • Optimized CI matrix to reduce redundant builds
  • Added Windows to the test matrix
  • Improved test resilience for CI environments
• Better cross-compilation:
  • Added vendored OpenSSL support for ARM64 builds
  • Fixed cross-compilation issues for Debian packages

🧪 Testing

• Added comprehensive Windows-specific integration tests
• Made integration tests more resilient to CI environment limitations
• All tests pass on Windows, macOS, and Linux

📦 Installation

Windows users can now:

Download the pre-built binary from this release (coming soon)

OR build from source:

git clone https://github.com/dweekly/ftr
cd ftr
cargo build --release

Binary will be at target/release/ftr.exe

OR install via cargo:

cargo install ftr

Linux users:

• Download the .deb package for your architecture (amd64 or arm64)
• Install with: `sudo dpkg -i ftr_0.2.3_*.deb`
• Or use the APT repository (see README)

macOS users:

brew tap dweekly/ftr && brew install ftr

🔧 Technical Details

• Uses native Windows ICMP API for better compatibility and performance
• No additional runtime requirements on Windows (no Npcap needed)
• Properly handles TTL setting through IP_OPTION_INFORMATION structure
• Maps Windows status codes to our ResponseType enum
• Thread-safe Winsock initialization ensures proper cleanup

📝 Full Changelog

Added

• Windows support (Windows 10/11, including ARM64)
  • Windows ICMP socket implementation using Windows ICMP API
  • Automatic Winsock initialization with thread-safe OnceLock pattern
  • Windows-specific error handling and status code mapping
  • Support for both x64 and ARM64 Windows architectures
• Windows-specific tests for socket functionality
• Vendored OpenSSL support for better cross-compilation

Changed

• Updated tokio from 1.46.1 to 1.47.0
• Updated windows-sys from 0.59.0 to 0.60.2
• Optimized CI test matrix for faster builds
• Improved test resilience for CI environments

Fixed

• ARM64 Debian package cross-compilation
• Windows CI test failures
• Test compatibility across different platforms

🙏 Contributors

Thank you to everyone who helped make Windows support possible, especially those who tested early builds and provided feedback!

---

Assets:

• `ftr_0.2.3_amd64.deb` - Debian package for x86_64 Linux
• `ftr_0.2.3_arm64.deb` - Debian package for ARM64 Linux

v0.2.2

ftr v0.2.2

🎉 New Features

Structured JSON Output

• Added --json flag for machine-readable output, perfect for integrating ftr into scripts and other tools
• JSON output includes version info, hop details, ASN information, and detected ISP data
• Example: ftr --json google.com

Verbose Mode

• Added -v/--verbose flag to show socket mode selection details
• Helps debug connectivity issues by showing which socket mode (Raw ICMP, DGRAM ICMP, or UDP) is being used
• Displays helpful fallback messages when permission issues occur

Port Selection for UDP Mode

• Added -p/--port option to specify target port for UDP traceroute (default: 443)
• Warns users when port is specified but won't be used (e.g., with ICMP protocol)
• Example: ftr --protocol udp --port 53 dns.google

Version Display

• Added --version flag to display the current version
• Version is also included in JSON output for programmatic version checking
• Development builds show "-UNRELEASED" suffix

🚀 Improvements

Smart Socket Mode Selection

• Implemented OS/protocol/privilege compatibility matrix
• Automatically selects the best available socket mode based on your OS and permissions
• Provides clear, OS-specific error messages when operations aren't supported
• Better fallback behavior when preferred modes aren't available

Enhanced Error Handling

• Input validation for --start-ttl (must be >= 1) and --probe-timeout-ms (must be > 0)
• Exit with proper error codes on failures (e.g., hostname resolution)
• More informative error messages for permission issues

🐛 Bug Fixes

• Fixed misaligned pointer dereference in UDP socket code that caused panics
• Fixed integration test timeouts in CI environments
• Fixed clippy warnings for better code quality

📦 Installation

Debian/Ubuntu (amd64 and arm64)

# Download the appropriate .deb file from the assets below
# For amd64:
sudo dpkg -i ftr_0.2.2_amd64.deb

# For arm64:
sudo dpkg -i ftr_0.2.2_arm64.deb

macOS (Homebrew)

brew tap dweekly/ftr && brew install ftr

From source (Cargo)

cargo install ftr

📝 Examples

JSON output for scripting

# Parse with jq to get just the ASN info
ftr --json google.com | jq '.hops[] | select(.asn_info \!= null) | .asn_info'

Verbose mode to debug issues

# See which socket mode is being used
ftr -v example.com

UDP traceroute with custom port

# Trace route to DNS server on port 53
ftr --protocol udp --port 53 8.8.8.8

🙏 Acknowledgments

Thanks to all contributors and users who provided feedback to make ftr better!

---

Full Changelog: v0.2.1...v0.2.2

v0.2.1

Fast TraceRoute (ftr) v0.2.1

This release introduces a major architectural improvement with the socket abstraction layer, adds support for multiple probes per TTL, and fixes critical issues with UDP traceroute on Linux.

🚀 New Features

Socket Abstraction Layer

• Unified interface for different socket types (Raw ICMP, DGRAM ICMP, UDP)
• Automatic fallback from raw sockets to DGRAM sockets when running without privileges
• Clean separation of concerns with factory pattern implementation

Multiple Probes per TTL

• New -q/--queries option to send multiple probes for each hop
• Helps identify load-balanced paths and improves reliability
• Default remains 1 probe per TTL for backward compatibility

Library Interface

• ftr can now be used as a Rust library for programmatic traceroute operations
• Clean public API exposing core types and socket creation functions

🐛 Bug Fixes

• Linux UDP traceroute: Fixed issue where only the final hop was shown
• Socket cloning: Improved error handling with proper error messages
• IP_RECVERR support: Enables privilege-free UDP traceroute on Linux

🔧 Improvements

• Test coverage increased from 6.89% to 13.31%
• CI/CD pipeline optimized from 5 minutes to 1 minute using pre-built binaries
• Enhanced pre-push hooks with security checks (cargo audit)
• Cleaned up temporary files and unused code

📦 Installation

Debian/Ubuntu (amd64/arm64)

# Add the APT repository
echo "deb [signed-by=/usr/share/keyrings/networkweather.gpg] https://apt.netweather.org stable main" | sudo tee /etc/apt/sources.list.d/networkweather.list

# Add the GPG key
curl -fsSL https://apt.netweather.org/networkweather.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/networkweather.gpg

# Install ftr
sudo apt update
sudo apt install ftr

From Source

cargo install --git https://github.com/dweekly/ftr --tag v0.2.1

📝 Changelog

See CHANGELOG.md for detailed changes.

🙏 Acknowledgments

Thanks to all contributors and testers who helped make this release possible!

ftr v0.2.0

What's Changed

Features

• Parallel ICMP traceroute with ASN lookup
• Support for IPv4 ICMP probing
• Early exit optimization when destination reached
• Automatic ISP detection
• Smart hop classification (LAN/ISP/BEYOND)
• Configurable timeouts and intervals

Improvements

• Fixed all clippy warnings
• Applied rustfmt formatting
• Fixed all unwrap() usage with proper error handling
• Updated all dependencies to latest versions
• Added comprehensive CI/CD workflow
• Added pre-commit and pre-push hooks
• Added Rust best practices and stricter linting
• Added code coverage with tarpaulin
• Added security audit and dependency checks
• Set MSRV to 1.82.0 (required by ICU dependencies)

Developer Experience

• Added AGENTS.md for AI agent guidelines
• Added RUST_BEST_PRACTICES.md
• Added TODO.md for tracking ongoing work
• Added comprehensive compliance checking

Full Changelog: v0.1.1...v0.2.0