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
//! Fixed, privacy-safe metadata for NetStatus's existing publication boundaries.
use crate::net_status::{MonitorState, NetworkSnapshot};
use crate::{LogLevel, LogType, OpenNetLogger};

/// Emit one safe diagnostic for a caller-visible terminal API error. This is
/// deliberately separate from the periodic worker's bounded FaultCycle logs.
pub(crate) fn emit_monitor_error(boundary: &'static str, error: &crate::NetError) {
    if !OpenNetLogger::is_enabled_for(LogType::Engine, LogLevel::Error) {
        return;
    }
    let diagnostics = error.network_monitor_diagnostics().unwrap_or_else(|| {
        // Lifecycle errors such as Closed need not have a monitoring phase.
        // Do not infer a native operation or inspect arbitrary source text.
        serde_json::json!({
            "kind": format!("{:?}", error.kind()),
            "stage": error.context().stage.map(|stage| format!("{stage:?}")),
        })
    });
    crate::log_e!(LogType::Engine; "net_status.error",
        "boundary|diagnostics", boundary, diagnostics);
}

#[cfg(test)]
#[path = "diagnostic_logging_tests.rs"]
mod diagnostic_logging_tests;

/// No names, error sources or user-owned values survive the commit lock here.
#[derive(Clone, Copy)]
pub(super) struct Transition {
    scope: &'static str,
    generation: u64,
    revision: u64,
    from: &'static str,
    to: &'static str,
    reachability: &'static str,
    ip_stack: &'static str,
    name_changed: bool,
}
impl Transition {
    pub(super) fn capture(
        scope: &'static str,
        generation: u64,
        previous: &NetworkSnapshot,
        next: &NetworkSnapshot,
        lifecycle_only: bool,
    ) -> Option<Self> {
        let from = monitor_name(&previous.state);
        let to = monitor_name(&next.state);
        let name_changed = previous.network_name != next.network_name;
        if from == to
            && (lifecycle_only
                || (previous.reachability == next.reachability
                    && previous.ip_stack == next.ip_stack
                    && !name_changed))
        {
            return None;
        }
        Some(Self {
            scope,
            generation,
            revision: next.revision,
            from,
            to,
            reachability: next
                .reachability
                .as_ref()
                .map_or("Unknown", |value| value.name()),
            ip_stack: next
                .ip_stack
                .as_ref()
                .map_or("Unknown", |value| value.name()),
            name_changed,
        })
    }
    pub(super) fn closed(generation: u64, previous: &NetworkSnapshot) -> Option<Self> {
        if matches!(previous.state, MonitorState::Closed) {
            return None;
        }
        Some(Self {
            scope: "view",
            generation,
            revision: previous.revision,
            from: monitor_name(&previous.state),
            to: "Closed",
            reachability: "Unknown",
            ip_stack: "Unknown",
            name_changed: previous.network_name.is_some(),
        })
    }
    pub(super) fn emit(self) {
        crate::log_s!(LogType::Engine, LogLevel::Key; "net_status.emit",
            "scope|generation|revision|from|to|reachability|ip_stack|name_changed",
            self.scope, self.generation, self.revision, self.from, self.to,
            self.reachability, self.ip_stack, self.name_changed);
    }
}
fn monitor_name(value: &MonitorState) -> &'static str {
    match value {
        MonitorState::Stopped => "Stopped",
        MonitorState::Starting => "Starting",
        MonitorState::Running => "Running",
        MonitorState::Failed(_) => "Failed",
        MonitorState::Closed => "Closed",
    }
}

