X-Git-Url: https://code.octet-stream.net/netwatcher/blobdiff_plain/1c34fe3947aaf8af2d773d59bdebf19e17d78527..487dfaa43e0370e63157dc302d55543cff2949cf:/src/lib.rs?ds=sidebyside diff --git a/src/lib.rs b/src/lib.rs index 61e4940..495b9e6 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,20 +1,28 @@ 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 +32,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 +40,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 +49,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 +67,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 +75,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, + } + } +} + +/// 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 use list::list_interfaces; -pub use watch::{watch_interfaces, 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 }) +}