breaker_machines 0.5.0 → 0.6.0

data/lib/breaker_machines/circuit/async_state_management.rb

@@ -41,7 +41,7 @@ module BreakerMachines
           end
 
           before_transition on: :hard_reset do |circuit|
-            circuit.storage.clear(circuit.name) if circuit.storage
+            circuit.storage&.clear(circuit.name)
             circuit.half_open_attempts.value = 0
             circuit.half_open_successes.value = 0
           end

data/lib/breaker_machines/circuit/base.rb

@@ -16,7 +16,8 @@ module BreakerMachines
         include Circuit::Callbacks
         include Circuit::StateCallbacks
 
-        attr_reader :name, :config, :opened_at, :storage, :metrics, :semaphore
+        # name/config/opened_at readers are defined in Circuit::Configuration
+        attr_reader :storage, :metrics, :semaphore
         attr_reader :half_open_attempts, :half_open_successes, :mutex
         attr_reader :last_failure_at, :last_error
       end

data/lib/breaker_machines/circuit/coordinated_state_management.rb

@@ -17,12 +17,12 @@ module BreakerMachines
 
           event :attempt_recovery do
             transition open: :half_open,
-                       if: ->(circuit) { circuit.recovery_allowed? }
+                       if: lambda(&:recovery_allowed?)
           end
 
           event :reset do
             transition %i[open half_open] => :closed,
-                       if: ->(circuit) { circuit.reset_allowed? }
+                       if: lambda(&:reset_allowed?)
             transition closed: :closed
           end
 
@@ -39,7 +39,7 @@ module BreakerMachines
           end
 
           before_transition on: :hard_reset do |circuit|
-            circuit.storage.clear(circuit.name) if circuit.storage
+            circuit.storage&.clear(circuit.name)
             circuit.half_open_attempts.value = 0
             circuit.half_open_successes.value = 0
           end

data/lib/breaker_machines/circuit/native.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # Native circuit breaker implementation using Rust FFI
+    #
+    # This provides a high-performance circuit breaker with state machine logic
+    # implemented in Rust. It's fully compatible with the Ruby circuit API but
+    # significantly faster for high-throughput scenarios.
+    #
+    # @example Basic usage
+    #   circuit = BreakerMachines::Circuit::Native.new('api_calls',
+    #     failure_threshold: 5,
+    #     failure_window_secs: 60.0
+    #   )
+    #
+    #   circuit.call { api.fetch_data }
+    class Native
+      # @return [String] Circuit name
+      attr_reader :name
+
+      # @return [Hash] Circuit configuration
+      attr_reader :config
+
+      # Create a new native circuit breaker
+      #
+      # @param name [String] Circuit name
+      # @param options [Hash] Configuration options
+      # @option options [Integer] :failure_threshold Number of failures to open circuit (default: 5)
+      # @option options [Float] :failure_window_secs Time window for counting failures (default: 60.0)
+      # @option options [Float] :half_open_timeout_secs Timeout before attempting reset (default: 30.0)
+      # @option options [Integer] :success_threshold Successes needed to close from half-open (default: 2)
+      # @option options [Boolean] :auto_register Register with global registry (default: true)
+      def initialize(name, options = {})
+        unless BreakerMachines.native_available?
+          raise BreakerMachines::ConfigurationError,
+                'Native extension not available. Install with native support or use Circuit::Ruby'
+        end
+
+        @name = name
+        @config = default_config.merge(options)
+
+        # Create the native circuit breaker
+        @native_circuit = BreakerMachinesNative::Circuit.new(
+          name,
+          {
+            failure_threshold: @config[:failure_threshold],
+            failure_window_secs: @config[:failure_window_secs],
+            half_open_timeout_secs: @config[:half_open_timeout_secs],
+            success_threshold: @config[:success_threshold]
+          }
+        )
+
+        # Register with global registry unless disabled
+        BreakerMachines::Registry.instance.register(self) unless @config[:auto_register] == false
+      end
+
+      # Execute a block with circuit breaker protection
+      #
+      # @yield Block to execute
+      # @return Result of the block
+      # @raise [CircuitOpenError] if circuit is open
+      def call
+        raise CircuitOpenError, "Circuit '#{@name}' is open" if open?
+
+        start_time = BreakerMachines.monotonic_time
+        begin
+          result = yield
+          duration = BreakerMachines.monotonic_time - start_time
+          @native_circuit.record_success(duration)
+          result
+        rescue StandardError => _e
+          duration = BreakerMachines.monotonic_time - start_time
+          @native_circuit.record_failure(duration)
+          raise
+        end
+      end
+
+      # Check if circuit is open
+      # @return [Boolean]
+      def open?
+        @native_circuit.is_open
+      end
+
+      # Check if circuit is closed
+      # @return [Boolean]
+      def closed?
+        @native_circuit.is_closed
+      end
+
+      # Get current state name
+      # @return [String] 'open' or 'closed'
+      def state
+        @native_circuit.state_name
+      end
+
+      # Reset the circuit (clear all events)
+      def reset!
+        @native_circuit.reset
+      end
+
+      # Get circuit status for inspection
+      # @return [Hash] Status information
+      def status
+        {
+          name: @name,
+          state: state,
+          open: open?,
+          closed: closed?,
+          config: @config
+        }
+      end
+
+      private
+
+      def default_config
+        {
+          failure_threshold: 5,
+          failure_window_secs: 60.0,
+          half_open_timeout_secs: 30.0,
+          success_threshold: 2,
+          auto_register: true
+        }
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit/state_callbacks.rb

