Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
refactor(iroh-net): portmapper and network monitor are crates (#2855)
## Description The non-controversial part of the big network-utils refactor as described in the title. ## Breaking Changes <details><summary>Full <code>cargo public-api</code> diff report</summary> ``` Removed items from the public API ================================= -pub struct iroh_net::metrics::PortmapMetrics -pub iroh_net::metrics::PortmapMetrics::external_address_updated: iroh_metrics::core::Counter -pub iroh_net::metrics::PortmapMetrics::local_port_updates: iroh_metrics::core::Counter -pub iroh_net::metrics::PortmapMetrics::mapping_attempts: iroh_metrics::core::Counter -pub iroh_net::metrics::PortmapMetrics::mapping_failures: iroh_metrics::core::Counter -pub iroh_net::metrics::PortmapMetrics::pcp_available: iroh_metrics::core::Counter -pub iroh_net::metrics::PortmapMetrics::pcp_probes: iroh_metrics::core::Counter -pub iroh_net::metrics::PortmapMetrics::probes_started: iroh_metrics::core::Counter -pub iroh_net::metrics::PortmapMetrics::upnp_available: iroh_metrics::core::Counter -pub iroh_net::metrics::PortmapMetrics::upnp_gateway_updated: iroh_metrics::core::Counter -pub iroh_net::metrics::PortmapMetrics::upnp_probes: iroh_metrics::core::Counter -pub iroh_net::metrics::PortmapMetrics::upnp_probes_failed: iroh_metrics::core::Counter -impl core::default::Default for iroh_net::metrics::PortmapMetrics -impl core::default::Default for iroh_net::metrics::PortmapMetrics -pub fn iroh_net::metrics::PortmapMetrics::default() -> Self -pub fn iroh_net::metrics::PortmapMetrics::default() -> Self -impl iroh_metrics::core::Metric for iroh_net::metrics::PortmapMetrics -impl iroh_metrics::core::Metric for iroh_net::metrics::PortmapMetrics -pub fn iroh_net::metrics::PortmapMetrics::name() -> &'static str -pub fn iroh_net::metrics::PortmapMetrics::name() -> &'static str -impl struct_iterable_internal::Iterable for iroh_net::metrics::PortmapMetrics -impl struct_iterable_internal::Iterable for iroh_net::metrics::PortmapMetrics -pub fn iroh_net::metrics::PortmapMetrics::iter<'a>(&'a self) -> alloc::vec::into_iter::IntoIter<(&'static str, &'a dyn core::any::Any)> -pub fn iroh_net::metrics::PortmapMetrics::iter<'a>(&'a self) -> alloc::vec::into_iter::IntoIter<(&'static str, &'a dyn core::any::Any)> -pub mod iroh_net::net -pub mod iroh_net::net::ip -pub struct iroh_net::net::ip::LocalAddresses -pub iroh_net::net::ip::LocalAddresses::loopback: alloc::vec::Vec<core::net::ip_addr::IpAddr> -pub iroh_net::net::ip::LocalAddresses::regular: alloc::vec::Vec<core::net::ip_addr::IpAddr> -impl iroh_net::net::ip::LocalAddresses -pub fn iroh_net::net::ip::LocalAddresses::new() -> Self -impl core::default::Default for iroh_net::net::ip::LocalAddresses -pub fn iroh_net::net::ip::LocalAddresses::default() -> Self -pub const fn iroh_net::net::ip::is_unicast_link_local(addr: core::net::ip_addr::Ipv6Addr) -> bool -pub mod iroh_net::net::netmon -pub struct iroh_net::net::netmon::CallbackToken(_) -pub struct iroh_net::net::netmon::Monitor -impl iroh_net::net::netmon::Monitor -pub async fn iroh_net::net::netmon::Monitor::network_change(&self) -> anyhow::Result<()> -pub async fn iroh_net::net::netmon::Monitor::new() -> anyhow::Result<Self> -pub async fn iroh_net::net::netmon::Monitor::subscribe<F>(&self, callback: F) -> anyhow::Result<iroh_net::net::netmon::CallbackToken> where F: core::ops::function::Fn(bool) -> futures_lite::future::Boxed<()> + 'static + core::marker::Sync + core::marker::Send -pub async fn iroh_net::net::netmon::Monitor::unsubscribe(&self, token: iroh_net::net::netmon::CallbackToken) -> anyhow::Result<()> -impl core::ops::drop::Drop for iroh_net::net::netmon::Monitor -pub fn iroh_net::net::netmon::Monitor::drop(&mut self) -pub enum iroh_net::net::IpFamily -pub iroh_net::net::IpFamily::V4 -pub iroh_net::net::IpFamily::V6 -impl iroh_net::net::IpFamily -pub fn iroh_net::net::IpFamily::local_addr(&self) -> core::net::ip_addr::IpAddr -pub fn iroh_net::net::IpFamily::unspecified_addr(&self) -> core::net::ip_addr::IpAddr -impl core::convert::From<core::net::ip_addr::IpAddr> for iroh_net::net::IpFamily -pub fn iroh_net::net::IpFamily::from(value: core::net::ip_addr::IpAddr) -> Self -impl core::convert::From<iroh_net::net::IpFamily> for socket2::Domain -pub fn socket2::Domain::from(value: iroh_net::net::IpFamily) -> Self -pub struct iroh_net::net::UdpSocket(_) -impl iroh_net::net::UdpSocket -pub fn iroh_net::net::UdpSocket::bind(network: iroh_net::net::IpFamily, port: u16) -> anyhow::Result<Self> -pub fn iroh_net::net::UdpSocket::bind_full(addr: impl core::convert::Into<core::net::socket_addr::SocketAddr>) -> anyhow::Result<Self> -pub fn iroh_net::net::UdpSocket::bind_local(network: iroh_net::net::IpFamily, port: u16) -> anyhow::Result<Self> -pub fn iroh_net::net::UdpSocket::bind_local_v4(port: u16) -> anyhow::Result<Self> -pub fn iroh_net::net::UdpSocket::bind_local_v6(port: u16) -> anyhow::Result<Self> -pub fn iroh_net::net::UdpSocket::bind_v4(port: u16) -> anyhow::Result<Self> -pub fn iroh_net::net::UdpSocket::bind_v6(port: u16) -> anyhow::Result<Self> -impl core::convert::From<tokio::net::udp::UdpSocket> for iroh_net::net::UdpSocket -pub fn iroh_net::net::UdpSocket::from(socket: tokio::net::udp::UdpSocket) -> Self -impl core::ops::deref::Deref for iroh_net::net::UdpSocket -pub type iroh_net::net::UdpSocket::Target = tokio::net::udp::UdpSocket -pub fn iroh_net::net::UdpSocket::deref(&self) -> &Self::Target -impl core::ops::drop::Drop for iroh_net::net::UdpSocket -pub fn iroh_net::net::UdpSocket::drop(&mut self) -impl std::os::fd::owned::AsFd for iroh_net::net::UdpSocket -pub fn iroh_net::net::UdpSocket::as_fd(&self) -> std::os::fd::owned::BorrowedFd<'_> -pub mod iroh_net::portmapper -pub struct iroh_net::portmapper::Client -impl iroh_net::portmapper::Client -pub fn iroh_net::portmapper::Client::deactivate(&self) -pub fn iroh_net::portmapper::Client::new(config: iroh_net::portmapper::Config) -> Self -pub fn iroh_net::portmapper::Client::probe(&self) -> tokio::sync::oneshot::Receiver<anyhow::Result<iroh_net::portmapper::ProbeOutput, alloc::string::String>> -pub fn iroh_net::portmapper::Client::procure_mapping(&self) -pub fn iroh_net::portmapper::Client::update_local_port(&self, local_port: core::num::nonzero::NonZeroU16) -pub fn iroh_net::portmapper::Client::watch_external_address(&self) -> tokio::sync::watch::Receiver<core::option::Option<core::net::socket_addr::SocketAddrV4>> -impl core::default::Default for iroh_net::portmapper::Client -pub fn iroh_net::portmapper::Client::default() -> Self -pub struct iroh_net::portmapper::Config -pub iroh_net::portmapper::Config::enable_nat_pmp: bool -pub iroh_net::portmapper::Config::enable_pcp: bool -pub iroh_net::portmapper::Config::enable_upnp: bool -impl core::default::Default for iroh_net::portmapper::Config -pub fn iroh_net::portmapper::Config::default() -> Self -pub struct iroh_net::portmapper::Metrics -pub iroh_net::portmapper::Metrics::external_address_updated: iroh_metrics::core::Counter -pub iroh_net::portmapper::Metrics::local_port_updates: iroh_metrics::core::Counter -pub iroh_net::portmapper::Metrics::mapping_attempts: iroh_metrics::core::Counter -pub iroh_net::portmapper::Metrics::mapping_failures: iroh_metrics::core::Counter -pub iroh_net::portmapper::Metrics::pcp_available: iroh_metrics::core::Counter -pub iroh_net::portmapper::Metrics::pcp_probes: iroh_metrics::core::Counter -pub iroh_net::portmapper::Metrics::probes_started: iroh_metrics::core::Counter -pub iroh_net::portmapper::Metrics::upnp_available: iroh_metrics::core::Counter -pub iroh_net::portmapper::Metrics::upnp_gateway_updated: iroh_metrics::core::Counter -pub iroh_net::portmapper::Metrics::upnp_probes: iroh_metrics::core::Counter -pub iroh_net::portmapper::Metrics::upnp_probes_failed: iroh_metrics::core::Counter -pub struct iroh_net::portmapper::ProbeOutput -pub iroh_net::portmapper::ProbeOutput::nat_pmp: bool -pub iroh_net::portmapper::ProbeOutput::pcp: bool -pub iroh_net::portmapper::ProbeOutput::upnp: bool -impl iroh_net::portmapper::ProbeOutput -pub fn iroh_net::portmapper::ProbeOutput::all_available(&self) -> bool -pub struct iroh_net::portmapper::Service Changed items in the public API =============================== -pub async fn iroh_net::netcheck::Client::get_report(&mut self, dm: iroh_net::relay::RelayMap, stun_conn4: core::option::Option<alloc::sync::Arc<iroh_net::net::UdpSocket>>, stun_conn6: core::option::Option<alloc::sync::Arc<iroh_net::net::UdpSocket>>) -> anyhow::Result<alloc::sync::Arc<iroh_net::netcheck::Report>> +pub async fn iroh_net::netcheck::Client::get_report(&mut self, dm: iroh_net::relay::RelayMap, stun_conn4: core::option::Option<alloc::sync::Arc<netwatch::udp::UdpSocket>>, stun_conn6: core::option::Option<alloc::sync::Arc<netwatch::udp::UdpSocket>>) -> anyhow::Result<alloc::sync::Arc<iroh_net::netcheck::Report>> -pub async fn iroh_net::netcheck::Client::get_report_channel(&mut self, dm: iroh_net::relay::RelayMap, stun_conn4: core::option::Option<alloc::sync::Arc<iroh_net::net::UdpSocket>>, stun_conn6: core::option::Option<alloc::sync::Arc<iroh_net::net::UdpSocket>>) -> anyhow::Result<tokio::sync::oneshot::Receiver<anyhow::Result<alloc::sync::Arc<iroh_net::netcheck::Report>>>> +pub async fn iroh_net::netcheck::Client::get_report_channel(&mut self, dm: iroh_net::relay::RelayMap, stun_conn4: core::option::Option<alloc::sync::Arc<netwatch::udp::UdpSocket>>, stun_conn6: core::option::Option<alloc::sync::Arc<netwatch::udp::UdpSocket>>) -> anyhow::Result<tokio::sync::oneshot::Receiver<anyhow::Result<alloc::sync::Arc<iroh_net::netcheck::Report>>>> -pub fn iroh_net::netcheck::Client::new(port_mapper: core::option::Option<iroh_net::portmapper::Client>, dns_resolver: iroh_net::dns::DnsResolver) -> anyhow::Result<Self> +pub fn iroh_net::netcheck::Client::new(port_mapper: core::option::Option<portmapper::Client>, dns_resolver: hickory_resolver::async_resolver::TokioAsyncResolver) -> anyhow::Result<Self> -pub iroh_net::netcheck::Report::portmap_probe: core::option::Option<iroh_net::portmapper::ProbeOutput> +pub iroh_net::netcheck::Report::portmap_probe: core::option::Option<portmapper::ProbeOutput> Added items to the public API ============================= +pub use iroh_net::metrics::PortmapMetrics ``` </details> - `iroh_net::net` is removed. The unchanged functionality can be found in the published crate `netwatch` which the `n0 team` will keep maintaining. This has been moved to allow serving a more general public. - `iroh_net::portmapper` is removed. The unchanged functionality can be found in the published crate `portmapper` which the `n0 team` will keep maintaining. This has been moved to allow serving a more general public. - The origin of `iroh_net::metrics::PortmapMetrics` is changed. The type is no longer internal to `iroh-net` but re-exported from `portmapper` - Some `netcheck` functions now require `netwatcher` and `portmapper` parameters that are _not_ currently re-exported. `netcheck` will be moved to it's own crate as well so this intermediate state is acceptable for the time being ## Notes & open questions - **what used to be called net** has a very small API that might not be as useful to the general public. It only gives a `subscribe` to changes that only reports if the change "is major" without any description of what being major is or the origin of the change. Providing a more detailed API and better docs is something we can do later, but it's worth noticing. - **portmapper** might be good to start doing the move to `thiserror` here since it's very clearly isolated. Maybe turn on/off as features specific protocols. All this, again, to make it more attractive/useful to a wider audience. - there is `netwatcher`, which I found by looking for what I thought was a natural name to this (`netwatch`) and it has the API I'd imagine this crate should provide. https://crates.io/crates/netwatcher ## Change checklist - [x] Self-review. - [x] Documentation updates following the [style guide](https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#appendix-a-full-conventions-text), if relevant. - [x] Tests if relevant. - [x] All breaking changes documented.
- Loading branch information
1 parent
fe684c2
commit fad3e24