chrono_machines 0.9.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b11004f5b8e42aefeb73fc0a754d18af5503163e75ba23b2e55f15f767c9b39
-  data.tar.gz: af89d525918c2164ef919dbafc840fd8f34c91cf3d97c9ff1067e4f8a07d0d4e
+  metadata.gz: e4195a7a57a7069769ba6b45dec7b2187ffd78be09e03d79c6b744881306423d
+  data.tar.gz: 17d103b281d335cd9b0d2d78590a57f9eb5f5e68eaf3910aa07b51ccfe1a7cb3
 SHA512:
-  metadata.gz: b6eac8b9834568cbe4eef64945fe6c18ef572a808936a280f3b615ae1db8694fa449fa659a042ff5fc97b20d20e94513e33bb367e3cdd55b85595ba4cedf162e
-  data.tar.gz: ac0dda8c7a9957e081ed952a9e2aed1d445f5a1ac80f4bf23ba31e07c5ef01fa1b1d54d49ad11df080d27af24da3d4049642b13d9cf5093b193951e3663f00b1
+  metadata.gz: 9d8638c3dbdfa33e746beecba8e3e5cfc92a75cce7c315a604d07a5e108188dcff339a03406c66e220a2dcaa8ec28115d9b3047179fdbe214e9ba95b1115f0ce
+  data.tar.gz: 167d0237c2ff6ea4e0958befc179f60b5a518b44ac86106a3409f5a0ae611809b1a43520a928d3a5026cd1389429aeab856f7d15522df3703259767d23100020

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 ## [Unreleased]
 
