chrono_machines 0.10.0-aarch64-linux → 0.12.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aeef5fdf2ecf22b876dedb43acf7873ac34ba2ca05249490ab5b190048885ce6
-  data.tar.gz: 1256e269112ab4703288f2a5d44bd8f7183230a3b2f8e40278a1e756e9f55fcb
+  metadata.gz: f9cbe0bcc4e1a9a8b286eabcab9b3f15bc74d28a91ce04b0aecda3d4e781670b
+  data.tar.gz: 066e08f1c403bdd2c3774007a9b115e5b89377eb43c0d81a24e7f181d4f27a3c
 SHA512:
-  metadata.gz: 5ad2fbc6e409420019e0589ed9d6b582a777c6d2e0a25bad4951d274af9c94df0811ae89b21558be6f3592ab69e8dfd0f7a0b59fe3115cbd14c85686eb131353
-  data.tar.gz: 9a64d22915c64d7a4a708abf18649a486338bbbcf5a58443ea4f11cc6e714e35758be3b2a8c6137d6c0432c8b7c0736d3fd02416e1fc861e2c0233ffd3246ee0
+  metadata.gz: b933ad2cd45d43512e5bc5b3eedb5b574736d490773649e3c30b40a8363c4885a04c278a0eecddccea3efb53eb7e262e37f13e9f6477992bbb495d99c57538ed
+  data.tar.gz: eca8035836bd8e81b7b04129a195302d2ec5055702cf2ed8557daf0a6fb823b60fb08c93e67dbba49e7c0eaf0efd2f84820571c28df53aa160592309e1e96795

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/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/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,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: chrono_machines
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.12.0
 platform: aarch64-linux
 authors:
 - Abdelkader Boudih
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-10-11 00:00:00.000000000 Z
+date: 2026-11-01 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: zeitwerk
   requirement: !ruby/object:Gem::Requirement