@@ -47,14 +47,26 @@ module BreakerMachines
       def reset_timeout_elapsed?
         return false unless @opened_at.value
 
-        # Add jitter to prevent thundering herd
-        jitter_factor = @config[:reset_timeout_jitter] || 0.25
-        # Calculate random jitter between -jitter_factor and +jitter_factor
-        jitter_multiplier = 1.0 + (((rand * 2) - 1) * jitter_factor)
-        timeout_with_jitter = @config[:reset_timeout] * jitter_multiplier
+        # Add jitter to prevent thundering herd using ChronoMachines
+        # This matches the Rust implementation which uses chrono-machines for jitter
+        timeout_with_jitter = if (jitter_factor = @config[:reset_timeout_jitter]) && jitter_factor.positive?
+                                calculate_timeout_with_jitter(@config[:reset_timeout], jitter_factor)
+                              else
+                                @config[:reset_timeout]
+                              end
 
         BreakerMachines.monotonic_time - @opened_at.value >= timeout_with_jitter
       end
+
+      # Calculate timeout with jitter using ChronoMachines algorithm
+      # Matches the Rust implementation: timeout * (1 - jitter + rand * jitter)
+      def calculate_timeout_with_jitter(base_timeout, jitter_factor)
+        # Use full jitter strategy from ChronoMachines
+        # Formula: base * (1 - jitter + rand * jitter)
+        # This gives values in range [base * (1-jitter), base]
+        normalized_jitter = [jitter_factor.to_f, 1.0].min
+        base_timeout * (1.0 - normalized_jitter + (rand * normalized_jitter))
+      end
     end
   end
 end

data/lib/breaker_machines/circuit/state_management.rb

@@ -36,7 +36,7 @@ module BreakerMachines
           end
 
           before_transition on: :hard_reset do |circuit|
-            circuit.storage.clear(circuit.name) if circuit.storage
+            circuit.storage&.clear(circuit.name)
             circuit.half_open_attempts.value = 0
             circuit.half_open_successes.value = 0
           end

data/lib/breaker_machines/native_extension.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  # Handles loading and status of the optional native extension
+  module NativeExtension
+    class << self
+      # Load the native extension and set availability flag
+      # Can be called multiple times - subsequent calls are memoized
+      def load!
+        return @loaded if defined?(@loaded)
+
+        @loaded = true
+        require 'breaker_machines_native/breaker_machines_native'
+        BreakerMachines.instance_variable_set(:@native_available, true)
+        BreakerMachines.log(:info, 'Native extension loaded successfully')
+        true
+      rescue LoadError => e
+        @loaded = false
+        BreakerMachines.instance_variable_set(:@native_available, false)
+
+        # Only log if it's not JRuby (expected failure) and logging is enabled
+        if RUBY_ENGINE != 'jruby'
+          BreakerMachines.log(:warn, "Native extension not available: #{e.message}")
+          BreakerMachines.log(:warn, 'Using pure Ruby backend (slower but functional)')
+        end
+
+        false
+      end
+
+      # Check if load was attempted
+      def loaded?
+        defined?(@loaded) && @loaded
+      end
+    end
+  end
+end

data/lib/breaker_machines/native_speedup.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'native_extension'
+
+# Load the native extension if available
+BreakerMachines::NativeExtension.load!

data/lib/breaker_machines/storage/bucket_memory.rb

@@ -21,6 +21,8 @@ module BreakerMachines
         @event_logs = Concurrent::Map.new
         @bucket_count = options[:bucket_count] || 300 # Default 5 minutes
         @max_events = options[:max_events] || 100
+        # Store creation time as anchor for relative timestamps (like Rust implementation)
+        @start_time = BreakerMachines.monotonic_time
       end
 
       def get_status(circuit_name)
@@ -160,7 +162,8 @@ module BreakerMachines
       end
 
       def monotonic_time
-        BreakerMachines.monotonic_time
+        # Return time relative to storage creation (matches Rust implementation)
+        BreakerMachines.monotonic_time - @start_time
       end
 
       def with_timeout(_timeout_ms)