+## [0.11.0](https://github.com/seuros/chrono_machines/compare/chrono_machines/v0.10.0...chrono_machines/v0.11.0) (2026-10-14)
+
+
+### ⚠ BREAKING CHANGES
+
+* **core:** RetryError::cause() returns &E and into_cause() returns E instead of Option.
+
+### Features
+
+* **core:** RetryError always carries its cause ([e5222a3](https://github.com/seuros/chrono_machines/commit/e5222a3c394974ba86605944f02d820345cbae8e))
+
+## [0.10.0](https://github.com/seuros/chrono_machines/compare/chrono_machines/v0.9.2...chrono_machines/v0.10.0) (2026-10-11)
+
+
+### Features
+
+* expose retry delays without executing or sleeping ([#30](https://github.com/seuros/chrono_machines/issues/30)) ([2f6ce19](https://github.com/seuros/chrono_machines/commit/2f6ce1999c7d2056d3adc8e57e0025c22087ca01))
+
+
+### Bug Fixes
+
+* reject a jitter random source without #rand ([50734ee](https://github.com/seuros/chrono_machines/commit/50734eee35608d8a8324b38cf38f9ab1cc101c65))
+
 ## [0.9.2](https://github.com/seuros/chrono_machines/compare/chrono_machines/v0.9.1...chrono_machines/v0.9.2) (2026-10-10)
 
 

data/Cargo.lock

@@ -69,7 +69,7 @@ dependencies = [
 
 [[package]]
 name = "chrono-machines"
-version = "0.8.0"
+version = "0.8.1"
 dependencies = [
  "rand",
  "tokio",
@@ -77,7 +77,7 @@ dependencies = [
 
 [[package]]
 name = "chrono_machines_native"
-version = "0.9.0"
+version = "0.9.1"
 dependencies = [
  "chrono-machines",
  "magnus",

data/README.md

@@ -221,6 +221,41 @@ The hook's return value controls the retry:
 
 Anything else raises `ArgumentError` - a broken hook fails loudly instead of silently mangling your retry cadence.
 
+### Scheduling retries without sleeping
+
+See the [Rails integration guide](docs/RAILS_INTEGRATION.md) for Active Job patterns, policy callbacks, and safe retries.
+
+`Executor#next_delay(attempt:, exception: nil)` returns seconds to wait, or `nil` to stop. `attempt: 1` means the initial call has failed; `max_attempts` includes that initial call. It uses the same backoff, jitter, exception rules, and `delay_from` hints as `call`, without executing work, sleeping, or running lifecycle callbacks. The caller owns the attempt count and scheduling. Without an exception, `delay_from` and exception filtering are skipped.
+
+For Active Job's `retry_on`, keep the attempt limit in sync with the policy:
+
+```ruby
+class FetchJob < ApplicationJob
+  RETRY_POLICY = ChronoMachines::Executor.new(max_attempts: 5, base_delay: 1)
+
+  retry_on IOError, attempts: 5,
+           wait: ->(executions) { RETRY_POLICY.next_delay(attempt: executions) }
+end
+```
+
+`retry_on` calls `wait` only while `executions < attempts`. If the two limits drift apart, `next_delay` returns `nil` and Active Job retries immediately, so keep `attempts:` equal to `max_attempts`.
+
+To use exception hints with durable jobs, pass the attempt count to the next job:
+
+```ruby
+def perform(record_id, attempt: 1)
+  fetch_record(record_id)
+rescue IOError => error
+  delay = RETRY_POLICY.next_delay(attempt: attempt, exception: error)
+  raise unless delay
+
+  self.class.set(wait_until: Time.current + delay)
+      .perform_later(record_id, attempt: attempt + 1)
+end
+```
+
+A hint beyond `max_delay` returns `nil`; it is never shortened to the cap. Use `random: Random.new(seed)` for deterministic jitter in tests, with either the Ruby or native backend.
+
 ## The Science of Temporal Jitter
 
 ChronoMachines implements **full jitter** exponential backoff:
@@ -239,16 +274,19 @@ ChronoMachines implements **full jitter** exponential backoff:
 
 This prevents the "thundering herd" problem where multiple clients retry simultaneously, overwhelming recovering services.
 
+Jitter is drawn from the `random:` option (Ruby's `Random` by default) on both backends; the native extension computes only the un-jittered base delay.
+
 ## Configuration Reference
 
 ### Policy Options
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `max_attempts` | `3` | Maximum number of retry attempts |
+| `max_attempts` | `3` | Maximum number of attempts, including the initial call |
 | `base_delay` | `0.1` | Initial delay in seconds |
 | `multiplier` | `2` | Exponential backoff multiplier |
 | `max_delay` | `10` | Maximum delay cap in seconds |
+| `random` | `Random` | Random source for jitter; accepts `Random.new(seed)` |
 | `retryable_exceptions` | `[StandardError]` | Array of exception classes to retry |
 | `on_success` | `nil` | Success callback: `(result:, attempts:)` |
 | `on_retry` | `nil` | Retry callback: `(exception:, attempt:, next_delay:)` |

data/ext/chrono_machines_native/core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "chrono-machines"
-version = "0.8.1"
+version = "0.9.0"
 edition.workspace = true
 rust-version.workspace = true
 authors = ["Abdelkader Boudih <terminale@gmail.com>"]

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

@@ -51,13 +51,7 @@ 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, error);
     if let Some(callback) = on_failure {
         callback(&retry_error);
     }
@@ -99,7 +93,7 @@ pub struct RetryError<E> {
     attempts: u8,
     max_attempts: u8,
     cumulative_delay_ms: u64,
-    cause: Option<E>,
+    cause: E,
 }
 
 impl<E> RetryError<E> {
@@ -108,7 +102,7 @@ impl<E> RetryError<E> {
         attempts: u8,
         max_attempts: u8,
         cumulative_delay_ms: u64,
-        cause: Option<E>,
+        cause: E,
     ) -> Self {
         Self {
             kind,
@@ -119,13 +113,13 @@ impl<E> RetryError<E> {
         }
     }
 
-    /// Retrieve the underlying cause when available.
-    pub const fn cause(&self) -> Option<&E> {
-        self.cause.as_ref()
+    /// The error from the final attempt.
+    pub const fn cause(&self) -> &E {
+        &self.cause
     }
 
-    /// Consume the error and return the underlying cause when available.
-    pub fn into_cause(self) -> Option<E> {
+    /// Consume the error and return the error from the final attempt.
+    pub fn into_cause(self) -> E {
         self.cause
     }
 
@@ -175,13 +169,11 @@ where
             }
         }
 
-        write!(f, " (cumulative delay {}ms)", self.cumulative_delay_ms)?;
-
-        if let Some(cause) = self.cause.as_ref() {
-            write!(f, ": {cause}")?;
-        }
-
-        Ok(())
+        write!(
+            f,
+            " (cumulative delay {}ms): {}",
+            self.cumulative_delay_ms, self.cause
+        )
     }
 }
 

data/lib/chrono_machines/executor.rb

@@ -15,6 +15,8 @@ module ChronoMachines
       @multiplier = policy_options[:multiplier] || 2
       @max_delay = policy_options[:max_delay]
       @jitter_factor = policy_options[:jitter_factor]
+      @random = policy_options[:random] || Random
+      raise ArgumentError, "random must respond to #rand; got #{@random.inspect}" unless @random.respond_to?(:rand)
       @retryable_exceptions = policy_options[:retryable_exceptions]
       @delay_from = policy_options[:delay_from]
       @on_failure = policy_options[:on_failure]
@@ -22,6 +24,14 @@ module ChronoMachines
       @on_success = policy_options[:on_success]
     end
 
+    def next_delay(attempt:, exception: nil)
+      raise ArgumentError, 'attempt must be a positive Integer' unless attempt.is_a?(Integer) && attempt.positive?
+      return if exception && !retryable_exception?(exception)
+      return if attempt >= @max_attempts
+
+      resolve_delay(exception, attempt)
+    end
+
     def call
       attempts = 0
 
@@ -34,22 +44,14 @@ module ChronoMachines
 
         result
       rescue StandardError => e
-        # Check if exception is retryable
-        unless @retryable_exceptions.any? { |ex| e.is_a?(ex) }
-          # Non-retryable exception - call failure callback and re-raise
+        delay = next_delay(attempt: attempts, exception: e)
+        unless delay
           handle_final_failure(e, attempts)
-          raise e
-        end
+          raise MaxRetriesExceededError.new(e, attempts) if retryable_exception?(e) && attempts >= @max_attempts
 
-        # Check if we've exhausted all attempts
-        if attempts >= @max_attempts
-          handle_final_failure(e, attempts)
-          raise MaxRetriesExceededError.new(e, attempts)
+          raise e
         end
 
-        # Calculate delay
-        delay = resolve_delay(e, attempts)
-
         # Call retry callback if defined
         @on_retry&.call(exception: e, attempt: attempts, next_delay: delay)
 
@@ -61,24 +63,25 @@ module ChronoMachines
 
     private
 
+    def retryable_exception?(exception)
+      @retryable_exceptions.any? { |type| exception.is_a?(type) }
+    end
+
     # delay_from(exception:, attempt:) overrides the backoff: nil -> backoff,
-    # Numeric -> verbatim (beyond max_delay: halt), :halt/false -> re-raise.
+    # Numeric -> verbatim (beyond max_delay: halt), :halt/false -> stop.
     def resolve_delay(exception, attempts)
-      return calculate_delay(attempts) unless @delay_from
+      return calculate_delay(attempts) unless exception && @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
+        return if @max_delay && hint > @max_delay
+
         hint
       when :halt, false
-        handle_final_failure(exception, attempts)
-        raise exception
+        nil
       else
         raise ArgumentError, "delay_from must return nil, a Numeric, :halt or false; got #{hint.inspect}"
       end
@@ -87,22 +90,19 @@ module ChronoMachines
     # 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
-      jitter_factor = normalized_jitter_factor
-      base_exponential_delay * (1 - jitter_factor + (rand * jitter_factor))
+      apply_jitter(base_exponential_delay)
     end
 
     # Pure Ruby implementation of constant backoff
     def ruby_calculate_delay_constant(_attempts)
-      jitter_factor = normalized_jitter_factor
-      @base_delay * (1 - jitter_factor + (rand * jitter_factor))
+      apply_jitter(@base_delay)
     end
 
     # Pure Ruby implementation of Fibonacci backoff
     def ruby_calculate_delay_fibonacci(attempts)
       fib = fibonacci(attempts)
       base_delay = [@base_delay * fib, @max_delay].min
-      jitter_factor = normalized_jitter_factor
-      base_delay * (1 - jitter_factor + (rand * jitter_factor))
+      apply_jitter(base_delay)
     end
 
     # Calculate Fibonacci number (1-indexed)
@@ -134,6 +134,11 @@ module ChronoMachines
     # By default, use Ruby implementation (may be overridden by native extension)
     alias_method :calculate_delay, :ruby_calculate_delay
 
+    def apply_jitter(delay)
+      jitter_factor = normalized_jitter_factor
+      delay * (1 - jitter_factor + (@random.rand * jitter_factor))
+    end
+
     def robust_sleep(delay)
       # Handle potential interruptions to sleep
       # In Ruby 3.2+, Kernel.sleep is fiber-aware

data/lib/chrono_machines/native_speedup.rb

@@ -22,32 +22,34 @@ begin
 
       # Override calculate_delay to dispatch to native implementations
       def calculate_delay(attempts)
-        case @backoff_strategy
-        when :exponential
-          ChronoMachinesNative.exponential_delay(
-            attempts,
-            @base_delay,
-            @multiplier,
-            @max_delay,
-            normalized_jitter_factor
-          )
-        when :constant
-          ChronoMachinesNative.constant_delay(
-            attempts,
-            @base_delay,
-            normalized_jitter_factor
-          )
-        when :fibonacci
-          ChronoMachinesNative.fibonacci_delay(
-            attempts,
-            @base_delay,
-            @max_delay,
-            normalized_jitter_factor
-          )
-        else
-          # Unknown strategy, fall back to Ruby
-          super
-        end
+        delay = case @backoff_strategy
+                when :exponential
+                  ChronoMachinesNative.exponential_delay(
+                    attempts,
+                    @base_delay,
+                    @multiplier,
+                    @max_delay,
+                    0.0
+                  )
+                when :constant
+                  ChronoMachinesNative.constant_delay(
+                    attempts,
+                    @base_delay,
+                    0.0
+                  )
+                when :fibonacci
+                  ChronoMachinesNative.fibonacci_delay(
+                    attempts,
+                    @base_delay,
+                    @max_delay,
+                    0.0
+                  )
+                else
+                  # Unknown strategy, fall back to Ruby
+                  return super
+                end
+
+        apply_jitter(delay)
       end
     end
 

data/lib/chrono_machines/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chrono_machines
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.11.0
 platform: ruby
 authors:
 - Abdelkader Boudih