hayate 5.1.1

High-performance completion-based QUIC transfer engine.
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
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170

//! Utilities for resolving and querying local network interface addresses and subnets.
//!
//! This module helps library users discover local IPv4 and IPv6 addresses on active
//! network interfaces without requiring manual network configuration. It combines
//! operating system interface queries with UDP socket route probes to find the most
//! reliable local address candidates.

use std::net::{IpAddr, Ipv4Addr, SocketAddr, UdpSocket};

/// Retrieves a list of all usable, non-loopback local IPv4 addresses.
///
/// This function queries network interfaces using operating-system APIs,
/// checks active routing tables, and initiates UDP socket connection probes to
/// compile a list of all IPv4 addresses that can be used for direct local communication.
///
/// Duplicate entries are filtered, and loopback, multicast, or unroutable addresses
/// are excluded.
///
/// # Examples
///
/// ```
/// use hayate::local_addr::local_ipv4s;
///
/// let ips = local_ipv4s();
/// for ip in ips {
///     println!("Active local IPv4: {ip}");
/// }
/// ```
#[must_use]
pub fn local_ipv4s() -> Vec<Ipv4Addr> {
    let mut ips = interface_ipv4s();

    for ip in route_probe_ipv4s() {
        if !ips.contains(&ip) {
            ips.push(ip);
        }
    }

    ips
}

/// Retrieves a list of the base network addresses (subnets) for all local interfaces.
///
/// The returned `Ipv4Addr`s represent the subnet prefix (e.g. `192.168.1.0` for `192.168.1.45`),
/// which is useful for scanning or network discovery tasks on local networks.
///
/// # Examples
///
/// ```
/// use hayate::local_addr::local_subnets;
///
/// let subnets = local_subnets();
/// for subnet in subnets {
///     println!("Available local subnet base: {subnet}");
/// }
/// ```
#[must_use]
pub fn local_subnets() -> Vec<Ipv4Addr> {
    let mut bases = Vec::new();
    for ip in local_ipv4s() {
        let o = ip.octets();
        let base = Ipv4Addr::new(o[0], o[1], o[2], 0);
        if !bases.contains(&base) {
            bases.push(base);
        }
    }
    bases
}

/// Gets the primary local IPv4 address of the machine, if any.
///
/// This returns the first usable, non-loopback IPv4 address discovered.
///
/// # Examples
///
/// ```
/// use hayate::local_addr::primary_local_ipv4;
///
/// if let Some(ip) = primary_local_ipv4() {
///     println!("Primary local IPv4 is: {ip}");
/// } else {
///     println!("No local network IPv4 address found.");
/// }
/// ```
#[must_use]
pub fn primary_local_ipv4() -> Option<Ipv4Addr> {
    local_ipv4s().into_iter().next()
}

/// Checks if a given IP address belongs to one of the local machine's active network interfaces.
///
/// Supports both IPv4 and IPv6 checks.
///
/// # Examples
///
/// ```
/// use std::net::IpAddr;
/// use hayate::local_addr::is_local_ip;
///
/// let test_ip: IpAddr = "127.0.0.1".parse().unwrap();
/// assert!(!is_local_ip(test_ip)); // Loopback is excluded by default
/// ```
#[must_use]
pub fn is_local_ip(ip: IpAddr) -> bool {
    if let Ok(ifaces) = if_addrs::get_if_addrs() {
        return ifaces
            .into_iter()
            .any(|iface| !iface.is_loopback() && iface.ip() == ip);
    }
    false
}

/// Queries network interfaces for IPv4 addresses.
fn interface_ipv4s() -> Vec<Ipv4Addr> {
    let mut ips = Vec::new();
    if let Ok(ifaces) = if_addrs::get_if_addrs() {
        for iface in ifaces {
            if iface.is_loopback() {
                continue;
            }
            if let if_addrs::IfAddr::V4(ifv4) = iface.addr
                && is_usable_local_ipv4(ifv4.ip)
                && !ips.contains(&ifv4.ip)
            {
                ips.push(ifv4.ip);
            }
        }
    }
    ips
}

/// Performs active UDP connection probes to common targets to deduce the local routing IP.
fn route_probe_ipv4s() -> Vec<Ipv4Addr> {
    let mut ips = Vec::new();
    let probes = [
        SocketAddr::from(([8, 8, 8, 8], 80)),
        SocketAddr::from(([1, 1, 1, 1], 80)),
        SocketAddr::from(([192, 168, 1, 1], 80)),
        SocketAddr::from(([10, 0, 0, 1], 80)),
    ];

    for target in probes {
        let Ok(socket) = UdpSocket::bind("0.0.0.0:0") else {
            continue;
        };
        if socket.connect(target).is_err() {
            continue;
        }
        let Ok(local_addr) = socket.local_addr() else {
            continue;
        };
        let IpAddr::V4(ip) = local_addr.ip() else {
            continue;
        };
        if is_usable_local_ipv4(ip) && !ips.contains(&ip) {
            ips.push(ip);
        }
    }

    ips
}

/// Returns true if the IP is a valid routable local address.
fn is_usable_local_ipv4(ip: Ipv4Addr) -> bool {
    !ip.is_loopback()
        && !ip.is_unspecified()
        && !ip.is_multicast()
        && !ip.is_broadcast()
        && !ip.is_documentation()
}