open-net 0.3.5

A cross-platform async networking library for Rust with HTTP and WebSocket clients, network status monitoring, configurable retries, WebSocket reconnection and heartbeats, and managed client lifecycles. Reuse common networking infrastructure across applications to avoid repeated implementation and debugging, helping save development time and AI coding tokens.
Documentation
use std::fmt;
use std::sync::Arc;
use std::time::Duration;

use crate::net_status::NetworkSnapshot;
use crate::net_status::NetworkStatusContext;
use crate::net_status::{
    NetworkEvent, NetworkEventOptions, NetworkObservation, NetworkRefreshResult,
};
use crate::subscription::{CallbackContext, EventReceiver, StateReceiver, Subscription};
use crate::{LogType, Result};

use crate::module::net_status::inner::facade::NetworkObservationOwner;

/// An independent view of the engine's shared network monitor.
/// Clones share this view's lifecycle; other named views remain independent.
#[derive(Clone)]
pub struct NetStatusClient {
    inner: Arc<NetworkObservationOwner>,
}

impl NetStatusClient {
    pub(crate) fn new(context: NetworkStatusContext) -> Result<Self> {
        Ok(Self {
            inner: NetworkObservationOwner::new(context)?,
        })
    }

    /// Start monitoring and await the first coherent observation.
    /// Repeated calls share the active monitor and its initialization result.
    pub async fn start(&self) -> Result<NetworkSnapshot> {
        crate::log_t!(LogType::Engine; "net_status.start");
        let result = self.inner.start().await;
        if let Err(error) = &result {
            crate::module::net_status::logging::emit_monitor_error("start", error);
        }
        result
    }

    /// Stop monitoring while keeping subscriptions alive for a later restart.
    pub async fn stop(&self) -> Result<()> {
        crate::log_t!(LogType::Engine; "net_status.stop");
        self.inner.request_stop()?;
        self.inner.wait_cleanup().await
    }

    /// Permanently close monitoring and publish its final Closed snapshot.
    pub async fn shutdown(&self) -> Result<()> {
        crate::log_t!(LogType::Engine; "net_status.shutdown");
        self.inner.request_close();
        self.inner.wait_cleanup().await
    }

    /// Read the latest coherent snapshot, including an inactive or final state.
    pub fn snapshot(&self) -> Result<NetworkSnapshot> {
        self.inner.snapshot()
    }

    /// Explicitly observe Windows Wi-Fi SSID or NLM network display names.
    ///
    /// This is the only monitoring API that enables name collection. It does
    /// not start connectivity monitoring or modify connectivity snapshots,
    /// HTTP observations, or network events. The returned observer owns its
    /// name demand and exposes a separate latest-value stream.
    ///
    /// A stopped connectivity client can observe names. `stop()` affects only
    /// connectivity; client shutdown/destroy and engine shutdown close names
    /// too. Drop requests cancellation; await the observer's `close()` to
    /// confirm that cached/pending values and in-flight work have retired.
    /// Already returned application-owned copies cannot be recalled.
    ///
    /// Invalid options are rejected before lifecycle checks. Closed clients
    /// reject admission; other platforms return `Unsupported`. Creation on
    /// Windows does not wait for an OS query. `recv()` starts with Pending
    /// unless the observer has already closed; `snapshot()` reads the latest
    /// state, which may already contain a result. Sampling errors are delivered
    /// on the name stream.
    pub fn observe_network_names(
        &self,
        options: crate::net_status::NetworkNameOptions,
    ) -> Result<crate::net_status::NetworkNameObserver> {
        self.inner.observe_network_names(options)
    }

    /// Collect a fresh LAN IPv4 inventory using [`crate::network::lan_ipv4_snapshot`].
    ///
    /// Synchronous OS query: it blocks this caller and needs no caller runtime.
    /// Stopped, Starting, Running and ordinary monitoring Failed states permit
    /// the query; it neither starts monitoring nor requires Internet access.
    /// It never changes the cached network snapshot, revisions or event stream.
    /// Existing network events do not guarantee notification of LAN-only changes.
    ///
    /// A closed client (including its clones), destroyed named client, or closing
    /// engine rejects new queries with Closed. A query admitted before closing
    /// may finish normally; shutdown does not wait for this caller's read-only
    /// query, which owns no monitored resources. Prefer a blocking worker when
    /// calling from async/UI code.
    pub fn query_lan_ipv4(&self) -> Result<crate::network::LanIpv4Snapshot> {
        self.inner.admit_lan_query()?;
        crate::network::lan_ipv4_snapshot()
    }

