chrono_machines 0.5.2 → 0.8.0

data/ext/chrono_machines_native/core/src/retry.rs

@@ -16,10 +16,31 @@ use alloc::boxed::Box;
 type DefaultRetryBuilder<F, B, T, E> = RetryBuilder<F, B, T, E, fn(&E) -> bool>;
 
 /// Type alias for boxed notify callback
-type NotifyCallback<E> = Box<dyn FnMut(&RetryContext<E>)>;
+///
+/// `Send` so that a configured builder — and therefore the future returned by
+/// [`RetryBuilder::call_async`] — can cross threads. Without it `tokio::spawn`
+/// rejects every retry that has a callback attached.
+type NotifyCallback<E> = Box<dyn FnMut(&RetryContext<E>) + Send>;
 
 /// Type alias for boxed failure callback
-type FailureCallback<E> = Box<dyn FnMut(&RetryError<E>)>;
+type FailureCallback<E> = Box<dyn FnMut(&RetryError<E>) + Send>;
+
+/// Type alias for boxed delay_from hook
+type DelayFromHook<E> = Box<dyn FnMut(&E, u8) -> DelayHint + Send>;
+
+/// What a [`delay_from`](RetryBuilder::delay_from) hook wants the loop to do
+/// next. The Rust counterpart of the Ruby executor's nil / Numeric / :halt
+/// return values.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DelayHint {
+    /// No opinion - use the backoff strategy.
+    Backoff,
+    /// Sleep exactly this long, no jitter. Beyond the strategy's max delay
+    /// the retry halts with [`RetryErrorKind::HintHalted`].
+    Ms(u64),
+    /// Stop retrying immediately, failing with the original error.
+    Halt,
+}
 
 /// Build a terminal [`RetryError`], firing the `on_failure` callback if present.
 fn finalize_failure<E>(
@@ -30,7 +51,13 @@ fn finalize_failure<E>(
     cumulative_delay_ms: u64,
     error: E,
 ) -> RetryError<E> {
-    let retry_error = RetryError::new(kind, attempt, max_attempts, cumulative_delay_ms, Some(error));
+    let retry_error = RetryError::new(
+        kind,
+        attempt,
+        max_attempts,
+        cumulative_delay_ms,
+        Some(error),
+    );
     if let Some(callback) = on_failure {
         callback(&retry_error);
     }
@@ -44,6 +71,9 @@ pub enum RetryErrorKind {
     Exhausted,
     /// The error was rejected by the `when` predicate.
     PredicateRejected,
+    /// A `delay_from` hint halted the retry, either explicitly or by asking
+    /// for a delay beyond the strategy's maximum.
+    HintHalted,
 }
 
 /// Context provided to retry callbacks with observability data.
@@ -136,6 +166,13 @@ where
             RetryErrorKind::PredicateRejected => {
                 write!(f, "retry aborted by predicate on attempt {}", self.attempts)?;
             }
+            RetryErrorKind::HintHalted => {
+                write!(
+                    f,
+                    "retry halted by delay_from hint on attempt {}",
+                    self.attempts
+                )?;
+            }
         }
 
         write!(f, " (cumulative delay {}ms)", self.cumulative_delay_ms)?;
@@ -234,6 +271,7 @@ where
             operation: self,
             backoff,
             when: None,
+            delay_from: None,
             notify: None,
             on_success: None,
             on_failure: None,
@@ -326,7 +364,10 @@ pub trait RetryableExt<T, E>: Retryable<T, E> {
     /// let outcome = check_status.with_constant(500).call()?;
     /// # Ok::<(), chrono_machines::RetryError<std::io::Error>>(())
     /// ```
-    fn with_constant(self, delay_ms: u64) -> DefaultRetryBuilder<Self, crate::backoff::ConstantBackoff, T, E>
+    fn with_constant(
+        self,
+        delay_ms: u64,
+    ) -> DefaultRetryBuilder<Self, crate::backoff::ConstantBackoff, T, E>
     where
         Self: Sized,
     {
@@ -387,6 +428,7 @@ pub struct RetryBuilder<F, B, T, E, W> {
     operation: F,
     backoff: B,
     when: Option<W>,
+    delay_from: Option<DelayFromHook<E>>,
     notify: Option<NotifyCallback<E>>,
     on_success: Option<NotifyCallback<E>>,
     on_failure: Option<FailureCallback<E>>,
@@ -394,9 +436,26 @@ pub struct RetryBuilder<F, B, T, E, W> {
     _phantom_e: core::marker::PhantomData<E>,
 }
 
+/// What the retry loop should do after one attempt.
+///
+/// Produced by [`RetryBuilder::step`], which holds every retry decision —
+/// predicate, exhaustion, delay, callbacks — so the sync and async drivers
+/// share one implementation and can never drift apart. The drivers differ
+/// only in how they await the operation and the sleep.
+enum Step<T, E> {
+    /// The attempt succeeded; return this outcome.
+    Done(RetryOutcome<T>),
+    /// Sleep this many milliseconds, then attempt again.
+    Sleep(u64),
+    /// Give up and return this error.
+    Fail(RetryError<E>),
+}
+
+// Configuration methods, plus the shared decision logic. Deliberately not bound
+// on `F`: the sync driver wants `FnMut() -> Result<T, E>` and the async one
+// wants `FnMut() -> impl Future`, and neither bound belongs on `.when()`.
 impl<F, B, T, E, W> RetryBuilder<F, B, T, E, W>
 where
-    F: FnMut() -> Result<T, E>,
     B: BackoffStrategy,
     W: Fn(&E) -> bool,
 {
@@ -435,6 +494,7 @@ where
             operation: self.operation,
             backoff: self.backoff,
             when: Some(predicate),
+            delay_from: self.delay_from,
             notify: self.notify,
             on_success: self.on_success,
             on_failure: self.on_failure,
@@ -443,6 +503,31 @@ where
         }
     }
 
+    /// Let the error dictate the next delay - e.g. HTTP `Retry-After` on 429s.
+    ///
+    /// Called with `(&error, attempt)` before each retry; the returned
+    /// [`DelayHint`] overrides the backoff strategy. A [`DelayHint::Ms`]
+    /// beyond the strategy's max delay halts with
+    /// [`RetryErrorKind::HintHalted`] - the server asked for more patience
+    /// than this policy allows.
+    ///
+    /// ```rust,ignore
+    /// let outcome = fetch
+    ///     .retry(ExponentialBackoff::default())
+    ///     .delay_from(|e: &ApiError, _attempt| match e.retry_after_ms() {
+    ///         Some(ms) => DelayHint::Ms(ms),
+    ///         None => DelayHint::Backoff,
+    ///     })
+    ///     .call()?;
+    /// ```
+    pub fn delay_from<C>(mut self, hook: C) -> Self
+    where
+        C: FnMut(&E, u8) -> DelayHint + Send + 'static,
+    {
+        self.delay_from = Some(Box::new(hook));
+        self
+    }
+
     /// Add a notification callback that's invoked before each retry
     ///
     /// The callback receives a [`RetryContext`] with comprehensive retry state information.
@@ -475,7 +560,7 @@ where
     /// ```
     pub fn notify<C>(mut self, callback: C) -> Self
     where
-        C: FnMut(&RetryContext<E>) + 'static,
+        C: FnMut(&RetryContext<E>) + Send + 'static,
     {
         self.notify = Some(Box::new(callback));
         self
@@ -486,7 +571,7 @@ where
     /// The callback receives a [`RetryContext`] with no error (error field is None).
     pub fn on_success<C>(mut self, callback: C) -> Self
     where
-        C: FnMut(&RetryContext<E>) + 'static,
+        C: FnMut(&RetryContext<E>) + Send + 'static,
     {
         self.on_success = Some(Box::new(callback));
         self
@@ -497,12 +582,137 @@ where
     /// The callback receives the rich [`RetryError`] describing the failure.
     pub fn on_failure<C>(mut self, callback: C) -> Self
     where
-        C: FnMut(&RetryError<E>) + 'static,
+        C: FnMut(&RetryError<E>) + Send + 'static,
     {
         self.on_failure = Some(Box::new(callback));
         self
     }
 
+    /// Decide what happens after one attempt, firing any callbacks it implies.
+    ///
+    /// This is the whole retry policy. A driver's only jobs are producing the
+    /// `Result` and honouring [`Step::Sleep`].
+    fn step<R: rand::Rng>(
+        &mut self,
+        result: Result<T, E>,
+        attempt: u8,
+        cumulative_delay_ms: u64,
+        rng: &mut R,
+    ) -> Step<T, E> {
+        let max_attempts = self.backoff.max_attempts();
+
+        let error = match result {
+            Ok(value) => {
+                if let Some(ref mut callback) = self.on_success {
+                    let ctx = RetryContext {
+                        attempt,
+                        next_delay_ms: None,
+                        cumulative_delay_ms,
+                        error: None,
+                    };
+                    callback(&ctx);
+                }
+                return Step::Done(RetryOutcome::new(value, attempt, cumulative_delay_ms));
+            }
+            Err(error) => error,
+        };
+
+        // An error the caller told us not to retry fails immediately, and is
+        // reported as rejected rather than exhausted.
+        if let Some(ref predicate) = self.when
+            && !predicate(&error)
+        {
+            return Step::Fail(finalize_failure(
+                self.on_failure.as_mut(),
+                RetryErrorKind::PredicateRejected,
+                attempt,
+                max_attempts,
+                cumulative_delay_ms,
+                error,
+            ));
+        }
+
+        // Out of attempts? Exhaustion wins over any delay hint.
+        if !self.backoff.should_retry(attempt) {
+            return Step::Fail(finalize_failure(
+                self.on_failure.as_mut(),
+                RetryErrorKind::Exhausted,
+                attempt,
+                max_attempts,
+                cumulative_delay_ms,
+                error,
+            ));
+        }
+
+        let hint = match self.delay_from {
+            Some(ref mut hook) => hook(&error, attempt),
+            None => DelayHint::Backoff,
+        };
+
+        let delay_ms = match hint {
+            DelayHint::Backoff => {
+                // The strategy may still decline to produce a delay.
+                let Some(delay_ms) = self.backoff.delay(attempt, rng) else {
+                    return Step::Fail(finalize_failure(
+                        self.on_failure.as_mut(),
+                        RetryErrorKind::Exhausted,
+                        attempt,
+                        max_attempts,
+                        cumulative_delay_ms,
+                        error,
+                    ));
+                };
+                delay_ms
+            }
+            DelayHint::Ms(delay_ms) => {
+                if self
+                    .backoff
+                    .max_delay_ms()
+                    .is_some_and(|cap| delay_ms > cap)
+                {
+                    return Step::Fail(finalize_failure(
+                        self.on_failure.as_mut(),
+                        RetryErrorKind::HintHalted,
+                        attempt,
+                        max_attempts,
+                        cumulative_delay_ms,
+                        error,
+                    ));
+                }
+                delay_ms
+            }
+            DelayHint::Halt => {
+                return Step::Fail(finalize_failure(
+                    self.on_failure.as_mut(),
+                    RetryErrorKind::HintHalted,
+                    attempt,
+                    max_attempts,
+                    cumulative_delay_ms,
+                    error,
+                ));
+            }
+        };
+
+        if let Some(ref mut notify) = self.notify {
+            let ctx = RetryContext {
+                attempt,
+                next_delay_ms: Some(delay_ms),
+                cumulative_delay_ms,
+                error: Some(&error),
+            };
+            notify(&ctx);
+        }
+
+        Step::Sleep(delay_ms)
+    }
+}
+
+impl<F, B, T, E, W> RetryBuilder<F, B, T, E, W>
+where
+    F: FnMut() -> Result<T, E>,
+    B: BackoffStrategy,
+    W: Fn(&E) -> bool,
+{
     /// Execute the retry operation with blocking sleep (requires `std` feature)
     ///
     /// Runs the operation synchronously, retrying with blocking sleep between attempts.
@@ -537,7 +747,9 @@ where
     /// Execute the retry operation with a custom sleeper
     ///
     /// This low-level method allows providing a custom sleep implementation,
-    /// enabling support for async runtimes, embedded systems, or testing.
+    /// enabling support for embedded systems or testing. The sleeper blocks,
+    /// so async runtimes should drive their own loop off
+    /// [`Policy::calculate_delay`](crate::Policy::calculate_delay) instead.
     ///
     /// # Arguments
     ///
@@ -591,921 +803,144 @@ where
         mut rng: R,
     ) -> Result<RetryOutcome<T>, RetryError<E>> {
         let mut attempt = 1u8;
-        let max_attempts = self.backoff.max_attempts();
         let mut cumulative_delay_ms: u64 = 0;
 
         loop {
-            match (self.operation)() {
-                Ok(_value) => {
-                    // Invoke on_success callback with context
-                    if let Some(ref mut callback) = self.on_success {
-                        let ctx = RetryContext {
-                            attempt,
-                            next_delay_ms: None,
-                            cumulative_delay_ms,
-                            error: None,
-                        };
-                        callback(&ctx);
-                    }
-                    return Ok(RetryOutcome::new(_value, attempt, cumulative_delay_ms));
-                }
-                Err(error) => {
-                    // Check if this error should be retried
-                    if let Some(ref predicate) = self.when
-                        && !predicate(&error) {
-                            // Error doesn't match predicate, fail immediately
-                            return Err(finalize_failure(
-                                self.on_failure.as_mut(),
-                                RetryErrorKind::PredicateRejected,
-                                attempt,
-                                max_attempts,
-                                cumulative_delay_ms,
-                                error,
-                            ));
-                        }
-
-                    // Check if we have retries remaining
-                    if !self.backoff.should_retry(attempt) {
-                        return Err(finalize_failure(
-                            self.on_failure.as_mut(),
-                            RetryErrorKind::Exhausted,
-                            attempt,
-                            max_attempts,
-                            cumulative_delay_ms,
-                            error,
-                        ));
-                    }
-
-                    // Calculate delay
-                    match self.backoff.delay(attempt, &mut rng) {
-                        Some(delay_ms) => {
-                            // Notify if callback is set
-                            if let Some(ref mut notify) = self.notify {
-                                let ctx = RetryContext {
-                                    attempt,
-                                    next_delay_ms: Some(delay_ms),
-                                    cumulative_delay_ms,
-                                    error: Some(&error),
-                                };
-                                notify(&ctx);
-                            }
-
-                            // Sleep before retry
-                            sleeper.sleep_ms(delay_ms);
-                            cumulative_delay_ms = cumulative_delay_ms.saturating_add(delay_ms);
-                            attempt = attempt.saturating_add(1);
-                        }
-                        None => {
-                            // Backoff says no more retries
-                            return Err(finalize_failure(
-                                self.on_failure.as_mut(),
-                                RetryErrorKind::Exhausted,
-                                attempt,
-                                max_attempts,
-                                cumulative_delay_ms,
-                                error,
-                            ));
-                        }
-                    }
+            let result = (self.operation)();
+            match self.step(result, attempt, cumulative_delay_ms, &mut rng) {
+                Step::Done(outcome) => return Ok(outcome),
+                Step::Fail(error) => return Err(error),
+                Step::Sleep(delay_ms) => {
+                    sleeper.sleep_ms(delay_ms);
+                    cumulative_delay_ms = cumulative_delay_ms.saturating_add(delay_ms);
+                    attempt = attempt.saturating_add(1);
                 }
             }
         }
     }
 }
 
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::backoff::{ConstantBackoff, ExponentialBackoff};
-    use crate::sleep::FnSleeper;
-
-    #[derive(Debug, PartialEq)]
-    enum TestError {
-        Retryable,
-        Fatal,
-    }
-
-    #[test]
-    fn test_retry_success_on_first_attempt() {
-        fn always_succeeds() -> Result<i32, TestError> {
-            Ok(42)
-        }
-
-        let result = always_succeeds
-            .retry(ExponentialBackoff::default())
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        let outcome = result.expect("retry should succeed");
-        assert_eq!(outcome.attempts(), 1);
-        assert_eq!(outcome.into_inner(), 42);
-    }
-
-    #[test]
-    fn test_retry_success_after_failures() {
-        use core::cell::Cell;
-
-        let attempts = Cell::new(0);
-
-        let operation = || {
-            let current = attempts.get();
-            attempts.set(current + 1);
-
-            if current < 2 {
-                Err(TestError::Retryable)
-            } else {
-                Ok(42)
-            }
-        };
-
-        let result = operation
-            .retry(ExponentialBackoff::default().max_attempts(3))
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        let outcome = result.expect("retry should succeed");
-        assert_eq!(outcome.attempts(), 3);
-        assert_eq!(outcome.into_inner(), 42);
-        assert_eq!(attempts.get(), 3);
-    }
-
-    #[test]
-    fn test_retry_exhausted() {
-        fn always_fails() -> Result<i32, TestError> {
-            Err(TestError::Retryable)
-        }
-
-        let result = always_fails
-            .retry(ExponentialBackoff::default().max_attempts(3))
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        let err = result.expect_err("retry should exhaust");
-        assert_eq!(err.kind(), RetryErrorKind::Exhausted);
-        assert_eq!(err.attempts(), 3);
-        assert_eq!(err.max_attempts(), 3);
-        assert!(err.cumulative_delay_ms() > 0);
-        if let Some(cause) = err.cause() {
-            assert_eq!(cause, &TestError::Retryable);
-        } else {
-            panic!("expected underlying cause");
-        }
-    }
-
-    #[test]
-    fn test_retry_when_predicate() {
-        fn fails_with_fatal() -> Result<i32, TestError> {
-            Err(TestError::Fatal)
-        }
-
-        let result = fails_with_fatal
-            .retry(ExponentialBackoff::default())
-            .when(|e| matches!(e, TestError::Retryable))
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        // Fatal error should not be retried
-        let err = result.expect_err("retry should stop due to predicate");
-        assert_eq!(err.kind(), RetryErrorKind::PredicateRejected);
-        if let Some(cause) = err.cause() {
-            assert_eq!(cause, &TestError::Fatal);
-        } else {
-            panic!("expected underlying cause");
-        }
-    }
-
-    #[test]
-    fn test_retry_notify_callback() {
-        use core::cell::{Cell, RefCell};
-        #[cfg(feature = "std")]
-        use std::rc::Rc;
-
-        #[cfg(not(feature = "std"))]
-        use alloc::rc::Rc;
-
-        let attempts = Cell::new(0);
-        let notify_calls = Rc::new(RefCell::new(Vec::new()));
-        let notify_calls_clone = Rc::clone(&notify_calls);
-
-        let operation = || {
-            let current = attempts.get();
-            attempts.set(current + 1);
-
-            if current < 2 {
-                Err(TestError::Retryable)
-            } else {
-                Ok(42)
-            }
-        };
-
-        let result = operation
-            .retry(ExponentialBackoff::default().max_attempts(3))
-            .notify(move |ctx| {
-                // Track notify calls
-                notify_calls_clone.borrow_mut().push((
-                    ctx.attempt,
-                    ctx.next_delay_ms,
-                    ctx.cumulative_delay_ms,
-                    ctx.error.is_some(),
-                ));
-                assert!(ctx.attempt >= 1);
-                assert!(ctx.next_delay_ms.is_some());
-                assert!(ctx.error.is_some());
-            })
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        let outcome = result.expect("retry should succeed");
-        assert_eq!(outcome.attempts(), 3);
-
-        // Verify notify was called twice (for the two failures)
-        let calls = notify_calls.borrow();
-        assert_eq!(calls.len(), 2);
-        assert_eq!(calls[0].0, 1); // First attempt
-        assert_eq!(calls[1].0, 2); // Second attempt
-    }
-
-    #[test]
-    fn test_on_success_callback_invoked() {
-        use core::cell::Cell;
-        use core::sync::atomic::{AtomicUsize, Ordering};
-
-        static SUCCESS_ATTEMPT: AtomicUsize = AtomicUsize::new(0);
-        static SUCCESS_CUMULATIVE_DELAY: AtomicUsize = AtomicUsize::new(0);
-
-        let attempts = Cell::new(0);
-
-        let operation = || {
-            let current = attempts.get();
-            attempts.set(current + 1);
-
-            if current < 1 {
-                Err(TestError::Retryable)
-            } else {
-                Ok(7)
-            }
-        };
-
-        SUCCESS_ATTEMPT.store(0, Ordering::SeqCst);
-        SUCCESS_CUMULATIVE_DELAY.store(0, Ordering::SeqCst);
-
-        let outcome = operation
-            .retry(ExponentialBackoff::default().max_attempts(3))
-            .on_success(|ctx| {
-                SUCCESS_ATTEMPT.store(ctx.attempt as usize, Ordering::SeqCst);
-                SUCCESS_CUMULATIVE_DELAY.store(ctx.cumulative_delay_ms as usize, Ordering::SeqCst);
-                assert!(ctx.error.is_none());
-                assert!(ctx.next_delay_ms.is_none());
-            })
-            .call_with_sleeper(FnSleeper(|_| {}))
-            .expect("retry should succeed");
-
-        assert_eq!(outcome.into_inner(), 7);
-        assert_eq!(SUCCESS_ATTEMPT.load(Ordering::SeqCst), 2);
-        // Should have some cumulative delay from the first retry
-        assert!(SUCCESS_CUMULATIVE_DELAY.load(Ordering::SeqCst) > 0);
-    }
-
-    #[test]
-    fn test_on_failure_callback_invoked() {
-        use core::sync::atomic::{AtomicUsize, Ordering};
-
-        static FAILURE_KIND: AtomicUsize = AtomicUsize::new(0);
-        static FAILURE_CUMULATIVE_DELAY: AtomicUsize = AtomicUsize::new(0);
+/// Begin a retry for an operation that returns a future.
+///
+/// The async counterpart to [`Retryable`], and the entry point for
+/// [`RetryBuilder::call_async`]. It is a separate trait because the operation's
+/// bound differs (`FnMut() -> impl Future` rather than `FnMut() -> Result`);
+/// everything after construction — `when`, `notify`, `on_success`,
+/// `on_failure` — is the same builder.
+///
+/// The closure is called once per attempt and must return a *fresh* future each
+/// time, which rules out passing a single future: futures are not restartable.
+///
+/// ```rust,ignore
+/// let outcome = (|| async { fetch().await })
+///     .retry_async(ExponentialBackoff::default())
+///     .when(|e| e.is_transient())
+///     .call_async(|ms| tokio::time::sleep(Duration::from_millis(ms)))
+///     .await?;
+/// ```
+#[cfg(feature = "async")]
+pub trait AsyncRetryable<T, E> {
+    /// Begin building a retry operation with the given backoff strategy
+    fn retry_async<B: BackoffStrategy>(self, backoff: B) -> DefaultRetryBuilder<Self, B, T, E>
+    where
+        Self: Sized;
+}
 
-        fn always_fails() -> Result<(), TestError> {
-            Err(TestError::Retryable)
+#[cfg(feature = "async")]
+impl<F, Fut, T, E> AsyncRetryable<T, E> for F
+where
+    F: FnMut() -> Fut,
+    Fut: core::future::Future<Output = Result<T, E>>,
+{
+    fn retry_async<B: BackoffStrategy>(
+        self,
+        backoff: B,
+    ) -> RetryBuilder<Self, B, T, E, fn(&E) -> bool> {
+        RetryBuilder {
+            operation: self,
+            backoff,
+            when: None,
+            delay_from: None,
+            notify: None,
+            on_success: None,
+            on_failure: None,
+            _phantom_t: core::marker::PhantomData,
+            _phantom_e: core::marker::PhantomData,
         }
-
-        FAILURE_KIND.store(0, Ordering::SeqCst);
-        FAILURE_CUMULATIVE_DELAY.store(0, Ordering::SeqCst);
-
-        let result = always_fails
-            .retry(ExponentialBackoff::default().max_attempts(2))
-            .on_failure(|err| {
-                let marker = match err.kind() {
-                    RetryErrorKind::Exhausted => 1,
-                    RetryErrorKind::PredicateRejected => 2,
-                };
-                FAILURE_KIND.store(marker, Ordering::SeqCst);
-                FAILURE_CUMULATIVE_DELAY.store(err.cumulative_delay_ms() as usize, Ordering::SeqCst);
-            })
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        assert!(result.is_err());
-        assert_eq!(FAILURE_KIND.load(Ordering::SeqCst), 1);
-        // Should have cumulative delay from retry attempt
-        assert!(FAILURE_CUMULATIVE_DELAY.load(Ordering::SeqCst) > 0);
-    }
-
-    #[test]
-    fn test_constant_backoff_retry() {
-        use core::cell::Cell;
-
-        let attempts = Cell::new(0);
-
-        let operation = || {
-            let current = attempts.get();
-            attempts.set(current + 1);
-
-            if current < 1 {
-                Err(TestError::Retryable)
-            } else {
-                Ok(42)
-            }
-        };
-
-        let result = operation
-            .retry(ConstantBackoff::new().delay_ms(10).max_attempts(2))
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        let outcome = result.expect("retry should succeed");
-        assert_eq!(outcome.attempts(), 2);
-        assert_eq!(outcome.into_inner(), 42);
-        assert_eq!(attempts.get(), 2);
     }
+}
 
+#[cfg(feature = "async")]
+impl<F, Fut, B, T, E, W> RetryBuilder<F, B, T, E, W>
+where
+    F: FnMut() -> Fut,
+    Fut: core::future::Future<Output = Result<T, E>>,
+    B: BackoffStrategy,
+    W: Fn(&E) -> bool,
+{
+    /// Execute the retry operation on an async runtime (requires `std`).
+    ///
+    /// Identical policy to [`call`](Self::call) — same predicate, callbacks and
+    /// backoff — but the operation is awaited and the delay yields to the
+    /// executor instead of blocking the thread.
+    ///
+    /// The `sleeper` supplies the runtime's timer. Any
+    /// `Fn(u64) -> Future<Output = ()>` works, so this crate stays free of a
+    /// runtime dependency:
+    ///
+    /// ```rust,ignore
+    /// use chrono_machines::{AsyncRetryable, ExponentialBackoff};
+    /// use std::time::Duration;
+    ///
+    /// let outcome = (|| async { reqwest::get(url).await })
+    ///     .retry_async(ExponentialBackoff::default())
+    ///     .call_async(|ms| tokio::time::sleep(Duration::from_millis(ms)))
+    ///     .await?;
+    /// ```
+    ///
+    /// # Cancellation
+    ///
+    /// Dropping the returned future cancels the retry wherever it stands, in
+    /// the operation or mid-sleep. The in-flight attempt is dropped with it, so
+    /// the operation must be cancel-safe if that matters to the caller;
+    /// `on_failure` does not fire, because nothing failed.
     #[cfg(feature = "std")]
-    #[test]
-    fn test_retry_with_std_sleeper() {
-        use core::cell::Cell;
-
-        let attempts = Cell::new(0);
-
-        let operation = || {
-            let current = attempts.get();
-            attempts.set(current + 1);
-
-            if current < 1 {
-                Err(TestError::Retryable)
-            } else {
-                Ok(42)
-            }
-        };
-
-        let start = std::time::Instant::now();
-        let result = operation
-            .retry(
-                ConstantBackoff::new()
-                    .delay_ms(10)
-                    .max_attempts(2)
-                    .jitter_factor(0.0),
-            )
-            .call();
-
-        let elapsed = start.elapsed();
-
-        let outcome = result.expect("retry should succeed");
-        assert_eq!(outcome.attempts(), 2);
-        assert_eq!(outcome.into_inner(), 42);
-        assert!(elapsed.as_millis() >= 9); // At least one 10ms sleep
-    }
-
-    #[test]
-    fn test_retry_context_comprehensive() {
-        use core::cell::{Cell, RefCell};
-        #[cfg(feature = "std")]
-        use std::rc::Rc;
-
-        #[cfg(not(feature = "std"))]
-        use alloc::rc::Rc;
-
-        let attempts = Cell::new(0);
-        let notify_contexts = Rc::new(RefCell::new(Vec::new()));
-        let notify_contexts_clone = Rc::clone(&notify_contexts);
-
-        let operation = || {
-            let current = attempts.get();
-            attempts.set(current + 1);
-
-            if current < 3 {
-                Err(TestError::Retryable)
-            } else {
-                Ok(42)
-            }
-        };
-
-        let result = operation
-            .retry(ConstantBackoff::new().delay_ms(100).max_attempts(5).jitter_factor(0.0))
-            .notify(move |ctx| {
-                // Capture context for verification
-                notify_contexts_clone.borrow_mut().push((
-                    ctx.attempt,
-                    ctx.next_delay_ms,
-                    ctx.cumulative_delay_ms,
-                ));
-
-                // Verify error is present during notify
-                assert!(ctx.error.is_some());
-                if let Some(err) = ctx.error {
-                    assert_eq!(err, &TestError::Retryable);
-                }
-            })
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        let outcome = result.expect("retry should succeed");
-        assert_eq!(outcome.attempts(), 4);
-
-        // Verify notify contexts
-        let contexts = notify_contexts.borrow();
-        assert_eq!(contexts.len(), 3); // Three failures before success
-
-        // First failure
-        assert_eq!(contexts[0].0, 1);
-        assert_eq!(contexts[0].1, Some(100));
-        assert_eq!(contexts[0].2, 0); // No cumulative delay yet
-
-        // Second failure
-        assert_eq!(contexts[1].0, 2);
-        assert_eq!(contexts[1].1, Some(100));
-        assert_eq!(contexts[1].2, 100); // One delay accumulated
-
-        // Third failure
-        assert_eq!(contexts[2].0, 3);
-        assert_eq!(contexts[2].1, Some(100));
-        assert_eq!(contexts[2].2, 200); // Two delays accumulated
-    }
-
-    #[test]
-    fn test_retry_context_on_success() {
-        use core::cell::{Cell, RefCell};
-        #[cfg(feature = "std")]
-        use std::rc::Rc;
-
-        #[cfg(not(feature = "std"))]
-        use alloc::rc::Rc;
-
-        let attempts = Cell::new(0);
-        let success_context = Rc::new(RefCell::new(None));
-        let success_context_clone = Rc::clone(&success_context);
-
-        let operation = || {
-            let current = attempts.get();
-            attempts.set(current + 1);
-
-            if current < 2 {
-                Err(TestError::Retryable)
-            } else {
-                Ok(100)
-            }
-        };
-
-        let result = operation
-            .retry(ConstantBackoff::new().delay_ms(50).max_attempts(5).jitter_factor(0.0))
-            .on_success(move |ctx| {
-                success_context_clone.borrow_mut().replace((
-                    ctx.attempt,
-                    ctx.next_delay_ms,
-                    ctx.cumulative_delay_ms,
-                    ctx.error.is_none(),
-                ));
-            })
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        let outcome = result.expect("retry should succeed");
-        assert_eq!(outcome.attempts(), 3);
-        assert_eq!(outcome.cumulative_delay_ms(), 100); // 2 delays of 50ms
-
-        // Verify success context
-        let ctx = success_context.borrow();
-        assert!(ctx.is_some());
-        let (attempt, next_delay, cumulative, no_error) = ctx.unwrap();
-        assert_eq!(attempt, 3);
-        assert_eq!(next_delay, None); // No next delay on success
-        assert_eq!(cumulative, 100);
-        assert!(no_error); // Error should be None
-    }
-
-    #[test]
-    fn test_retry_context_cumulative_accuracy() {
-        use core::cell::{Cell, RefCell};
-        #[cfg(feature = "std")]
-        use std::rc::Rc;
-
-        #[cfg(not(feature = "std"))]
-        use alloc::rc::Rc;
-
-        let attempts = Cell::new(0);
-        let cumulative_progression = Rc::new(RefCell::new(Vec::new()));
-        let cumulative_progression_clone = Rc::clone(&cumulative_progression);
-
-        let operation = || {
-            let current = attempts.get();
-            attempts.set(current + 1);
-            Err::<(), TestError>(TestError::Retryable)
-        };
-
-        let _result = operation
-            .retry(ConstantBackoff::new().delay_ms(25).max_attempts(4).jitter_factor(0.0))
-            .notify(move |ctx| {
-                cumulative_progression_clone.borrow_mut().push(ctx.cumulative_delay_ms);
-            })
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        // Verify cumulative delay progression
-        let progression = cumulative_progression.borrow();
-        assert_eq!(progression.len(), 3); // 3 retries before exhaustion
-        assert_eq!(progression[0], 0);    // Before first sleep
-        assert_eq!(progression[1], 25);   // After first sleep
-        assert_eq!(progression[2], 50);   // After second sleep
-    }
-
-    // ============================================================================
-    // RetryableExt Tests
-    // ============================================================================
-
-    #[test]
-    fn test_with_exponential_success() {
-        use super::RetryableExt;
-
-        fn always_succeeds() -> Result<i32, TestError> {
-            Ok(42)
-        }
-
-        let result = always_succeeds
-            .with_exponential()
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        let outcome = result.expect("retry should succeed");
-        assert_eq!(outcome.attempts(), 1);
-        assert_eq!(outcome.into_inner(), 42);
-    }
-
-    #[test]
-    fn test_with_exponential_retry_behavior() {
-        use super::RetryableExt;
-        use core::cell::Cell;
-
-        let attempts = Cell::new(0);
-
-        let operation = || {
-            let current = attempts.get();
-            attempts.set(current + 1);
-
-            if current < 2 {
-                Err(TestError::Retryable)
-            } else {
-                Ok(100)
-            }
-        };
-
-        let result = operation
-            .with_exponential()
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        let outcome = result.expect("retry should succeed");
-        assert_eq!(outcome.attempts(), 3);
-        assert_eq!(outcome.into_inner(), 100);
-        // Verify default max_attempts was used (3)
-        assert_eq!(attempts.get(), 3);
-    }
-
-    #[test]
-    fn test_with_exponential_exhausted() {
-        use super::RetryableExt;
-
-        fn always_fails() -> Result<i32, TestError> {
-            Err(TestError::Retryable)
-        }
-
-        let result = always_fails
-            .with_exponential()
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        let err = result.expect_err("retry should exhaust");
-        assert_eq!(err.kind(), RetryErrorKind::Exhausted);
-        assert_eq!(err.attempts(), 3); // Default max_attempts
-        assert_eq!(err.max_attempts(), 3);
-    }
-
-    #[test]
-    fn test_with_exponential_chaining() {
-        use super::RetryableExt;
-        use core::cell::Cell;
-
-        let attempts = Cell::new(0);
-
-        let operation = || {
-            let current = attempts.get();
-            attempts.set(current + 1);
-
-            if current < 1 {
-                Err(TestError::Retryable)
-            } else {
-                Ok(7)
-            }
-        };
-
-        // Test that .with_exponential() can be chained with other builder methods
-        let result = operation
-            .with_exponential()
-            .when(|e| matches!(e, TestError::Retryable))
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        let outcome = result.expect("retry should succeed");
-        assert_eq!(outcome.attempts(), 2);
-        assert_eq!(outcome.into_inner(), 7);
-    }
-
-    #[test]
-    fn test_with_constant_success() {
-        use super::RetryableExt;
-
-        fn always_succeeds() -> Result<i32, TestError> {
-            Ok(99)
-        }
-
-        let result = always_succeeds
-            .with_constant(250)
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        let outcome = result.expect("retry should succeed");
-        assert_eq!(outcome.attempts(), 1);
-        assert_eq!(outcome.into_inner(), 99);
+    pub async fn call_async<S: crate::sleep::AsyncSleeper>(
+        self,
+        sleeper: S,
+    ) -> Result<RetryOutcome<T>, RetryError<E>> {
+        let rng: StdRng = rand::make_rng();
+        self.call_async_with_rng(sleeper, rng).await
     }
 
-    #[test]
-    fn test_with_constant_uses_correct_delay() {
-        use super::RetryableExt;
-        use core::cell::{Cell, RefCell};
-        #[cfg(feature = "std")]
-        use std::rc::Rc;
-
-        #[cfg(not(feature = "std"))]
-        use alloc::rc::Rc;
-
-        let attempts = Cell::new(0);
-        let delays = Rc::new(RefCell::new(Vec::new()));
-        let delays_clone = Rc::clone(&delays);
-
-        let operation = || {
-            let current = attempts.get();
-            attempts.set(current + 1);
-
-            if current < 2 {
-                Err(TestError::Retryable)
-            } else {
-                Ok(42)
-            }
-        };
+    /// Execute the retry operation on an async runtime with a caller-supplied RNG.
+    ///
+    /// The `no_std` entry point, mirroring
+    /// [`call_with_sleeper_and_rng`](Self::call_with_sleeper_and_rng): callers
+    /// provide their own [`rand::Rng`] for jitter instead of relying on the
+    /// `std`-only `make_rng`.
+    pub async fn call_async_with_rng<S: crate::sleep::AsyncSleeper, R: rand::Rng>(
+        mut self,
+        sleeper: S,
+        mut rng: R,
+    ) -> Result<RetryOutcome<T>, RetryError<E>> {
+        let mut attempt = 1u8;
+        let mut cumulative_delay_ms: u64 = 0;
 
-        let result = operation
-            .with_constant(500)
-            .notify(move |ctx| {
-                if let Some(delay) = ctx.next_delay_ms {
-                    delays_clone.borrow_mut().push(delay);
+        loop {
+            let result = (self.operation)().await;
+            match self.step(result, attempt, cumulative_delay_ms, &mut rng) {
+                Step::Done(outcome) => return Ok(outcome),
+                Step::Fail(error) => return Err(error),
+                Step::Sleep(delay_ms) => {
+                    sleeper.sleep_ms(delay_ms).await;
+                    cumulative_delay_ms = cumulative_delay_ms.saturating_add(delay_ms);
+                    attempt = attempt.saturating_add(1);
                 }
-            })
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        let outcome = result.expect("retry should succeed");
-        assert_eq!(outcome.attempts(), 3);
-
-        // Verify constant delay was used (ConstantBackoff default has no jitter)
-        let recorded_delays = delays.borrow();
-        assert_eq!(recorded_delays.len(), 2); // Two retries
-        assert_eq!(recorded_delays[0], 500);
-        assert_eq!(recorded_delays[1], 500);
-    }
-
-    #[test]
-    fn test_with_constant_chaining() {
-        use super::RetryableExt;
-        use core::cell::Cell;
-
-        let attempts = Cell::new(0);
-
-        let operation = || {
-            let current = attempts.get();
-            attempts.set(current + 1);
-
-            if current < 1 {
-                Err(TestError::Fatal)
-            } else {
-                Ok(123)
             }
-        };
-
-        // Test that .with_constant() can be chained with predicate
-        let result = operation
-            .with_constant(100)
-            .when(|e| matches!(e, TestError::Retryable))
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        // Should fail immediately due to predicate
-        let err = result.expect_err("retry should fail due to predicate");
-        assert_eq!(err.kind(), RetryErrorKind::PredicateRejected);
-        assert_eq!(err.attempts(), 1);
-    }
-
-    #[test]
-    fn test_with_fibonacci_success() {
-        use super::RetryableExt;
-
-        fn always_succeeds() -> Result<String, TestError> {
-            Ok("success".to_string())
         }
-
-        let result = always_succeeds
-            .with_fibonacci()
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        let outcome = result.expect("retry should succeed");
-        assert_eq!(outcome.attempts(), 1);
-        assert_eq!(outcome.into_inner(), "success");
-    }
-
-    #[test]
-    fn test_with_fibonacci_retry_behavior() {
-        use super::RetryableExt;
-        use core::cell::Cell;
-
-        let attempts = Cell::new(0);
-
-        let operation = || {
-            let current = attempts.get();
-            attempts.set(current + 1);
-
-            if current < 3 {
-                Err(TestError::Retryable)
-            } else {
-                Ok(777)
-            }
-        };
-
-        let result = operation
-            .with_fibonacci()
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        let outcome = result.expect("retry should succeed");
-        assert_eq!(outcome.attempts(), 4);
-        assert_eq!(outcome.into_inner(), 777);
-    }
-
-    #[test]
-    fn test_with_fibonacci_exhausted() {
-        use super::RetryableExt;
-
-        fn always_fails() -> Result<i32, TestError> {
-            Err(TestError::Retryable)
-        }
-
-        let result = always_fails
-            .with_fibonacci()
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        let err = result.expect_err("retry should exhaust");
-        assert_eq!(err.kind(), RetryErrorKind::Exhausted);
-        assert_eq!(err.attempts(), 8); // Fibonacci default max_attempts
-        assert_eq!(err.max_attempts(), 8);
-    }
-
-    #[test]
-    fn test_with_fibonacci_chaining() {
-        use super::RetryableExt;
-        use core::cell::Cell;
-        use core::sync::atomic::{AtomicUsize, Ordering};
-
-        static SUCCESS_COUNT: AtomicUsize = AtomicUsize::new(0);
-        let attempts = Cell::new(0);
-
-        let operation = || {
-            let current = attempts.get();
-            attempts.set(current + 1);
-
-            if current < 2 {
-                Err(TestError::Retryable)
-            } else {
-                Ok(555)
-            }
-        };
-
-        SUCCESS_COUNT.store(0, Ordering::SeqCst);
-
-        // Test that .with_fibonacci() can be chained with callbacks
-        let result = operation
-            .with_fibonacci()
-            .on_success(|_ctx| {
-                SUCCESS_COUNT.fetch_add(1, Ordering::SeqCst);
-            })
-            .call_with_sleeper(FnSleeper(|_| {}));
-
-        let outcome = result.expect("retry should succeed");
-        assert_eq!(outcome.attempts(), 3);
-        assert_eq!(outcome.into_inner(), 555);
-        assert_eq!(SUCCESS_COUNT.load(Ordering::SeqCst), 1);
-    }
-
-    #[test]
-    fn test_all_extension_methods_produce_working_retries() {
-        use super::RetryableExt;
-        use core::cell::Cell;
-
-        let attempts_exp = Cell::new(0);
-        let op_exp = || {
-            let current = attempts_exp.get();
-            attempts_exp.set(current + 1);
-            if current < 1 {
-                Err(TestError::Retryable)
-            } else {
-                Ok(1)
-            }
-        };
-
-        let attempts_const = Cell::new(0);
-        let op_const = || {
-            let current = attempts_const.get();
-            attempts_const.set(current + 1);
-            if current < 1 {
-                Err(TestError::Retryable)
-            } else {
-                Ok(2)
-            }
-        };
-
-        let attempts_fib = Cell::new(0);
-        let op_fib = || {
-            let current = attempts_fib.get();
-            attempts_fib.set(current + 1);
-            if current < 1 {
-                Err(TestError::Retryable)
-            } else {
-                Ok(3)
-            }
-        };
-
-        // All extension methods should produce working retry builders
-        let r1 = op_exp
-            .with_exponential()
-            .call_with_sleeper(FnSleeper(|_| {}))
-            .expect("exponential retry works");
-
-        let r2 = op_const
-            .with_constant(100)
-            .call_with_sleeper(FnSleeper(|_| {}))
-            .expect("constant retry works");
-
-        let r3 = op_fib
-            .with_fibonacci()
-            .call_with_sleeper(FnSleeper(|_| {}))
-            .expect("fibonacci retry works");
-
-        assert_eq!(r1.into_inner(), 1);
-        assert_eq!(r2.into_inner(), 2);
-        assert_eq!(r3.into_inner(), 3);
-    }
-
-    #[cfg(feature = "std")]
-    #[test]
-    fn test_with_exponential_std_sleeper() {
-        use super::RetryableExt;
-        use core::cell::Cell;
-
-        let attempts = Cell::new(0);
-
-        let operation = || {
-            let current = attempts.get();
-            attempts.set(current + 1);
-
-            if current < 1 {
-                Err(TestError::Retryable)
-            } else {
-                Ok(999)
-            }
-        };
-
-        // Test with std sleeper
-        let result = operation.with_exponential().call();
-
-        let outcome = result.expect("retry should succeed");
-        assert_eq!(outcome.attempts(), 2);
-        assert_eq!(outcome.into_inner(), 999);
-    }
-
-    #[cfg(feature = "std")]
-    #[test]
-    fn test_with_constant_std_sleeper() {
-        use super::RetryableExt;
-
-        fn always_succeeds() -> Result<i32, TestError> {
-            Ok(888)
-        }
-
-        // Test with std sleeper
-        let result = always_succeeds.with_constant(50).call();
-
-        let outcome = result.expect("retry should succeed");
-        assert_eq!(outcome.into_inner(), 888);
-    }
-
-    #[cfg(feature = "std")]
-    #[test]
-    fn test_with_fibonacci_std_sleeper() {
-        use super::RetryableExt;
-
-        fn always_succeeds() -> Result<i32, TestError> {
-            Ok(444)
-        }
-
-        // Test with std sleeper
-        let result = always_succeeds.with_fibonacci().call();
-
-        let outcome = result.expect("retry should succeed");
-        assert_eq!(outcome.into_inner(), 444);
     }
 }
+
+#[cfg(test)]
+mod tests;