data/lib/breaker_machines/storage/memory.rb

@@ -17,6 +17,8 @@ module BreakerMachines
         @events = Concurrent::Map.new
         @event_logs = Concurrent::Map.new
         @max_events = options[:max_events] || 100
+        # Store creation time as anchor for relative timestamps (like Rust implementation)
+        @start_time = BreakerMachines.monotonic_time
       end
 
       def get_status(circuit_name)
@@ -130,7 +132,8 @@ module BreakerMachines
       end
 
       def monotonic_time
-        BreakerMachines.monotonic_time
+        # Return time relative to storage creation (matches Rust implementation)
+        BreakerMachines.monotonic_time - @start_time
       end
     end
   end

data/lib/breaker_machines/storage/native.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module Storage
+    # Native extension storage backend for high-performance event tracking
+    #
+    # This backend provides identical functionality to Memory storage but with
+    # significantly better performance for sliding window calculations. It's
+    # particularly beneficial for high-throughput applications where circuit
+    # breaker state checks happen on every request.
+    #
+    # Performance: ~63x faster than Memory storage for sliding window calculations
+    #
+    # Usage:
+    #   BreakerMachines.configure do |config|
+    #     config.default_storage = :native
+    #   end
+    #
+    # Fallback: If the native extension isn't available (e.g., on JRuby or if
+    # Rust wasn't installed during gem installation), this will raise LoadError.
+    # Use Storage::Memory as a fallback in such cases.
+    class Native < Base
+      def initialize(**options)
+        super
+        unless defined?(BreakerMachinesNative::Storage)
+          raise LoadError, 'Native extension not available. Use Storage::Memory instead.'
+        end
+
+        @native = BreakerMachinesNative::Storage.new
+      end
+
+      def get_status(_circuit_name)
+        # Status is still managed by Ruby layer
+        # This storage backend only handles event tracking
+        nil
+      end
+
+      def set_status(circuit_name, status, opened_at = nil)
+        # Status management delegated to Ruby layer
+        # This backend focuses on high-performance event counting
+      end
+
+      def record_success(circuit_name, duration)
+        @native.record_success(circuit_name.to_s, duration.to_f)
+      end
+
+      def record_failure(circuit_name, duration)
+        @native.record_failure(circuit_name.to_s, duration.to_f)
+      end
+
+      def success_count(circuit_name, window_seconds)
+        @native.success_count(circuit_name.to_s, window_seconds.to_f)
+      end
+
+      def failure_count(circuit_name, window_seconds)
+        @native.failure_count(circuit_name.to_s, window_seconds.to_f)
+      end
+
+      def clear(circuit_name)
+        @native.clear(circuit_name.to_s)
+      end
+
+      def clear_all
+        @native.clear_all
+      end
+
+      def record_event_with_details(circuit_name, type, duration, error: nil, new_state: nil)
+        # Basic event recording (native extension handles type and duration)
+        case type
+        when :success
+          record_success(circuit_name, duration)
+        when :failure
+          record_failure(circuit_name, duration)
+        end
+
+        # NOTE: Error and state details not tracked in native backend
+        # This is intentional for performance - use Memory backend if you need full event details
+      end
+
+      def event_log(circuit_name, limit)
+        @native.event_log(circuit_name.to_s, limit)
+      end
+
+      def with_timeout(_timeout_ms)
+        # Native operations should be instant
+        yield
+      end
+    end
+  end
+end

data/lib/breaker_machines/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BreakerMachines
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 end

data/lib/breaker_machines.rb

@@ -15,32 +15,94 @@ loader.ignore("#{__dir__}/breaker_machines/console.rb")
 loader.ignore("#{__dir__}/breaker_machines/async_support.rb")
 loader.ignore("#{__dir__}/breaker_machines/hedged_async_support.rb")
 loader.ignore("#{__dir__}/breaker_machines/circuit/async_state_management.rb")
+loader.ignore("#{__dir__}/breaker_machines/native_speedup.rb")
+loader.ignore("#{__dir__}/breaker_machines/native_extension.rb")
 loader.setup
 
 # BreakerMachines provides a thread-safe implementation of the Circuit Breaker pattern
 # for Ruby applications, helping to prevent cascading failures in distributed systems.
 module BreakerMachines
+  # Global configuration class for BreakerMachines
+  class Configuration
+    attr_accessor :default_storage,
+                  :default_timeout,
+                  :default_reset_timeout,
+                  :default_failure_threshold,
+                  :log_events,
+                  :fiber_safe
+
+    def initialize
+      @default_storage = :bucket_memory
+      @default_timeout = nil
+      @default_reset_timeout = 60.seconds
+      @default_failure_threshold = 5
+      @log_events = true
+      @fiber_safe = false
+    end
+  end
+
   class << self
     def loader
       loader
     end
-  end
-
-  # Global configuration
-  include ActiveSupport::Configurable
 
-  config_accessor :default_storage, default: :bucket_memory
-  config_accessor :default_timeout, default: nil
-  config_accessor :default_reset_timeout, default: 60.seconds
-  config_accessor :default_failure_threshold, default: 5
-  config_accessor :log_events, default: true
-  config_accessor :fiber_safe, default: false
+    def config
+      @config ||= Configuration.new
+    end
 
-  class << self
     def configure
       yield config
     end
 
+    # Delegate config attributes to config object for backward compatibility
+    def default_storage
+      config.default_storage
+    end
+
+    def default_storage=(value)
+      config.default_storage = value
+    end
+
+    def default_timeout
+      config.default_timeout
+    end
+
+    def default_timeout=(value)
+      config.default_timeout = value
+    end
+
+    def default_reset_timeout
+      config.default_reset_timeout
+    end
+
+    def default_reset_timeout=(value)
+      config.default_reset_timeout = value
+    end
+
+    def default_failure_threshold
+      config.default_failure_threshold
+    end
+
+    def default_failure_threshold=(value)
+      config.default_failure_threshold = value
+    end
+
+    def log_events
+      config.log_events
+    end
+
+    def log_events=(value)
+      config.log_events = value
+    end
+
+    def fiber_safe
+      config.fiber_safe
+    end
+
+    def fiber_safe=(value)
+      config.fiber_safe = value
+    end
+
     def setup_notifications
       return unless config.log_events
 
@@ -65,12 +127,27 @@ module BreakerMachines
 
     attr_writer :logger
 
+    # Centralized logging helper
+    # @param level [Symbol] log level (:debug, :info, :warn, :error)
+    # @param message [String] message to log
+    def log(level, message)
+      return unless config.log_events && logger
+
+      logger.public_send(level, "[BreakerMachines] #{message}")
+    end
+
     def instrument(event, payload = {})
       return unless config.log_events
 
       ActiveSupport::Notifications.instrument("breaker_machines.#{event}", payload)
     end
 
+    # Check if native extension is available
+    # @return [Boolean] true if native extension loaded successfully
+    def native_available?
+      @native_available || false
+    end
+
     # Launch the interactive console
     def console
       require_relative 'breaker_machines/console'
@@ -111,3 +188,13 @@ module BreakerMachines
   # Set up notifications on first use
   setup_notifications if config.log_events
 end
+
+# Load optional native speedup after core is loaded
+# Opt-in with BREAKER_MACHINES_NATIVE=1 to enable native extensions
+if ENV['BREAKER_MACHINES_NATIVE'] == '1'
+  begin
+    require_relative 'breaker_machines/native_speedup'
+  rescue LoadError
+    # Native gem not available, skip native support
+  end
+end

data/sig/breaker_machines.rbs

@@ -1,14 +1,27 @@
 module BreakerMachines
   VERSION: String
 
+  class Configuration
+    attr_accessor default_storage: (:memory | :bucket_memory | :null | untyped)
+    attr_accessor default_timeout: Integer?
+    attr_accessor default_reset_timeout: Integer
+    attr_accessor default_failure_threshold: Integer
+    attr_accessor log_events: bool
+    attr_accessor fiber_safe: bool
+
+    def initialize: () -> void
+  end
+
   # Global configuration
-  extend ActiveSupport::Configurable
+  self.@config: Configuration?
+  def self.config: () -> Configuration
+
+  # Class methods
+  def self.configure: () { (Configuration config) -> void } -> void
 
-  # Configuration accessors
-  self.@config: untyped
-  def self.config: () -> ActiveSupport::Configurable::Configuration
+  # Delegated config accessors for backward compatibility
   def self.default_storage: () -> (:memory | :bucket_memory | :null | untyped)
-  def self.default_storage=: (:memory | :bucket_memory | :null | untyped value) -> void
+  def self.default_storage=: ((:memory | :bucket_memory | :null | untyped) value) -> void
   def self.default_timeout: () -> Integer?
   def self.default_timeout=: (Integer? value) -> void
   def self.default_reset_timeout: () -> Integer
@@ -17,9 +30,8 @@ module BreakerMachines
   def self.default_failure_threshold=: (Integer value) -> void
   def self.log_events: () -> bool
   def self.log_events=: (bool value) -> void
-
-  # Class methods
-  def self.configure: () { (untyped config) -> void } -> void
+  def self.fiber_safe: () -> bool
+  def self.fiber_safe=: (bool value) -> void
   def self.setup_notifications: () -> void
   def self.logger: () -> ActiveSupport::Logger?
   def self.logger=: (ActiveSupport::Logger? logger) -> void