chrono_machines 0.0.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 474f154ed5894dbea202693d26b61a75e4df4bdb1dbbfc0ef1823536a2f477dc
-  data.tar.gz: 1c29822882e486842767c41e91d9c3dcdcbce464e7b75fe8ccf5bf0a224a7674
+  metadata.gz: 8617cc9e32d231563c1f075a8446728ff851ec0ec6c755aa00e807de5adde85d
+  data.tar.gz: de5c482f0bb089ce720f5cd3f3019a88fa6b149e83061b729d4d6287161601a3
 SHA512:
-  metadata.gz: d7efe36430add656b675ead11255f00ac25e332deeb3b965521f74838c72585b2d0aa22cfe22dd23e83ca02a43a793f205480a89b1efcebce043e4b7c6ac0a03
-  data.tar.gz: 9d8e72a5da90ccb7dac0c933440a23d19ca7b7c1e68f789c8de3103fd8b6358ee5d288b9b372b660658c08d8e1dc032d72724eb77ed37e0bcb2f17b8a0889cc3
+  metadata.gz: 482988d7dd362bb4159af9e9651312b84c3a4e2633d9f4e48f00d9208991328d89ff66bcabd9001c3144c29a347b98f7476849499e310cd6530c08066e0b8f4a
+  data.tar.gz: 99c5ed6434f2e18236257efb87a652094354c24711d3c7aed651dcfd20b0a0fade2ae15214fbf3ea002730e814f696951dfd7f8af964942937ff0d8b1d91f723

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+## [Unreleased]
+
+## [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 coffee 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/lib/chrono_machines/async_support.rb

@@ -0,0 +1,37 @@
+# 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
+          current_task.sleep(delay)
+        else
+          original_robust_sleep(delay)
+        end
+      end
+    end
+  end
+end

data/lib/chrono_machines/configuration.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ChronoMachines
+  class Configuration
+    DEFAULT_POLICY_NAME = :default
+
+    attr_reader :policies
+
+    def initialize
+      @policies = {
+        DEFAULT_POLICY_NAME => {
+          max_attempts: 3,
+          base_delay: 0.1, # seconds
+          multiplier: 2,
+          max_delay: 10, # seconds
+          jitter_factor: 0.1, # 10% jitter (though full jitter makes this less direct)
+          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)
+      @policies[name.to_sym] = @policies[DEFAULT_POLICY_NAME].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,97 @@
+# 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
+
+      @max_attempts = policy_options[:max_attempts]
+      @base_delay = policy_options[:base_delay]
+      @multiplier = policy_options[:multiplier]
+      @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
+
+        # Call retry callback if defined
+        @on_retry&.call(exception: e, attempt: attempts, next_delay: calculate_delay(attempts))
+
+        # Calculate and execute delay with robust sleep
+        delay = calculate_delay(attempts)
+        robust_sleep(delay)
+        retry
+      end
+    end
+
+    private
+
+    def calculate_delay(attempts)
+      # Calculate the base exponential backoff delay
+      # Ensure it doesn't exceed max_delay
+      base_exponential_delay = [@base_delay * (@multiplier**(attempts - 1)), @max_delay].min
+
+      # Apply full jitter: random value between 0 and the base_exponential_delay
+      rand * base_exponential_delay
+    end
+
+    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
+  end
+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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ChronoMachines
-  VERSION = "0.0.0"
+  VERSION = '0.2.0'
 end

data/lib/chrono_machines.rb

@@ -1,8 +1,36 @@
 # frozen_string_literal: true
 
-require_relative "chrono_machines/version"
+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
-  class Error < StandardError; end
-  # Your code goes here...
+  # 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

@@ -1,25 +1,51 @@
 --- !ruby/object:Gem::Specification
 name: chrono_machines
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Abdelkader Boudih
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
-description: ChronoMachines provides a unique framework for managing temporal flows
-  within Ruby systems, allowing for precise control over event sequencing and re-engagement.
-  Explore the possibilities of time-based operations.
+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, along with customizable
+  callbacks for success, retry, and failure events. Define and manage retry policies
+  with a clean DSL for seamless integration.
 email:
 - terminale@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
 - 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/test_helper.rb
 - lib/chrono_machines/version.rb
+- sig/chrono_machines.rbs
 homepage: https://github.com/seuros/chrono_machines
 licenses:
 - MIT
@@ -28,6 +54,7 @@ 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
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -35,7 +62,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -44,5 +71,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: A temporal manipulation engine for Ruby applications.
+summary: A robust Ruby gem for implementing retry mechanisms with exponential backoff
+  and jitter.
 test_files: []