    /// Subscribe to the current snapshot and later changes across stop/restart.
    pub fn subscribe(&self) -> Result<StateReceiver<NetworkSnapshot>> {
        crate::log_t!(LogType::Engine; "net_status.subscribe");
        self.inner.subscribe_terminal()
    }

    /// Observe the same snapshots as an asynchronous subscription on the shared
    /// callback pool. Keep the returned owner alive while observing changes.
    pub fn on_change<F>(&self, callback: F) -> Result<Subscription>
    where
        F: Fn(CallbackContext, Result<NetworkSnapshot>) + Send + Sync + 'static,
    {
        self.subscribe()?.into_callback(callback)
    }

    /// Subscribe atomically to an initial baseline and ordered committed events.
    /// Each subscription has its own bounded queue. Overflow drains the queued
    /// prefix, reports a failure, and ends that subscription; subscribe again to
    /// establish a fresh baseline. Initial and lifecycle entries use capacity.
    pub fn subscribe_events(
        &self,
        options: NetworkEventOptions,
    ) -> Result<EventReceiver<NetworkEvent>> {
        crate::log_t!(LogType::Engine; "net_status.subscribe_events",
            "capacity|max_bytes", options.capacity, options.max_bytes);
        self.inner.subscribe_events(options)
    }

    /// Observe the same ordered events with a serial callback on the shared
    /// callback pool. Retain the returned Subscription while observing events.
    pub fn on_event<F>(&self, options: NetworkEventOptions, callback: F) -> Result<Subscription>
    where
        F: Fn(CallbackContext, std::result::Result<NetworkEvent, crate::error::ReceiveError>)
            + Send
            + Sync
            + 'static,
    {
        self.subscribe_events(options)?.into_callback(callback)
    }

    /// Observe ordered events and automatically reestablish an atomic baseline
    /// after a bounded queue overflows. The same logical subscription and
    /// callback context ID survive every recovery and monitor stop/restart.
    ///
    /// The retained prefix is delivered first, then `Reconciled`, then events
    /// after that baseline. Callbacks are serial across recovery. Only queue
    /// overflow is recovered; other errors terminate the observer, and callback
    /// panic stops delivery. Dispatch failures cannot always invoke the callback
    /// again, but remain observable through `Subscription::close` and logs.
    ///
    /// Unsubscribe cancels future callback admission and recovery. On success,
    /// [`Subscription::close`] additionally confirms that the driver and admitted
    /// callbacks have retired. Polling close inside a subscription callback
    /// follows its shared context rule: it unsubscribes and returns `InvalidInput`
    /// without confirming retirement; use [`CallbackContext::unsubscribe`] there.
    pub fn on_recoverable_event<F>(
        &self,
        options: NetworkEventOptions,
        callback: F,
    ) -> Result<Subscription>
    where
        F: Fn(CallbackContext, Result<NetworkObservation>) + Send + Sync + 'static,
    {
        crate::log_t!(LogType::Engine; "net_status.on_recoverable_event",
            "capacity|max_bytes|callback", options.capacity, options.max_bytes, "provided");
        self.inner.on_recoverable_event(options, callback)
    }

    /// Compatibility alias for [`Self::refresh_reachability`].
    ///
    /// This method no longer queries, caches, or publishes network names.
    #[deprecated(note = "use refresh_reachability; network names require observe_network_names")]
    pub async fn refresh(&self, timeout: Duration) -> Result<NetworkRefreshResult> {
        crate::log_t!(LogType::Engine; "net_status.refresh", "timeout", timeout);
        crate::module::net_status::inner::refresh::refresh(self.inner.clone(), timeout).await
    }

