wordval-utils 1.0.8

Wordval utilities: string manipulation, date handling, masking, ID generation, validation, crypto, web helpers, collection tools, retry utilities
Documentation
//! 指数退避 + 抖动 + 重连风暴防护
//!
//! 用于长连接客户端重连、外部服务调用等场景:
//!
//! - [`ExponentialBackoff`]:参数构造期校验(返回 `Result` 而非 panic)、
//!   `immediate_first` 只在首跳生效一次、**饱和期把抖动基数降为
//!   `delay_max - jitter` 保持随机分布**(否则顶格后延迟塌缩成单一值,
//!   断网恢复时所有客户端同刻重连)、jitter 宽于 max 时 floor 保底非零;
//! - [`ReconnectThrottle`]:滑动窗口节流。指数退避防不住「对端在连接
//!   稳定阈值刚过时断开」的循环——每次断开都重置退避会让尝试频率退化为
//!   每轮一次的立即重连。窗口内尝试次数触顶后强制拉高最小间隔。
//!
//! # 边界条件(诚实文档)
//!
//! - `ExponentialBackoff` 不是线程安全的:内部有 `delay_current` 状态,
//!   多线程共享请包 `Mutex`(通常退避属于单个重连任务,无需共享)。
//! - `ReconnectThrottle` 同样非线程安全,归属同一重连任务。
//! - 退避只负责算延迟;「连接稳定多久才重置退避」由调用方决定
//!   (推荐:稳定满阈值秒数再调 [`ExponentialBackoff::reset`])。
//!
//! ```rust
//! use std::time::Duration;
//! use wordval_utils::backoff::ExponentialBackoff;
//!
//! let mut backoff = ExponentialBackoff::new(
//!     Duration::from_millis(100), Duration::from_secs(30), 2.0, 0, false,
//! ).unwrap();
//! assert_eq!(backoff.next_duration(), Duration::from_millis(100));
//! assert_eq!(backoff.next_duration(), Duration::from_millis(200));
//! ```

use std::collections::VecDeque;
use std::time::Duration;

use crate::correctness::{check_in_range_f64, check_predicate_true, CorrectnessResult};

/// 重连节流的默认滑动窗口(2 分钟足够捕捉「稳定阈值刚过就断开」的循环)
pub const RECONNECT_WINDOW: Duration = Duration::from_secs(120);
/// 窗口内触发最小间隔的尝试次数阈值
pub const RECONNECT_WINDOW_ATTEMPTS: usize = 3;
/// 触发节流后的最小尝试间隔
pub const RECONNECT_MIN_DELAY: Duration = Duration::from_secs(1);

/// 滑动窗口重连节流器:防「稳定阈值刚过就断开」的重连风暴
///
/// 记录最近的重连尝试时刻;窗口内尝试次数达到
/// [`RECONNECT_WINDOW_ATTEMPTS`] 后,[`Self::gated_delay`] 把延迟抬到
/// 至少 [`RECONNECT_MIN_DELAY`],直到窗口内的尝试随时间自然滑出。
///
/// 注意:窗口是**纯时间驱动**的——连接保持稳定并不清空窗口
/// (稳定的存活时间不能视为恢复),只有时间流逝让旧尝试滑出才解除节流。
#[derive(Debug, Default, Clone)]
pub struct ReconnectThrottle {
    recent_attempts: VecDeque<std::time::Instant>,
}

impl ReconnectThrottle {
    /// 根据窗口内的尝试数,返回下一跳应等待的延迟:
    /// 触顶时取 `max(backoff_delay, RECONNECT_MIN_DELAY)`,未触顶原样放行
    pub fn gated_delay(&mut self, backoff_delay: Duration) -> Duration {
        self.prune_expired();
        if self.recent_attempts.len() >= RECONNECT_WINDOW_ATTEMPTS {
            backoff_delay.max(RECONNECT_MIN_DELAY)
        } else {
            backoff_delay
        }
    }

    /// 记录一次重连尝试(调用时机:实际发起连接前)
    pub fn record_attempt(&mut self) {
        self.prune_expired();
        self.recent_attempts.push_back(std::time::Instant::now());
    }

    /// 窗口内当前记录的尝试次数(测试与观测用)
    pub fn attempts_in_window(&self) -> usize {
        self.recent_attempts.len()
    }

    fn prune_expired(&mut self) {
        while self
            .recent_attempts
            .front()
            .is_some_and(|oldest| oldest.elapsed() > RECONNECT_WINDOW)
        {
            self.recent_attempts.pop_front();
        }
    }
}

/// 带抖动与 immediate-first 的指数退避
///
/// 从 `delay_initial` 起步,每次按 `factor` 增长并封顶 `delay_max`,
/// 结果叠加 `[0, jitter_ms]` 随机抖动。`immediate_first = true` 时首次
/// 返回零延迟(且仅首次)。[`Self::reset`] 恢复初始延迟与 original
/// immediate-first 设置(在连接稳定后调用)。
#[derive(Debug, Clone)]
pub struct ExponentialBackoff {
    delay_initial: Duration,
    delay_max: Duration,
    delay_current: Duration,
    factor: f64,
    jitter_ms: u64,
    immediate_first: bool,
    immediate_first_original: bool,
}

impl ExponentialBackoff {
    /// 创建退避实例,参数在构造期校验
    ///
    /// # Errors
    ///
    /// - `delay_initial` 为零
    /// - `delay_max` 小于 `delay_initial`
    /// - `factor` 不在 `[1.0, 100.0]`(上限防「重连刷屏」式的配置错误)
    pub fn new(
        delay_initial: Duration,
        delay_max: Duration,
        factor: f64,
        jitter_ms: u64,
        immediate_first: bool,
    ) -> CorrectnessResult<Self> {
        check_predicate_true(!delay_initial.is_zero(), "delay_initial must be non-zero")?;
        check_predicate_true(
            delay_max >= delay_initial,
            "delay_max must be >= delay_initial",
        )?;
        check_in_range_f64(factor, 1.0, 100.0, "factor")?;

        Ok(Self {
            delay_initial,
            delay_max,
            delay_current: delay_initial,
            factor,
            jitter_ms,
            immediate_first,
            immediate_first_original: immediate_first,
        })
    }

    /// 返回下一跳延迟(含抖动)并推进内部状态
    ///
    /// 饱和期把抖动基数压到 `delay_max - jitter`,保证顶格后仍有随机分布;
    /// 结果钳制到 `[min(delay_initial, delay_max), delay_max]`——floor 避免
    /// 「jitter 宽于 delay_max 时基数归零」的意外零延迟。
    pub fn next_duration(&mut self) -> Duration {
        if self.immediate_first && self.delay_current == self.delay_initial {
            self.immediate_first = false;
            return Duration::ZERO;
        }

        use rand::Rng;
        let jitter = rand::thread_rng().gen_range(0..=self.jitter_ms);

        let base = std::cmp::min(
            self.delay_current,
            self.delay_max.saturating_sub(Duration::from_millis(self.jitter_ms)),
        );
        let with_jitter = base + Duration::from_millis(jitter);

        let floor = std::cmp::min(self.delay_initial, self.delay_max);
        let clamped = with_jitter.clamp(floor, self.delay_max);

        // f64 乘法 saturate:溢出时由 min 兜底回 delay_max
        let next_nanos = (self.delay_current.as_nanos() as f64 * self.factor) as u64;
        self.delay_current =
            Duration::from_nanos(next_nanos.min(self.delay_max.as_nanos() as u64));

        clamped
    }

    /// 重置到初始状态(连接稳定后调用,恢复 immediate-first 设置)
    pub const fn reset(&mut self) {
        self.delay_current = self.delay_initial;
        self.immediate_first = self.immediate_first_original;
    }

