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 crate::{NetError, Result};
use std::time::{Duration, Instant};

/// Automatic retry policy for one connection cycle; defaults to jittered exponential backoff.
#[derive(Clone, Debug)]
pub enum ReconnectPolicy {
    /// Do not retry failed connections or reconnect after termination.
    Disabled,
    /// Retry with jittered exponential backoff and count/elapsed-time limits.
    Backoff(
        /// Retry count, delay, and elapsed-time limits for the cycle.
        BackoffConfig,
    ),
}

impl Default for ReconnectPolicy {
    fn default() -> Self {
        Self::Backoff(BackoffConfig::default())
    }
}

impl ReconnectPolicy {
    /// Creates a jittered exponential backoff policy without a retry-count or
    /// cycle-elapsed-time limit.
    ///
    /// The delay caps remain the safe defaults from [`BackoffConfig::default`],
    /// so an unavailable endpoint does not turn retries into a busy loop. A
    /// session still stops promptly when it is cancelled or closed.
    /// The policy does not change
    /// [`ConnectOptions::connect_timeout`](crate::ws::ConnectOptions::connect_timeout); callers
    /// that also want an unlimited initial connection wait must set that option
    /// to `None` explicitly.
    pub fn long_running() -> Self {
        Self::Backoff(BackoffConfig::unlimited())
    }

    /// Validates the selected retry policy.
    pub fn validate(&self) -> Result<()> {
        match self {
            Self::Disabled => Ok(()),
            Self::Backoff(config) => config.validate(),
        }
    }
}

/// Full-jitter exponential backoff parameters; each wait is random from zero to its cap.
#[derive(Clone, Debug)]
pub struct BackoffConfig {
    /// Additional retries after the initial attempt (6 by default; zero disables retries).
    pub max_retries: usize,
    /// First retry's random delay cap (250 ms by default); later caps grow by powers of two.
    pub initial_delay: Duration,
    /// Maximum random delay cap (8 s by default), which must not be below the initial delay.
    pub max_delay: Duration,
    /// Maximum cycle elapsed time including attempts and waits (30 s default); `None` is unlimited.
    pub max_elapsed: Option<Duration>,
}

impl Default for BackoffConfig {
    fn default() -> Self {
        Self {
            max_retries: 6,
            initial_delay: Duration::from_millis(250),
            max_delay: Duration::from_secs(8),
            max_elapsed: Some(Duration::from_secs(30)),
        }
    }
}

impl BackoffConfig {
    /// Creates a backoff configuration with no retry-count or cycle-elapsed-time
    /// limit while retaining the default jitter delay caps.
    ///
    /// `usize::MAX` is used as the retry-count sentinel because the public
    /// configuration stores a count. The worker treats it as the largest
    /// representable number of additional attempts and still propagates
    /// cancellation and shutdown immediately.
    pub fn unlimited() -> Self {
        Self {
            max_retries: usize::MAX,
            max_elapsed: None,
            ..Self::default()
        }
    }

    /// Validates delay ordering and monotonic deadline representability.
    pub fn validate(&self) -> Result<()> {
        validate_duration(self.initial_delay, "reconnect.initial_delay")?;
        validate_duration(self.max_delay, "reconnect.max_delay")?;
        if let Some(max_elapsed) = self.max_elapsed {
            validate_duration(max_elapsed, "reconnect.max_elapsed")?;
        }
        if self.max_delay < self.initial_delay {
            return Err(NetError::config(
                "reconnect.max_delay",
                "must be greater than or equal to reconnect.initial_delay",
            ));
        }
        Ok(())
    }
}

fn validate_duration(value: Duration, field: &str) -> Result<()> {
    if value.is_zero() {
        return Err(NetError::config(field, "must be greater than zero"));
    }
    if Instant::now().checked_add(value).is_none() {
        return Err(NetError::config(
            field,
            "must fit a monotonic Instant deadline",
        ));
    }
    Ok(())
}

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