chrono_machines 0.5.2 → 0.9.1

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

@@ -1,15 +1,24 @@
 //! Sleep abstraction for no_std compatibility
 //!
-//! This module provides traits and implementations for sleeping/delaying
-//! in various environments (std, async, embedded).
+//! Two traits live here, and which one you want is decided by your runtime:
+//!
+//! - [`Sleeper`] blocks the calling thread. Use it from sync code and embedded.
+//! - [`AsyncSleeper`] yields to a reactor (`async` feature). Use it from tokio,
+//!   async-std, embassy or any other executor.
+//!
+//! They are separate traits rather than one trait with two methods because a
+//! blocking sleep cannot be adapted into an async one: `block_on` inside a
+//! runtime worker stalls that worker, and deadlocks outright on a
+//! current-thread runtime.
 
-/// Trait for sleep/delay implementations
+/// Trait for blocking sleep/delay implementations
 ///
 /// This trait abstracts sleep operations to support different runtime environments:
 /// - Standard library blocking sleep
-/// - Tokio/async-std async sleep
-/// - Embassy timer for embedded
+/// - Embassy/HAL busy-wait or timer delays for embedded
 /// - Custom implementations
+///
+/// Async runtimes want [`AsyncSleeper`] instead.
 pub trait Sleeper {
     /// Sleep for the specified number of milliseconds
     fn sleep_ms(&self, ms: u64);
@@ -42,7 +51,7 @@ impl Sleeper for StdSleeper {
 /// Function pointer sleeper for custom sleep implementations
 ///
 /// Wraps a function pointer that takes milliseconds and performs sleep.
-/// Useful for async runtimes or testing.
+/// Useful for embedded HAL delays or testing.
 ///
 /// # Example
 ///
@@ -67,31 +76,56 @@ impl Sleeper for FnSleeper {
     }
 }
 
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[cfg(feature = "std")]
-    #[test]
-    fn test_std_sleeper() {
-        let sleeper = StdSleeper;
-        let start = std::time::Instant::now();
-        sleeper.sleep_ms(10);
-        let elapsed = start.elapsed();
-
-        // Allow some margin for timing precision
-        assert!(elapsed.as_millis() >= 9 && elapsed.as_millis() <= 20);
-    }
-
-    #[test]
-    fn test_fn_sleeper() {
-        fn test_sleep(ms: u64) {
-            // In a real test, we'd need interior mutability
-            // For this test, we just verify it compiles and runs
-            assert!(ms > 0);
-        }
+/// Trait for asynchronous sleep/delay implementations
+///
+/// The async counterpart to [`Sleeper`], used by
+/// [`RetryBuilder::call_async`](crate::RetryBuilder::call_async). It is defined
+/// with an `async fn` in trait rather than a boxed future, so the returned
+/// future stays a concrete type and the crate needs no `async-trait`
+/// dependency and performs no allocation per sleep.
+///
+/// Any `Fn(u64) -> Future<Output = ()>` implements it, which covers every
+/// runtime without this crate depending on one:
+///
+/// ```rust,ignore
+/// // tokio
+/// let sleeper = |ms| tokio::time::sleep(Duration::from_millis(ms));
+///
+/// // embassy
+/// let sleeper = |ms| embassy_time::Timer::after_millis(ms);
+/// ```
+///
+/// # `Send` futures
+///
+/// The trait declares no `Send` bound, so it stays usable on
+/// single-threaded executors. Send-ness is not lost, though: it leaks through
+/// auto-trait inference at the concrete instantiation, so a retry future built
+/// from a `Send` sleeper and a `Send` operation is itself `Send` and can be
+/// handed to `tokio::spawn`. Only code that is *itself generic* over
+/// `S: AsyncSleeper` and must promise `Send` needs to spell the bound out, via
+/// return-type notation:
+///
+/// ```rust,ignore
+/// async fn spawnable<S>(sleeper: S)
+/// where
+///     S: AsyncSleeper<sleep_ms(..): Send> + Send + 'static,
+/// ```
+#[cfg(feature = "async")]
+pub trait AsyncSleeper {
+    /// Sleep for the specified number of milliseconds, yielding to the executor
+    fn sleep_ms(&self, ms: u64) -> impl core::future::Future<Output = ()>;
+}
 
-        let sleeper = FnSleeper(test_sleep);
-        sleeper.sleep_ms(100);
+#[cfg(feature = "async")]
+impl<F, Fut> AsyncSleeper for F
+where
+    F: Fn(u64) -> Fut,
+    Fut: core::future::Future<Output = ()>,
+{
+    fn sleep_ms(&self, ms: u64) -> impl core::future::Future<Output = ()> {
+        self(ms)
     }
 }
+
+#[cfg(test)]
+mod tests;

data/ext/chrono_machines_native/ffi/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "chrono_machines_native"
-version = "0.3.0"
+version = "0.9.0"
 edition = "2024"
 authors = ["Abdelkader Boudih <terminale@gmail.com>"]
 license = "MIT"
@@ -14,9 +14,9 @@ crate-type = ["cdylib"]
 
 [dependencies]
 chrono-machines = { workspace = true, features = ["std"] }
-magnus = "0.8.2"
+magnus = "0.9"
 rand = { workspace = true }
-rb-sys = { version = "0.9.117", default-features = false, features = ["stable-api-compiled-fallback"] }
+rb-sys = { version = "0.9.124", default-features = false, features = ["stable-api-compiled-fallback"] }
 
 [features]
 default = ["std"]

data/ext/chrono_machines_native/ffi/src/lib.rs

@@ -7,9 +7,9 @@
 #![warn(clippy::all)]
 
 use chrono_machines::fibonacci;
-use magnus::{function, Error, Ruby};
-use rand::rngs::StdRng;
+use magnus::{Error, Ruby, function};
 use rand::RngExt;
+use rand::rngs::StdRng;
 use std::cell::RefCell;
 
 // Thread-local RNG for performance (avoids reseeding from entropy on every call)
@@ -106,6 +106,11 @@ fn apply_jitter(base: f64, jitter_factor: f64) -> f64 {
 /// Initialize the Ruby extension
 #[magnus::init]
 fn init(ruby: &Ruby) -> Result<(), Error> {
+    // Must precede every method definition: Ruby marks methods Ractor-safe as
+    // they are defined. The RNG is thread-local, so Ractors never share it.
+    // SAFETY: called on the loading thread during extension initialisation.
+    unsafe { rb_sys::rb_ext_ractor_safe(true) };
+
     // Create ChronoMachinesNative module
     let module = ruby.define_module("ChronoMachinesNative")?;
 
@@ -124,69 +129,4 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
 }
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-    use rand::SeedableRng;
-
-    #[test]
-    fn test_exponential_delay() {
-        RNG.with(|rng| {
-            *rng.borrow_mut() = StdRng::seed_from_u64(1337);
-        });
-
-        let delay = calculate_delay_exponential(1, 0.0004, 1.0, 0.001, 0.5);
-
-        assert!(
-            delay >= 0.0002 && delay <= 0.0004,
-            "expected delay in [0.0002, 0.0004], got {delay}"
-        );
-    }
-
-    #[test]
-    fn test_constant_delay() {
-        RNG.with(|rng| {
-            *rng.borrow_mut() = StdRng::seed_from_u64(42);
-        });
-
-        // Constant delay with 10% jitter should be 90-100% of base
-        let delay = calculate_delay_constant(5, 1.0, 0.1);
-        assert!(delay >= 0.9 && delay <= 1.0, "got {delay}");
-
-        // No jitter should return exact value
-        let delay = calculate_delay_constant(3, 0.5, 0.0);
-        assert_eq!(delay, 0.5);
-    }
-
-    #[test]
-    fn test_fibonacci_delay() {
-        RNG.with(|rng| {
-            *rng.borrow_mut() = StdRng::seed_from_u64(123);
-        });
-
-        // Fibonacci sequence: 1, 1, 2, 3, 5, 8, 13...
-        // Attempt 1: base_delay * 1 = 0.1
-        let delay1 = calculate_delay_fibonacci(1, 0.1, 10.0, 0.0);
-        assert_eq!(delay1, 0.1);
-
-        // Attempt 5: base_delay * 5 = 0.5
-        let delay5 = calculate_delay_fibonacci(5, 0.1, 10.0, 0.0);
-        assert_eq!(delay5, 0.5);
-
-        // Attempt 8: base_delay * 21 = 2.1
-        let delay8 = calculate_delay_fibonacci(8, 0.1, 10.0, 0.0);
-        assert_eq!(delay8, 2.1);
-    }
-
-    #[test]
-    fn test_fibonacci_sequence() {
-        assert_eq!(fibonacci(0), 0);
-        assert_eq!(fibonacci(1), 1);
-        assert_eq!(fibonacci(2), 1);
-        assert_eq!(fibonacci(3), 2);
-        assert_eq!(fibonacci(4), 3);
-        assert_eq!(fibonacci(5), 5);
-        assert_eq!(fibonacci(6), 8);
-        assert_eq!(fibonacci(7), 13);
-        assert_eq!(fibonacci(8), 21);
-    }
-}
+mod tests;

data/lib/chrono_machines/configuration.rb

@@ -18,6 +18,7 @@ module ChronoMachines
           max_delay: 10,   # seconds
           jitter_factor: 1.0, # 1.0 = full jitter (recommended), 0.0 = no jitter
           retryable_exceptions: [StandardError],
+          delay_from: nil, # Optional delay override from the exception (e.g. HTTP Retry-After)
           on_failure: nil, # Fallback block when all retries are exhausted
           on_retry: nil,   # Callback block when a retry occurs
           on_success: nil  # Callback block when operation succeeds

data/lib/chrono_machines/executor.rb

@@ -16,6 +16,7 @@ module ChronoMachines
       @max_delay = policy_options[:max_delay]
       @jitter_factor = policy_options[:jitter_factor]
       @retryable_exceptions = policy_options[:retryable_exceptions]
+      @delay_from = policy_options[:delay_from]
       @on_failure = policy_options[:on_failure]
       @on_retry = policy_options[:on_retry]
       @on_success = policy_options[:on_success]
@@ -47,7 +48,7 @@ module ChronoMachines
         end
 
         # Calculate delay
-        delay = calculate_delay(attempts)
+        delay = resolve_delay(e, attempts)
 
         # Call retry callback if defined
         @on_retry&.call(exception: e, attempt: attempts, next_delay: delay)
@@ -60,6 +61,29 @@ module ChronoMachines
 
     private
 
+    # delay_from(exception:, attempt:) overrides the backoff: nil -> backoff,
+    # Numeric -> verbatim (beyond max_delay: halt), :halt/false -> re-raise.
+    def resolve_delay(exception, attempts)
+      return calculate_delay(attempts) unless @delay_from
+
+      hint = @delay_from.call(exception: exception, attempt: attempts)
+      case hint
+      when nil
+        calculate_delay(attempts)
+      when Numeric
+        if @max_delay && hint > @max_delay
+          handle_final_failure(exception, attempts)
+          raise exception
+        end
+        hint
+      when :halt, false
+        handle_final_failure(exception, attempts)
+        raise exception
+      else
+        raise ArgumentError, "delay_from must return nil, a Numeric, :halt or false; got #{hint.inspect}"
+      end
+    end
+
     # Pure Ruby implementation of delay calculation (exponential backoff)
     def ruby_calculate_delay_exponential(attempts)
       base_exponential_delay = [@base_delay * (@multiplier**(attempts - 1)), @max_delay].min

data/lib/chrono_machines/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ChronoMachines
-  VERSION = '0.5.2'
+  VERSION = '0.9.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chrono_machines
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.9.1
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -79,14 +79,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.3.0
+      version: 4.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.20
 specification_version: 4
 summary: A robust Ruby gem for implementing retry mechanisms with exponential backoff
   and jitter.