    /// 当前基础延迟(不含抖动;即下次 `next_duration` 的基数)
    pub const fn current_delay(&self) -> Duration {
        self.delay_current
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn no_jitter_exponential_growth_and_cap() {
        let mut b = ExponentialBackoff::new(
            Duration::from_millis(100),
            Duration::from_millis(1600),
            2.0,
            0,
            false,
        )
        .unwrap();
        assert_eq!(b.next_duration(), Duration::from_millis(100));
        assert_eq!(b.next_duration(), Duration::from_millis(200));
        assert_eq!(b.next_duration(), Duration::from_millis(400));
        assert_eq!(b.next_duration(), Duration::from_millis(800));
        assert_eq!(b.next_duration(), Duration::from_millis(1600));
        assert_eq!(b.next_duration(), Duration::from_millis(1600));
    }

    #[test]
    fn validation_errors() {
        assert!(ExponentialBackoff::new(Duration::ZERO, Duration::from_secs(1), 2.0, 0, false)
            .is_err());
        assert!(ExponentialBackoff::new(
            Duration::from_secs(2),
            Duration::from_secs(1),
            2.0,
            0,
            false
        )
        .is_err());
        assert!(ExponentialBackoff::new(
            Duration::from_millis(100),
            Duration::from_secs(1),
            150.0,
            0,
            false
        )
        .is_err());
        assert!(ExponentialBackoff::new(
            Duration::from_millis(100),
            Duration::from_secs(1),
            0.5,
            0,
            false
        )
        .is_err());
    }

    #[test]
    fn immediate_first_only_once_and_reset_restores() {
        let mut b = ExponentialBackoff::new(
            Duration::from_millis(100),
            Duration::from_millis(1600),
            2.0,
            0,
            true,
        )
        .unwrap();
        assert_eq!(b.next_duration(), Duration::ZERO);
        assert_eq!(b.next_duration(), Duration::from_millis(100));
        assert_eq!(b.next_duration(), Duration::from_millis(200));
        b.reset();
        assert_eq!(b.next_duration(), Duration::ZERO);
        assert_eq!(b.current_delay(), Duration::from_millis(100));
    }

    #[test]
    fn jitter_within_bounds_and_never_exceeds_max() {
        let mut b = ExponentialBackoff::new(
            Duration::from_millis(100),
            Duration::from_secs(1),
            2.0,
            500,
            false,
        )
        .unwrap();
        while b.current_delay() < Duration::from_secs(1) {
            b.next_duration();
        }
        for _ in 0..200 {
            let d = b.next_duration();
            assert!(!d.is_zero(), "饱和期延迟不得为零");
            assert!(d <= Duration::from_secs(1), "延迟不得超过 delay_max");
        }
    }

    /// 回归:顶格后 jitter 必须仍保持随机分布(否则断网恢复时全体同刻重连)
    #[test]
    fn jitter_spreads_at_cap() {
        let mut b = ExponentialBackoff::new(
            Duration::from_millis(100),
            Duration::from_secs(1),
            2.0,
            500,
            false,
        )
        .unwrap();
        while b.current_delay() < Duration::from_secs(1) {
            b.next_duration();
        }
        let mut distinct = std::collections::HashSet::new();
        for _ in 0..100 {
            distinct.insert(b.next_duration());
        }
        assert!(distinct.len() >= 2, "饱和期抖动必须保持离散分布");
    }

    #[test]
    fn throttle_passes_below_threshold() {
        let mut t = ReconnectThrottle::default();
        for _ in 0..RECONNECT_WINDOW_ATTEMPTS {
            assert_eq!(t.gated_delay(Duration::ZERO), Duration::ZERO);
            t.record_attempt();
        }
    }

    #[test]
    fn throttle_floors_once_threshold_trips() {
        let mut t = ReconnectThrottle::default();
        for _ in 0..RECONNECT_WINDOW_ATTEMPTS {
            t.record_attempt();
        }
        assert_eq!(t.gated_delay(Duration::ZERO), RECONNECT_MIN_DELAY);
        assert_eq!(
            t.gated_delay(Duration::from_millis(25)),
            RECONNECT_MIN_DELAY
        );
        // 不会压低本就更大的退避延迟
        assert_eq!(t.gated_delay(Duration::from_secs(5)), Duration::from_secs(5));
    }
}