chrono_machines 0.9.2-aarch64-linux → 0.11.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09a86cb08e19697cbac9456c15de806f0d5ba1461345675319a014340c5e580f'
-  data.tar.gz: '0558916e71edf61d3643433f2ba247804b1ef4bf86a88ba890f410d50a126743'
+  metadata.gz: fc22547860d54b36a7bc9c5c2afabc18840c94869a924a8318ea50036924f374
+  data.tar.gz: ab5a3d65ec8e91f04dfdb8eb0b6327bd5cbf5aba9be015f800be78a6c7d7e037
 SHA512:
-  metadata.gz: c0bab09a36137f09c991551a38354b164c908da05a05a58fa51492455f866e2fb4862912e654be5c28ed82ea53622d99c3e76cdf361fd24fe3c5497b2c2ddfc6
-  data.tar.gz: e416d74f419f6c1f89ef2814af04e27cf9dc4f57f5c2f3f2be04458833cf6aaee9cf4efaedcb56f2323391c8cba726a6b71cd68601630efea4e471af9fe18feb
+  metadata.gz: 0aa6eeb316ac2a1a415bc5e92682554bef7cedbcd52bca87b597ff8e32b1f1a7696954e0247c994e7dd3ab06435a1cb42c1fe0176641dc06e3146bc62027c27b
+  data.tar.gz: 26a71d24a664a8b19ece84ca8199c8200b4b5fa133820ae36fde090c05813eaaf5e9a7bf595aee17781c36546cdf556bccd669a84c30e16b3e4a5f2cac5fed23

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/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/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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chrono_machines
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.11.0
 platform: aarch64-linux
 authors:
 - Abdelkader Boudih
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-10-10 00:00:00.000000000 Z
+date: 2026-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk