chrono_machines 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8784b5114cde3b48cafa9ee9dff5fe69778795235610ecce63a44c73204c28f7
-  data.tar.gz: b87ddb52e946b220b0a2552647c85c928aa6b2a0e65e513005a40f1fbfd9e33a
+  metadata.gz: 520c4b33c24d8122f82758ed724886bfdd7955b427a98de6432bfd2b85f8355e
+  data.tar.gz: 7f31ccc205a392a0f26f932cdebdd13efb56204137598d38e818768f6116da53
 SHA512:
-  metadata.gz: 1c04099978047a09d84ad12e52ec228bf632063f228cc227ca993012044eec481956703bdac03e57a81995ebec87b46c515e3859d2095262c56d866be94b3b64
-  data.tar.gz: 387168ff2aa02a535b1c2e25ce9a2541afa535786b50e8cd28bce5cea56deee20a3fedd9255b74f886948f3b4d567fd1f39a13d0e5b7d13ecab8e67a8a49a7ae
+  metadata.gz: 51dbb600f208195e5c42f6cc8eec21069aa361f1c1056df5c960ea331a4335c1f18fb328fb27748d5535d9477fea99ae20f1a5961b1cd53ced563b336bc96542
+  data.tar.gz: 7a82f044a7fe6e185399021cb09e141a51e0370a468767df79058cf78567fda1ecc96dc0b916de6154d02b828a4b5b4ac803a5a0aa7e78078c147220383c0bfc

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 ## [Unreleased]
 