/// One bounded cycle per monitor task and sampling lane. Each fixed failure
/// class gets its first record even if another class already failed. Only a
/// successful operation resets the cycle; alternating failures cannot flood it.
#[derive(Default)]
pub(super) struct FaultCycle {
    seen: u16,
    suppressed: u64,
}
#[derive(Clone, Copy)]
#[cfg_attr(not(any(target_os = "windows", test)), allow(dead_code))]
pub(super) enum Fault {
    RefreshRequest,
    Timeout,
    QueueFull,
    ResourceExhausted,
    SampleFailed,
    Io,
    RuntimeUnavailable,
    Closed,
    Internal,
    ItemTooLarge,
}
impl Fault {
    #[cfg(any(target_os = "windows", test))]
    pub(super) fn from_error(error: &crate::NetError) -> Self {
        match error.kind() {
            crate::error::ErrorKind::TimedOut => Self::Timeout,
            crate::error::ErrorKind::QueueFull => Self::QueueFull,
            crate::error::ErrorKind::ResourceExhausted => Self::ResourceExhausted,
            crate::error::ErrorKind::Io => Self::Io,
            crate::error::ErrorKind::RuntimeUnavailable => Self::RuntimeUnavailable,
            crate::error::ErrorKind::Closed | crate::error::ErrorKind::QueueClosed => Self::Closed,
            crate::error::ErrorKind::Internal => Self::Internal,
            crate::error::ErrorKind::ItemTooLarge => Self::ItemTooLarge,
            _ => Self::SampleFailed,
        }
    }
    fn name(self) -> &'static str {
        match self {
            Self::RefreshRequest => "refresh_channel_closed",
            Self::Timeout => "timed_out",
            Self::QueueFull => "queue_full",
            Self::ResourceExhausted => "resource_exhausted",
            Self::SampleFailed => "sample_failed",
            Self::Io => "io",
            Self::RuntimeUnavailable => "runtime_unavailable",
            Self::Closed => "closed",
            Self::Internal => "internal",
            Self::ItemTooLarge => "item_too_large",
        }
    }
}
impl FaultCycle {
    fn admit(&mut self, fault: Fault, enabled: bool) -> bool {
        if !enabled {
            return false;
        }
        let bit = 1 << fault as u8;
        if self.seen & bit != 0 {
            self.suppressed = self.suppressed.saturating_add(1);
            return false;
        }
        self.seen |= bit;
        true
    }
    pub(super) fn failure(&mut self, operation: &'static str, fault: Fault) {
        if self.admit(
            fault,
            OpenNetLogger::is_enabled_for(LogType::Engine, LogLevel::Error),
        ) {
            crate::log_e!(LogType::Engine; "net_status.failure",
                "operation|reason|retained_previous", operation, fault.name(), true);
        }
    }
    pub(super) fn recovered(&mut self, operation: &'static str) {
        let previous = std::mem::take(self);
        if previous.seen != 0 {
            crate::log_s!(LogType::Engine, LogLevel::Key; "net_status.recovered",
                "operation|suppressed", operation, previous.suppressed);
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn failure_budget_is_per_lane_reason_and_recovery_and_ignores_disabled_logs() {
        let mut first = FaultCycle::default();
        let mut second = FaultCycle::default();
        assert!(!first.admit(Fault::Timeout, false));
        assert!(first.admit(Fault::Timeout, true));
        for _ in 0..100 {
            assert!(!first.admit(Fault::Timeout, true));
        }
        assert_eq!(first.suppressed, 100);
        assert!(first.admit(Fault::QueueFull, true));
        assert!(!first.admit(Fault::Timeout, true));
        assert!(second.admit(Fault::Timeout, true));
        first.recovered("test");
        assert!(first.admit(Fault::Timeout, true));
        first.suppressed = u64::MAX;
        assert!(!first.admit(Fault::Timeout, true));
        assert_eq!(first.suppressed, u64::MAX);
    }
}

// LAN queries also exist as a free function, with no owning client. This gate
// is deliberately process-wide per fixed failure class, at most once per minute
// per class. Missing optional metadata and an empty inventory never enter it.
pub(super) fn lan_failure(classes: u8) {
    use std::sync::Mutex;
    use std::time::Instant;
    static LAST: Mutex<[Option<Instant>; 4]> = Mutex::new([None; 4]);
    if classes == 0 || !OpenNetLogger::is_enabled_for(LogType::Engine, LogLevel::Error) {
        return;
    }
    let now = Instant::now();
    let admitted = {
        let mut last = LAST.lock().unwrap_or_else(|poisoned| poisoned.into_inner());
        lan_admit(&mut last, classes, now, true)
    };
    if admitted != 0 {
        crate::log_e!(LogType::Engine; "net_status.lan_failure",
            "classes|scope|enumeration_failed|invalid_inventory|route_metadata_failed|interface_metadata_failed",
            classes, "process", admitted & 1 != 0, admitted & 2 != 0,
            admitted & 4 != 0, admitted & 8 != 0);
    }
}

fn lan_admit(
    last: &mut [Option<std::time::Instant>; 4],
    classes: u8,
    now: std::time::Instant,
    enabled: bool,
) -> u8 {
    if !enabled {
        return 0;
    }
    let mut admitted = 0;
    for (index, slot) in last.iter_mut().enumerate() {
        let bit = 1 << index;
        if classes & bit != 0
            && slot.is_none_or(|previous| {
                now.saturating_duration_since(previous) >= std::time::Duration::from_secs(60)
            })
        {
            *slot = Some(now);
            admitted |= bit;
        }
    }
    admitted
}

#[cfg(test)]
mod lan_tests {
    use super::lan_admit;
    use std::time::{Duration, Instant};
    #[test]
    fn classes_are_independent_with_an_exact_minute_budget() {
        let now = Instant::now();
        let mut last = [None; 4];
        assert_eq!(lan_admit(&mut last, 15, now, false), 0);
        assert_eq!(last, [None; 4]);
        assert_eq!(lan_admit(&mut last, 1, now, true), 1);
        assert_eq!(
            lan_admit(&mut last, 1, now + Duration::from_secs(59), true),
            0
        );
        assert_eq!(
            lan_admit(&mut last, 5, now + Duration::from_secs(59), true),
            4
        );
        assert_eq!(
            lan_admit(&mut last, 5, now + Duration::from_secs(60), true),
            1
        );
        assert_eq!(
            lan_admit(&mut last, 5, now + Duration::from_secs(119), true),
            4
        );
        assert_eq!(
            lan_admit(&mut last, 0, now + Duration::from_secs(120), true),
            0
        );
        // One query aggregates every newly admitted class into a single record.
        assert_eq!(
            lan_admit(&mut last, 15, now + Duration::from_secs(180), true),
            15
        );
    }
}