ftr 0.7.0

A fast, parallel ICMP traceroute with ASN lookup, reverse DNS, and ISP detection
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155

//! Example demonstrating proper error handling with ftr's structured errors
//!
//! Run with: cargo run --example error_handling

use ftr::{Ftr, ProbeProtocol, SocketMode, TracerouteConfigBuilder, TracerouteError};

#[tokio::main]
async fn main() {
    println!("ftr Error Handling Example\n");

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

    // Example 1: Handle permission errors gracefully
    println!("1. Testing permission handling:");
    let config = TracerouteConfigBuilder::new()
        .target("google.com")
        .socket_mode(SocketMode::Raw) // Requires root
        .build()
        .unwrap();

    match ftr.trace_with_config(config).await {
        Ok(result) => {
            println!("  Traceroute succeeded! Found {} hops", result.hop_count());
        }
        Err(TracerouteError::InsufficientPermissions {
            required,
            suggestion,
        }) => {
            println!("  Permission error detected!");
            println!("  - Required: {}", required);
            println!("  - Suggestion: {}", suggestion);
            println!("  - Action: Could retry with UDP mode or prompt for sudo");
        }
        Err(e) => {
            println!("  Other error: {}", e);
        }
    }

    // Example 2: Handle unimplemented features
    println!("\n2. Testing unimplemented feature handling:");
    let config = TracerouteConfigBuilder::new()
        .target("google.com")
        .protocol(ProbeProtocol::Tcp)
        .build()
        .unwrap();

    match ftr.trace_with_config(config).await {
        Ok(_) => println!("  Unexpected success!"),
        Err(TracerouteError::NotImplemented { feature }) => {
            println!("  Feature not implemented: {}", feature);
            println!("  - Action: Could fall back to ICMP or UDP protocol");
        }
        Err(e) => println!("  Other error: {}", e),
    }

    // Example 3: Handle IPv6 not supported
    println!("\n3. Testing IPv6 handling:");
    match ftr.trace("2001:4860:4860::8888").await {
        Ok(_) => println!("  Unexpected success!"),
        Err(TracerouteError::Ipv6NotSupported) => {
            println!("  IPv6 not supported yet");
            println!("  - Action: Could resolve to IPv4 or inform user");
        }
        Err(e) => println!("  Other error: {}", e),
    }

    // Example 4: Handle resolution errors
    println!("\n4. Testing DNS resolution error handling:");
    match ftr.trace("this-definitely-does-not-exist.invalid").await {
        Ok(_) => println!("  Unexpected success!"),
        Err(TracerouteError::ResolutionError(msg)) => {
            println!("  DNS resolution failed: {}", msg);
            println!("  - Action: Could suggest checking network or spelling");
        }
        Err(e) => println!("  Other error: {}", e),
    }

    // Example 5: Handle configuration errors
    println!("\n5. Testing configuration error handling:");
    let config_result = TracerouteConfigBuilder::new()
        .target("google.com")
        .start_ttl(10)
        .max_hops(5) // Invalid: max_hops < start_ttl
        .build();

    match config_result {
        Ok(_) => println!("  Unexpected success!"),
        Err(msg) => {
            println!("  Configuration error: {}", msg);
            println!("  - Action: Show validation rules to user");
        }
    }

    // Example 6: Programmatic fallback on errors
    println!("\n6. Demonstrating automatic fallback:");
    let target = "google.com";

    // Try different modes in order of preference
    let modes = vec![
        (SocketMode::Raw, "Raw socket (fastest)"),
        (SocketMode::Dgram, "ICMP datagram"),
        // UDP doesn't need a socket mode specification
    ];

    let mut success = false;
    for (mode, desc) in modes {
        println!("  Trying {}...", desc);
        let config = TracerouteConfigBuilder::new()
            .target(target)
            .socket_mode(mode)
            .max_hops(10)
            .build()
            .unwrap();

        match ftr.trace_with_config(config).await {
            Ok(result) => {
                println!(
                    "  ✓ Success with {}! Found {} hops",
                    desc,
                    result.hop_count()
                );
                success = true;
                break;
            }
            Err(TracerouteError::InsufficientPermissions { .. }) => {
                println!("  ✗ Insufficient permissions for {}", desc);
            }
            Err(e) => {
                println!("  ✗ Failed with {}: {}", desc, e);
            }
        }
    }

    if !success {
        println!("  Trying UDP mode (no special permissions)...");
        let config = TracerouteConfigBuilder::new()
            .target(target)
            .protocol(ProbeProtocol::Udp)
            .max_hops(10)
            .build()
            .unwrap();

        match ftr.trace_with_config(config).await {
            Ok(result) => {
                println!("  ✓ Success with UDP! Found {} hops", result.hop_count());
            }
            Err(e) => {
                println!("  ✗ All methods failed. Last error: {}", e);
            }
        }
    }

    println!("\nError handling example complete!");
}