+## [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)
+
+
+### Bug Fixes
+
+* **ci:** attach release gems with gh release upload ([87466ea](https://github.com/seuros/chrono_machines/commit/87466eafe0126e5473ff49f176180eae08337657))
+
+
+### Performance Improvements
+
+* allocate outside the policy registry lock; adopt clippy pedantic and nursery ([80b40d8](https://github.com/seuros/chrono_machines/commit/80b40d87e5869c74b356a71425639ebf560cec4e))
+
 ## [0.9.1](https://github.com/seuros/chrono_machines/compare/chrono_machines/v0.9.0...chrono_machines/v0.9.1) (2026-10-05)
 
 

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

@@ -1,7 +1,20 @@
 [workspace]
 members = ["ext/chrono_machines_native/core", "ext/chrono_machines_native/ffi"]
-resolver = "2"
+resolver = "3"
+
+[workspace.package]
+edition = "2024"
+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"] }
+
+[workspace.lints.rust]
+unsafe_code = "deny"
+unused_must_use = "warn"
+
+[workspace.lints.clippy]
+all = "warn"
+pedantic = "warn"
+nursery = "warn"

data/README.md

@@ -221,6 +221,39 @@ 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
+
+`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 +272,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,7 +1,8 @@
 [package]
 name = "chrono-machines"
-version = "0.8.0"
-edition = "2024"
+version = "0.8.1"
+edition.workspace = true
+rust-version.workspace = true
 authors = ["Abdelkader Boudih <terminale@gmail.com>"]
 license = "MIT"
 description = "Exponential, constant, and Fibonacci backoff retry library with full jitter support - no_std compatible"
@@ -29,3 +30,6 @@ rand = { version = "0.10", default-features = false, features = ["std_rng"] }
 
 [dev-dependencies]
 tokio = { version = "1", features = ["rt", "rt-multi-thread", "macros", "time"] }
+
+[lints]
+workspace = true

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

@@ -8,7 +8,7 @@ use rand::RngExt;
 
 /// `f64::powi`, implemented by hand so it works in `core` (`no_std`).
 #[inline]
-pub(crate) fn powi_f64(base: f64, exp: i32) -> f64 {
+fn powi_f64(base: f64, exp: i32) -> f64 {
     if exp == 0 {
         return 1.0;
     }
@@ -25,7 +25,36 @@ pub(crate) fn powi_f64(base: f64, exp: i32) -> f64 {
     acc
 }
 
+/// Widen a delay (or Fibonacci factor) 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
+/// converts exactly; larger values only ever lose to the `max_delay_ms` cap.
+#[inline]
+#[expect(
+    clippy::cast_precision_loss,
+    reason = "inherent to u64 -> f64; exact below 2^53"
+)]
+const fn lossy_f64(n: u64) -> f64 {
+    n as f64
+}
+
+/// Un-jittered exponential delay: `base_delay_ms * multiplier^(attempt - 1)`,
+/// capped at `max_delay_ms`.
+#[inline]
+pub(crate) fn exponential_ms(
+    base_delay_ms: u64,
+    multiplier: f64,
+    max_delay_ms: u64,
+    attempt: u8,
+) -> f64 {
+    let exponent = i32::from(attempt.saturating_sub(1));
+    let base_exponential = lossy_f64(base_delay_ms) * powi_f64(multiplier, exponent);
+    base_exponential.min(lossy_f64(max_delay_ms))
+}
+
 /// Calculate the nth Fibonacci number (1-indexed): 1, 1, 2, 3, 5, 8, 13, ...
+#[must_use]
 pub fn fibonacci(n: u8) -> u64 {
     match n {
         0 => 0,
@@ -47,7 +76,22 @@ pub fn fibonacci(n: u8) -> u64 {
 ///
 /// `jitter_factor` is clamped to `[0.0, 1.0]`: `0.0` returns `base` unchanged,
 /// `1.0` yields a uniform value in `[0, base]`.
-fn apply_jitter<R: Rng>(base: f64, jitter_factor: f64, rng: &mut R) -> u64 {
+// Clippy only suggests `mul_add` when `std` provides it; `core` has no
+// `f64::mul_add`, so the suggestion would break the `no_std` build.
+#[cfg_attr(
+    feature = "std",
+    expect(
+        clippy::suboptimal_flops,
+        reason = "`f64::mul_add` is std-only (breaks no_std) and would change the rounding"
+    )
+)]
+#[expect(
+    clippy::cast_possible_truncation,
+    clippy::cast_sign_loss,
+    reason = "`as` is the saturating float -> int conversion: NaN and negatives \
+              become 0, overflow becomes u64::MAX, which is the clamp we want"
+)]
+pub(crate) fn apply_jitter<R: Rng>(base: f64, jitter_factor: f64, rng: &mut R) -> u64 {
     let jitter_factor = jitter_factor.clamp(0.0, 1.0);
     let random_scalar: f64 = rng.random_range(0.0..=1.0);
     let jitter_blend = 1.0 - jitter_factor + random_scalar * jitter_factor;
@@ -126,7 +170,7 @@ pub trait BackoffStrategy {
 
 /// Exponential backoff strategy with configurable jitter
 ///
-/// Delays grow exponentially: base_delay * multiplier^(attempt-1)
+/// Delays grow exponentially: `base_delay_ms * multiplier^(attempt - 1)`
 ///
 /// # Example
 ///
@@ -156,36 +200,48 @@ pub struct ExponentialBackoff {
 
 impl ExponentialBackoff {
     /// Create a new exponential backoff builder with default values
-    pub fn new() -> Self {
-        Self::default()
+    #[must_use]
+    pub const fn new() -> Self {
+        Self {
+            max_attempts: 3,
+            base_delay_ms: 100,
+            multiplier: 2.0,
+            max_delay_ms: 10_000,
+            jitter_factor: 1.0, // Full jitter by default
+        }
     }
 
     /// Set the base delay in milliseconds
-    pub fn base_delay_ms(mut self, ms: u64) -> Self {
+    #[must_use]
+    pub const fn base_delay_ms(mut self, ms: u64) -> Self {
         self.base_delay_ms = ms;
         self
     }
 
     /// Set the exponential multiplier
-    pub fn multiplier(mut self, multiplier: f64) -> Self {
+    #[must_use]
+    pub const fn multiplier(mut self, multiplier: f64) -> Self {
         self.multiplier = multiplier;
         self
     }
 
     /// Set the maximum delay cap in milliseconds
-    pub fn max_delay_ms(mut self, ms: u64) -> Self {
+    #[must_use]
+    pub const fn max_delay_ms(mut self, ms: u64) -> Self {
         self.max_delay_ms = ms;
         self
     }
 
     /// Set the maximum number of attempts
-    pub fn max_attempts(mut self, attempts: u8) -> Self {
+    #[must_use]
+    pub const fn max_attempts(mut self, attempts: u8) -> Self {
         self.max_attempts = attempts;
         self
     }
 
     /// Set the jitter factor (0.0 = no jitter, 1.0 = full jitter)
-    pub fn jitter_factor(mut self, factor: f64) -> Self {
+    #[must_use]
+    pub const fn jitter_factor(mut self, factor: f64) -> Self {
         self.jitter_factor = factor.clamp(0.0, 1.0);
         self
     }
@@ -193,13 +249,7 @@ impl ExponentialBackoff {
 
 impl Default for ExponentialBackoff {
     fn default() -> Self {
-        Self {
-            max_attempts: 3,
-            base_delay_ms: 100,
-            multiplier: 2.0,
-            max_delay_ms: 10_000,
-            jitter_factor: 1.0, // Full jitter by default
-        }
+        Self::new()
     }
 }
 
@@ -209,9 +259,12 @@ impl BackoffStrategy for ExponentialBackoff {
             return None;
         }
 
-        let exponent = attempt.saturating_sub(1) as i32;
-        let base_exponential = (self.base_delay_ms as f64) * powi_f64(self.multiplier, exponent);
-        let capped = base_exponential.min(self.max_delay_ms as f64);
+        let capped = exponential_ms(
+            self.base_delay_ms,
+            self.multiplier,
+            self.max_delay_ms,
+            attempt,
+        );
 
         Some(apply_jitter(capped, self.jitter_factor, rng))
     }
@@ -255,24 +308,32 @@ pub struct ConstantBackoff {
 
 impl ConstantBackoff {
     /// Create a new constant backoff builder with default values
-    pub fn new() -> Self {
-        Self::default()
+    #[must_use]
+    pub const fn new() -> Self {
+        Self {
+            delay_ms: 100,
+            max_attempts: 3,
+            jitter_factor: 0.0, // No jitter for constant by default
+        }
     }
 
     /// Set the constant delay in milliseconds
-    pub fn delay_ms(mut self, ms: u64) -> Self {
+    #[must_use]
+    pub const fn delay_ms(mut self, ms: u64) -> Self {
         self.delay_ms = ms;
         self
     }
 
     /// Set the maximum number of attempts
-    pub fn max_attempts(mut self, attempts: u8) -> Self {
+    #[must_use]
+    pub const fn max_attempts(mut self, attempts: u8) -> Self {
         self.max_attempts = attempts;
         self
     }
 
     /// Set the jitter factor (0.0 = no jitter, 1.0 = full jitter)
-    pub fn jitter_factor(mut self, factor: f64) -> Self {
+    #[must_use]
+    pub const fn jitter_factor(mut self, factor: f64) -> Self {
         self.jitter_factor = factor.clamp(0.0, 1.0);
         self
     }
@@ -280,11 +341,7 @@ impl ConstantBackoff {
 
 impl Default for ConstantBackoff {
     fn default() -> Self {
-        Self {
-            delay_ms: 100,
-            max_attempts: 3,
-            jitter_factor: 0.0, // No jitter for constant by default
-        }
+        Self::new()
     }
 }
 
@@ -294,7 +351,11 @@ impl BackoffStrategy for ConstantBackoff {
             return None;
         }
 
-        Some(apply_jitter(self.delay_ms as f64, self.jitter_factor, rng))
+        Some(apply_jitter(
+            lossy_f64(self.delay_ms),
+            self.jitter_factor,
+            rng,
+        ))
     }
 
     fn should_retry(&self, attempt: u8) -> bool {
@@ -309,7 +370,7 @@ impl BackoffStrategy for ConstantBackoff {
 /// Fibonacci backoff strategy
 ///
 /// Delays follow the Fibonacci sequence: 1, 1, 2, 3, 5, 8, 13, ...
-/// Each delay is base_delay_ms * fibonacci(attempt).
+/// Each delay is `base_delay_ms * fibonacci(attempt)`.
 ///
 /// # Example
 ///
@@ -336,30 +397,40 @@ pub struct FibonacciBackoff {
 
 impl FibonacciBackoff {
     /// Create a new Fibonacci backoff builder with default values
-    pub fn new() -> Self {
-        Self::default()
+    #[must_use]
+    pub const fn new() -> Self {
+        Self {
+            base_delay_ms: 100,
+            max_delay_ms: 10_000,
+            max_attempts: 8,
+            jitter_factor: 1.0, // Full jitter by default
+        }
     }
 
     /// Set the base delay in milliseconds
-    pub fn base_delay_ms(mut self, ms: u64) -> Self {
+    #[must_use]
+    pub const fn base_delay_ms(mut self, ms: u64) -> Self {
         self.base_delay_ms = ms;
         self
     }
 
     /// Set the maximum delay cap in milliseconds
-    pub fn max_delay_ms(mut self, ms: u64) -> Self {
+    #[must_use]
+    pub const fn max_delay_ms(mut self, ms: u64) -> Self {
         self.max_delay_ms = ms;
         self
     }
 
     /// Set the maximum number of attempts
-    pub fn max_attempts(mut self, attempts: u8) -> Self {
+    #[must_use]
+    pub const fn max_attempts(mut self, attempts: u8) -> Self {
         self.max_attempts = attempts;
         self
     }
 
     /// Set the jitter factor (0.0 = no jitter, 1.0 = full jitter)
-    pub fn jitter_factor(mut self, factor: f64) -> Self {
+    #[must_use]
+    pub const fn jitter_factor(mut self, factor: f64) -> Self {
         self.jitter_factor = factor.clamp(0.0, 1.0);
         self
     }
@@ -367,12 +438,7 @@ impl FibonacciBackoff {
 
 impl Default for FibonacciBackoff {
     fn default() -> Self {
-        Self {
-            base_delay_ms: 100,
-            max_delay_ms: 10_000,
-            max_attempts: 8,
-            jitter_factor: 1.0, // Full jitter by default
-        }
+        Self::new()
     }
 }
 
@@ -383,7 +449,8 @@ impl BackoffStrategy for FibonacciBackoff {
         }
 
         let fib = fibonacci(attempt);
-        let base = ((self.base_delay_ms as f64) * (fib as f64)).min(self.max_delay_ms as f64);
+        let base =
+            (lossy_f64(self.base_delay_ms) * lossy_f64(fib)).min(lossy_f64(self.max_delay_ms));
 
         Some(apply_jitter(base, self.jitter_factor, rng))
     }
@@ -417,11 +484,12 @@ pub enum BackoffPolicy {
 
 impl BackoffPolicy {
     /// Return the maximum retry attempts for the wrapped strategy.
-    pub fn max_attempts(&self) -> u8 {
+    #[must_use]
+    pub const fn max_attempts(&self) -> u8 {
         match self {
-            BackoffPolicy::Exponential(policy) => policy.max_attempts,
-            BackoffPolicy::Constant(policy) => policy.max_attempts,
-            BackoffPolicy::Fibonacci(policy) => policy.max_attempts,
+            Self::Exponential(policy) => policy.max_attempts,
+            Self::Constant(policy) => policy.max_attempts,
+            Self::Fibonacci(policy) => policy.max_attempts,
         }
     }
 }
@@ -429,52 +497,52 @@ impl BackoffPolicy {
 impl BackoffStrategy for BackoffPolicy {
     fn delay<R: Rng>(&self, attempt: u8, rng: &mut R) -> Option<u64> {
         match self {
-            BackoffPolicy::Exponential(policy) => policy.delay(attempt, rng),
-            BackoffPolicy::Constant(policy) => policy.delay(attempt, rng),
-            BackoffPolicy::Fibonacci(policy) => policy.delay(attempt, rng),
+            Self::Exponential(policy) => policy.delay(attempt, rng),
+            Self::Constant(policy) => policy.delay(attempt, rng),
+            Self::Fibonacci(policy) => policy.delay(attempt, rng),
         }
     }
 
     fn should_retry(&self, attempt: u8) -> bool {
         match self {
-            BackoffPolicy::Exponential(policy) => policy.should_retry(attempt),
-            BackoffPolicy::Constant(policy) => policy.should_retry(attempt),
-            BackoffPolicy::Fibonacci(policy) => policy.should_retry(attempt),
+            Self::Exponential(policy) => policy.should_retry(attempt),
+            Self::Constant(policy) => policy.should_retry(attempt),
+            Self::Fibonacci(policy) => policy.should_retry(attempt),
         }
     }
 
     fn max_attempts(&self) -> u8 {
         match self {
-            BackoffPolicy::Exponential(policy) => policy.max_attempts(),
-            BackoffPolicy::Constant(policy) => policy.max_attempts(),
-            BackoffPolicy::Fibonacci(policy) => policy.max_attempts(),
+            Self::Exponential(policy) => policy.max_attempts(),
+            Self::Constant(policy) => policy.max_attempts(),
+            Self::Fibonacci(policy) => policy.max_attempts(),
         }
     }
 
     fn max_delay_ms(&self) -> Option<u64> {
         match self {
-            BackoffPolicy::Exponential(policy) => policy.max_delay_ms(),
-            BackoffPolicy::Constant(policy) => policy.max_delay_ms(),
-            BackoffPolicy::Fibonacci(policy) => policy.max_delay_ms(),
+            Self::Exponential(policy) => policy.max_delay_ms(),
+            Self::Constant(policy) => policy.max_delay_ms(),
+            Self::Fibonacci(policy) => policy.max_delay_ms(),
         }
     }
 }
 
 impl From<ExponentialBackoff> for BackoffPolicy {
     fn from(value: ExponentialBackoff) -> Self {
-        BackoffPolicy::Exponential(value)
+        Self::Exponential(value)
     }
 }
 
 impl From<ConstantBackoff> for BackoffPolicy {
     fn from(value: ConstantBackoff) -> Self {
-        BackoffPolicy::Constant(value)
+        Self::Constant(value)
     }
 }
 
 impl From<FibonacciBackoff> for BackoffPolicy {
     fn from(value: FibonacciBackoff) -> Self {
-        BackoffPolicy::Fibonacci(value)
+        Self::Fibonacci(value)
     }
 }
 

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

@@ -22,7 +22,7 @@ pub enum DslError<E> {
 
 impl<E> From<RetryError<E>> for DslError<E> {
     fn from(value: RetryError<E>) -> Self {
-        DslError::Execution(value)
+        Self::Execution(value)
     }
 }
 
@@ -32,8 +32,8 @@ where
 {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
-            DslError::PolicyMissing(name) => write!(f, "retry policy '{}' is not registered", name),
-            DslError::Execution(err) => write!(f, "{err}"),
+            Self::PolicyMissing(name) => write!(f, "retry policy '{name}' is not registered"),
+            Self::Execution(err) => write!(f, "{err}"),
         }
     }
 }
@@ -41,6 +41,11 @@ where
 impl<E> std::error::Error for DslError<E> where E: fmt::Display + std::error::Error {}
 
 /// Construct a [`RetryBuilder`] using a named policy from the global registry.
+///
+/// # Errors
+///
+/// Returns [`DslError::PolicyMissing`] when no policy is registered under
+/// `policy_name`.
 pub fn builder_for_policy<F, T, E>(
     policy_name: &str,
     operation: F,
@@ -55,6 +60,12 @@ where
 }
 
 /// Execute an operation using a named policy from the global registry.
+///
+/// # Errors
+///
+/// Returns [`DslError::PolicyMissing`] when no policy is registered under
+/// `policy_name`, or [`DslError::Execution`] wrapping the [`RetryError`] when
+/// the retry gives up.
 pub fn retry_with_policy<F, T, E>(
     policy_name: &str,
     operation: F,