X-Git-Url: https://code.octet-stream.net/netwatcher/blobdiff_plain/0ecc1ee8ddfdf50d813fe18794eb27ac4ec0cf56..refs/heads/main:/src/lib.rs?ds=inline diff --git a/src/lib.rs b/src/lib.rs index af5b7af..dfc4395 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,13 +1,70 @@ +//! # netwatcher +//! +//! `netwatcher` is a cross-platform library for enumerating network interfaces and their +//! IP addresses, featuring the ability to watch for changes to those interfaces +//! _efficiently_. It uses platform-specific methods to detect when interface changes +//! have occurred instead of polling, which means that you find out about changes more +//! quickly and there is no CPU or wakeup overhead when nothing is happening. +//! +//! ## List example +//! +//! ``` +//! /// Returns a HashMap from ifindex (a `u32`) to an `Interface` struct +//! let interfaces = netwatcher::list_interfaces().unwrap(); +//! for i in interfaces.values() { +//! println!("interface {} has {} IPs", i.name, i.ips.len()); +//! } +//! ``` +//! +//! ## Watch example +//! +//! ``` +//! let handle = netwatcher::watch_interfaces(|update| { +//! // This callback will fire once immediately with the existing state +//! +//! // Update includes the latest snapshot of all interfaces +//! println!("Current interface map: {:#?}", update.interfaces); +//! +//! // The `UpdateDiff` describes changes since previous callback +//! // You can choose whether to use the snapshot, diff, or both +//! println!("ifindexes added: {:?}", update.diff.added); +//! println!("ifindexes removed: {:?}", update.diff.removed); +//! for (ifindex, if_diff) in update.diff.modified { +//! println!("Interface index {} has changed", ifindex); +//! println!("Added IPs: {:?}", if_diff.addrs_added); +//! println!("Removed IPs: {:?}", if_diff.addrs_removed); +//! } +//! }); +//! // keep `handle` alive as long as you want callbacks +//! // ... +//! drop(handle); +//! ``` + use std::{ - collections::HashMap, + collections::{HashMap, HashSet}, net::{IpAddr, Ipv4Addr, Ipv6Addr}, + ops::Sub, }; -#[cfg_attr(windows, path = "imp_win.rs")] -mod imp; +mod error; + +#[cfg_attr(windows, path = "list_win.rs")] +#[cfg_attr(unix, path = "list_unix.rs")] +mod list; + +#[cfg_attr(windows, path = "watch_win.rs")] +#[cfg_attr(target_vendor = "apple", path = "watch_mac.rs")] +#[cfg_attr( + any(target_os = "linux", target_os = "android"), + path = "watch_linux.rs" +)] +mod watch; type IfIndex = u32; +pub use error::Error; + +/// Information about one network interface at a point in time. #[derive(Debug, Clone, PartialEq, Eq)] pub struct Interface { pub index: u32, @@ -17,6 +74,7 @@ pub struct Interface { } impl Interface { + /// Helper to iterate over only the IPv4 addresses on this interface. pub fn ipv4_ips(&self) -> impl Iterator { self.ips.iter().filter_map(|ip| match ip { IpAddr::V4(v4) => Some(v4), @@ -24,6 +82,7 @@ impl Interface { }) } + /// Helper to iterate over only the IPv6 addresses on this interface. pub fn ipv6_ips(&self) -> impl Iterator { self.ips.iter().filter_map(|ip| match ip { IpAddr::V4(_) => None, @@ -32,40 +91,111 @@ impl Interface { } } +/// Information delivered via callback when a network interface change is detected. +/// +/// This contains up-to-date information about all interfaces, plus a diff which +/// details which interfaces and IP addresses have changed since the last callback. #[derive(Debug, Clone, PartialEq, Eq)] pub struct Update { pub interfaces: HashMap, pub diff: UpdateDiff, } -#[derive(Debug, Clone, PartialEq, Eq)] +/// What changed between one `Update` and the next. +#[derive(Debug, Clone, PartialEq, Eq, Default)] pub struct UpdateDiff { pub added: Vec, pub removed: Vec, pub modified: HashMap, } -#[derive(Debug, Clone, PartialEq, Eq)] +/// What changed within a single interface between updates, if it was present in both. +#[derive(Debug, Clone, PartialEq, Eq, Default)] pub struct InterfaceDiff { pub hw_addr_changed: bool, pub addrs_added: Vec, pub addrs_removed: Vec, } -#[derive(Debug, Clone, PartialEq, Eq)] -pub enum Error { - Internal, +#[derive(Default, PartialEq, Eq)] +struct List(HashMap); + +impl List { + fn diff_from(&self, prev: &List) -> UpdateDiff { + let prev_index_set: HashSet = prev.0.keys().cloned().collect(); + let curr_index_set: HashSet = self.0.keys().cloned().collect(); + let added = curr_index_set.sub(&prev_index_set).into_iter().collect(); + let removed = prev_index_set.sub(&curr_index_set).into_iter().collect(); + let mut modified = HashMap::new(); + for index in curr_index_set.intersection(&prev_index_set) { + if prev.0[index] == self.0[index] { + continue; + } + let prev_addr_set: HashSet<&IpAddr> = prev.0[index].ips.iter().collect(); + let curr_addr_set: HashSet<&IpAddr> = self.0[index].ips.iter().collect(); + let addrs_added: Vec = curr_addr_set + .sub(&prev_addr_set) + .iter() + .cloned() + .cloned() + .collect(); + let addrs_removed: Vec = prev_addr_set + .sub(&curr_addr_set) + .iter() + .cloned() + .cloned() + .collect(); + let hw_addr_changed = prev.0[index].hw_addr != self.0[index].hw_addr; + modified.insert( + *index, + InterfaceDiff { + hw_addr_changed, + addrs_added, + addrs_removed, + }, + ); + } + UpdateDiff { + added, + removed, + modified, + } + } } -pub fn list_interfaces() -> Result, Error> { - imp::list_interfaces() +/// A handle to keep alive as long as you wish to receive callbacks. +/// +/// If the callback is executing at the time the handle is dropped, drop will block until +/// the callback is finished and it's guaranteed that it will not be called again. +/// +/// Do not drop the handle from within the callback itself. It will probably deadlock. +pub struct WatchHandle { + _inner: watch::WatchHandle, } -pub struct WatchHandle; +/// Retrieve information about all enabled network interfaces and their IP addresses. +/// +/// This is a once-off operation. If you want to detect changes over time, see `watch_interfaces`. +pub fn list_interfaces() -> Result, Error> { + list::list_interfaces().map(|list| list.0) +} -pub fn watch_interfaces(callback: F) -> WatchHandle { - // stop current worker thread - // post this into a thread that will use it - drop(callback); - WatchHandle +/// Retrieve interface information and watch for changes, which will be delivered via callback. +/// +/// If setting up the watch is successful, this returns a `WatchHandle` which must be kept for +/// as long as the provided callback should operate. +/// +/// The callback will fire once immediately with an initial interface list, and a diff as if +/// there were originally no interfaces present. +/// +/// This function will return an error if there is a problem configuring the watcher, or if there +/// is an error retrieving the initial interface list. +/// +/// We assume that if listing the interfaces worked the first time, then it will continue to work +/// for as long as the watcher is running. If listing interfaces begins to fail later, those +/// failures will be swallowed and the callback will not be called for that change event. +pub fn watch_interfaces( + callback: F, +) -> Result { + watch::watch_interfaces(callback).map(|handle| WatchHandle { _inner: handle }) }