chrono_machines 0.5.1-aarch64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3184a28d31c4f22e7e445670e62c4a1912fe8c989bafd3626513547cf2ea4434
+  data.tar.gz: 0a628e34a0e801ea30bbc09b72eac8834d083be7ed5717a89def1aa765bace41
+SHA512:
+  metadata.gz: 8a4bcbacf0d62e161cd2907bfe7b507717467eefb69d4d50f99b74f369b0ee6d82c3a494c86608b4d96a3ccd1bcac7b53d9d3f564ffb7296e5cf2d41cd734308
+  data.tar.gz: cde6a4494eecdeb1b9b7a95f522db9a7c55085b70f1507a4c5876fa0fe03fcc7b76b3b5bd56db39e5bbb1fc9a27af3a218fe2f6dc32e1dabf5cd80c98c33290f

data/CHANGELOG.md

@@ -0,0 +1,86 @@
+## [Unreleased]
+
+## [0.5.1](https://github.com/seuros/chrono_machines/compare/chrono_machines/v0.5.0...chrono_machines/v0.5.1) (2026-08-07)
+
+
+### Bug Fixes
+
+* package workspace Cargo manifest so source builds work ([#17](https://github.com/seuros/chrono_machines/issues/17)) ([ac0ddad](https://github.com/seuros/chrono_machines/commit/ac0ddad15d26528771825240a05ed8c84fb61520))
+
+## [0.5.0](https://github.com/seuros/chrono_machines/compare/chrono_machines/v0.4.4...chrono_machines/v0.5.0) (2026-06-24)
+
+
+### Features
+
+* **native:** make core crate no_std capable ([#15](https://github.com/seuros/chrono_machines/issues/15)) ([76129a3](https://github.com/seuros/chrono_machines/commit/76129a31ad75142641e4a29a82424ad26fb9ecd6))
+
+
+### Bug Fixes
+
+* **native:** use workspace dependency for chrono-machines in ffi ([fdeca2f](https://github.com/seuros/chrono_machines/commit/fdeca2f938e2647107793cfcf4c5c7c77e62e09b))
+
+## [0.4.4](https://github.com/seuros/chrono_machines/compare/chrono_machines/v0.4.3...chrono_machines/v0.4.4) (2026-06-16)
+
+
+### Bug Fixes
+
+* Upgrade setup-java action to version 5 ([f6dcecc](https://github.com/seuros/chrono_machines/commit/f6dcecc233d4d4f74bacad8bfe893eff981a4737))
+
+## [0.4.3](https://github.com/seuros/chrono_machines/compare/chrono_machines/v0.4.2...chrono_machines/v0.4.3) (2026-06-15)
+
+
+### Bug Fixes
+
+* **native:** deduplicate backoff jitter, fibonacci, and retry-failure logic ([46f861a](https://github.com/seuros/chrono_machines/commit/46f861acc7e29024fc35dafb39aaec22db33440d))
+
+## [0.4.2](https://github.com/seuros/chrono_machines/compare/chrono_machines/v0.4.1...chrono_machines/v0.4.2) (2026-05-25)
+
+
+### Bug Fixes
+
+* remove unused Magnus embed feature ([3b0877a](https://github.com/seuros/chrono_machines/commit/3b0877a11f768a135c877980320cae53fa58cd3d))
+
+## [0.4.1](https://github.com/seuros/chrono_machines/compare/chrono_machines/v0.4.0...chrono_machines/v0.4.1) (2026-03-19)
+
+
+### Bug Fixes
+
+* **native:** upgrade rand to 0.10 ([#10](https://github.com/seuros/chrono_machines/issues/10)) ([d7e2738](https://github.com/seuros/chrono_machines/commit/d7e2738552a98e4f528055f671cfdfbdb02b0c7a))
+
+## [0.4.0](https://github.com/seuros/chrono_machines/compare/chrono_machines/v0.3.0...chrono_machines/v0.4.0) (2025-12-19)
+
+
+### Features
+
+* add async support, error classification ([#6](https://github.com/seuros/chrono_machines/issues/6)) ([3d6d2c6](https://github.com/seuros/chrono_machines/commit/3d6d2c6e06de58247c74cdcef94e78a099b11e31))
+* add constant and fibonacci backoff strategies with native acceleration ([582ba9c](https://github.com/seuros/chrono_machines/commit/582ba9ccd84072ec4ccf5d3340eced27cc4d1925))
+
+
+### Bug Fixes
+
+* add Ruby 4.0.0-preview3 to test matrix ([#9](https://github.com/seuros/chrono_machines/issues/9)) ([df8a3a2](https://github.com/seuros/chrono_machines/commit/df8a3a23acf5ea37b115ab7d05936331b4ae2018))
+
+## [0.3.0](https://github.com/seuros/chrono_machines/compare/chrono_machines/v0.2.0...chrono_machines/v0.3.0) (2025-10-14)
+
+
+### Features
+
+* add COSS (Contribution Open Source Standard) metadata ([de5b64a](https://github.com/seuros/chrono_machines/commit/de5b64af5c443d8987909199a69030fa332fa323))
+* add GitHub Packages native compilation workflow ([0d7e950](https://github.com/seuros/chrono_machines/commit/0d7e9502d13a8de6b47756c27d682339435fe663))
+* Add Rust native speedup with fluent retry DSL ([#4](https://github.com/seuros/chrono_machines/issues/4)) ([ac980bf](https://github.com/seuros/chrono_machines/commit/ac980bfda450b4e63739e4dc3c19513dd989e819))
+
+
+### Bug Fixes
+
+* CI compilation using extconf.rb instead of rb_sys task ([bd844a5](https://github.com/seuros/chrono_machines/commit/bd844a594f25745edb407695ef36f7e214a29347))
+
+## [0.2.0](https://github.com/seuros/chrono_machines/compare/chrono_machines-v0.1.0...chrono_machines/v0.2.0) (2025-07-20)
+
+
+### Features
+
+* migrate to Zeitwerk autoloading and improve Ruby compatibility ([#1](https://github.com/seuros/chrono_machines/issues/1)) ([162a1cb](https://github.com/seuros/chrono_machines/commit/162a1cb6ad81c3c59778dcd325cebdfe637c22cb))
+
+## [0.1.0] - 2025-07-12
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Abdelkader Boudih
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,618 @@
+# ChronoMachines
+
+> The temporal manipulation engine that rewrites the rules of retry!
+
+A sophisticated Ruby implementation of exponential backoff and retry mechanisms, built for temporal precision in distributed systems where time itself is your greatest ally.
+
+## Quick Start
+
+```bash
+gem 'chrono_machines'
+```
+
+```ruby
+class PaymentService
+  include ChronoMachines::DSL
+
+  chrono_policy :stripe_payment, max_attempts: 5, base_delay: 0.1, multiplier: 2
+
+  def charge(amount)
+    with_chrono_policy(:stripe_payment) do
+      Stripe::Charge.create(amount: amount)
+    end
+  end
+end
+
+# Or use it directly
+result = ChronoMachines.retry(max_attempts: 3) do
+  perform_risky_operation
+end
+```
+
+## A Message from the Time Lords
+
+So your microservices are failing faster than your deployment pipeline can recover, and you're stuck in an infinite loop of "let's just add more retries"?
+
+Welcome to the temporal wasteland—where every millisecond matters, exponential backoff is law, and jitter isn't just a feeling you get when watching your error rates spike.
+
+Still here? Excellent. Because in the fabric of spacetime, nobody can hear your servers screaming about cascading failures. It's all just timing and patience.
+
+### 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.
+
+## Features
+
+- **Temporal Precision** - Full jitter exponential backoff with microsecond accuracy
+- **Advanced Retry Logic** - Configurable retryable exceptions and intelligent failure handling
+- **Rich Instrumentation** - Success, retry, and failure callbacks with contextual data
+- **Fallback Mechanisms** - Execute alternative logic when all retries are exhausted
+- **Declarative DSL** - Clean policy definitions with builder patterns
+- **Fiber-Safe Operations** - Async-aware sleep handling for modern Ruby
+- **Custom Exceptions** - MaxRetriesExceededError with original exception context
+- **Policy Management** - Named retry policies with inheritance and overrides
+- **Robust Error Handling** - Interrupt-preserving sleep with graceful degradation
+
+## The Temporal Manifesto
+
+### You Think: "I'll just add `retry` and call it resilience!"
+### Reality: You're creating a time paradox that crashes your entire fleet
+
+When your payment service fails, you don't want to hammer it into submission. You want to approach it like a time traveler—carefully, with exponential patience, and a healthy respect for the butterfly effect.
+
+## Core Usage Patterns
+
+### Direct Retry with Options
+
+```ruby
+# Simple retry with exponential backoff
+result = ChronoMachines.retry(max_attempts: 3, base_delay: 0.1) do
+  fetch_external_data
+end
+
+# Advanced configuration
+result = ChronoMachines.retry(
+  max_attempts: 5,
+  base_delay: 0.2,
+  multiplier: 3,
+  max_delay: 30,
+  retryable_exceptions: [Net::TimeoutError, HTTPError],
+  on_retry: ->(exception:, attempt:, next_delay:) {
+    Rails.logger.warn "Retry #{attempt}: #{exception.message}, waiting #{next_delay}s"
+  },
+  on_failure: ->(exception:, attempts:) {
+    Metrics.increment('api.retry.exhausted', tags: ["attempts:#{attempts}"])
+  }
+) do
+  external_api_call
+end
+```
+
+### Policy-Based Configuration
+
+```ruby
+# Configure global policies
+ChronoMachines.configure do |config|
+  config.define_policy(:aggressive, max_attempts: 10, base_delay: 0.01, multiplier: 1.5)
+  config.define_policy(:conservative, max_attempts: 3, base_delay: 1.0, multiplier: 2)
+  config.define_policy(:database, max_attempts: 5, retryable_exceptions: [ActiveRecord::ConnectionError])
+end
+
+# Use named policies
+result = ChronoMachines.retry(:database) do
+  User.find(user_id)
+end
+```
+
+### DSL Integration
+
+```ruby
+class ApiClient
+  include ChronoMachines::DSL
+
+  # Define policies at class level
+  chrono_policy :standard_api, max_attempts: 5, base_delay: 0.1, multiplier: 2
+  chrono_policy :critical_api, max_attempts: 10, base_delay: 0.05, max_delay: 5
+
+  def fetch_user_data(id)
+    with_chrono_policy(:standard_api) do
+      api_request("/users/#{id}")
+    end
+  end
+
+  def emergency_shutdown
+    # Use inline options for one-off scenarios
+    with_chrono_policy(max_attempts: 1, base_delay: 0) do
+      shutdown_api_call
+    end
+  end
+end
+```
+
+## Advanced Temporal Mechanics
+
+### Callback Instrumentation
+
+```ruby
+# Monitor retry patterns
+policy_options = {
+  max_attempts: 5,
+  on_success: ->(result:, attempts:) {
+    Metrics.histogram('operation.attempts', attempts)
+    Rails.logger.info "Operation succeeded after #{attempts} attempts"
+  },
+
+  on_retry: ->(exception:, attempt:, next_delay:) {
+    Metrics.increment('operation.retry', tags: ["attempt:#{attempt}"])
+    Honeybadger.notify(exception, context: { attempt: attempt, next_delay: next_delay })
+  },
+
+  on_failure: ->(exception:, attempts:) {
+    Metrics.increment('operation.failure', tags: ["final_attempts:#{attempts}"])
+    PagerDuty.trigger("Operation failed after #{attempts} attempts: #{exception.message}")
+  }
+}
+
+ChronoMachines.retry(policy_options) do
+  critical_operation
+end
+```
+
+### Exception Handling
+
+```ruby
+begin
+  ChronoMachines.retry(max_attempts: 3) do
+    risky_operation
+  end
+rescue ChronoMachines::MaxRetriesExceededError => e
+  # Access the original exception and retry context
+  Rails.logger.error "Failed after #{e.attempts} attempts: #{e.original_exception.message}"
+
+  # The original exception is preserved
+  case e.original_exception
+  when Net::TimeoutError
+    handle_timeout_failure
+  when HTTPError
+    handle_http_failure
+  end
+end
+```
+
+### Fallback Mechanisms
+
+```ruby
+# Execute fallback logic when retries are exhausted
+ChronoMachines.retry(
+  max_attempts: 3,
+  on_failure: ->(exception:, attempts:) {
+    # Fallback doesn't throw - original exception is still raised
+    Rails.cache.write("fallback_data_#{user_id}", cached_response, expires_in: 5.minutes)
+    SlackNotifier.notify("API down, serving cached data for user #{user_id}")
+  }
+) do
+  fetch_fresh_user_data
+end
+```
+
+## The Science of Temporal Jitter
+
+ChronoMachines implements **full jitter** exponential backoff:
+
+```ruby
+# Instead of predictable delays that create thundering herds:
+# Attempt 1: 100ms
+# Attempt 2: 200ms
+# Attempt 3: 400ms
+
+# ChronoMachines uses full jitter:
+# Attempt 1: random(0, 100ms)
+# Attempt 2: random(0, 200ms)
+# Attempt 3: random(0, 400ms)
+```
+
+This prevents the "thundering herd" problem where multiple clients retry simultaneously, overwhelming recovering services.
+
+## Configuration Reference
+
+### Policy Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `max_attempts` | `3` | Maximum number of retry attempts |
+| `base_delay` | `0.1` | Initial delay in seconds |
+| `multiplier` | `2` | Exponential backoff multiplier |
+| `max_delay` | `10` | Maximum delay cap in seconds |
+| `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:)` |
+| `on_failure` | `nil` | Failure callback: `(exception:, attempts:)` |
+
+### DSL Methods
+
+| Method | Scope | Description |
+|--------|-------|-------------|
+| `chrono_policy(name, options)` | Class | Define a named retry policy |
+| `with_chrono_policy(policy_or_options, &block)` | Instance | Execute block with retry policy |
+
+## Real-World Examples
+
+### Database Connection Resilience
+
+```ruby
+class DatabaseService
+  include ChronoMachines::DSL
+
+  chrono_policy :db_connection,
+    max_attempts: 5,
+    base_delay: 0.1,
+    retryable_exceptions: [
+      ActiveRecord::ConnectionTimeoutError,
+      ActiveRecord::DisconnectedError,
+      PG::ConnectionBad
+    ],
+    on_retry: ->(exception:, attempt:, next_delay:) {
+      Rails.logger.warn "DB retry #{attempt}: #{exception.class}"
+    }
+
+  def find_user(id)
+    with_chrono_policy(:db_connection) do
+      User.find(id)
+    end
+  end
+end
+```
+
+### HTTP API Integration
+
+```ruby
+class WeatherService
+  include ChronoMachines::DSL
+
+  chrono_policy :weather_api,
+    max_attempts: 4,
+    base_delay: 0.2,
+    max_delay: 10,
+    retryable_exceptions: [Net::TimeoutError, Net::HTTPServerError],
+    on_failure: ->(exception:, attempts:) {
+      # Serve stale data when API is completely down
+      Rails.cache.write("weather_service_down", true, expires_in: 5.minutes)
+    }
+
+  def current_weather(location)
+    with_chrono_policy(:weather_api) do
+      response = HTTP.timeout(connect: 2, read: 5)
+                    .get("https://api.weather.com/#{location}")
+      JSON.parse(response.body)
+    end
+  rescue ChronoMachines::MaxRetriesExceededError
+    # Return cached data if available
+    Rails.cache.fetch("weather_#{location}", expires_in: 1.hour) do
+      { temperature: "Unknown", status: "Service Unavailable" }
+    end
+  end
+end
+```
+
+### Background Job Retry Logic
+
+```ruby
+class EmailDeliveryJob
+  include ChronoMachines::DSL
+
+  chrono_policy :email_delivery,
+    max_attempts: 8,
+    base_delay: 1,
+    multiplier: 1.5,
+    max_delay: 300, # 5 minutes max
+    retryable_exceptions: [Net::SMTPServerBusy, Net::SMTPTemporaryError],
+    on_failure: ->(exception:, attempts:) {
+      # Move to dead letter queue after all retries
+      DeadLetterQueue.push(job_data, reason: exception.message)
+    }
+
+  def perform(email_data)
+    with_chrono_policy(:email_delivery) do
+      EmailService.deliver(email_data)
+    end
+  end
+end
+```
+
+## Testing Strategies
+
+### Mocking Time and Retries
+
+```ruby
+require "minitest/autorun"
+require "mocha/minitest"
+
+class PaymentServiceTest < Minitest::Test
+  def setup
+    @service = PaymentService.new
+  end
+
+  def test_retries_payment_on_timeout
+    charge_response = { id: "ch_123", amount: 100 }
+
+    Stripe::Charge.expects(:create)
+      .raises(Net::TimeoutError).once
+      .then.returns(charge_response)
+
+    # Mock sleep to avoid test delays
+    ChronoMachines::Executor.any_instance.expects(:robust_sleep).at_least_once
+
+    result = @service.charge(100)
+    assert_equal charge_response, result
+  end
+
+  def test_respects_max_attempts
+    Stripe::Charge.expects(:create)
+      .raises(Net::TimeoutError).times(3)
+
+    assert_raises(ChronoMachines::MaxRetriesExceededError) do
+      @service.charge(100)
+    end
+  end
+
+  def test_preserves_original_exception
+    original_error = Net::TimeoutError.new("Connection timed out")
+    Stripe::Charge.expects(:create).raises(original_error).times(3)
+
+    begin
+      @service.charge(100)
+      flunk "Expected MaxRetriesExceededError to be raised"
+    rescue ChronoMachines::MaxRetriesExceededError => e
+      assert_equal 3, e.attempts
+      assert_equal original_error, e.original_exception
+      assert_equal "Connection timed out", e.original_exception.message
+    end
+  end
+end
+```
+
+### Testing Callbacks
+
+```ruby
+class CallbackTest < Minitest::Test
+  def test_calls_retry_callback_with_correct_context
+    retry_calls = []
+    call_count = 0
+
+    result = ChronoMachines.retry(
+      max_attempts: 3,
+      base_delay: 0.001, # Short delay for tests
+      on_retry: ->(exception:, attempt:, next_delay:) {
+        retry_calls << {
+          attempt: attempt,
+          delay: next_delay,
+          exception_message: exception.message
+        }
+      }
+    ) do
+      call_count += 1
+      raise "Fail" if call_count < 2
+      "Success"
+    end
+
+    assert_equal "Success", result
+    assert_equal 1, retry_calls.length
+    assert_equal 1, retry_calls.first[:attempt]
+    assert retry_calls.first[:delay] > 0
+    assert_equal "Fail", retry_calls.first[:exception_message]
+  end
+
+  def test_calls_success_callback
+    success_called = false
+    result_captured = nil
+    attempts_captured = nil
+
+    result = ChronoMachines.retry(
+      on_success: ->(result:, attempts:) {
+        success_called = true
+        result_captured = result
+        attempts_captured = attempts
+      }
+    ) do
+      "Operation succeeded"
+    end
+
+    assert success_called
+    assert_equal "Operation succeeded", result_captured
+    assert_equal 1, attempts_captured
+  end
+
+  def test_calls_failure_callback
+    failure_called = false
+    exception_captured = nil
+
+    assert_raises(ChronoMachines::MaxRetriesExceededError) do
+      ChronoMachines.retry(
+        max_attempts: 2,
+        on_failure: ->(exception:, attempts:) {
+          failure_called = true
+          exception_captured = exception
+        }
+      ) do
+        raise "Always fails"
+      end
+    end
+
+    assert failure_called
+    assert_equal "Always fails", exception_captured.message
+  end
+end
+```
+
+### Testing DSL Integration
+
+```ruby
+class DSLTestExample < Minitest::Test
+  class TestService
+    include ChronoMachines::DSL
+
+    chrono_policy :test_policy, max_attempts: 2, base_delay: 0.001
+
+    def risky_operation
+      with_chrono_policy(:test_policy) do
+        # Simulated operation
+        yield if block_given?
+      end
+    end
+  end
+
+  def test_dsl_policy_definition
+    service = TestService.new
+
+    call_count = 0
+    result = service.risky_operation do
+      call_count += 1
+      raise "Fail" if call_count < 2
+      "Success"
+    end
+
+    assert_equal "Success", result
+    assert_equal 2, call_count
+  end
+
+  def test_dsl_with_inline_options
+    service = TestService.new
+
+    assert_raises(ChronoMachines::MaxRetriesExceededError) do
+      service.with_chrono_policy(max_attempts: 1) do
+        raise "Always fails"
+      end
+    end
+  end
+end
+```
+
+## TestHelper for Library Authors
+
+ChronoMachines provides a test helper module for library authors who want to integrate ChronoMachines testing utilities into their own test suites.
+
+### Setup
+
+```ruby
+require 'chrono_machines/test_helper'
+
+class MyLibraryTest < Minitest::Test
+  include ChronoMachines::TestHelper
+
+  def setup
+    super # Important: calls ChronoMachines config reset
+    # Your setup code here
+  end
+end
+```
+
+### Features
+
+**Configuration Reset**: The TestHelper automatically resets ChronoMachines configuration before each test, ensuring test isolation.
+
+**Custom Assertions**: Provides specialized assertions for testing delay ranges:
+
+```ruby
+def test_delay_calculation
+  executor = ChronoMachines::Executor.new(base_delay: 0.1, multiplier: 2)
+  delay = executor.send(:calculate_delay, 1)
+
+  # Assert delay is within expected jitter range
+  assert_cm_delay_range(delay, 0.0, 0.1, "First attempt delay out of range")
+end
+```
+
+**Available Assertions**:
+- `assert_cm_delay_range(delay, min, max, message = nil)` - Assert delay falls within expected range
+
+### Integration Example
+
+```ruby
+# In your gem's test_helper.rb
+require 'minitest/autorun'
+require 'chrono_machines/test_helper'
+
+class TestBase < Minitest::Test
+  include ChronoMachines::TestHelper
+
+  def setup
+    super
+    # Reset any additional state
+  end
+end
+
+# In your specific tests
+class RetryServiceTest < TestBase
+  def test_retry_with_custom_policy
+    # ChronoMachines config is automatically reset
+    # You can safely define test-specific policies
+
+    ChronoMachines.configure do |config|
+      config.define_policy(:test_policy, max_attempts: 2)
+    end
+
+    result = ChronoMachines.retry(:test_policy) do
+      "success"
+    end
+
+    assert_equal "success", result
+  end
+end
+```
+
+## Why ChronoMachines?
+
+### Built for Modern Ruby
+- **Ruby 3.2+ 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
+
+### Time-Tested Patterns
+- **Exponential Backoff**: Industry-standard retry timing
+- **Circuit Breaking**: Fail-fast when upstream is down
+- **Fallback Support**: Graceful degradation strategies
+- **Exception Preservation**: Original errors aren't lost in retry logic
+
+## A Word from the Time Corps Engineering Division
+
+*The Temporal Commentary Engine activates:*
+
+"Time isn't linear—especially when your payment processor is having 'a moment.'
+
+The universe doesn't care about your startup's burn rate or your post on X about 'building in public.' It cares about one immutable law:
+
+**Does your system handle failure gracefully across the fourth dimension?**
+
+If not, welcome to the Time Corps. We have exponential backoff.
+
+Remember: The goal isn't to prevent temporal anomalies—it's to fail fast, fail smart, and retry with mathematical precision.
+
+As I always say when debugging production: 'Time heals all wounds, but jitter prevents thundering herds.'"
+
+*— Temporal Commentary Engine, Log Entry ∞*
+
+## Contributing to the Timeline
+
+1. Fork it (like it's 2005, but with better temporal mechanics)
+2. Create your feature branch (`git checkout -b feature/quantum-retries`)
+3. Commit your changes (`git commit -am 'Add temporal stabilization'`)
+4. Push to the branch (`git push origin feature/quantum-retries`)
+5. Create a new Pull Request (and wait for the Time Lords to review)
+
+## License
+
+MIT License. See [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- The Ruby community - For building a language worth retrying for
+- Every timeout that ever taught us patience - You made us stronger
+- The Time Corps - For maintaining temporal stability
+- The universe - For being deterministically random
+
+## Author
+
+Built with time and Brawndo (it's got electrolytes) by temporal engineers fighting entropy one retry at a time.
+
+**Remember: In the fabric of spacetime, nobody can hear your API timeout. But they can feel your exponential backoff working as intended.**

data/ext/chrono_machines_native/extconf.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'ffi/extconf'

data/lib/chrono_machines/async_support.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# This file provides optional integration with the Async gem.
+# It will only patch if Async is available.
+
+async_available = defined?(Async) || begin
+  require 'async'
+  true
+rescue LoadError
+  false
+end
+
+if async_available
+  module ChronoMachines
+    # Patch the Executor's robust_sleep method to use Async's non-blocking sleep
+    # if an Async task is currently running.
+    class Executor
+      alias original_robust_sleep robust_sleep
+
+      def robust_sleep(delay)
+        # Check if we're in an Async context and safely call current
+        current_task = begin
+          Async::Task.current
+        rescue RuntimeError
+          # No async task available
+          nil
+        end
+
+        if current_task
+          # Use Kernel#sleep which is now fiber-aware in async 2.x
+          sleep(delay)
+        else
+          original_robust_sleep(delay)
+        end
+      end
+    end
+  end
+end

data/lib/chrono_machines/configuration.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ChronoMachines
+  class Configuration
+    DEFAULT_POLICY_NAME = :default
+
+    attr_reader :policies
+    attr_accessor :engine_override
+
+    def initialize
+      @engine_override = nil # nil = auto-detect, :ruby = force Ruby, :native = force native
+      @policies = {
+        DEFAULT_POLICY_NAME => {
+          backoff_strategy: :exponential, # :exponential, :constant, or :fibonacci
+          max_attempts: 3,
+          base_delay: 0.1, # seconds
+          multiplier: 2,   # For exponential backoff
+          max_delay: 10,   # seconds
+          jitter_factor: 1.0, # 1.0 = full jitter (recommended), 0.0 = no jitter
+          retryable_exceptions: [StandardError],
+          on_failure: nil, # Fallback block when all retries are exhausted
+          on_retry: nil,   # Callback block when a retry occurs
+          on_success: nil  # Callback block when operation succeeds
+        }
+      }
+    end
+
+    def define_policy(name, options)
+      # Deep copy the default policy to avoid shared mutable references
+      default_copy = @policies[DEFAULT_POLICY_NAME].transform_values do |value|
+        case value
+        when Array
+          value.dup
+        when Proc
+          value # Procs are immutable, no need to dup
+        else
+          value # Primitives (numbers, symbols, nil) are immutable
+        end
+      end
+
+      @policies[name.to_sym] = default_copy.merge(options)
+    end
+
+    def get_policy(name)
+      @policies[name.to_sym] || raise(ArgumentError, "Policy '#{name}' not found.")
+    end
+  end
+end

data/lib/chrono_machines/dsl.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ChronoMachines
+  module DSL
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def chrono_policy(name, options = {})
+        ChronoMachines.configure do |config|
+          config.define_policy(name, options)
+        end
+      end
+    end
+
+    def with_chrono_policy(policy_name_or_options, &)
+      ChronoMachines.retry(policy_name_or_options, &)
+    end
+  end
+end

data/lib/chrono_machines/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ChronoMachines
+  class Error < StandardError; end
+
+  class MaxRetriesExceededError < Error
+    attr_reader :original_exception, :attempts
+
+    def initialize(original_exception, attempts)
+      @original_exception = original_exception
+      @attempts = attempts
+      super("Max retries (#{attempts}) exceeded. Original error: #{original_exception.class}: #{original_exception.message}")
+    end
+  end
+end

data/lib/chrono_machines/executor.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module ChronoMachines
+  class Executor
+    def initialize(policy_or_options = {})
+      policy_options = if policy_or_options.is_a?(Symbol)
+                         ChronoMachines.config.get_policy(policy_or_options)
+                       else
+                         ChronoMachines.config.get_policy(Configuration::DEFAULT_POLICY_NAME).merge(policy_or_options)
+                       end
+
+      @backoff_strategy = policy_options[:backoff_strategy] || :exponential
+      @max_attempts = policy_options[:max_attempts]
+      @base_delay = policy_options[:base_delay]
+      @multiplier = policy_options[:multiplier] || 2
+      @max_delay = policy_options[:max_delay]
+      @jitter_factor = policy_options[:jitter_factor]
+      @retryable_exceptions = policy_options[:retryable_exceptions]
+      @on_failure = policy_options[:on_failure]
+      @on_retry = policy_options[:on_retry]
+      @on_success = policy_options[:on_success]
+    end
+
+    def call
+      attempts = 0
+
+      begin
+        attempts += 1
+        result = yield
+
+        # Call success callback if defined
+        @on_success&.call(result: result, attempts: attempts)
+
+        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
+          handle_final_failure(e, attempts)
+          raise e
+        end
+
+        # Check if we've exhausted all attempts
+        if attempts >= @max_attempts
+          handle_final_failure(e, attempts)
+          raise MaxRetriesExceededError.new(e, attempts)
+        end
+
+        # Calculate delay
+        delay = calculate_delay(attempts)
+
+        # Call retry callback if defined
+        @on_retry&.call(exception: e, attempt: attempts, next_delay: delay)
+
+        # Execute delay with robust sleep
+        robust_sleep(delay)
+        retry
+      end
+    end
+
+    private
+
+    # 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))
+    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))
+    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))
+    end
+
+    # Calculate Fibonacci number (1-indexed)
+    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
+    end
+
+    # Main calculate_delay dispatches to the appropriate strategy
+    def ruby_calculate_delay(attempts)
+      case @backoff_strategy
+      when :exponential
+        ruby_calculate_delay_exponential(attempts)
+      when :constant
+        ruby_calculate_delay_constant(attempts)
+      when :fibonacci
+        ruby_calculate_delay_fibonacci(attempts)
+      else
+        raise ArgumentError, "Unknown backoff strategy: #{@backoff_strategy}"
+      end
+    end
+
+    # By default, use Ruby implementation (may be overridden by native extension)
+    alias_method :calculate_delay, :ruby_calculate_delay
+
+    def robust_sleep(delay)
+      # Handle potential interruptions to sleep
+      # In Ruby 3.2+, Kernel.sleep is fiber-aware
+      return if delay <= 0
+
+      begin
+        sleep(delay)
+      rescue Interrupt
+        # Re-raise interrupt signals
+        raise
+      rescue StandardError
+        # Log or handle other sleep interruptions, but continue
+        # In most cases, we want to proceed with the retry
+      end
+    end
+
+    def handle_final_failure(exception, attempts)
+      # Execute fallback block if defined
+      return unless @on_failure
+
+      begin
+        @on_failure.call(exception: exception, attempts: attempts)
+      rescue StandardError
+        # Don't let fallback errors mask the original error
+        # Could log this or handle as needed
+      end
+    end
+
+    def normalized_jitter_factor
+      factor = Float(@jitter_factor)
+      raise ArgumentError, 'jitter_factor cannot be NaN' if factor.nan?
+
+      factor.clamp(0.0, 1.0)
+    rescue ArgumentError, TypeError
+      raise ArgumentError, 'jitter_factor must be a numeric value'
+    end
+  end
+end
+
+# Load optional native speedup if available
+begin
+  require_relative 'native_speedup'
+rescue LoadError
+  # Native extension not available, continue with pure Ruby implementation
+end

data/lib/chrono_machines/native_speedup.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Optional native speedup for ChronoMachines
+# This file is loaded conditionally and monkey-patches the Executor
+# 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
+
+  module ChronoMachines
+    # Native speedup module that overrides backoff calculations
+    # The original Ruby implementations remain available as ruby_calculate_delay_*
+    module NativeExecutor
+      private
+
+      # 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
+      end
+    end
+
+    class Executor
+      prepend NativeExecutor
+    end
+  end
+rescue LoadError
+  # Native extension not available (e.g., on JRuby or failed compilation)
+  # Silently fall back to pure Ruby implementation
+end

data/lib/chrono_machines/test_helper.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+
+module ChronoMachines
+  module TestHelper
+    def setup
+      super
+      # Reset configuration before each test
+      ChronoMachines.instance_variable_set(:@config, ChronoMachines::Configuration.new)
+    end
+
+    module Assertions
+      def assert_cm_delay_range(delay, expected_min, expected_max, message = nil)
+        assert_operator(delay, :>=, expected_min, "Expected delay #{delay} to be >= #{expected_min}. #{message}")
+        assert_operator(delay, :<=, expected_max, "Expected delay #{delay} to be <= #{expected_max}. #{message}")
+      end
+    end
+
+    include Assertions
+  end
+end

data/lib/chrono_machines/version.rb

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

data/lib/chrono_machines.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'zeitwerk'
+
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/chrono_machines/errors.rb")
+loader.ignore("#{__dir__}/chrono_machines/async_support.rb")
+loader.ignore("#{__dir__}/chrono_machines/test_helper.rb")
+loader.inflector.inflect('dsl' => 'DSL')
+loader.setup
+
+require_relative 'chrono_machines/errors'
+
+module ChronoMachines
+  # Global configuration instance
+  @config = Configuration.new
+
+  def self.configure
+    yield @config
+  end
+
+  def self.config
+    @config
+  end
+
+  def self.retry(policy_name_or_options = {}, &)
+    Executor.new(policy_name_or_options).call(&)
+  end
+end
+
+# Load optional async support after core is loaded
+begin
+  require_relative 'chrono_machines/async_support'
+rescue LoadError
+  # Async gem not available, skip async support
+end

data/sig/chrono_machines.rbs

@@ -0,0 +1,4 @@
+module ChronoMachines
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: chrono_machines
+version: !ruby/object:Gem::Version
+  version: 0.5.1
+platform: aarch64-linux
+authors:
+- Abdelkader Boudih
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-08-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+description: ChronoMachines offers a flexible and configurable solution for handling
+  transient failures in distributed Ruby applications. It provides powerful retry
+  strategies, including exponential backoff and full jitter, with customizable callbacks.
+  Features optional Rust-powered native performance on CRuby with pure Ruby fallback
+  for JRuby compatibility.
+email:
+- terminale@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/chrono_machines_native/extconf.rb
+- lib/chrono_machines.rb
+- lib/chrono_machines/async_support.rb
+- lib/chrono_machines/configuration.rb
+- lib/chrono_machines/dsl.rb
+- lib/chrono_machines/errors.rb
+- lib/chrono_machines/executor.rb
+- lib/chrono_machines/native_speedup.rb
+- lib/chrono_machines/test_helper.rb
+- lib/chrono_machines/version.rb
+- lib/chrono_machines_native/3.4/chrono_machines_native.so
+- lib/chrono_machines_native/4.0/chrono_machines_native.so
+- sig/chrono_machines.rbs
+homepage: https://github.com/seuros/chrono_machines
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/seuros/chrono_machines
+  source_code_uri: https://github.com/seuros/chrono_machines
+  changelog_uri: https://github.com/seuros/chrono_machines/blob/main/CHANGELOG.md
+  github_repo: ssh://github.com/seuros/chrono_machines
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: chrono_machines_native
+  cargo_manifest_path: ext/chrono_machines_native/ffi/Cargo.toml
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: A robust Ruby gem for implementing retry mechanisms with exponential backoff
+  and jitter.
+test_files: []