chrono_machines 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 520c4b33c24d8122f82758ed724886bfdd7955b427a98de6432bfd2b85f8355e
-  data.tar.gz: 7f31ccc205a392a0f26f932cdebdd13efb56204137598d38e818768f6116da53
+  metadata.gz: 6657b6db5e08ccde2f9145ccb5f2f5701ee4edd1c54a89998bfbe047510e024d
+  data.tar.gz: f34228d0ed9ce646a7d5eb4f180ff4c775f53bd9e799d33ec4cc80b861c27401
 SHA512:
-  metadata.gz: 51dbb600f208195e5c42f6cc8eec21069aa361f1c1056df5c960ea331a4335c1f18fb328fb27748d5535d9477fea99ae20f1a5961b1cd53ced563b336bc96542
-  data.tar.gz: 7a82f044a7fe6e185399021cb09e141a51e0370a468767df79058cf78567fda1ecc96dc0b916de6154d02b828a4b5b4ac803a5a0aa7e78078c147220383c0bfc
+  metadata.gz: 9c11744285959ebbaeb17cb77e141ea6c8e763b5dddce05a0de06cdcef7fd8ddedfa54a26f381a8435345490b0ad9ec1bae217463ed62bfcd795b05ac069384c
+  data.tar.gz: b4d6d6a1b519abba7b0d03c648cd4339782af0eda8d13e78e34232777105cb1023eef1d5040a08a57f41fec329d2dd587557578a466f79f04af8f519a8c6b868

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 ## [Unreleased]
 
