feat: Allow total duration with max retries

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2023-10-03
+
+### Added
+
+- Total duration algorithm can now be configured to also consider max retries, calculated applying no jitter (1.0)
+  - We enforce whatever comes first, total duration or max retries
+
 ## [0.2.0] - 2023-07-21
 
 ### Changed

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "retry-policies"
-version = "0.2.0"
+version = "0.2.1"
 authors = ["Luca Palmieri <[email protected]>"]
 edition = "2018"
 description = "A collection of plug-and-play retry policies for Rust projects."

README.md

@@ -19,7 +19,7 @@ Add `retry-policies` to your dependencies
 ```toml
 [dependencies]
 # ...
-retry-policies = "0.2.0"
+retry-policies = "0.2.1"
 ```
 
 ## License

src/policies/exponential_backoff.rs

@@ -133,6 +133,11 @@ impl ExponentialBackoffTimed {
             started_at,
         }
     }
+
+    /// Maximum number of allowed retries attempts.
+    pub fn max_retries(&self) -> Option<u32> {
+        self.backoff.max_n_retries
+    }
 }
 
 impl ExponentialBackoffWithStart {
@@ -227,8 +232,8 @@ impl ExponentialBackoffBuilder {
     ///     .checked_sub_signed(chrono::Duration::seconds(25 * 60 * 60))
     ///     .unwrap();
     ///
-    /// backoff.for_task_started_at(started_at)
-    ///     .should_retry(0); // RetryDecision::DoNotRetry
+    /// let should_retry = backoff.for_task_started_at(started_at).should_retry(0);
+    /// assert!(matches!(RetryDecision::DoNotRetry, should_retry));
     /// ```
     pub fn build_with_total_retry_duration(
         self,
@@ -244,8 +249,86 @@ impl ExponentialBackoffBuilder {
             },
         }
     }
-}
 
+    /// Builds an [`ExponentialBackoff`] with the given maximum total duration and calculates max
+    /// retries that should happen applying no jitter.
+    ///
+    /// For example if we set total duration 24 hours, with retry bounds [1s, 24h], we would calculate
+    /// 17 max retries, as 1s * pow(2, 16) = 65536s = ~18 hours and 18th attempt would be way
+    /// after the 24 hours total duration.
+    ///
+    /// If the 17th retry ends up being scheduled after 10 hours due to jitter, [`ExponentialBackoff::should_retry`]
+    /// will return false anyway: no retry will be allowed after total duration.
+    ///
+    /// If one of the 17 allowed retries for some reason (e.g. previous attempts taking a long time) ends up
+    /// being scheduled after total duration, [`ExponentialBackoff::should_retry`] will return false.
+    ///
+    /// Basically we will enforce whatever comes first, max retries or total duration.
+    ///
+    /// Requires the use of [`ExponentialBackoffTimed::for_task_started_at()`].
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use chrono::{DateTime, Utc};
+    /// use retry_policies::{RetryDecision, RetryPolicy};
+    /// use retry_policies::policies::ExponentialBackoff;
+    /// use std::time::Duration;
+    ///
+    /// let exponential_backoff_timed = ExponentialBackoff::builder()
+    ///     .retry_bounds(Duration::from_secs(1), Duration::from_secs(6 * 60 * 60))
+    ///     .build_with_total_retry_duration_and_max_retries(Duration::from_secs(24 * 60 * 60));
+    ///
+    /// assert_eq!(exponential_backoff_timed.max_retries(), Some(17));
+    ///
+    /// let started_at = Utc::now()
+    ///     .checked_sub_signed(chrono::Duration::seconds(25 * 60 * 60))
+    ///     .unwrap();
+    ///
+    /// let should_retry = exponential_backoff_timed.for_task_started_at(started_at).should_retry(0);
+    /// assert!(matches!(RetryDecision::DoNotRetry, should_retry));
+    ///
+    /// let started_at = Utc::now()
+    ///     .checked_sub_signed(chrono::Duration::seconds(1 * 60 * 60))
+    ///     .unwrap();
+    ///
+    /// let should_retry = exponential_backoff_timed.for_task_started_at(started_at).should_retry(18);
+    /// assert!(matches!(RetryDecision::DoNotRetry, should_retry));
+    ///
+    /// ```
+    pub fn build_with_total_retry_duration_and_max_retries(
+        self,
+        total_duration: Duration,
+    ) -> ExponentialBackoffTimed {
+        let mut max_n_retries = None;
+
+        let delays = (0u32..).map(|n| {
+            min(
+                self.max_retry_interval,
+                self.min_retry_interval * 2_u32.checked_pow(n).unwrap_or(u32::MAX),
+            )
+        });
+
+        let mut total = Duration::from_secs(0);
+        for (n, delay) in delays.enumerate() {
+            total += delay;
+            if total >= total_duration {
+                max_n_retries = Some(n as _);
+                break;
+            }
+        }
+
+        ExponentialBackoffTimed {
+            max_total_retry_duration: total_duration,
+            backoff: ExponentialBackoff {
+                min_retry_interval: self.min_retry_interval,
+                max_retry_interval: self.max_retry_interval,
+                max_n_retries,
+                jitter: self.jitter,
+            },
+        }
+    }
+}
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -364,4 +447,50 @@ mod tests {
             }
         }
     }
+
+    #[test]
+    fn does_not_retry_before_total_retry_duration_if_max_retries_exceeded() {
+        let backoff = ExponentialBackoff::builder()
+            // This configuration should allow 17 max retries inside a 24h total duration
+            .retry_bounds(Duration::from_secs(1), Duration::from_secs(6 * 60 * 60))
+            .build_with_total_retry_duration_and_max_retries(Duration::from_secs(24 * 60 * 60));
+
+        {
+            let started_at = Utc::now()
+                .checked_sub_signed(chrono::Duration::seconds(23 * 60 * 60))
+                .unwrap();
+
+            let decision = backoff.for_task_started_at(started_at).should_retry(0);
+
+            match decision {
+                RetryDecision::Retry { .. } => {}
+                _ => panic!("should retry"),
+            }
+        }
+        {
+            let started_at = Utc::now()
+                .checked_sub_signed(chrono::Duration::seconds(23 * 60 * 60))
+                .unwrap();
+
+            // Zero based, so this is the 18th retry
+            let decision = backoff.for_task_started_at(started_at).should_retry(17);
+
+            match decision {
+                RetryDecision::DoNotRetry => {}
+                _ => panic!("should not retry"),
+            }
+        }
+        {
+            let started_at = Utc::now()
+                .checked_sub_signed(chrono::Duration::seconds(25 * 60 * 60))
+                .unwrap();
+
+            let decision = backoff.for_task_started_at(started_at).should_retry(0);
+
+            match decision {
+                RetryDecision::DoNotRetry => {}
+                _ => panic!("should not retry"),
+            }
+        }
+    }
 }