X-Git-Url: https://code.octet-stream.net/netwatcher/blobdiff_plain/1c34fe3947aaf8af2d773d59bdebf19e17d78527..518e4dd38939e602cbfd19379d64b901cbcb96ce:/src/lib.rs diff --git a/src/lib.rs b/src/lib.rs index 61e4940..dfc4395 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,20 +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, }; +mod error; + #[cfg_attr(windows, path = "list_win.rs")] -#[cfg_attr(target_vendor = "apple", path = "list_mac.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; -mod util; - 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, @@ -24,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), @@ -31,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, @@ -39,19 +91,17 @@ 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, } -impl Update { - pub fn diff_from_previous(_prev: &Update) -> UpdateDiff { - // TODO: real calculation - UpdateDiff::default() - } -} - +/// What changed between one `Update` and the next. #[derive(Debug, Clone, PartialEq, Eq, Default)] pub struct UpdateDiff { pub added: Vec, @@ -59,6 +109,7 @@ pub struct UpdateDiff { pub modified: HashMap, } +/// 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, @@ -66,12 +117,85 @@ pub struct InterfaceDiff { pub addrs_removed: Vec, } -#[derive(Debug, Clone, PartialEq, Eq)] -pub enum Error { - // TODO: handle all cases with proper sources - 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 use list::list_interfaces; -pub use watch::{watch_interfaces, WatchHandle}; +/// 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, +} +/// 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) +} + +/// 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 }) +}