+## [0.12.0](https://github.com/seuros/chrono_machines/compare/chrono_machines/v0.11.0...chrono_machines/v0.12.0) (2026-11-01)
+
+
+### ⚠ BREAKING CHANGES
+
+* `chrono_machines::fibonacci` returns f64, and `max_attempts` outside 1..255 is rejected instead of silently computed on one backend only.
+
+### Features
+
+* expose full jitter as a one-shot ([ff78a9c](https://github.com/seuros/chrono_machines/commit/ff78a9ca3a9e3a3b3a64a5427290e9f72e55305a))
+* honour an ambient deadline during retries ([97b24d0](https://github.com/seuros/chrono_machines/commit/97b24d0b73751a6a25f1ee703cb251ff43ed167a))
+
+
+### Bug Fixes
+
+* a failing success callback no longer re-runs the operation ([920ecc9](https://github.com/seuros/chrono_machines/commit/920ecc9002b66a7617ed99537c63ab6b2238c1ba))
+* a lone checkout can bundle ([19276ef](https://github.com/seuros/chrono_machines/commit/19276ef6b78f0a13c18c7d23e91e2830d9cf0b1c))
+* a source install can build, and a failed gem push fails the release ([cd85f2c](https://github.com/seuros/chrono_machines/commit/cd85f2cc5270830a89b35e7217a10e2454813ab3))
+* build the native speedup on CRuby only ([0b30fc6](https://github.com/seuros/chrono_machines/commit/0b30fc61b753908a9bff39e77b8854ab74ef603f))
+* Fibonacci backoff no longer saturates on the native backend ([213413c](https://github.com/seuros/chrono_machines/commit/213413ce86af8107396d8462449e7cebd2430e17))
+* load the native build tasks on CRuby only ([f0826ca](https://github.com/seuros/chrono_machines/commit/f0826ca5e9636facde86fb02fd30d5be28b683e0))
+* ship the core's test files so the packaged crate builds ([89b1de5](https://github.com/seuros/chrono_machines/commit/89b1de5067b222de580d761ce17b439e8b689533))
+
+## [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)
 
 

data/Cargo.lock

@@ -69,7 +69,7 @@ dependencies = [
 
 [[package]]
 name = "chrono-machines"
-version = "0.8.1"
+version = "0.9.0"
 dependencies = [
  "rand",
  "tokio",
@@ -233,9 +233,9 @@ checksum = "953f07c43838f8e6f9758cab68bf5bed85465e7587ebe0b823f1bcd81978ad3a"
 
 [[package]]
 name = "magnus"
-version = "0.9.2"
+version = "0.9.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b9068710e00d21be762edca59b9c4c8946dbdb29820d4f76ad559afea07982c9"
+checksum = "40ef424404d166cbb71c8b8d19c9c589c748c4547c1afa1928c5504299f6c713"
 dependencies = [
  "magnus-macros",
  "rb-sys",

data/Cargo.toml

@@ -8,7 +8,7 @@ rust-version = "1.99"
 
 [workspace.dependencies]
 chrono-machines = { path = "ext/chrono_machines_native/core" }
-rand = { version = "0.10", default-features = false, features = ["std_rng", "sys_rng"] }
+rand = { version = "0.10", default-features = false, features = ["std_rng"] }
 
 [workspace.lints.rust]
 unsafe_code = "deny"

data/README.md

@@ -39,7 +39,7 @@ Still here? Excellent. Because in the fabric of spacetime, nobody can hear your
 
 ### The Pattern Time Forgot
 
-Built for Ruby 3.2+ with fiber-aware sleep and full jitter implementation, because when you're manipulating time itself, precision matters.
+Built for Ruby 4.0+ with fiber-aware sleep and full jitter implementation, because when you're manipulating time itself, precision matters.
 
 ## Features
 
@@ -223,6 +223,8 @@ Anything else raises `ArgumentError` - a broken hook fails loudly instead of sil
 
 ### 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:
@@ -280,7 +282,7 @@ Jitter is drawn from the `random:` option (Ruby's `Random` by default) on both b
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `max_attempts` | `3` | Maximum number of attempts, including the initial call |
+| `max_attempts` | `3` | Maximum number of attempts, including the initial call; `1..255` |
 | `base_delay` | `0.1` | Initial delay in seconds |
 | `multiplier` | `2` | Exponential backoff multiplier |
 | `max_delay` | `10` | Maximum delay cap in seconds |
@@ -625,7 +627,7 @@ end
 ## Why ChronoMachines?
 
 ### Built for Modern Ruby
-- **Ruby 3.2+ Support**: Fiber-aware sleep handling
+- **Ruby 4.0+ Support**: Fiber-aware sleep handling
 - **Clean Architecture**: Separation of concerns with configurable policies
 - **Rich Instrumentation**: Comprehensive callback system for monitoring
 - **Battle-Tested**: Full jitter implementation prevents thundering herds

data/ext/chrono_machines_native/core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "chrono-machines"
-version = "0.8.1"
+version = "0.10.0"
 edition.workspace = true
 rust-version.workspace = true
 authors = ["Abdelkader Boudih <terminale@gmail.com>"]
@@ -10,7 +10,7 @@ repository = "https://github.com/seuros/chrono_machines"
 keywords = ["retry", "backoff", "exponential", "jitter", "resilience"]
 categories = ["no-std", "algorithms"]
 readme = "README.md"
-exclude = ["tests/", "src/**/tests.rs"]
+exclude = ["tests/"]
 
 [lib]
 name = "chrono_machines"
@@ -26,7 +26,7 @@ alloc = []
 async = ["alloc"]
 
 [dependencies]
-rand = { version = "0.10", default-features = false, features = ["std_rng"] }
+rand = { workspace = true }
 
 [dev-dependencies]
 tokio = { version = "1", features = ["rt", "rt-multi-thread", "macros", "time"] }

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

@@ -25,7 +25,7 @@ fn powi_f64(base: f64, exp: i32) -> f64 {
     acc
 }
 
-/// Widen a delay (or Fibonacci factor) to `f64` for the backoff arithmetic.
+/// Widen a delay to `f64` for the backoff arithmetic.
 ///
 /// There is no lossless `u64 -> f64` conversion. Rounding only starts above
 /// 2^53 (2^53 ms is ~285,000 years), so every delay that can actually be slept
@@ -53,23 +53,25 @@ pub(crate) fn exponential_ms(
     base_exponential.min(lossy_f64(max_delay_ms))
 }
 
-/// Calculate the nth Fibonacci number (1-indexed): 1, 1, 2, 3, 5, 8, 13, ...
+/// The nth Fibonacci number (1-indexed), as a delay factor: 1, 1, 2, 3, 5, 8, ...
+///
+/// The sequence passes `2^53` at n = 79 and `u64::MAX` at n = 94, so no integer
+/// accumulator reaches the end of the `u8` attempt range. One that stops at its
+/// own ceiling scales to a delay *under* `max_delay`, which is then silently
+/// wrong rather than capped; the `f64` recurrence keeps growing and leaves the
+/// decision to the cap. It rounds from n = 82 on, within two ulps of the exact
+/// sequence over the whole range, and the gem's pure-Ruby backoff runs the same
+/// recurrence, so the two backends agree bit for bit.
 #[must_use]
-pub fn fibonacci(n: u8) -> u64 {
-    match n {
-        0 => 0,
-        1 | 2 => 1,
-        _ => {
-            let mut a = 1u64;
-            let mut b = 1u64;
-            for _ in 2..n {
-                let next = a.saturating_add(b);
-                a = b;
-                b = next;
-            }
-            b
-        }
-    }
+pub fn fibonacci(n: u8) -> f64 {
+    let mut previous = 0.0_f64;
+    let mut current = 1.0_f64;
+    for _ in 0..n {
+        let next = previous + current;
+        previous = current;
+        current = next;
+    }
+    previous
 }
 
 /// Blend a base delay with jitter using the full-jitter algorithm.
@@ -448,9 +450,8 @@ impl BackoffStrategy for FibonacciBackoff {
             return None;
         }
 
-        let fib = fibonacci(attempt);
         let base =
-            (lossy_f64(self.base_delay_ms) * lossy_f64(fib)).min(lossy_f64(self.max_delay_ms));
+            (lossy_f64(self.base_delay_ms) * fibonacci(attempt)).min(lossy_f64(self.max_delay_ms));
 
         Some(apply_jitter(base, self.jitter_factor, rng))
     }

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/ext/chrono_machines_native/ffi/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "chrono_machines_native"
-version = "0.9.1"
+version = "0.10.0"
 edition.workspace = true
 rust-version.workspace = true
 authors = ["Abdelkader Boudih <terminale@gmail.com>"]
@@ -15,7 +15,7 @@ crate-type = ["cdylib"]
 
 [dependencies]
 chrono-machines = { workspace = true, features = ["std"] }
-magnus = "0.9"
+magnus = { version = ">= 0.9.3", default-features = false, features = ["io"] }
 rand = { workspace = true }
 rb-sys = { version = "0.9.124", default-features = false, features = ["stable-api-compiled-fallback"] }
 

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

@@ -73,14 +73,7 @@ fn calculate_delay_fibonacci(
 ) -> f64 {
     let jitter_factor = normalize_jitter(jitter_factor);
 
-    // Fibonacci numbers pass 2^53 at n = 79; from there the cast rounds to the
-    // nearest f64, an error far below anything a delay in seconds can express.
-    #[expect(
-        clippy::cast_precision_loss,
-        reason = "u64 -> f64 has no lossless conversion; rounding only starts above 2^53"
-    )]
-    let fib = fibonacci(attempt_u8(attempt)) as f64;
-    let base = (base_delay * fib).min(max_delay);
+    let base = (base_delay * fibonacci(attempt_u8(attempt))).min(max_delay);
 
     apply_jitter(base, jitter_factor)
 }

data/lib/chrono_machines/executor.rb

@@ -2,6 +2,8 @@
 
 module ChronoMachines
   class Executor
+    ATTEMPT_LIMIT = 255
+
     def initialize(policy_or_options = {})
       policy_options = if policy_or_options.is_a?(Symbol)
                          ChronoMachines.config.get_policy(policy_or_options)
@@ -11,6 +13,11 @@ module ChronoMachines
 
       @backoff_strategy = policy_options[:backoff_strategy] || :exponential
       @max_attempts = policy_options[:max_attempts]
+      unless @max_attempts.is_a?(Integer) && @max_attempts.between?(1, ATTEMPT_LIMIT)
+        raise ArgumentError, "max_attempts must be an Integer in 1..#{ATTEMPT_LIMIT} " \
+                             "(the native backend counts attempts in a u8); got #{@max_attempts.inspect}"
+      end
+
       @base_delay = policy_options[:base_delay]
       @multiplier = policy_options[:multiplier] || 2
       @max_delay = policy_options[:max_delay]
@@ -34,16 +41,14 @@ module ChronoMachines
 
     def call
       attempts = 0
+      DeadlineMachines.check!
 
-      begin
+      result = begin
         attempts += 1
-        result = yield
-
-        # Call success callback if defined
-        @on_success&.call(result: result, attempts: attempts)
-
-        result
+        yield
       rescue StandardError => e
+        raise if caller_gave_up?(e)
+
         delay = next_delay(attempt: attempts, exception: e)
         unless delay
           handle_final_failure(e, attempts)
@@ -52,17 +57,33 @@ module ChronoMachines
           raise e
         end
 
-        # Call retry callback if defined
-        @on_retry&.call(exception: e, attempt: attempts, next_delay: delay)
-
-        # Execute delay with robust sleep
-        robust_sleep(delay)
+        stop_on_spent_budget(e, attempts)
+        budget = DeadlineMachines.clamp_sleep(delay)
+        @on_retry&.call(exception: e, attempt: attempts, next_delay: budget)
+        robust_sleep(DeadlineMachines.clamp_sleep(budget))
+        stop_on_spent_budget(e, attempts)
         retry
       end
+
+      @on_success&.call(result: result, attempts: attempts)
+      result
     end
 
     private
 
+    # A deadline error from a narrower inner scope is a timeout worth retrying.
+    # One raised because this caller's own budget is gone is not.
+    def caller_gave_up?(error)
+      error.is_a?(DeadlineMachines::Error) && DeadlineMachines.current&.done?
+    end
+
+    def stop_on_spent_budget(exception, attempts)
+      return unless DeadlineMachines.current&.done?
+
+      handle_final_failure(exception, attempts)
+      DeadlineMachines.check!
+    end
+
     def retryable_exception?(exception)
       @retryable_exceptions.any? { |type| exception.is_a?(type) }
     end
@@ -105,16 +126,14 @@ module ChronoMachines
       apply_jitter(base_delay)
     end
 
-    # Calculate Fibonacci number (1-indexed)
+    # The nth Fibonacci number (1-indexed), as a delay factor, accumulated step
+    # for step with `fibonacci` in ext/chrono_machines_native/core/src/backoff.rs,
+    # whose documentation covers why neither side counts in integers.
     def fibonacci(n)
-      return 0 if n.zero?
-      return 1 if n <= 2
-
-      a, b = 1, 1
-      (2...n).each do
-        a, b = b, a + b
-      end
-      b
+      previous = 0.0
+      current = 1.0
+      n.times { previous, current = current, previous + current }
+      previous
     end
 
     # Main calculate_delay dispatches to the appropriate strategy

data/lib/chrono_machines/native_speedup.rb

@@ -5,14 +5,9 @@
 # to use the native Rust implementation for delay calculations.
 
 begin
-  # Try to load the native extension
-  # Prefer local development version if it exists
-  local_ext_path = File.expand_path('../../ext/chrono_machines_native/chrono_machines_native', __dir__)
-  if File.exist?("#{local_ext_path}.bundle") || File.exist?("#{local_ext_path}.so")
-    require local_ext_path
-  else
-    require 'chrono_machines_native/chrono_machines_native'
-  end
+  # `rake compile` installs the extension here. A leftover build under ext/
+  # must not shadow it: that is how a stale native backend gets tested.
+  require 'chrono_machines_native/chrono_machines_native'
 
   module ChronoMachines
     # Native speedup module that overrides backoff calculations

data/lib/chrono_machines/version.rb

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

data/lib/chrono_machines.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'deadline_machines'
 require 'zeitwerk'
 
 loader = Zeitwerk::Loader.for_gem
@@ -27,6 +28,17 @@ module ChronoMachines
   def self.retry(policy_name_or_options = {}, &)
     Executor.new(policy_name_or_options).call(&)
   end
+
+  # Full jitter over a single duration: the result lands in
+  # `seconds * (1 - factor)` to `seconds`, so a fleet of callers waiting the
+  # same nominal time does not wake up together.
+  def self.jitter(seconds, factor:, random: Random)
+    factor = Float(factor)
+    raise ArgumentError, 'factor cannot be NaN' if factor.nan?
+
+    factor = factor.clamp(0.0, 1.0)
+    seconds * (1 - factor + (random.rand * factor))
+  end
 end
 
 # Load optional async support after core is loaded

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chrono_machines
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -9,6 +9,34 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: deadline_machines
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement