retry 2.2.0

Utilities for retrying operations that can fail.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

use std::{
    ops::{Range as StdRange, RangeInclusive},
    time::Duration,
};

use rand::{
    distr::{uniform::Error as UniformError, Distribution, Uniform},
    random,
    rngs::ThreadRng,
};

/// Each retry uses a duration randomly chosen from a range. (When the `random` Cargo feature is
/// enabled.)
#[derive(Debug)]
pub struct Range {
    distribution: Uniform<u64>,
    rng: ThreadRng,
}

impl Range {
    /// Create a new [`Range`] between the given millisecond durations, excluding the maximum value.
    ///
    /// # Panics
    ///
    /// Panics if the minimum is greater than or equal to the maximum.
    #[must_use]
    pub fn from_millis_exclusive(minimum: u64, maximum: u64) -> Self {
        Range {
            distribution: Uniform::new(minimum, maximum)
                .expect("minimum must be less than maximum"),
            rng: rand::rng(),
        }
    }

    /// Attempt to create a new [`Range`] between the given millisecond durations, excluding the
    /// maximum value.
    ///
    /// # Errors
    ///
    /// Returns an error if the minimum is greater than or equal to the maximum.
    pub fn try_from_millis_exclusive(minimum: u64, maximum: u64) -> Result<Self, UniformError> {
        Ok(Range {
            distribution: Uniform::new(minimum, maximum)?,
            rng: rand::rng(),
        })
    }

    /// Create a new [`Range`] between the given millisecond durations, including the maximum value.
    ///
    /// # Panics
    ///
    /// Panics if the minimum is greater than or equal to the maximum.
    #[must_use]
    pub fn from_millis_inclusive(minimum: u64, maximum: u64) -> Self {
        Range {
            distribution: Uniform::new_inclusive(minimum, maximum)
                .expect("minimum must be less than maximum"),
            rng: rand::rng(),
        }
    }

    /// Attempt to create a new [`Range`] between the given millisecond durations, including the
    /// maximum value.
    ///
    /// # Errors
    ///
    /// Returns an error if the minimum is greater than or equal to the maximum.
    pub fn try_from_millis_inclusive(minimum: u64, maximum: u64) -> Result<Self, UniformError> {
        Ok(Range {
            distribution: Uniform::new_inclusive(minimum, maximum)?,
            rng: rand::rng(),
        })
    }
}

impl Iterator for Range {
    type Item = Duration;

    fn next(&mut self) -> Option<Duration> {
        Some(Duration::from_millis(
            self.distribution.sample(&mut self.rng),
        ))
    }
}

impl From<StdRange<Duration>> for Range {
    fn from(range: StdRange<Duration>) -> Self {
        Self::from_millis_exclusive(range.start.as_millis() as u64, range.end.as_millis() as u64)
    }
}

impl From<RangeInclusive<Duration>> for Range {
    fn from(range: RangeInclusive<Duration>) -> Self {
        Self::from_millis_inclusive(
            range.start().as_millis() as u64,
            range.end().as_millis() as u64,
        )
    }
}

/// Apply full random jitter to a duration. (When the `random` Cargo feature is enabled.)
#[must_use]
pub fn jitter(duration: Duration) -> Duration {
    duration.mul_f64(random::<f64>())
}

#[test]
fn range_uniform() {
    let mut range = Range::from_millis_exclusive(0, 1);
    assert_eq!(Duration::from_millis(0), range.next().unwrap());
    assert_eq!(Duration::from_millis(0), range.next().unwrap());
    assert_eq!(Duration::from_millis(0), range.next().unwrap());
}

#[test]
#[should_panic]
fn range_exclusive_uniform_wrong_input() {
    let _panic = Range::from_millis_exclusive(1, 0);
}

#[test]
#[should_panic]
fn range_inclusive_uniform_wrong_input() {
    let _panic = Range::from_millis_inclusive(1, 0);
}

#[test]
fn try_range_uniform() {
    assert!(Range::try_from_millis_exclusive(0, 1).is_ok());
    assert!(Range::try_from_millis_inclusive(0, 1).is_ok());

    assert!(Range::try_from_millis_exclusive(1, 0).is_err());
    assert!(Range::try_from_millis_inclusive(1, 0).is_err());
}

#[test]
fn test_jitter() {
    assert_eq!(Duration::from_millis(0), jitter(Duration::from_millis(0)));
    assert!(Duration::from_millis(0) < jitter(Duration::from_millis(2)));
}