    /// Query and commit fresh Windows reachability without querying a name.
    /// Uses a separate bounded worker so a slow or failed network-name query
    /// cannot block this query or background reachability monitoring. The IP
    /// stack retains its latest background value. The compatibility name field
    /// is always None, with NotCollected provenance and no name diagnostics.
    /// Requires Running and a positive timeout covering admission, sampling and
    /// commit. Dropping this future invalidates uncommitted results. A newer
    /// committed reachability sample supersedes an older query with Cancelled.
    /// After input and lifecycle validation, other platforms return Unsupported.
    /// As with [`Self::refresh`], the timeout is a result-validity budget, not a
    /// hard real-time return deadline; success does not await observer callbacks.
    pub async fn refresh_reachability(&self, timeout: Duration) -> Result<NetworkRefreshResult> {
        crate::log_t!(LogType::Engine; "net_status.refresh_reachability", "timeout", timeout);
        crate::module::net_status::inner::refresh::refresh_reachability(self.inner.clone(), timeout)
            .await
    }

    /// Compatibility alias for [`Self::refresh_reachability_blocking`].
    ///
    /// This no longer queries names. It has the same
    /// sampling, field provenance and lifecycle checks. A positive timeout is
    /// required; after input and lifecycle validation, other platforms return
    /// `Unsupported`. Errors never silently fall back to [`Self::snapshot`].
    /// Expired samples cannot commit, but scheduling and lock contention can
    /// delay the return beyond the budget; it is not a hard real-time bound.
    /// Success means the sample was committed, not that observers have finished.
    ///
    /// Blocks the calling thread. Ordinary threads, external Tokio runtimes,
    /// nested futures executors and the SDK's separate subscription callback
    /// pool are supported; the SDK drives its own timers and sampling workers.
    /// Prefer [`Self::refresh_reachability`] in async code and avoid blocking a UI thread.
    /// SDK management-runtime threads (including its blocking pool) and sampling
    /// threads are rejected before any query with `InvalidInput`, stage
    /// `NetworkMonitor`, and field `network_status.refresh_blocking.context`.
    /// Entering an SDK runtime context alone does not trigger this rejection.
    #[deprecated(
        note = "use refresh_reachability_blocking; network names require observe_network_names"
    )]
    pub fn refresh_blocking(&self, timeout: Duration) -> Result<NetworkRefreshResult> {
        crate::log_t!(LogType::Engine; "net_status.refresh_blocking", "timeout", timeout);
        crate::module::net_status::inner::refresh::refresh_blocking(self.inner.clone(), timeout)
    }

    /// Synchronously query and commit fresh Windows reachability only.
    ///
    /// The blocking counterpart of [`Self::refresh_reachability`], using its
    /// independent sampling lane. The IP-stack value remains cached; no name
    /// is queried or returned. Requires Running
    /// and a positive timeout; other platforms return `Unsupported` after these
    /// checks. Never substitutes a cached snapshot for a failed fresh query.
    ///
    /// The blocking, timeout and SDK-thread restrictions of
    /// [`Self::refresh_blocking`] apply. Async callers should normally use
    /// [`Self::refresh_reachability`] instead.
    ///
    /// ```no_run
    /// use open_net::{NetStatusClient, NetworkRefreshResult, Result};
    /// use std::time::Duration;
    ///
    /// // Call from a synchronous integration after start().await has succeeded.
    /// fn query_now(client: &NetStatusClient) -> Result<NetworkRefreshResult> {
    ///     client.refresh_reachability_blocking(Duration::from_secs(3))
    /// }
    /// ```
    pub fn refresh_reachability_blocking(&self, timeout: Duration) -> Result<NetworkRefreshResult> {
        crate::log_t!(LogType::Engine; "net_status.refresh_reachability_blocking", "timeout", timeout);
        crate::module::net_status::inner::refresh::refresh_reachability_blocking(
            self.inner.clone(),
            timeout,
        )
    }

    pub(crate) fn request_destroy(&self) {
        self.inner.request_close();
    }

    pub(crate) async fn destroy(&self) -> Result<()> {
        self.inner.request_close();
        self.inner.wait_cleanup().await
    }
}

impl fmt::Debug for NetStatusClient {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("NetStatusClient")
            .finish_non_exhaustive()
    }
}